Tổng Kho eSIM
Versioning

Release History

API versioning follows path prefixes (/v1). Breaking changes warrant new path versions without silent regressions to /v1. Webhooks version independently of REST. Current OpenAPI spec version: v2.4.0.

Release History

v2.4.0Latest
  • AddedMembers with OpenAPI access can create tke_member_test_ keys on api-testing.tongkhoesim.com, with virtual funds, simulated orders/eSIMs, seed/reset and scenario controls. Key management separates Live/Test; test data does not affect real wallets, history, rank or invoices.
  • NoteMember bulk and webhooks remain unsupported in both modes. Refund review is live-only; test cancellation refunds virtual funds. Member seed/reset require Idempotency-Key and reset requires reason. Test never calls real providers or issues real MISA invoices.
v2.3.0Stable
  • AddedSelected members can receive live Open API keys from an admin. They remain members: orders, wallets, refunds and invoices retain member ownership. Agreed custom prices are final and do not receive another rank discount.
  • NoteAdds member GET/POST /v1/esims/{id}/refund-requests and optional invoice_buyer on member orders. Omitting the buyer retains the existing consumer invoice flow. Bulk, webhooks and test mode remain organization-only; members receive capability.not_supported.
v2.2.0Stable
  • AddedEvery per-eSIM webhook (esim.delivered, esim.activated, esim.usage_threshold, esim.expiring) now carries order_id and external_ref — the order reference you sent when ordering — so you can match each eSIM back to your own order without an extra API call.
  • AddedThe eSIM block (GET /v1/esims, GET /v1/esims/{id}, an order's items[]) gains an external_ref field, and GET /v1/esims can filter by ?external_ref=… to fetch every eSIM of an order by your own reference. If all you have is an ICCID, keep using ?iccid=… to get the id.
  • AddedTest mode: simulating the customer enabling an eSIM (POST /v1/testmode/esims/{id}/simulate with status enabled) now fires the esim.activated webhook exactly once, just like a live order — so you can test the full "customer installed the eSIM" flow on the test host.
  • NotePrices in /v1/catalog/packages are exactly what an order will charge your organisation (including any contract-specific price), no longer the base price.
  • NoteBackwards compatible: fields were only added, none changed or removed. external_ref is always present and is null when the order was placed without one.
v2.1.0Stable
  • AddedPer-organisation provider scope: when your organisation is granted the catalogue of a specific supplier, /v1/catalog/packages, package detail, orders and plan-options only expose packages within that scope; anything outside it behaves as non-existent (partner.package_not_visible / order.package_not_allowed). Lists carry the new warning filtered_by_provider_scope (one more value in the closed code set); catalog.updated webhooks only carry in-scope SKUs. No field ever reveals the supplier.
  • NoteBackwards compatible: organisations without a scope see no difference.
v2.0.0Stable
  • AddedNew response shape across all of /v1: a unified list envelope {items, next_cursor, page_size, total, mode, warnings[]}; every entity carries an id; amounts are {amount, currency} objects instead of bare integers; usage is consolidated into a single usage{} block; install (LPA/QR) is only returned when requested via ?include=lpa; added cancellable{allowed,reason,disclosed_at}; topup-options/topup renamed to plan-options/change-plan.
  • AddedTest mode for partners: a dedicated host, api-testing.tongkhoesim.com, only accepts tke_test_ keys (the live host only accepts tke_live_, calling the wrong host returns 403 partner.wrong_host); new /v1/testmode/* endpoints (status, seed, reset, esims/{id}/simulate, webhooks/fire, webhooks/fail-next); sample data auto-created for an organization's first test key; self-running usage (drift) on a fixed interval.
  • NoteBefore this release, /v1 had zero integrated partners; from here on the contract starts to stabilize.