NOX GSM API

Place and track orders from your own system

Overview

This API lets you browse the catalog, place orders and follow them from your own website, app or bot — the same things you can do in the store, using your store account and wallet balance.

Base URL — the domain of the store where your account is registered, followed by /api:

{BASE_URL} = https://<store-domain>/api

All requests and responses are JSON over HTTPS. Send these headers on every request:

HeaderValue
Acceptapplication/jsonRequired
Content-Typeapplication/jsonFor POST requests
AuthorizationBearer {token}For endpoints marked “Bearer token”
Accept-Languageen, ar, tr, kuOptional — language of names and messages

Response envelope — every response has the same shape:

{
  "success": true,
  "message": "Human-readable message",
  "data": { ... }
}

The login endpoints use { "status", "message", "data", "token" } instead. Prices and amounts are returned in your account currency.

Authentication

  1. Call POST {BASE_URL}/login with the email (or phone) and password of your store account.
  2. Keep the token from the response and send it as Authorization: Bearer {token} on every protected request.
  3. The token stays valid until you call POST {BASE_URL}/logout or change your password. Do not log in before every request.
Two-factor authentication: if 2FA is enabled on the account, /login answers 403 with "two_factor_required": true and a "challenge_token". Send challenge_token and code (the 6-digit code from the authenticator app) to POST {BASE_URL}/auth/two-factor to receive the login token. For an automated integration, use an account without 2FA and keep its password safe.

Keep the token secret, like a password. Never put it in a public website or app.

Placing an order

  1. Find the product — browse GET /services → GET /services/{id}/children (sub-categories) → GET /services/{id}/variants, or search with GET /search?search=…. The product to buy is a variant; keep its id.
  2. Read its fields — GET /service-variants/{id} returns fields: the inputs this product needs (for example a player ID or an IMEI). Each field has a key and required.
  3. Buy — POST /orders/buy-now with service_variant_id, quantity and the field values in metadata.provider_inputs, using the exact key of each field. The price is taken from your wallet.
  4. Follow the result — many products are delivered within seconds; others take longer. Poll GET /orders/{id} (every 30–60 seconds is enough) until each line is completed or failed.
  5. Read the result — on a completed line, codes / PINs / the result text are in fulfillment_deliverables (and codes for instant stock products). On a failed line, customer_failure_reason says why; the amount is returned to your wallet automatically.
A line that is pending or processing is still being handled — do not order it again, or it may be delivered twice.

Order statuses

Line statusMeaning
pendingReceived, not started yet.
processingBeing executed. Keep polling.
completedDelivered. Read fulfillment_deliverables / codes.
failedNot delivered. See customer_failure_reason. The amount is refunded to the wallet.

The order itself has a summary status: pending, completed, partial (some lines failed) or failed.

Each line also has execution_seconds (how long it took) and resolved_at once it is finished.

Errors

HTTPMeaning
200 / 201OK. For buy-now, 201 = delivered immediately, 200 = accepted and still processing.
400The order could not be placed (for example the product is unavailable). Read message.
401Missing or expired token — log in again.
403Not allowed (or two-factor code required at login).
404Not found (wrong id, or the order belongs to another account).
422Invalid input. errors lists the problem per field (for example not enough balance or a missing required field).
429Too many requests — slow down and retry later.
500Server error — retry later. If you were placing an order, check GET /orders before ordering again.
{
  "message": "The given data was invalid.",
  "errors": { "quantity": ["The quantity field is required."] }
}

Endpoints