{"openapi":"3.0.3","info":{"title":"Simtasy Wholesale API","version":"1.1.0","description":"Reseller API for the eSIM catalog, wallet-funded orders, eSIM usage, top-ups and wallet.\n\n**Authentication** — send your API key as `Authorization: Bearer sk_live_…`. Keys are created under Dashboard → Developers.\n\n**Money** — orders are paid from your prepaid wallet. If the balance does not cover the order you receive `402 insufficient_funds` and nothing is charged or provisioned.\n\n**Idempotency** — send an `Idempotency-Key` header with `POST /orders`; repeating a request with the same key returns the original order instead of buying a second eSIM.\n\n**Webhooks** — configure HTTPS endpoints in the dashboard to receive `order.completed`, `esim.status` and `esim.usage`, signed with HMAC-SHA256 (`X-Simtasy-Signature`)."},"servers":[{"url":"/api/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key: sk_live_…"}},"schemas":{"Product":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"slug":{"type":"string"},"name":{"type":"string"},"country_code":{"type":"string","nullable":true,"example":"JP"},"country_name":{"type":"string","nullable":true},"data_mb":{"type":"integer","nullable":true,"description":"null = unlimited"},"validity_days":{"type":"integer","nullable":true},"wholesale_price":{"type":"number","description":"What you pay per eSIM (your plan's discount already applied)"},"retail_price":{"type":"number","description":"Suggested end-customer price from your pricing rules"},"currency":{"type":"string","example":"EUR"}}},"Esim":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"iccid":{"type":"string","nullable":true},"lpa_string":{"type":"string","nullable":true,"description":"Activation code (LPA:1$…)"},"qr_code_url":{"type":"string","nullable":true},"status":{"type":"string","enum":["pending","ready","installed","in_use","exhausted","expired","suspended","cancelled","revoked","failed"]},"access_token":{"type":"string","description":"Token for the hosted customer eSIM page"}}},"OrderResult":{"type":"object","properties":{"order_id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["pending","provisioning","completed","failed","cancelled","refunded"]},"cost":{"type":"number","description":"Amount debited from your wallet"},"esim":{"$ref":"#/components/schemas/Esim","nullable":true}}},"InsufficientFunds":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string","enum":["insufficient_funds"]},"required":{"type":"number"},"available":{"type":"number"},"currency":{"type":"string"}}}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"Catalog"},{"name":"Orders"},{"name":"eSIMs"},{"name":"Wallet"}],"paths":{"/countries":{"get":{"tags":["Catalog"],"summary":"List countries with available plans","responses":{"200":{"description":"OK"}}}},"/products":{"get":{"tags":["Catalog"],"summary":"List products with your prices","parameters":[{"name":"country","in":"query","schema":{"type":"string"},"description":"ISO-3166 alpha-2, e.g. JP"}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}}}}}}},"/products/{id}":{"get":{"tags":["Catalog"],"summary":"Get one product","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message"},"code":{"type":"string","description":"Stable machine-readable code"}}}}}}}}},"/orders":{"get":{"tags":["Orders"],"summary":"List your orders (latest 100)","responses":{"200":{"description":"OK"}}},"post":{"tags":["Orders"],"summary":"Create an order (charges the wallet, returns the eSIM)","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","minLength":8,"maxLength":128},"description":"Repeating a request with the same key returns the existing order."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["product_id"],"properties":{"product_id":{"type":"string","format":"uuid"},"quantity":{"type":"integer","minimum":1,"maximum":50,"default":1},"email":{"type":"string","format":"email","description":"Customer e-mail — triggers a branded delivery e-mail"},"name":{"type":"string"},"idempotency_key":{"type":"string","description":"Alternative to the Idempotency-Key header"}}}}}},"responses":{"200":{"description":"Order placed. `status` is usually `completed` with the eSIM attached.","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/OrderResult"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message"},"code":{"type":"string","description":"Stable machine-readable code"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message"},"code":{"type":"string","description":"Stable machine-readable code"}}}}}},"402":{"description":"Wallet balance too low — nothing was charged or provisioned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InsufficientFunds"}}}}}}},"/orders/{id}":{"get":{"tags":["Orders"],"summary":"Get an order with its eSIM","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message"},"code":{"type":"string","description":"Stable machine-readable code"}}}}}}}}},"/esims/{iccid}":{"get":{"tags":["eSIMs"],"summary":"Get an eSIM by ICCID","parameters":[{"name":"iccid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message"},"code":{"type":"string","description":"Stable machine-readable code"}}}}}}}}},"/esims/{iccid}/usage":{"get":{"tags":["eSIMs"],"summary":"Fetch live data usage from the network","parameters":[{"name":"iccid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Usage snapshot: dataUsedMb, dataRemainingMb, …"},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message"},"code":{"type":"string","description":"Stable machine-readable code"}}}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message"},"code":{"type":"string","description":"Stable machine-readable code"}}}}}}}}},"/esims/{iccid}/topups":{"get":{"tags":["eSIMs"],"summary":"List available top-ups","parameters":[{"name":"iccid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"}}},"post":{"tags":["eSIMs"],"summary":"Purchase a top-up (charges the wallet)","parameters":[{"name":"iccid","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"402":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message"},"code":{"type":"string","description":"Stable machine-readable code"}}}}}}}}},"/wallet":{"get":{"tags":["Wallet"],"summary":"Wallet balance and recent transactions","responses":{"200":{"description":"OK"}}},"post":{"tags":["Wallet"],"summary":"Create a Stripe checkout link to top up the wallet","requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["amount"],"properties":{"amount":{"type":"number","minimum":10,"maximum":50000},"success_url":{"type":"string","format":"uri"},"cancel_url":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"{ data: { checkout_url, id } }"},"503":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Human-readable message"},"code":{"type":"string","description":"Stable machine-readable code"}}}}}}}}}},"x-webhooks":{"signature":"HMAC-SHA256 over the raw request body with your endpoint secret, hex-encoded, sent as X-Simtasy-Signature. Event name in X-Simtasy-Event.","envelope":{"id":"string","event":"string","created_at":"ISO-8601","data":"object"},"events":["order.completed","esim.status","esim.usage","ping"],"timeout":"10 seconds; respond 2xx. Failed deliveries can be retried from the dashboard."}}