Пре слања
Пошаљите SMS или подржану MMS поруку користећи број за слање подешен за ваш налог. Ово је операција у продукционом окружењу која може контактирати примаоце и створити трошкове. Шаљите само примаоцима за које имате овлашћење и само одобрене врсте саобраћаја; бројеви и референца у примеру испод су измишљени.
Вашем налогу су потребни одобрење за слање одлазних порука и одговарајуће дозволе за пошиљаоца, земљу и врсту саобраћаја. Директни кориснички акредитиви за личне/потрошачке налоге не испуњавају услове за овај API. Одобрени наменски API акредитиви имају засебан поступак утврђивања подобности; за мобилне P2P пошиљаоце могу бити потребне додатне дозволе за P2P и САД/Канаду. Проверите са MultiTEL-ом да ли је налог правилно подешен, уместо да API акредитив сматрате аутоматском дозволом за слање било које врсте саобраћаја.
Захтев за слање
Аутентификујте се преко HTTPS-а помоћу омогућеног API налога, са његове дозвољене изворне IP адресе. Чувајте акредитиве у складишту тајни на серверу. Користите POST са пољима кодираним као образац, или JSON објекат када нису наведена поља обрасца нити параметри упита. Не стављајте акредитиве ни текст поруке у 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| Поље | Обавезно | Значење |
|---|---|---|
| from | Да | Ваш подешени број за слање, пожељно наведен свим цифрама у међународном формату. |
| to | Да | Једно одредиште, одредишта раздвојена зарезима или JSON низ. Пожељно је навести све цифре у међународном формату. Групни захтев може бити одбијен због применљивих P2P ограничења или ограничења за земљу; ово није API за неограничено масовно слање. |
| text | За SMS | Текст поруке у UTF-8 кодирању. Потребан је бар непразан текст или медијски садржај. Шаљите стварне знакове и преломе редова уместо HTML-а или текста кодираног процентним секвенцама. Неке путање преко оператера нормализују дословно наведене escape секвенце. |
| media | За MMS само са медијским садржајем | Медијски садржај кодиран у Base64 формату, а не URL или путања до датотеке. Доступност MMS-а, формат и величина зависе од подешене руте. Проверите са MultiTEL-ом који медијски садржаји су подржани; овај обрађивач не утврђује универзално ограничење величине медијског садржаја. |
| reference | Препоручено | Ваша ознака за повезивање података, која се чува у евиденцији и повратним позивима. Наведите је ради решавања проблема. Она није кључ идемпотентности. |
| notifyurl | Не | Ваш HTTPS пријемник повратних позива. Обрађивач може да пошаље почетни резултат методом POST након обраде. Пријемник мора бити под вашом контролом и не сме бити URL интерног сервиса. |
За JSON низ користите стварни низ у пољу to; не стављајте текстуални запис JSON низа у поље обрасца. За почетни тест интеграције користите слање једном примаоцу. Подршка за групно слање и MMS разликује се у зависности од руте, па пре употребе проверите која комбинација је подржана.
Прочитајте цео резултат
Приказана су само одабрана поља ради илустрације; приказани трошак није понуда цене.
{
"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"
}
}Заједно проверите HTTP статус, JSON поље status.code и поља status/message у одговору. Кодови резултата могу бити ниске. Сачувајте sms_log_id_ori и враћене вредности поруке и референце ради повезивања података при обраћању подршци. Вредности uniqueid и pid из старијег система разликују се у зависности од руте; немојте изводити закључке о њиховом формату нити претпостављати да су то клијентски токени идемпотентности.
Success или Message queued обично означава прихватање на изабраној рути, а не пријем на телефону примаоца. Почетни статус повратног позива као што је sent сам по себи не потврђује коначну испоруку.
Сегменти и трошкови
Користите анализу дужине SMS поруке на целом коначном тексту пре слања. Цене SMS порука зависе од одредишта и услуге на налогу; применљиве накнаде оператера додају се по сегменту. Поступак слања сабира цене за примаоце и применљиве накнаде, а затим тај збир множи израчунатим бројем SMS сегмената. За овај обрачун MMS захтев се третира као једна порука.
cost и permsg су форматиране ниске са новчаним износима у одговору старијег система. carrier_fee_usd приказује део износа који се односи на накнаду оператера у валути USD и већ је укључен у израчунати укупан трошак слања; немојте га додавати други пут. За свој налог морате проверити стварне цене и доступност рута. Овај захтев није операција само за проверу цене.
Прегледани код задужује налог након успешног проласка кроз поступак слања преко оператера, али прихватање код оператера, локално трајно чување и наплата нису једна трансакција. Грешка или истек времена чекања могу настати након што је узводни сервис прихватио захтев. Клијентски кључ идемпотентности није доступан: понављање исте референце може довести до поновног слања и наплате.
Локална испорука и мешовити резултати
Бројеви који се хостују локално могу бити прихваћени (accepted) у MultiTEL-ов ток долазних порука без слања преко спољног оператера. За захтев у коме су сви примаоци локални, одговор може садржати accepted, message_id, provider и delivery_status. Локално прихватање не гарантује да је подешено одредиште прослеђивања примаоца радило.
Прегледајте local_delivery_results и partial када су присутни. За примаоца може бити приказано accepted true иако је резултат прослеђивања неуспешан. Мешовити захтев може имати примаоце прихваћене код оператера (accepted) и неуспешан локални део. Немојте аутоматски поновити целу групу: прво усагласите резултате за сваког примаоца.
Када су сви примаоци локални, прихватање у овом поступку пријављује нулти трошак одлазног слања, док примаоцима и даље могу бити наплаћене уобичајене накнаде за долазне поруке. Нулти трошак одлазног слања не тумачите као гаранцију да ниједан налог није задужен.
Повратни позиви и повезивање података
Када је наведен notifyurl, почетни повратни позив садржи омотач status и поља одговора која укључују message_id, reference, from, to, status, status_text, error_code, timestamp и accepted. Могу бити присутни и локални резултати. Чувајте податке за повезивање без бележења API акредитива или непотребног садржаја порука у дневнике.
Овај обрађивач не додаје поље за потписивање у тај почетни повратни позив. Не користите непроверен повратни позив као самостално овлашћење за другу радњу. Проверите подржана подешавања интеграције и веб-хука за свој налог и усагласите неизвесне резултате са евиденцијом на порталу или уз помоћ подршке. Не претпостављајте да повратни позиви стижу само једном или редоследом коначне испоруке.
Неуспеси и безбедан опоравак
Грешке валидације могу користити API код 403. Одбијања због одобрења налога, P2P правила и правила за земљу такође могу поставити HTTP 403 и укључити машински читљив response.code. Ограничења учесталости захтева могу користити 429 са информацијама о поновном покушају. Недоступност правила или неуспех слања или локалног трајног чувања могу користити 503 или 500; недовољно стање у старијем систему такође може вратити 500.
За 429 поштујте Retry-After и сваку наведену вредност response.retry_after. У случају одбијања због налога, пошиљаоца, земље или примаоца, отклоните узрок пре поновног покушаја. Ако истекне време чекања или је резултат слања нејасан, сачувајте време захтева, референцу и враћене идентификаторе, проверите портал и обратите се подршци пре поновног слања. Само одсуство записа у дневнику није доказ да ниједан оператер није прихватио захтев.