Documentație API

Tot ce trebuie pentru prima integrare

Autentificare

Fiecare cerere are nevoie de o cheie de API, generată din contul tău. Cheia se trimite în antetul Authorization, ca token de tip Bearer:

Authorization: Bearer sk_live_xxxxxxxxxxxxxxxx

Cheile sunt legate de contul tău și pot fi revocate oricând, fără să afecteze celelalte integrări. O cheie revocată primește 401 Unauthorized la următoarea cerere.

Nu publica niciodată cheia în cod client, în aplicații mobile sau într-un repository. Dacă o cheie a fost expusă, revoc-o și generează alta.

Toate cererile se fac prin HTTPS către https://sms.afk.ro. Cererile pe HTTP sunt refuzate.

Expeditor

Mesajele pleacă de la codul scurt numeric 23576, comun tuturor conturilor. Destinatarul vede acest număr ca expeditor.

Un cod scurt numeric poate primi răspunsuri, spre deosebire de un expeditor alfanumeric. Asta face posibilă dezabonarea prin STOP, descrisă mai jos.

Expeditorii personalizați per client sunt o funcționalitate viitoare; până atunci recomandăm ca numele firmei să apară în primele cuvinte ale mesajului.

Segmente și costuri

Un SMS nu transportă text liber, ci text codat într-unul din două alfabete, iar alfabetul decide câte caractere încap într-un segment. Fiecare segment consumă un credit.

GSM-7, alfabetul standard: 160 de caractere pe segment, sau 153 când mesajul se împarte în mai multe segmente.
UCS-2, folosit când apare orice caracter din afara GSM-7: 70 de caractere pe segment, sau 67 la mesaje concatenate.

Diacriticele românești (ă, â, î, ș, ț) nu fac parte din GSM-7. Este suficient unul singur, oriunde în text, ca întregul mesaj să treacă pe UCS-2 și limita să scadă de la 160 la 70.

Răspunsul la trimitere include câmpurile segments și encoding, ca să știi exact ce ai plătit. Poți activa eliminarea automată a diacriticelor din setările contului.

Dezabonare (STOP)

Un destinatar care răspunde STOP intră automat în registrul de dezabonare al contului tău și este exclus definitiv din trimiterile viitoare.

O cerere către un număr dezabonat nu eșuează: este acceptată și înregistrată cu starea BLOCKED_OPTOUT, fără să consume credit. Verifică starea în rapoarte dacă un mesaj nu ajunge.

Dezabonarea este per cont: un contact care s-a dezabonat de la tine poate primi în continuare mesaje de la alt client al platformei, dacă și-a dat acordul acolo.

Erori

Erorile folosesc codurile HTTP standard, iar corpul răspunsului conține întotdeauna un câmp error cu un cod stabil și un câmp message lizibil.

400 cerere invalidă: lipsește un câmp obligatoriu sau numărul nu este într-un format valid.
401 cheie lipsă, invalidă sau revocată.
402 credite insuficiente pentru numărul de segmente cerut.
409 idempotencyKey deja folosit cu un alt conținut.
429 prea multe cereri; reia după intervalul din antetul Retry-After.
5xx eroare de platformă; reluarea cu același idempotencyKey este sigură.

Referință endpoint-uri

Fiecare apel are nevoie de antetul de autentificare descris mai sus.

POSThttps://sms.afk.ro/api/v1/messagesTrimite un mesaj

Acceptă mesajul și îl pune în coadă. Răspunsul confirmă preluarea, nu livrarea: starea finală vine prin webhook sau prin interogarea mesajului.

Câmp	Tip	Obligatoriu	Descriere
to	string	Da	Numărul destinatarului, format internațional (+407xxxxxxxx).
text	string	Da	Conținutul mesajului.
scheduledFor	string (ISO 8601)	Nu	Momentul trimiterii. Absent înseamnă imediat.
idempotencyKey	string	Nu	Cheie unică proprie. Repetarea aceleiași cereri nu trimite mesajul de două ori.
stripDiacritics	boolean	Nu	Elimină diacriticele înainte de trimitere, pentru a rămâne pe GSM-7. Implicit ia valoarea din setările contului.

curl -X POST https://sms.afk.ro/api/v1/messages \
  -H "Authorization: Bearer $SMS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+40770000000",
    "text": "Va reamintim programarea de maine, ora 10:30.",
    "idempotencyKey": "appt-8123-reminder"
  }'

Răspuns

{
  "id": "cmsx1a2b3c4d5e6f",
  "status": "PENDING",
  "to": "+40770000000",
  "segments": 1,
  "encoding": "GSM",
  "scheduledFor": "2026-08-05T09:00:00.000Z",
  "createdAt": "2026-08-05T08:59:41.220Z"
}

GEThttps://sms.afk.ro/api/v1/messages/{id}Verifică starea unui mesaj

Returnează starea curentă și, pentru mesajele eșuate, motivul raportat de operator.

Câmp	Tip	Obligatoriu	Descriere
id	string	Da	Identificatorul primit la trimitere, în calea cererii.

curl https://sms.afk.ro/api/v1/messages/cmsx1a2b3c4d5e6f \
  -H "Authorization: Bearer $SMS_API_KEY"

Răspuns

{
  "id": "cmsx1a2b3c4d5e6f",
  "status": "DELIVERED",
  "segments": 1,
  "encoding": "GSM",
  "sentAt": "2026-08-05T09:00:01.004Z",
  "deliveredAt": "2026-08-05T09:00:03.771Z",
  "errorCode": null,
  "errorMessage": null
}

POSThttps://aplicatia-ta.ro/webhooks/smsRaport de livrare (webhook)

Endpoint-ul este al tău, configurat în cont. Îl apelăm la fiecare schimbare de stare. Răspunde cu 2xx pentru a confirma primirea; orice altceva declanșează reîncercări cu interval crescător timp de 24 de ore.

Câmp	Tip	Obligatoriu	Descriere
id	string	Da	Identificatorul mesajului.
status	string	Da	SENT, DELIVERED, FAILED sau una dintre stările BLOCKED_*.
errorCode	string \| null	Nu	Codul raportat de operator, când starea este FAILED.
occurredAt	string (ISO 8601)	Da	Momentul schimbării de stare.
signature	string	Da	HMAC-SHA256 al corpului, cu secretul din contul tău. Verifică-l înainte de a avea încredere în cerere.

{
  "id": "cmsx1a2b3c4d5e6f",
  "status": "DELIVERED",
  "errorCode": null,
  "occurredAt": "2026-08-05T09:00:03.771Z",
  "signature": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b"
}