Mwanzo wa haraka wa API ya wasanidi

API ya wasanidi ya SmsGrab inaipa programu yako nambari zilezile zilizo kwenye programu ya simu, kupitia REST API inayotumia JSON. Ni huduma ya kulipia yenye bei za wasanidi zake, inayolipwa kutoka kwenye salio lako la kawaida la SmsGrab, na inalindwa na marejesho yaleyale ya kiotomatiki.

Nani anaweza kuitumia

• Akaunti ya barua pepe yenye anwani iliyothibitishwa. Akaunti za wageni haziwezi kutengeneza funguo.
• Akaunti isiyowekewa vikwazo.

1. Tengeneza ufunguo wa API

Fungua Akaunti > Wasanidi kwenye tovuti, au Mipangilio > API ya wasanidi kwenye programu, na utengeneze ufunguo. Kwa usalama, unathibitisha kwa nenosiri lako, na kwa msimbo wa uthibitishaji wa hatua mbili kama umewashwa. Chagua wigo wa read kwa zana zinazosoma tu, au read na purchase ili kununua nambari.

Ufunguo unaanza na sgk_ na unaonyeshwa mara moja tu. Uhifadhi kwenye hifadhi ya siri ya seva yako. Tazama Funguo za API na usalama.

2. Uthibitishaji wa ombi

URL ya msingi ni https://smsgrab.com/api/dev/v1. Tuma ufunguo kama bearer token, au kwenye kichwa X-Api-Key:

GET /api/dev/v1/balance HTTP/1.1
Host: smsgrab.com
Authorization: Bearer sgk_your_key_here

Mahali pa ufunguo ni kwenye seva. Usiuweke kamwe kwenye tovuti, kiendelezi cha kivinjari au programu unayowapa watu wengine.

3. Angalia salio na bei

export SMSGRAB_KEY="sgk_your_key_here"

curl -s https://smsgrab.com/api/dev/v1/balance \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s "https://smsgrab.com/api/dev/v1/prices?service=whatsapp&country=indonesia" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Pesa huonyeshwa kila mara kwa kipimo kidogo zaidi cha USD, kwa hiyo 18 inamaanisha 0.18 USD. price_minor ni bei yako ya msanidi na retail_price_minor ni bei kwenye programu.

{ "currency": "USD", "markup_percent": 80,
  "items": [ { "service_id": "whatsapp", "country_id": "indonesia", "price_minor": 18,
               "retail_price_minor": 25, "available_numbers": 30412 } ] }

4. Nunua nambari

curl -s -X POST https://smsgrab.com/api/dev/v1/activations \
  -H "Authorization: Bearer $SMSGRAB_KEY" \
  -H "Idempotency-Key: order-7f3c2a" \
  -H "Content-Type: application/json" \
  -d '{"service":"whatsapp","country":"indonesia","max_price_minor":20}'

• service na country zinakubali vitambulisho vyetu, kama whatsapp na indonesia. Nchi pia inakubali misimbo ya ISO kama ID.
• max_price_minor inakulinda: bei ikipanda, hakuna kinachokatwa na unapata 409 PRICE_CHANGED.
• Idempotency-Key inafanya kurudia kuwe salama. Kurudia ombi kwa ufunguo uleule kunarudisha matokeo ya kwanza badala ya kununua mara mbili.

Jibu ni 201 Created pamoja na uanzishaji:

{ "id": "5c1d0c2e-8a41-4f7e-9d7a-2f1d9f1b8c11", "compat_id": 100000123, "status": "WAITING_SMS",
  "service_id": "whatsapp", "country_id": "indonesia", "phone_number": "+6281234567890",
  "price_minor": 18, "currency": "USD",
  "created_at": "2026-09-27T10:05:00.000Z", "expires_at": "2026-09-27T10:25:00.000Z",
  "refunded": false, "refund_minor": 0, "sms": [] }

5. Subiri SMS

Badala ya kuuliza tena na tena kwenye mzunguko wa haraka, iache API ishikilie ombi hadi sekunde 30 mpaka kitu kibadilike:

curl -s "https://smsgrab.com/api/dev/v1/activations/100000123?wait=25" \
  -H "Authorization: Bearer $SMSGRAB_KEY"

Ujumbe unapofika, status inabadilika kuwa CODE_RECEIVED na sms ina ujumbe wote hadi sasa:

{ "status": "CODE_RECEIVED",
  "sms": [ { "code": "482913", "text": "Your WhatsApp code is 482-913", "sender": "WhatsApp",
             "received_at": "2026-09-27T10:06:12.004Z" } ] }

Unapendelea kusukumiwa kuliko kuuliza? Weka webhook.

6. Maliza au ghairi

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/finish \
  -H "Authorization: Bearer $SMSGRAB_KEY"

curl -s -X POST https://smsgrab.com/api/dev/v1/activations/100000123/cancel \
  -H "Authorization: Bearer $SMSGRAB_KEY"

• finish baada ya kutumia msimbo. Inakubaliwa tu baada ya msimbo kufika.
• cancel wakati bado unasubiri msimbo wa kwanza. Bei yote inarejeshwa.
• Usipofanya chochote, nambari isiyo na msimbo inaisha muda baada ya dakika 20 na inarejeshewa pesa kiotomatiki.

Thamani za hali

Hitilafu

Kila hitilafu ina muundo uleule. Fanya kazi kulingana na code na reason, na upuuze sababu ambazo bado huzijui:

{ "code": "NO_NUMBERS_AVAILABLE", "message": "No numbers available for this service and country", "reason": "OUT_OF_STOCK" }

Hali za kawaida ni 402 INSUFFICIENT_BALANCE, 409 NO_NUMBERS_AVAILABLE, 409 PRICE_CHANGED, 422 yenye ACTIVATION_LIMIT_REACHED (hadi nambari 100 zinaweza kusubiri kwa wakati mmoja kwa kila akaunti), na 429 RATE_LIMITED yenye kichwa Retry-After.

Marejeo kamili yako kwenye nyaraka za wasanidi.