Documentation de l'API

Chaque requête doit inclure votre clé API :

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Forme d'en-tête alternative : X-API-Key: jm_xxx…

Créez et révoquez vos clés sur /account/api-keys. Chaque utilisateur peut détenir jusqu'à 10 clés actives. Le token complet n'est affiché qu'une seule fois à la création — conservez-le en lieu sûr.

Toutes les erreurs renvoient du JSON :

{ "ok": false, "code": "RATE_LIMITED", "message": "..." }

Limites de débit: Par clé, fenêtre glissante de 60s. Endpoints d'écriture (orders, cancel, next-sms) 10 req/min ; endpoints de lecture (account, services, prices, list) 60 req/min.

Récupérer votre solde actuel et votre profil de base.

curl https://jiema.my/api/v1/account \
  -H "Authorization: Bearer jm_xxx"

# 200 OK
{ "ok": true, "data": {
  "id": "clxxxxxxxxxxx",
  "balanceCents": "1200",       // string to preserve precision; $12.00
  "referralCode": "abc123",
  "displayName": "Alice",
  "lang": "en"
}}

Liste des services avec leur disponibilité. Mis en cache côté serveur ~5 min.

curl https://jiema.my/api/v1/services -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "code": "tg", "slug": "telegram", "name": "Telegram",
    "minCostUsd": 0.18, "totalCount": 1234, "countryCount": 24 },
  ...
] }}

Utilisez code (ou le slug convivial) comme valeur de service lors de la création d'une commande.

curl https://jiema.my/api/v1/countries -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "items": [
  { "id": 7, "slug": "my", "name": "Malaysia" },
  ...
] }}

id est l'id numérique du pays chez le fournisseur ; slug est le code court SEO (par ex. "my" / "us"). Les deux formes sont acceptées comme valeur de country.

Prix et disponibilité par pays pour un service donné. Les prix incluent déjà la marge/remise configurée par l'équipe ops.

curl "https://jiema.my/api/v1/prices?service=tg" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "service": "tg",
  "items": [
    { "countryId": 7, "countrySlug": "my", "priceCents": "32", "count": 540 },
    ...
  ]
}}

Créer une commande de vérification par SMS. Le système réserve un numéro chez le fournisseur et débite le montant correspondant de votre solde.

curl -X POST https://jiema.my/api/v1/orders \
  -H "Authorization: Bearer jm_xxx" \
  -H "content-type: application/json" \
  -d '{ "service": "tg", "country": 7 }'

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "WAITING",
  "service": "tg",
  "country": "7",
  "phone": "+60123456789",
  "expiresAt": "2026-05-22T08:30:00.000Z",
  "chargedCents": "32"
}}

Aucun champ optionnel en dehors de service / country.

Codes d'erreur courants : INSUFFICIENT (recharge requise), NO_NUMBERS, BAD_SERVICE, BAD_COUNTRY.

Interrogez jusqu'à ce que status passe à RECEIVED et que smsBody ne soit plus nul.

curl https://jiema.my/api/v1/orders/ckxxxxx -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "id": "ckxxxxx",
  "status": "RECEIVED",
  "phone": "+60123456789",
  "smsBody": "Your verification code is 123456",
  "smsHistory": [
    { "body": "Your verification code is 123456", "receivedAt": "..." }
  ],
  "smsReceivedAt": "2026-05-22T08:12:34.000Z",
  ...
}}

Statuts : WAITING (numéro actif, en attente du SMS) · RECEIVED (code reçu) · COMPLETED / FAILED / CANCELLED sont terminaux.

Intervalle de polling suggéré : toutes les 3–5 secondes. La synchronisation avec le fournisseur s'effectue dans cet endpoint, donc le polling fait avancer l'état même si le worker en arrière-plan est occupé.

Annuler une commande qui n'a pas encore reçu de code. Remboursement intégral sur votre solde.

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/cancel \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "CANCELLED" }}

Rejetée avec CODE_RECEIVED si le numéro a déjà reçu un SMS, ou ALREADY_CHANGED si le statut a changé en parallèle.

Après RECEIVED, demander au fournisseur de garder le numéro actif et d'attendre un autre SMS (sans frais supplémentaires pendant la fenêtre active).

curl -X POST https://jiema.my/api/v1/orders/ckxxxxx/next-sms \
  -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": { "id": "ckxxxxx", "status": "WAITING" }}

Liste paginée par curseur de vos commandes récentes.

curl "https://jiema.my/api/v1/orders?limit=20" -H "Authorization: Bearer jm_xxx"

{ "ok": true, "data": {
  "items": [ { "id": "ck...", "status": "RECEIVED", "service": "tg", ... }, ... ],
  "nextCursor": "ck..." | null
}}

Paramètres optionnels : status · limit 1–100 (par défaut 20) · cursor = nextCursor de la page précédente.

1. Rechargez via l'interface web → GET /v1/account pour confirmer le solde.
2. Choisissez un service : GET /v1/services et GET /v1/prices?service=tg.
3. Créez une commande : POST /v1/orders avec service + country.
4. Lisez data.phone et déclenchez l'envoi du SMS chez le fournisseur depuis votre client (par ex. collez le numéro dans l'inscription Telegram).
5. Interrogez GET /v1/orders/:id toutes les 3–5s. Lorsque status === "RECEIVED", lisez smsBody.
6. Si le SMS reçu n'est pas le bon ou si vous voulez un second code : POST /v1/orders/:id/next-sms → retour à WAITING.
7. Terminé. Si vous annulez avant l'arrivée d'un SMS : POST /v1/orders/:id/cancel pour un remboursement intégral.