API-Dokumentation

Jede Anfrage muss deinen API-Schlüssel enthalten:

Authorization: Bearer jm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternative Header-Form: X-API-Key: jm_xxx…

Schlüssel unter /account/api-keys erstellen und widerrufen. Jeder Nutzer kann bis zu 10 aktive Schlüssel halten. Das vollständige Token wird nur einmal bei der Erstellung angezeigt — bewahre es sicher auf.

Alle Fehler geben JSON zurück:

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

Ratenbegrenzungen: Pro Schlüssel, gleitendes 60s-Fenster. Schreib-Endpunkte (orders, cancel, next-sms) 10 req/min; Lese-Endpunkte (account, services, prices, list) 60 req/min.

Aktuelles Guthaben und Basisprofil abrufen.

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"
}}

Dienste mit Bestand auflisten. Serverseitig ca. 5 Min. gecacht.

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 },
  ...
] }}

Verwende code (oder den lesbaren slug) als service-Feld beim Erstellen einer Bestellung.

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

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

id ist die numerische Länder-ID des Anbieters; slug ist der kurze SEO-Code (z. B. "my" / "us"). Beide Formen funktionieren als country-Feld.

Preis und Bestand pro Land für einen bestimmten Dienst. Die Preise enthalten bereits den von Operations konfigurierten Aufschlag/Rabatt.

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 },
    ...
  ]
}}

Erstellt eine SMS-Verifizierungsbestellung. Das System reserviert eine Telefonnummer beim Anbieter und zieht den berechneten Betrag von deinem Guthaben ab.

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"
}}

Außer service / country gibt es keine optionalen Felder.

Häufige Fehlercodes: INSUFFICIENT (Aufladung erforderlich), NO_NUMBERS, BAD_SERVICE, BAD_COUNTRY.

Pollen, bis status gleich RECEIVED ist und smsBody nicht null ist.

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",
  ...
}}

Status: WAITING (Nummer aktiv, wartet auf SMS) · RECEIVED (Code eingetroffen) · COMPLETED / FAILED / CANCELLED sind Endzustände.

Empfohlener Polling-Intervall: alle 3–5 Sekunden. Die Anbieter-Synchronisation läuft innerhalb dieses Endpunkts, sodass das Pollen den Zustand weiterbringt, selbst wenn der Hintergrund-Worker beschäftigt ist.

Storniere eine Bestellung, die noch keinen Code erhalten hat. Vollständige Rückerstattung auf dein Guthaben.

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

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

Abgelehnt mit CODE_RECEIVED, wenn die Nummer bereits eine SMS erhalten hat, oder ALREADY_CHANGED, wenn sich der Status gleichzeitig geändert hat.

Fordere nach RECEIVED den Anbieter auf, die Nummer aktiv zu halten und auf eine weitere SMS zu warten (keine zusätzlichen Gebühren innerhalb des aktiven Fensters).

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

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

Cursor-paginierte Liste deiner letzten Bestellungen.

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
}}

Optionale Query: status · limit 1–100 (Standard 20) · cursor = nextCursor der vorherigen Seite.

1. Über die Web-Oberfläche aufladen → GET /v1/account, um das Guthaben zu bestätigen.
2. Dienst auswählen: GET /v1/services und GET /v1/prices?service=tg.
3. Bestellung erstellen: POST /v1/orders mit service + country.
4. data.phone auslesen und die Anbieter-SMS von deinem Client aus auslösen (z. B. in die Telegram-Registrierung einfügen).
5. GET /v1/orders/:id alle 3–5s pollen. Wenn status === "RECEIVED", smsBody auslesen.
6. Bei falscher SMS oder wenn du einen zweiten Code möchtest: POST /v1/orders/:id/next-sms → zurück zu WAITING.
7. Fertig. Wenn du vor Eintreffen einer SMS stornierst: POST /v1/orders/:id/cancel für vollständige Rückerstattung.