Separate public catalogue from private reception
Public data describes service, country, price and duration. It contains no allocated phone number or code. Activations belong to an account and order with separate private tracking.
The service and country directory is separate from commercial offers. The integration contract requires an API catalogue with authoritative price and availability for orders.
Catalogue and ordering
The existing contract specifies GET /catalog/products and GET /catalog/products/:slug. The backend supplies authoritative price, duration and explicit availability; absent stock remains unknown.
Orders send a product identifier with an idempotency key. The server checks price and stock before reservation or allocation. Reading a page does not trigger sensitive actions.
Reception states
The module distinguishes allocating, waiting, received, completed, cancelled, expired and failed. Allocation can be pending without a number; real waiting and reception require the backend’s number and expiry.
Each message has a stable identifier, timestamp and text. The backend may provide an extracted code; the interface must not guess an OTP. The public directory contains no allocated phone number or private code.
Authorised actions and updates
GET /activations and GET /activations/:id are private reads. POST /activations/:id/actions sends cancel, finish or resend with an idempotency key. The backend announces and rechecks allowed actions.
Private reads use the session, interface language and suitable caching. Tracking intervals follow the contract; server expiry and state take priority over a browser timer.
Payment, allocation and provider secrets
The invoice fixes asset, network, amount, address and expiry. Payment confirmation and number allocation are separate events. The backend handles failures and retries without double allocation.
Provider keys and payment secrets stay on the server. The API authorises every account read, defines message retention and keeps internal provider identifiers private. This page documents the integration contract and does not announce an operational public API.
Contract endpoint reference
| Method | Endpoint | Role |
|---|---|---|
GET | /catalog/products | Public catalogue |
GET | /activations | Account activations |
GET | /activations/:id | Private reception tracking |
POST | /activations/:id/actions | Authorised action |
These are the existing frontend contract paths, not published production endpoints. Provider, authentication and payment integration remain to be connected.