{"openapi":"3.1.0","info":{"title":"GLOBALCELL connector API","version":"1.0.0","description":"Sell GLOBALCELL travel eSIMs and data packages.\n\n**Channel API** (`/v1`): for resellers, dealers, business clients, web shops and apps with a connector key\n(`Authorization: Bearer <key>`). Sandbox keys come after the NDA, live keys after the contract.\nA sandbox connector pays with `\"paymentMethod\": \"simulated\"` and settles it with `POST /v1/sandbox/orders/{id}/pay`;\neverything after that is the real flow against the test reseller.\n\n**Public storefront** (`/public/v1`): no key, for the mobile app and AI agents. Orders are read back with the\norder token returned at creation. The MCP server for AI agents is at `POST /mcp`.\n\nFlow: list products → create an order → send the customer to `checkoutUrl` → poll the order until `status` is\n`fulfilled` → show the install kit (one-tap iPhone/Android links, QR, manual codes).\nStatuses: `pending_payment` → `paid` → `fulfilling` → `fulfilled`, or `expired`, `payment_failed`,\n`fulfilment_failed` (manual review). Prices always come from the catalog, never from the request.","contact":{"name":"GLOBALCELL partners","url":"https://globalcell.io"}},"servers":[{"url":"https://api.globalcell.dev","description":"Production (live keys)"},{"url":"https://sandbox.globalcell.dev","description":"Sandbox (sandbox keys, simulated payments)"}],"tags":[{"name":"Channel API","description":"Connector key required"},{"name":"Sandbox","description":"Sandbox connectors only"},{"name":"Public storefront","description":"No key"},{"name":"Partner portals","description":"For the servers of globalcell.deals and globalcell.business only, with the portal's own key.\nA dealer or corporate client registers on the portal, accepts the terms and the NDA, and picks a vendor (shop)\nand one of its currencies. The portal registers them here and shows the **sandbox key** in their settings at once.\nAfter the contract is signed GLOBALCELL approves them, and the portal can issue their **production key**.\nKeys are returned only once: show them once, then offer \"new key\" (the old one stops working).\nSandbox keys are limited to a few test orders, and package activations only on their own test eSIMs."}],"security":[{"connectorKey":[]}],"paths":{"/v1/connector":{"get":{"tags":["Channel API"],"summary":"Who am I: connector name, type and environment","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Connector"}}}},"401":{"description":"Missing or wrong key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getConnector"}},"/v1/products":{"get":{"tags":["Channel API"],"summary":"Products this connector sells, optionally for one country","parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166 code, e.g. SK","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"activation":{"$ref":"#/components/schemas/ActivationOptions"}}}}}}},"operationId":"listProducts"}},"/v1/destinations":{"get":{"tags":["Channel API"],"summary":"Countries and regions with products","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Destinations"}}}}},"operationId":"listDestinations"}},"/v1/orders":{"get":{"tags":["Channel API"],"summary":"Your newest orders, optionally of one status","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/Order"}}}}}}}},"operationId":"listOrders"},"post":{"tags":["Channel API"],"summary":"Create an order (new eSIM or package activation) and its payment","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique per order attempt (8-128 letters, digits, - or _). A retry with the same key returns the first order instead of creating a second payment.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["package","new_esim"]},"sku":{"type":"string","maxLength":64},"iccid":{"type":"string","pattern":"^[0-9]{18,22}$"},"esimId":{"type":"integer","exclusiveMinimum":0,"maximum":999999999999},"currency":{"type":"string","enum":["EUR","USD","GEL"]},"paymentMethod":{"type":"string","enum":["btcpay","stripe","keepz","simulated","cryptopay","telegram"]},"customerEmail":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"returnUrl":{"type":"string","maxLength":2000,"format":"uri"},"activation":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"now"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"on_arrival"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"scheduled"},"startAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"endAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["mode","startAt"]}]},"customer":{"type":"object","properties":{"telegramUserId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"telegramUsername":{"type":"string","maxLength":64},"name":{"type":"string","maxLength":200},"language":{"type":"string","maxLength":10},"ipCountry":{"type":"string","maxLength":2}}},"consents":{"type":"object","properties":{"earlyStart":{"type":"boolean"},"terms":{"type":"boolean"},"territory":{"type":"boolean"},"notificationsAndOffers":{"default":false,"type":"boolean"}},"required":["earlyStart","terms","territory"]}},"required":["type","sku","currency","paymentMethod","returnUrl"]}}}},"responses":{"200":{"description":"Same Idempotency-Key: the original order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid request, unknown sku, activation mode or currency not offered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"insufficient_balance (paymentMethod \"balance\")","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"eSIM not found (package orders)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"esim_out_of_stock: new eSIMs are sold out (nothing was charged); package orders still work","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"createOrder"}},"/v1/orders/{id}":{"get":{"tags":["Channel API"],"summary":"An order of this connector","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getOrder"}},"/v1/orders/{id}/cancel":{"post":{"tags":["Channel API"],"summary":"Cancel a balance-paid package that has not started (within 14 days); refunded to the balance","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Already started, cancelled, not balance-paid or too late","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"cancelOrder"}},"/v1/esims":{"get":{"tags":["Channel API"],"summary":"eSIMs you sold or added packages to","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"listEsims"}},"/v1/esims/{iccid}/diagnosis":{"get":{"tags":["Channel API"],"summary":"Why an eSIM may not work: line state, packages and the last network it registered on","parameters":[{"name":"iccid","in":"path","required":true,"description":"ICCID","schema":{"type":"string","pattern":"^[0-9]{18,22}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not your eSIM","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"diagnoseEsim"}},"/v1/balance":{"get":{"tags":["Channel API"],"summary":"Prepaid balance in EUR and USDT (minor units)","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object"}}}}},"operationId":"getBalance"}},"/v1/orders/{id}/qr.svg":{"get":{"tags":["Channel API"],"summary":"QR code of a delivered new eSIM","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string"}}],"responses":{"200":{"description":"QR code (SVG). Installs the eSIM: do not cache or share.","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"Not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getOrderQr"}},"/v1/esims/{iccid}":{"get":{"tags":["Channel API"],"summary":"eSIM status, numbers and packages with usage","parameters":[{"name":"iccid","in":"path","required":true,"description":"ICCID","schema":{"type":"string","pattern":"^[0-9]{18,22}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Esim"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getEsim"}},"/v1/esims/{iccid}/hotspot":{"put":{"tags":["Channel API"],"summary":"Allow or block hotspot (connectors with this permission)","parameters":[{"name":"iccid","in":"path","required":true,"description":"ICCID","schema":{"type":"string","pattern":"^[0-9]{18,22}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["allowed"],"properties":{"allowed":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"iccid":{"type":"string"},"hotspotAllowed":{"type":"boolean"}}}}}},"403":{"description":"Not enabled for this connector","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"setHotspot"}},"/v1/subscribers/{subscriberId}":{"get":{"tags":["Channel API"],"summary":"eSIM by subscriber id (only ids from this connector's own fulfilled orders)","parameters":[{"name":"subscriberId","in":"path","required":true,"description":"Subscriber id from a fulfilled order","schema":{"type":"string","pattern":"^[1-9][0-9]{0,14}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Esim"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"getSubscriber"}},"/v1/sandbox/orders/{id}/pay":{"post":{"tags":["Sandbox"],"summary":"Decide what happened to a simulated payment","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["outcome"],"properties":{"outcome":{"enum":["paid","failed","expired"]},"amountMinor":{"type":"integer","description":"Pretend a different amount was paid, to see the mismatch refused"}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"404":{"description":"Not a sandbox connector or unknown order","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"sandboxPay"}},"/public/v1/destinations":{"get":{"tags":["Public storefront"],"security":[],"summary":"Countries and regions with products","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Destinations"}}}}},"operationId":"publicListDestinations"}},"/public/v1/products":{"get":{"tags":["Public storefront"],"security":[],"summary":"Products, optionally for one country","parameters":[{"name":"country","in":"query","required":false,"description":"ISO 3166 code, e.g. SK","schema":{"type":"string","pattern":"^[A-Za-z]{2}$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}}},"operationId":"publicListProducts"}},"/public/v1/products/{sku}":{"get":{"tags":["Public storefront"],"security":[],"summary":"One product","parameters":[{"name":"sku","in":"path","required":true,"description":"Product sku","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"404":{"description":"Unknown sku","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"publicGetProduct"}},"/public/v1/orders":{"post":{"tags":["Public storefront"],"security":[],"summary":"Create an order; returns the payment page and the order token","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"Unique per order attempt (8-128 letters, digits, - or _). A retry with the same key returns the first order instead of creating a second payment.","schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{8,128}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","enum":["package","new_esim"]},"sku":{"type":"string","maxLength":64},"iccid":{"type":"string","pattern":"^[0-9]{18,22}$"},"esimId":{"type":"integer","exclusiveMinimum":0,"maximum":999999999999},"currency":{"type":"string","enum":["EUR","USD","GEL"]},"customerEmail":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"activation":{"oneOf":[{"type":"object","properties":{"mode":{"type":"string","const":"now"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"on_arrival"}},"required":["mode"]},{"type":"object","properties":{"mode":{"type":"string","const":"scheduled"},"startAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"},"endAt":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"}},"required":["mode","startAt"]}]},"customer":{"type":"object","properties":{"telegramUserId":{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991},"telegramUsername":{"type":"string","maxLength":64},"name":{"type":"string","maxLength":200},"language":{"type":"string","maxLength":10},"ipCountry":{"type":"string","maxLength":2}}},"consents":{"type":"object","properties":{"earlyStart":{"type":"boolean"},"terms":{"type":"boolean"},"territory":{"type":"boolean"},"notificationsAndOffers":{"default":false,"type":"boolean"}},"required":["earlyStart","terms","territory"]}},"required":["type","sku","currency"]}}}},"responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOrderCreated"}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"eSIM not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"esim_out_of_stock: new eSIMs are sold out","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Too many orders from this address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"publicCreateOrder"}},"/public/v1/orders/{id}":{"get":{"tags":["Public storefront"],"security":[],"summary":"Order status and, once fulfilled, the install kit","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string"}},{"name":"token","in":"query","required":true,"description":"orderToken from POST /public/v1/orders","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicOrder"}}}},"404":{"description":"Not found or wrong token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"publicGetOrder"}},"/public/v1/orders/{id}/qr.svg":{"get":{"tags":["Public storefront"],"security":[],"summary":"QR code of a delivered new eSIM","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string"}},{"name":"token","in":"query","required":true,"description":"orderToken from POST /public/v1/orders","schema":{"type":"string"}}],"responses":{"200":{"description":"QR code (SVG). Installs the eSIM: do not cache or share.","content":{"image/svg+xml":{"schema":{"type":"string"}}}},"404":{"description":"Not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"publicGetOrderQr"}},"/public/v1/orders/{id}/page":{"get":{"tags":["Public storefront"],"security":[],"summary":"The customer's order page (HTML): status, install buttons, QR","parameters":[{"name":"id","in":"path","required":true,"description":"Order id","schema":{"type":"string"}},{"name":"token","in":"query","required":true,"description":"orderToken from POST /public/v1/orders","schema":{"type":"string"}}],"responses":{"200":{"description":"HTML page","content":{"text/html":{"schema":{"type":"string"}}}}},"operationId":"publicOrderPage"}},"/provision/v1/vendors":{"get":{"tags":["Partner portals"],"summary":"Vendors (shops) and the currencies each sells in, for the registration form","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"vendors":{"type":"array","items":{"$ref":"#/components/schemas/Vendor"}}}}}}},"401":{"description":"Missing or wrong portal key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"portalListVendors"}},"/provision/v1/partners":{"post":{"tags":["Partner portals"],"summary":"Register a dealer or corporate client and get its sandbox key","description":"Repeating it with the same externalId returns the same partner (200) with `sandbox: null`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"externalId":{"type":"string","minLength":1,"maxLength":128},"kind":{"type":"string","enum":["dealer","business"]},"company":{"type":"string","minLength":1,"maxLength":200},"contactEmail":{"type":"string","maxLength":254,"format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"vendor":{"type":"string","maxLength":64},"currency":{"type":"string","enum":["EUR","USD","GEL"]},"acceptedTermsVersion":{"type":"string","minLength":1,"maxLength":32},"acceptedNdaVersion":{"type":"string","minLength":1,"maxLength":32},"returnUrlPrefixes":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","maxLength":500,"format":"starts_with","pattern":"^https:\\/\\/.*"}}},"required":["externalId","kind","company","contactEmail","vendor","currency","acceptedTermsVersion","acceptedNdaVersion"]}}}},"responses":{"200":{"description":"Already registered","content":{"application/json":{"schema":{"type":"object","properties":{"partner":{"$ref":"#/components/schemas/Partner"},"sandbox":{"type":"null"}}}}}},"201":{"description":"Registered","content":{"application/json":{"schema":{"type":"object","properties":{"partner":{"$ref":"#/components/schemas/Partner"},"sandbox":{"$ref":"#/components/schemas/IssuedKey"}}}}}},"400":{"description":"Invalid request, unknown_vendor or currency_not_offered_by_vendor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"portalRegisterPartner"}},"/provision/v1/partners/{id}":{"get":{"tags":["Partner portals"],"summary":"A partner this portal registered: status, account, keys","parameters":[{"name":"id","in":"path","required":true,"description":"Partner id","schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"partner":{"$ref":"#/components/schemas/Partner"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"portalGetPartner"}},"/provision/v1/partners/{id}/keys":{"post":{"tags":["Partner portals"],"summary":"Issue a new sandbox or production key (the old one stops working)","parameters":[{"name":"id","in":"path","required":true,"description":"Partner id","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["environment"],"properties":{"environment":{"enum":["sandbox","live"]}}}}}},"responses":{"201":{"description":"New key","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/IssuedKey"},{"type":"object","properties":{"environment":{"enum":["sandbox","live"]},"partner":{"$ref":"#/components/schemas/Partner"}}}]}}}},"403":{"description":"production_not_approved or partner_suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"operationId":"portalIssuePartnerKey"}}},"components":{"securitySchemes":{"connectorKey":{"type":"http","scheme":"bearer","description":"Connector key from GLOBALCELL"}},"schemas":{"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"},"details":{"type":"object"}}},"Vendor":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"currencies":{"type":"array","items":{"enum":["EUR","USD","GEL"]}}}},"IssuedKey":{"type":"object","properties":{"apiKey":{"type":"string","description":"Shown only in this answer. Store or show it once; GLOBALCELL keeps only its hash."},"baseUrl":{"type":"string"},"docsUrl":{"type":"string"}}},"Partner":{"type":"object","properties":{"id":{"type":"string"},"externalId":{"type":"string"},"kind":{"enum":["dealer","business"]},"company":{"type":"string"},"contactEmail":{"type":"string"},"vendor":{"type":"string"},"currency":{"enum":["EUR","USD","GEL"]},"acceptedTermsVersion":{"type":"string"},"acceptedNdaVersion":{"type":"string"},"status":{"enum":["sandbox","approved","suspended"],"description":"approved = contract signed; production keys can be issued"},"accountId":{"type":["integer","null"],"description":"Account under the vendor's reseller; null until one is free"},"createdAt":{"type":"string"},"approvedAt":{"type":["string","null"]},"sandbox":{"type":"object","properties":{"keyActive":{"type":"boolean"},"orderLimit":{"type":"integer"},"ordersUsed":{"type":"integer"}}},"production":{"type":"object","properties":{"available":{"type":"boolean"},"keyActive":{"type":"boolean"}}}}},"Connector":{"type":"object","properties":{"name":{"type":"string"},"type":{"enum":["shop","app","reseller","dealer","business","ai","internal","portal"]},"environment":{"enum":["live","sandbox"]},"simulatedPayments":{"type":"boolean"},"newEsimAvailable":{"type":"boolean","description":"False while new eSIMs are sold out; package activations still work"}}},"Coverage":{"type":"object","properties":{"iso2":{"type":"string"},"country":{"type":"string"},"operators":{"type":"array","items":{"type":"string"}}}},"Product":{"type":"object","properties":{"sku":{"type":"string"},"name":{"type":"string"},"description":{"type":["string","null"]},"dataGB":{"type":["number","null"]},"validityDays":{"type":["integer","null"]},"hotspot":{"type":["boolean","null"]},"prices":{"type":"object","description":"Price per currency in minor units","propertyNames":{"enum":["EUR","USD","GEL"]},"additionalProperties":{"type":"integer"}},"forNewEsim":{"type":"boolean"},"forPackage":{"type":"boolean","description":"Can be activated on an existing eSIM"},"region":{"type":["string","null"],"description":"Name of a multi-country region"},"coverage":{"type":"array","items":{"$ref":"#/components/schemas/Coverage"}}}},"ActivationOptions":{"type":"object","properties":{"default":{"enum":["now","on_arrival","scheduled"]},"modes":{"type":"array","items":{"enum":["now","on_arrival","scheduled"]}},"fees":{"type":"object","description":"Extra charge per mode and currency (minor units). A mode with a fee table is only offered in those currencies."}}},"Activation":{"type":"object","properties":{"mode":{"enum":["now","on_arrival","scheduled"]},"validityDays":{"type":"integer"},"startAt":{"type":"string","format":"date-time"},"endAt":{"type":"string","format":"date-time"}}},"Destinations":{"type":"object","properties":{"countries":{"type":"array","items":{"type":"object","properties":{"iso2":{"type":"string"},"country":{"type":"string"},"operators":{"type":"array","items":{"type":"string"}},"products":{"type":"integer"},"from":{"type":"object","description":"Price per currency in minor units","propertyNames":{"enum":["EUR","USD","GEL"]},"additionalProperties":{"type":"integer"}}}}},"regions":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"countries":{"type":"array","items":{"type":"string"}},"products":{"type":"integer"},"from":{"type":"object","description":"Price per currency in minor units","propertyNames":{"enum":["EUR","USD","GEL"]},"additionalProperties":{"type":"integer"}}}}}}},"InstallKit":{"type":"object","description":"Everything needed to install a new eSIM","properties":{"lpa":{"type":"string"},"smdpAddress":{"type":"string"},"activationCode":{"type":"string"},"iosUrl":{"type":"string","description":"One-tap install on iPhone (iOS 17.4+)"},"androidUrl":{"type":"string","description":"One-tap install on Android"},"qrSvgUrl":{"type":"string"}}},"Order":{"type":"object","properties":{"id":{"type":"string"},"type":{"enum":["new_esim","package"]},"sku":{"type":"string"},"iccid":{"type":["string","null"]},"subscriberId":{"type":["integer","null"],"description":"Core subscriber id; store it as the customer id"},"currency":{"enum":["EUR","USD","GEL"]},"amountMinor":{"type":"integer","description":"Total charged"},"priceMinor":{"type":"integer","description":"Amount in minor units (cents)"},"activationFeeMinor":{"type":"integer","description":"Amount in minor units (cents)"},"activation":{"$ref":"#/components/schemas/Activation"},"paymentMethod":{"type":"string"},"checkoutUrl":{"type":["string","null"],"description":"Where the customer pays (while pending_payment)"},"status":{"enum":["pending_payment","paid","fulfilling","fulfilled","expired","payment_failed","fulfilment_failed"]},"esim":{"oneOf":[{"type":"null"},{"type":"object","properties":{"iccid":{"type":"string"},"smdpServer":{"type":"string"},"activationCode":{"type":"string"},"lpa":{"type":"string"},"install":{"$ref":"#/components/schemas/InstallKit"}}}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}},"PublicOrder":{"type":"object","properties":{"id":{"type":"string"},"type":{"enum":["new_esim","package"]},"sku":{"type":"string"},"productName":{"type":"string"},"iccid":{"type":["string","null"]},"status":{"type":"string"},"currency":{"enum":["EUR","USD","GEL"]},"amountMinor":{"type":"integer","description":"Amount in minor units (cents)"},"priceMinor":{"type":"integer","description":"Amount in minor units (cents)"},"activationFeeMinor":{"type":"integer","description":"Amount in minor units (cents)"},"activation":{"$ref":"#/components/schemas/Activation"},"checkoutUrl":{"type":["string","null"]},"orderPageUrl":{"type":"string"},"statusUrl":{"type":"string"},"install":{"oneOf":[{"type":"null"},{"$ref":"#/components/schemas/InstallKit"}]},"createdAt":{"type":"string"},"updatedAt":{"type":"string"}}},"PublicOrderCreated":{"allOf":[{"$ref":"#/components/schemas/PublicOrder"},{"type":"object","properties":{"orderToken":{"type":"string","description":"The only key to read this order later. Returned once; keep it private."}}}]},"Esim":{"type":"object","properties":{"iccid":{"type":"string"},"subscriberId":{"type":["integer","null"]},"imsi":{"type":"array","items":{"type":"string"}},"msisdn":{"type":"array","items":{"type":"string"}},"status":{"type":["string","null"]},"esimStatus":{"type":["string","null"]},"activatedAt":{"type":["string","null"]},"lastUsedAt":{"type":["string","null"]},"hotspotAllowed":{"type":["boolean","null"]},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":["integer","null"]},"name":{"type":["string","null"]},"dataTotalBytes":{"type":["integer","null"]},"dataUsedBytes":{"type":["integer","null"]},"assignedAt":{"type":["string","null"]},"activatedAt":{"type":["string","null"]},"expiresAt":{"type":["string","null"]},"validityDays":{"type":["integer","null"]},"active":{"type":"boolean"}}}}}}}}}