HTTP GET/POST API

SMS Gateway HTTP GET/POST rozhraní je určeno pro jednoduchou komunikaci mezi klientem a SMS bránou.

Ukázka jednoduché implementace HTTP GET/POST API: GitHub – smsgw-demo-apps

Zabezpečení

Komunikace probíhá protokolem HTTPS a kient se přihlašuje certifikátem.

Protokol

S bránou je možno komunikovat příkazy HTTP protokolu GET a POST. Příkazy GET a POST se liší pouze způsobem předávaní dat. Příkaz GET je navíc omezen na délku parametrů.

Označení parametrů:

x  povinný
o  nepovinný
–   nepodporovaný

Požadavek

Parametry jsou posílány standardně dle specifikace metody GET nebo POST HTTP protokolu.

parametrsendreceiveconfirmdélkapopisvýchozí hodnota
actionxxxsend - poslat textovou SMS
receive - vyzvednutí SMS
confirm - potvrzení vyzvednuté SMS
baIDxxxidentifikace Business Application
toNumberx--cílové číslo ve formátu +420123456789
textx--text SMS
msgIDo--identifikace SMS
deliveryReporto--TRUE - z doručenkou
FALSE - bez doručenky
TRUE
intrudero--TRUE - SMS se zobrazí ihned
FALSE - standardní SMS
FALSE
multiparto--TRUE - delší SMS se rozdělí na více částí, max 900 znaků
FALSE - standardní SMS, max 160 znaků
FALSE
suffixo--BA Suffix number
validityPeriodo--počet sekund, jak dlouho se bude SMS snažit doručit příjemci
priorityo--1 - VIP
2 - vysoká
3 - normální
refMsgID--xmsgID potvrzované SMS
refBaID--xbaID potvrzované SMS
fromNumbero--odchozí číslo

Odpověď

Parametry odpovědi jsou zasílány v těle odpovědi ve formátu: název=hodnota<nový řádek>

parametrsendreceiveconfirmdélkapopis
selectorxxxTextSms - příchozí textová SMS
BinarySms - příchozí binární SMS
Response - status report (doručenka)
baIDxxxidentifikace Business Application
refMsgIDxoxmsgID potvrzované SMS
fromNumber-o-odchozí číslo ve formátu +420123456789
toNumber-x-příchozí číslo
timestampxxxčas generování odpovědi
text-o-text SMS
responseTypexoxtyp odpovědi
responseCodexoxnávratový kód
responseDescriptionxoxpopis responseCode
data-o-binární SMS v hexa formátu
header-o-hlavíčka SMS v hexa formátu
dataCodingScheme-o-data coding scheme pro binární SMS
protocolIdentifieroo-identifikator SMS zprávy (0 - 255)

Návratové kódy

