Integrarea cu Calisero nu are nevoie de SDK, de configurări speciale sau de o perioadă de aprobare. Ai nevoie de un cont, de o cheie API și de un singur apel HTTP.
Generează cheia API
Intră în contul tău, secțiunea Chei API, și creează o cheie nouă. Cheia se afișează o singură dată, la creare — copiaz-o imediat într-un manager de secrete sau în variabilele de mediu ale aplicației tale. Nu o pune niciodată în codul versionat.
Recomandăm o cheie separată pentru fiecare mediu: una pentru producție, una pentru staging, una pentru dezvoltare locală. Dacă una dintre ele ajunge unde nu trebuie, o revoci fără să oprești restul sistemelor.
Trimite primul mesaj
Un singur POST către endpoint-ul de mesaje este suficient:
curl -X POST 'https://rest.calisero.ro/api/v1/messages' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer {token}' \
-d '{
"recipient": "+40712345678",
"body": "Comanda ta a fost expediata. AWB: 1234567890.",
"sender": "CALISERO"
}'
Răspunsul conține id-ul mesajului, statusul inițial și numărul de părți în care a fost împărțit. Păstrează id-ul: pe el îl folosești ca să interoghezi starea livrării sau ca să corelezi callback-urile.
Verifică formatul numărului
Cea mai frecventă eroare la prima integrare este formatul destinatarului. Calisero acceptă numere în format internațional E.164 — prefix de țară, fără spații, fără paranteze, fără zero inițial local. Pentru România: +40712345678, nu 0712345678.
Dacă lucrezi cu numere introduse de utilizatori, normalizează-le înainte de trimitere. O bibliotecă de parsare a numerelor de telefon îți economisește mult timp de depanare.
Numără caracterele înainte de trimitere
Un SMS standard are 160 de caractere în alfabet GSM-7. Dacă mesajul conține diacritice românești sau emoji, codificarea trece automat pe UCS-2 și limita scade la 70 de caractere per parte. Un mesaj de 200 de caractere cu diacritice se împarte în trei părți și se taxează ca trei mesaje.
Răspunsul API-ului îți spune exact în câte părți a fost împărțit mesajul, în câmpul parts. Verifică-l în teste, nu în factură.
Testează înainte de producție
Contul nou include 1 € credit de test. Trimite mesaje de test către propriul număr și verifică: textul ajunge întreg, diacriticele se afișează corect, expeditorul este cel așteptat.
De aici, pasul următor este să asculți evenimentele de livrare prin webhook, ca să știi nu doar că ai trimis, ci și că a ajuns.
