Tuma SMS kutoka kwenye mfumo wako

Ombi moja la HTTP linatuma ujumbe. Litumie kwa OTP, uthibitisho wa malipo, taarifa za oda — chochote ambacho programu yako inahitaji kumjulisha mteja.

Anza haraka

Anza kutumia kwa hatua tatu

  1. 1
    Fungua akaunti
    na upate Sender ID iliyoidhinishwa.
  2. 2
    Tengeneza API key
    kwenye Dashibodi → API Keys. Itunze kwenye seva yako pekee.
  3. 3
    Tuma SMS yako ya kwanza
    kwa kutumia ombi lililo upande wa kulia.
Pata API key yako
curl -X POST https://pigasms.com/api/v1/send \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sender": "ZAWADI",
    "to": ["+255712345678", "+255754111222"],
    "message": "Habari! Order yako imefika."
  }'
Marejeleo

Endpoints

URL ya msingi ni https://pigasms.com/api/v1. Tuma JSON pamoja na header Authorization: Bearer YOUR_API_KEY.

MbinuEndpointMaelezo
POST /send Tuma SMS kwa namba moja au nyingi
GET /messages/{id} Pata ujumbe mmoja na hali yake
GET /campaigns/{id} Pata utumaji mmoja: ngapi zimetumwa, zimeshindikana au bado zinasubiri
GET /balance Angalia salio lako lililobaki
GET /senderids Orodha ya Sender ID zako na hali zake

to inapokea namba moja au orodha ya hadi 10,000. Si lazima: schedule_at kutuma baadaye, reference (ID yako mwenyewe, inarudishwa kwenye webhooks) na header ya Idempotency-Key, ili ombi ambalo mfumo wako unalirudia lisitumwe mara mbili.

Jibu

Unachopokea

Kila mpokeaji anapata ID yake ya ujumbe ili uweze kufuatilia kila ujumbe peke yake.

201 Created — POST /send
{
  "campaign_id": 1024,
  "status": "sending",
  "test": false,
  "reference": "order-1001",
  "recipients": 2,
  "credits_used": 2,
  "balance": 18448,
  "scheduled_at": null,
  "opted_out": 0,
  "invalid": [],
  "messages": [
    { "id": 99201, "to": "+255712345678", "status": "sent", "parts": 1, "network": "Yas" },
    { "id": 99202, "to": "+255754111222", "status": "queued", "parts": 1, "network": "Vodacom" }
  ]
}
Webhooks

Taarifa za hali zinakufikia zenyewe

Weka webhook URL kwenye dashibodi yako. Ujumbe uliotuma kupitia API unapopokelewa na mtandao au unaposhindikana, tunatuma POST iliyosainiwa kama hii:

POST https://your-site.co.tz/sms-callback
PigaSMS-Signature: t=1795267500,v1=5f2c9a…
{
  "id": "evt_8ea66a2ee7c976bae8f0d4b5",
  "event": "message.sent",
  "created": "2026-11-21T14:25:03+03:00",
  "test": false,
  "data": {
    "id": 99201,
    "campaign_id": 1024,
    "to": "+255712345678",
    "sender": "ZAWADI",
    "status": "sent",
    "parts": 1,
    "network": "Yas",
    "test": false,
    "reference": "order-1001",
    "delivery": null,
    "error": null,
    "created_at": "2026-11-21T14:25:02+03:00",
    "sent_at": "2026-11-21T14:25:03+03:00"
  }
}

Matukio: message.sent (umepokelewa na mtandao), message.failed, na baadaye message.delivered au message.undelivered mtandao wa simu unaporipoti kama umefika kwenye simu (delivery ndani ya data). Kwenye sandbox kila ujumbe uliotumwa unafika papo hapo.

Jibu kwa HTTP 200. Usipojibu hivyo, tunajaribu tena baada ya dakika 1, dakika 5, dakika 30 na hadi saa 24. Hakiki header ya PigaSMS-Signature kwa siri ya webhook yako: dashibodi inaonyesha jinsi ya kufanya.

Makosa

Misimbo ya makosa

Makosa hurudisha JSON yenye code kwa ajili ya programu yako na message inayoeleza tatizo lilikuwa nini.

MsimboMaana
400
Ombi si sahihi
Maudhui ya ombi si JSON sahihi.
401
Hujaidhinishwa
API key haipo, si sahihi au imefutwa.
402
Salio halitoshi
Ongeza salio lako kisha ujaribu tena.
403
Hairuhusiwi
Ombi limetoka kwenye anwani ambayo key hairuhusu, au akaunti imesimamishwa.
404
Haipatikani
Hakuna endpoint, ujumbe au kampeni hiyo kwenye akaunti yako.
422
Uhakiki umeshindikana
Mfano: Sender ID haijaidhinishwa, namba ya simu si sahihi au ujumbe hauna maandishi.
429
Maombi mengi mno
Punguza kasi — jaribu tena baada ya muda ulioonyeshwa kwenye header ya Retry-After.

Hali ya sandbox

Tumia key ya majaribio (ps_test_…) kujaribu kila endpoint bila kutuma SMS halisi wala kutumia salio. Ujumbe kwenda 255700000001 hushindikana kila mara, ili uweze kujaribu pia jinsi mfumo wako unavyoshughulikia kushindikana.

Usalama

HTTPS pekee. Tunza key kwenye seva yako, tengeneza moja kwa kila mfumo, ifute yoyote papo hapo kupitia dashibodi, na ruhusu kila key kutumika kutoka IP za seva yako tu.

Viwango vya kasi

Maombi 120 kwa dakika kwa kila key, kila ombi likiwa na hadi namba 10,000. Unahitaji zaidi? Ongea nasi.

Jenga ukitumia PigaSMS

Fungua akaunti bure upate sandbox key na API key halisi.