typkódpopis
APPL_ERROREAPP_003BaID neni aktivni - EAPP_003 - BaID is not active
APPL_ERROREAPP_019Zprava zaslana po terminu platnosti zkusebniho rezimu - EAPP_019 - Trial period has expired
APPL_ERROREAPP_020Pocet zprav ve zkusebnim rezimu vycerpan - EAPP_020 - No. of messages in trial mode exceeded
APPL_ERROREAPP_023Prekrocen maximalni pocet zprav, ktere je mozne zaslat v jednom mesici - EAPP_023 - Maximum quota of messages per month exceeded
APPL_ERROREAPP_024Prekrocen maximalni pocet zprav, ktere je mozne zaslat behem jednoho dne - EAPP_024 - Maximum quota of messages per day exceeded
APPL_ERROREAPP_025Zprava potvrzovana pres pozadavek Confirm neni k dispozici - EAPP_025 - No message found for Confirm request
APPL_ERROREAPP_037 Limit zprav cekajicich na potvrzeni prijeti prekrocen - EAPP_037 - Too many messages waiting for confirmation
APPL_ERROREAPP_050Maximalni limit soucasnych pozadavku prekrocen - EAPP_050 - Maximum number of concurrent requests exceeded
APPL_ERROREAPP_051Nadlimitni pocet soucasnych pozadavku na potvrzeni prijeti zpravy EAPP_051 - Too many concurrent confirm requests
APPL_ERROREAPP_052Nadlimitni pocet soucasnych pozadavku na prijeti zpravy - EAPP_052 - Too many concurrent receive requests
APPL_ERROREAPP_053Nadlimitni pocet soucasnych pozadavku na zaslani zpravy - EAPP_053 - Too many concurrent send requests
APPL_ERROREAPP_060Aplikace neni opravnena pouzivat cislo MSISDN v poli fromNumber - EAPP_060 - Application is not authorised to use MSISDN number in fromNumber field
APPL_ERROREAPP_101Zprava musi byt potvrzena pres stejne rozhrani, pres jake byla prijata - EAPP_101 - Message must be confirmed via same interface through which it was received
AUTHORIZATION_ERROREAUT_001Neplatny certifikat - EAUT_001 - Invalid certificate
AUTHORIZATION_ERROREAUT_002ID neni platne nebo není autorizovano pro certifikat - EAUT_002 - BA ID not valid or not authorised for certificate
AUTHORIZATION_ERROR EAUT_003Ref BA ID neni autorizovano pro certifikat - EAUT_003 - Ref BA ID not authorised for certificate
FORMAT_ERROREFMT_004Neplatny identifikator zpravy - EFMT_004 - Invalid message ID
FORMAT_ERROREFMT_005Neplatna priorita zpravy - EFMT_005 - Invalid message priority
FORMAT_ERROREFMT_006Nesoulad cisla fromNumber s BA ID - EFMT_006 - Invalid fromNumber (mismatch with BA ID)
FORMAT_ERROREFMT_007Neplatny format MSISDN cisla prijemce - EFMT_007 - Invalid recipient MSISDN number format
FORMAT_ERROREFMT_008Neznama hodnota pole Selector - EFMT_008 - Unknown Selector value
FORMAT_ERROREFMT_009Prilis dlouhy sufix zpravy - EFMT_009 - Message suffix too long
FORMAT_ERROREFMT_010Neplatny format MSISDN cisla fromNumber - EFMT_010 - Invalid MSISDN number format of fromNumber
FORMAT_ERROREFMT_011Sufix zpravy musi byt ciselna hodnota - EFMT_011 - Message suffix must be numeric
FORMAT_ERROREFMT_012Jen jedno z poli suffix a fromNumber muze byt vyplneno - EFMT_012 - Only one of the suffix and fromNumber fields might be filled in
FORMAT_ERROREFMT_013Neplatna hodnota pole Report Level / Delivery Report - EFMT_013 - Invalid Report Level / Delivery Report
FORMAT_ERROREFMT_016Neplatny format pole Validity period - EFMT-016 - Incorrect message validity format
FORMAT_ERROREFMT_025SMS nemuze byt soucasne poslana jako multipart a intruder - EFMT_025 - SMS cannot be sent as multipart and intruder at the same time.
FORMAT_ERROREFMT_026Nepripustna delka zpravy - EFMT_026 - Message too long
FORMAT_ERROREFMT_032Pole BA ID je prazdne - EFMT_032 - BA ID empty
FORMAT_ERROREFMT_034Zprava neobsahuje zadny text - EFMT_034 – Text message empty
FORMAT_ERROREFMT_035Neplatny pozadavek - EFMT_035 - Bad Request
FORMAT_ERROREFMT_101Neplatna hodnota pole Intruder - EFMT_101 - Invalid intruder format
FORMAT_ERROREFMT_102Neplatna hodnota pole multipart - EFMT_102 - Invalid multipart format
FORMAT_ERROREFMT_105Text zpravy obsahuje nepodporovane znaky - EFMT_105 - SMS text contains unsupported characters
FORMAT_ERROREFMT_106Neplatna hodnota pole data coding scheme - EFMT_106 - Invalid data coding scheme
FORMAT_ERROREFMT_121Neplatna hodnota pole protocolIdentifier - EFMT_121 - Invalid protocolIdentifier value
INTERNAL_ERROREINT_005Zprava zamitnuta SMSC/MMSC - EINT_005 - Message rejected by SMSC/MMSC2
INTERNAL_ERROREINT_012Chyba - Zprava nedorucena z technickych duvodu - EINT_012 - Message not delivered for technical reasons
INTERNAL_ERROREINT_102Zprava nedorucena z technickych duvodu - EINT_102 - Message not delivered for technical reasons
SUCCESSISUC_001Pozadavek Send uspesne zpracovan - ISUC_001 - Send request successfully processed
SUCCESSISUC_002Pozadavek Confirm uspesne zpracovan - ISUC_002 - Confirm request successfully processed
SUCCESSISUC_005Zprava byla dorucena - ISUC_005 - Message delivered
SUCCESSISUC_006Zprava nebyla dorucena - ISUC_006 - Message delivery failed
SUCCESSISUC_010Zprava byla dorucena na SMSC/MMSC - ISUC_010 - Message forwarded to SMSC/MMSC

