Înainte de trimitere
Trimiteți un SMS sau un MMS acceptat folosind un număr de expediere configurat pentru contul dvs. Aceasta este o operațiune în mediul de producție, care poate contacta destinatari și genera costuri. Trimiteți numai către destinatari autorizați și numai trafic aprobat; numerele și referința din exemplul de mai jos sunt fictive.
Contul dvs. necesită aprobarea pentru trimiterea de mesaje și permisiunile aplicabile expeditorului, țării și traficului. Datele de autentificare directe ale utilizatorilor personali/consumatorilor nu sunt eligibile pentru acest API. Datele de autentificare dedicate API-ului și aprobate au o procedură separată de stabilire a eligibilității; expeditorii mobili P2P pot necesita permisiuni suplimentare pentru P2P și SUA/Canada. Confirmați cu MultiTEL configurarea corectă a contului, fără a considera că datele de autentificare API reprezintă automat permisiunea de a trimite orice trafic.
Cererea de trimitere
Autentificați-vă prin HTTPS cu un cont API activat, de la adresa IP sursă permisă pentru acesta. Păstrați datele de autentificare într-un sistem de stocare a secretelor pe server. Folosiți POST cu câmpuri codificate ca formular sau un obiect JSON atunci când nu sunt furnizate câmpuri de formular ori parametri de interogare. Nu introduceți datele de autentificare sau textul mesajului într-un URL.
curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
--data-urlencode 'from=12025550123' \
--data-urlencode 'to=12025550124' \
--data-urlencode 'text=Your requested update is ready.' \
--data-urlencode 'reference=order-update-example' \
https://api.multitel.net/v3/sendsms| Câmp | Obligatoriu | Semnificație |
|---|---|---|
| from | Da | Numărul de expediere configurat pentru dvs., de preferință exprimat prin toate cifrele formatului internațional. |
| to | Da | O destinație, mai multe destinații separate prin virgulă sau un tablou JSON. Folosiți de preferință toate cifrele formatului internațional. O cerere de grup poate fi respinsă din cauza limitelor P2P sau de țară aplicabile; acesta nu este un API de trimitere în masă fără restricții. |
| text | Pentru SMS | Textul mesajului în UTF-8. Este necesar cel puțin un text nevid sau conținut media. Trimiteți caracterele și întreruperile de rând efective, în loc de HTML sau text codificat cu secvențe procentuale. Unele fluxuri ale operatorilor normalizează șirurile care conțin secvențe de escape literale. |
| media | Pentru MMS doar cu conținut media | Conținutul media codificat în Base64, nu un URL sau o cale către un fișier. Disponibilitatea, formatul și dimensiunea MMS-urilor depind de ruta configurată. Confirmați cu MultiTEL tipurile de conținut media acceptate; această componentă de procesare nu stabilește o limită universală pentru dimensiunea conținutului media. |
| reference | Recomandat | Eticheta dvs. de corelare, păstrată în înregistrări și notificări de tip callback. Includeți o astfel de etichetă pentru depanare. Aceasta nu este o cheie de idempotență. |
| notifyurl | Nu | Punctul dvs. de recepție HTTPS pentru notificări de tip callback. Componenta de procesare poate trimite prin POST un rezultat inițial după procesare. Acesta trebuie să fie un punct de recepție pe care îl controlați și nu trebuie să fie URL-ul unui serviciu intern. |
Pentru un tablou JSON, folosiți un tablou propriu-zis în to; nu introduceți un șir care reprezintă un tablou JSON într-un câmp de formular. Folosiți trimiterea către un singur destinatar ca test inițial de integrare. Compatibilitatea cu grupurile și MMS-urile diferă în funcție de rută, așa că verificați combinația acceptată înainte de a le utiliza.
Citiți rezultatul complet
Sunt prezentate doar câteva câmpuri cu titlu ilustrativ; costul afișat nu reprezintă o ofertă de preț.
{
"status": {
"code": "200",
"msg": ""
},
"response": {
"sms_log_id_ori": 42,
"to": "12025550124",
"from": "12025550123",
"status": "Success",
"message": "Message queued",
"causecode": 0,
"uniqueid": "fixture-message",
"cost": "$0.0120",
"carrier_fee_usd": "0.0020000000",
"chars": 31,
"parts": 1,
"encoding": "GSM-7",
"permsg": "$0.0120",
"pid": "fixture-reference"
}
}Verificați împreună starea HTTP, status.code din JSON și câmpurile status/message din răspuns. Codurile de rezultat pot fi șiruri de caractere. Păstrați sms_log_id_ori și valorile returnate pentru mesaj și referință, pentru corelarea de către asistență. Valorile uniqueid și pid din sistemul vechi variază în funcție de rută; nu deduceți formatul lor și nu presupuneți că sunt tokenuri de idempotență ale clientului.
Success sau Message queued descrie în mod normal acceptarea de către ruta selectată, nu primirea pe telefonul unei persoane. O stare inițială dintr-o notificare de tip callback, precum sent, nu confirmă singură livrarea finală.
Segmente și costuri
Folosiți analiza lungimii SMS-ului pentru întregul text final înainte de trimitere. Prețurile SMS-urilor depind de destinație și de serviciul contului; taxele aplicabile ale operatorilor se adaugă pentru fiecare segment. Fluxul de trimitere însumează prețurile pentru destinatari și taxele aplicabile, apoi înmulțește suma cu numărul calculat de segmente SMS. Pentru acest calcul, o cerere MMS este tratată ca un singur mesaj.
cost și permsg sunt șiruri de caractere formatate ca valori monetare în răspunsul din sistemul vechi. carrier_fee_usd indică partea aferentă taxelor operatorului în USD și este deja inclusă în totalul calculat al trimiterii; nu o adăugați a doua oară. Prețurile efective și disponibilitatea rutelor trebuie verificate pentru contul dvs. Cererea nu este o operațiune destinată exclusiv aflării prețului.
Codul analizat debitează contul după parcurgerea cu succes a fluxului de trimitere prin operator, dar acceptarea de către operator, salvarea persistentă locală și facturarea nu constituie o singură tranzacție. O eroare sau o expirare a timpului de așteptare poate apărea după acceptarea unei cereri de către sistemul din amonte. Nu este expusă nicio cheie de idempotență pentru client: repetarea aceleiași referințe poate duce la o nouă trimitere și o nouă taxare.
Livrare locală și rezultate mixte
Numerele găzduite local pot fi acceptate, cu starea accepted, în fluxul MultiTEL de mesaje primite, fără trimitere printr-un operator extern. Pentru o cerere cu destinatari exclusiv locali, răspunsul poate include accepted, message_id, provider și delivery_status. Acceptarea locală nu garantează că destinația de redirecționare configurată de destinatar a funcționat.
Examinați local_delivery_results și partial atunci când sunt prezente. Pentru un destinatar se poate afișa accepted cu valoarea true, deși rezultatul redirecționării sale indică un eșec. O cerere mixtă poate avea destinatari acceptați de operator, cu starea accepted, și o parte locală eșuată. Nu reîncercați automat întregul lot: reconciliați mai întâi rezultatul fiecărui destinatar.
În acest flux, acceptarea unei cereri cu destinatari exclusiv locali raportează un cost de trimitere zero, însă destinatarii pot suporta în continuare taxele obișnuite pentru mesajele primite. Nu interpretați un cost de trimitere zero ca pe o garanție că niciun cont nu este taxat.
Notificări de tip callback și corelare
Când este furnizat notifyurl, notificarea inițială de tip callback are o structură de încadrare status și câmpuri de răspuns care includ message_id, reference, from, to, status, status_text, error_code, timestamp și accepted. Pot fi prezente și rezultate locale. Stocați informațiile de corelare fără a înregistra în jurnale datele de autentificare API sau conținutul mesajelor care nu este necesar.
Această componentă de procesare nu adaugă un câmp de semnătură la notificarea inițială de tip callback. Nu folosiți o notificare de tip callback neverificată drept unică autorizare pentru o altă acțiune. Consultați configurația de integrare/webhook acceptată pentru contul dvs. și reconciliați rezultatele incerte cu înregistrările din portal sau cu ajutorul asistenței. Nu presupuneți că notificările de tip callback sosesc o singură dată sau în ordinea livrării finale.
Erori și recuperare în siguranță
Erorile de validare pot folosi codul API 403. Refuzurile legate de aprobarea contului, de P2P și de politicile de țară pot, de asemenea, seta HTTP 403 și include un response.code prelucrabil automat. Limitările ratei cererilor pot folosi 429 împreună cu informații pentru reîncercare. O politică indisponibilă sau o eroare de trimitere ori de salvare persistentă locală poate folosi 503 sau 500; și soldul insuficient în sistemul vechi poate genera 500.
Pentru 429, respectați Retry-After și orice valoare response.retry_after. În cazul unui refuz legat de cont, expeditor, țară sau destinatar, remediați cauza înainte de a reîncerca. În cazul expirării timpului de așteptare sau al unui rezultat de trimitere neclar, păstrați ora cererii, referința și identificatorii returnați, verificați portalul și contactați asistența înainte de a retrimite. Simpla absență a unei înregistrări în jurnal nu dovedește că niciun operator nu a acceptat cererea.