Para dërgimit
Dërgoni një SMS ose një MMS të mbështetur duke përdorur një numër dërgues të konfiguruar për llogarinë tuaj. Ky është një veprim në mjedisin e prodhimit që mund të kontaktojë marrësit dhe të shkaktojë tarifime. Përdorni vetëm marrës të autorizuar dhe trafik të miratuar; numrat dhe referenca në shembullin më poshtë janë të sajuar.
Llogaria juaj ka nevojë për miratim për dërgimin e mesazheve dalëse dhe për lejet përkatëse për dërguesin, shtetin dhe trafikun. Kredencialet e drejtpërdrejta të përdoruesve Personalë/Konsumatorë nuk kualifikohen për këtë API. Kredencialet e dedikuara të API-së, të miratuara, kanë një procedurë të veçantë kualifikimi; dërguesit celularë P2P mund të kërkojnë leje shtesë për P2P dhe SHBA/Kanada. Konfirmoni me MultiTEL konfigurimin e duhur të llogarisë, në vend që ta trajtoni një kredencial të API-së si leje automatike për të dërguar çfarëdo trafiku.
Kërkesa për dërgim
Autentikohuni përmes HTTPS me një llogari API të aktivizuar, nga adresa IP burimore e lejuar për të. Ruajini kredencialet në një depo sekretesh në anën e serverit. Përdorni POST me fusha të koduara si formular, ose një objekt JSON kur nuk jepen fusha formulari apo parametra të vargut të kërkimit. Mos vendosni kredenciale ose tekst mesazhi në një 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| Fusha | E detyrueshme | Kuptimi |
|---|---|---|
| from | Po | Numri juaj dërgues i konfiguruar, mundësisht me të gjitha shifrat e formatit ndërkombëtar. |
| to | Po | Një destinacion, destinacione të ndara me presje ose një varg JSON. Preferoni të gjitha shifrat e formatit ndërkombëtar. Një kërkesë në grup mund të refuzohet për shkak të kufizimeve përkatëse P2P/të shtetit; kjo nuk është një API për dërgime masive pa kufizime. |
| text | Për SMS | Teksti i mesazhit në UTF-8. Kërkohet të paktën tekst jo i zbrazët ose përmbajtje multimediale. Dërgoni karaktere reale dhe ndarje rreshtash, në vend të HTML-së ose tekstit të koduar me shenja përqindjeje. Disa rrugë të operatorëve normalizojnë vargjet që përmbajnë sekuenca escape të shkruara fjalë për fjalë. |
| media | Për MMS vetëm me përmbajtje multimediale | Përmbajtja multimediale e koduar në Base64, jo një URL apo shteg skedari. Disponueshmëria, formati dhe madhësia e MMS-ve varen nga rruga e konfiguruar. Konfirmoni me MultiTEL përmbajtjet multimediale të mbështetura; ky përpunues nuk përcakton një kufi universal për madhësinë e tyre. |
| reference | E rekomanduar | Etiketa juaj për lidhjen e të dhënave përkatëse, e cila ruhet në regjistra/thirrje kthyese. Përfshini një të tillë për diagnostikimin e problemeve. Ajo nuk është çelës idempotence. |
| notifyurl | Jo | Marrësi juaj HTTPS i thirrjeve kthyese. Përpunuesi mund të dërgojë me POST një rezultat fillestar pas përpunimit. Ai duhet të jetë një marrës që e kontrolloni ju dhe nuk duhet të jetë URL e një shërbimi të brendshëm. |
Për një varg JSON, përdorni një varg të mirëfilltë në to; mos vendosni një varg JSON të paraqitur si tekst brenda një fushe formulari. Përdorni dërgimin te një marrës i vetëm si testin fillestar të integrimit. Mbështetja për grupet dhe MMS ndryshon sipas rrugës, ndaj konfirmoni kombinimin e mbështetur përpara se t'i përdorni.
Lexoni rezultatin e plotë
Paraqiten vetëm disa fusha të përzgjedhura për ilustrim; kostoja e shfaqur nuk është ofertë çmimi.
{
"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"
}
}Kontrolloni së bashku statusin HTTP, status.code në JSON dhe status/message të përgjigjes. Kodet e rezultateve mund të jenë vargje teksti. Ruani sms_log_id_ori dhe vlerat e kthyera të mesazhit/referencës për të lidhur të dhënat përkatëse gjatë asistencës. Vlerat e trashëguara uniqueid dhe pid ndryshojnë sipas rrugës; mos nxirrni përfundime për formatin e tyre dhe mos supozoni se janë tokena idempotence të klientit.
Success ose Message queued zakonisht përshkruan pranimin nga rruga e përzgjedhur, jo marrjen në telefonin e personit. Një status fillestar i thirrjes kthyese, si sent, nuk vërteton më vete dorëzimin përfundimtar.
Segmentet dhe tarifimet
Përdorni Analizën e gjatësisë së SMS-së mbi tekstin përfundimtar të plotë përpara dërgimit. Çmimet e SMS-ve varen nga destinacioni dhe shërbimi i llogarisë; tarifat përkatëse të operatorit shtohen për çdo segment. Rrjedha e dërgimit bashkon çmimet për marrësit dhe tarifat përkatëse, pastaj i shumëzon me numrin e llogaritur të segmenteve SMS. Për këtë llogaritje, një kërkesë MMS trajtohet si një mesazh.
cost dhe permsg janë vargje teksti të formatuara si shuma monetare në përgjigjen e trashëguar. carrier_fee_usd raporton pjesën e tarifës së operatorit në USD dhe është tashmë e përfshirë në totalin e llogaritur të dërgimit; mos e shtoni për herë të dytë. Çmimet reale dhe disponueshmëria e rrugëve duhen kontrolluar për llogarinë tuaj. Kërkesa nuk është një veprim vetëm për marrjen e çmimit.
Kodi i shqyrtuar debiton llogarinë pasi rrjedha e tij e dërgimit përmes operatorit përfundon me sukses, por pranimi nga operatori, ruajtja lokale dhe faturimi nuk përbëjnë një transaksion të vetëm. Një gabim ose tejkalim i kohës së pritjes mund të ndodhë pasi një kërkesë është pranuar nga shërbimi i sipërm. Nuk ofrohet asnjë çelës idempotence për klientin: përsëritja e së njëjtës referencë mund të shkaktojë dërgim dhe tarifim përsëri.
Dorëzimi lokal dhe rezultatet e përziera
Numrat e strehuar lokalisht mund të pranohen (accepted) në rrjedhën e mesazheve hyrëse të MultiTEL pa dërgim përmes një operatori të jashtëm. Për një kërkesë me të gjithë marrësit lokalë, përgjigjja mund të përfshijë accepted, message_id, provider dhe delivery_status. Pranimi lokal nuk garanton se destinacioni i përcjelljes i konfiguruar nga marrësi ka funksionuar.
Shqyrtoni local_delivery_results dhe partial kur janë të pranishme. Një marrës mund të shfaqë accepted true, ndërkohë që rezultati i përcjelljes së tij është i pasuksesshëm. Një kërkesë e përzier mund të ketë marrës të pranuar (accepted) nga operatori dhe një pjesë lokale të dështuar. Mos e riprovoni automatikisht të gjithë grupin: rakordoni fillimisht rezultatin për çdo marrës.
Pranimi i një kërkese me të gjithë marrësit lokalë raporton kosto dalëse zero në këtë rrjedhë, ndërkohë që marrësve mund t'u zbatohen ende tarifat e tyre të zakonshme për mesazhet hyrëse. Mos e interpretoni koston dalëse zero si garanci se nuk tarifohet asnjë llogari.
Thirrjet kthyese dhe lidhja e të dhënave përkatëse
Kur jepet notifyurl, thirrja kthyese fillestare ka një strukturë mbështjellëse status dhe fusha përgjigjeje që përfshijnë message_id, reference, from, to, status, status_text, error_code, timestamp dhe accepted. Mund të jenë të pranishme edhe rezultate lokale. Ruani informacionin për lidhjen e të dhënave përkatëse pa regjistruar në log kredencialet e API-së ose përmbajtje të panevojshme të mesazheve.
Ky përpunues nuk shton një fushë nënshkrimi në atë thirrje kthyese fillestare. Mos përdorni një thirrje kthyese të paverifikuar si autorizim të vetëm për një veprim tjetër. Konsultoni konfigurimin e mbështetur të integrimit/webhook-ut për llogarinë tuaj dhe rakordoni rezultatet e pasigurta me regjistrat e portalit ose me asistencën. Mos supozoni se thirrjet kthyese mbërrijnë vetëm një herë ose sipas rendit të dorëzimit përfundimtar.
Dështimet dhe rikuperimi i sigurt
Dështimet e validimit mund të përdorin kodin API 403. Refuzimet lidhur me miratimin e llogarisë, P2P dhe politikat e shtetit mund të vendosin gjithashtu HTTP 403 dhe të përfshijnë një response.code të lexueshëm nga makina. Kufizimet e shpeshtësisë së kërkesave mund të përdorin 429 me informacion për riprovimin. Një politikë e padisponueshme ose një dështim i dërgimit apo i ruajtjes lokale mund të përdorë 503 ose 500; edhe gjendja e pamjaftueshme e llogarisë në sjelljen e trashëguar mund të kthejë 500.
Për 429, respektoni Retry-After dhe çdo vlerë të response.retry_after. Në rast refuzimi për shkak të llogarisë, dërguesit, shtetit ose marrësit, korrigjoni shkakun përpara se të riprovoni. Në rast tejkalimi të kohës së pritjes ose rezultati të paqartë të dërgimit, ruani kohën e kërkesës, referencën dhe identifikuesit e kthyer, shqyrtoni portalin dhe kontaktoni asistencën përpara se të ridërgoni. Vetëm mungesa e një hyrjeje në log nuk është provë se asnjë operator nuk e ka pranuar kërkesën.