Příklady

Ping

POST /smsconnector/getpost/GP HTTP/1.0
Content-Length: 23
Host: vftestsms.lbox.cz:8443

action=ping&baID=111222

HTTP/1.1 200 OK
Content-Length: 138

baID=111222
code=ISUC_000
description=Ping request performed successfully
refBaID=111222
timestamp=2012-01-25T14:58:51+01:00
type=SUCCESS

 

Send SMS

POST /smsconnector/getpost/GP HTTP/1.0
Content-Length: 241
Host: vftestsms.lbox.cz:8443

fromNumber=1991001&text=smsgw+HTTP%2C+test+send+25.01.2012+14%3A58&baID=111222&intruder=False&multipart=False&
deliveryReport=True&msgID=v4x4v54z8vz&priority=1&toNumber=%2B420123456789&action=send&validityPeriod=10000

HTTP/1.1 200 OK
Content-Length: 273

baID=111222
msgID=c0465d63-38f0-4f31-93b3-0dc80a063baf
code=ISUC_001
description=Pozadavek Send uspesne zpracovan - ISUC_001 - Send request successfully processed
refBaID=111222
refMsgID=v4x4v54z8vz
timestamp=2012-01-25T14:58:53+01:00
type=SUCCESS

Doručenka

POST /smsconnector/getpost/GP HTTP/1.0
Content-Length: 26
Host: vftestsms.lbox.cz:8443

action=receive&baID=111222

HTTP/1.1 200 OK
Content-Length: 208

baID=111222
msgID=2012-01-23 16:32:20.764674+01
code=ISUC_005
description=Zprava byla dorucena - ISUC_005 - Message delivered
refBaID=111222
refMsgID= v4x4v54z8vz
timestamp=2012-01-25T14:58:53+01:00
type=SUCCESS
selector=Response

Příchozí SMS

POST /smsconnector/getpost/GP HTTP/1.0
Content-Length: 26
Host: vftestsms.lbox.cz:8443

action=receive&baID=111222

HTTP/1.1 200 OK
Content-Length: 180

selector=TextSms
baID=111222
msgID=2012-01-25 16:48:28.208871+01
dataCodingScheme=0
fromNumber=+420987654321
protocolIdentifier=0
intruder=FALSE
multiPart=FALSE
text=prichozi sms

Potvrzení doručenky nebo příchozí SMS

POST /smsconnector/getpost/GP HTTP/1.0
Content-Length: 86
Host: vftestsms.lbox.cz:8444

action=confirm&refBaID=111222&baID=111222&refMsgID=2012-01-23+16%3A32%3A20.764674%2B01

HTTP/1.1 200 OK
Content-Length: 216

baID=111222
msgID=2012-01-23 16:32:20.764674+01
code=ISUC_002
description=Confirm request successfully processed
refBaID=111222
refMsgID=2012-01-23 16:32:20.764674+01
timestamp=2012-01-25T14:58:54+01:00
type=SUCCESS