HTTP GET/POST API - LinuxBox.cz

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.

parametr	send	receive	confirm	popis	výchozí hodnota
action	x	x	x	send - poslat textovou SMS receive - vyzvednutí SMS confirm - potvrzení vyzvednuté SMS
baID	x	x	x	identifikace Business Application
toNumber	x	-	-	cílové číslo ve formátu +420123456789
text	x	-	-	text SMS
msgID	o	-	-	identifikace SMS
deliveryReport	o	-	-	TRUE - z doručenkou FALSE - bez doručenky	TRUE
intruder	o	-	-	TRUE - SMS se zobrazí ihned FALSE - standardní SMS	FALSE
multipart	o	-	-	TRUE - delší SMS se rozdělí na více částí, max 900 znaků FALSE - standardní SMS, max 160 znaků	FALSE
suffix	o	-	-	BA Suffix number
validityPeriod	o	-	-	počet sekund, jak dlouho se bude SMS snažit doručit příjemci
priority	o	-	-	1 - VIP 2 - vysoká 3 - normální
refMsgID	-	-	x	msgID potvrzované SMS
refBaID	-	-	x	baID potvrzované SMS
fromNumber	o	-	-	odchozí číslo

Odpověď

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

parametr	send	receive	confirm	popis
selector	x	x	x	TextSms - příchozí textová SMS BinarySms - příchozí binární SMS Response - status report (doručenka)
baID	x	x	x	identifikace Business Application
refMsgID	x	o	x	msgID potvrzované SMS
fromNumber	-	o	-	odchozí číslo ve formátu +420123456789
toNumber	-	x	-	příchozí číslo
timestamp	x	x	x	čas generování odpovědi
text	-	o	-	text SMS
responseType	x	o	x	typ odpovědi
responseCode	x	o	x	návratový kód
responseDescription	x	o	x	popis 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
protocolIdentifier	o	o	-	identifikator SMS zprávy (0 - 255)

Návratové kódy

typ	kód	popis
APPL_ERROR	EAPP_003	BaID neni aktivni - EAPP_003 - BaID is not active
APPL_ERROR	EAPP_019	Zprava zaslana po terminu platnosti zkusebniho rezimu - EAPP_019 - Trial period has expired
APPL_ERROR	EAPP_020	Pocet zprav ve zkusebnim rezimu vycerpan - EAPP_020 - No. of messages in trial mode exceeded
APPL_ERROR	EAPP_023	Prekrocen maximalni pocet zprav, ktere je mozne zaslat v jednom mesici - EAPP_023 - Maximum quota of messages per month exceeded
APPL_ERROR	EAPP_024	Prekrocen maximalni pocet zprav, ktere je mozne zaslat behem jednoho dne - EAPP_024 - Maximum quota of messages per day exceeded
APPL_ERROR	EAPP_025	Zprava potvrzovana pres pozadavek Confirm neni k dispozici - EAPP_025 - No message found for Confirm request
APPL_ERROR	EAPP_037	Limit zprav cekajicich na potvrzeni prijeti prekrocen - EAPP_037 - Too many messages waiting for confirmation
APPL_ERROR	EAPP_050	Maximalni limit soucasnych pozadavku prekrocen - EAPP_050 - Maximum number of concurrent requests exceeded
APPL_ERROR	EAPP_051	Nadlimitni pocet soucasnych pozadavku na potvrzeni prijeti zpravy EAPP_051 - Too many concurrent confirm requests
APPL_ERROR	EAPP_052	Nadlimitni pocet soucasnych pozadavku na prijeti zpravy - EAPP_052 - Too many concurrent receive requests
APPL_ERROR	EAPP_053	Nadlimitni pocet soucasnych pozadavku na zaslani zpravy - EAPP_053 - Too many concurrent send requests
APPL_ERROR	EAPP_060	Aplikace neni opravnena pouzivat cislo MSISDN v poli fromNumber - EAPP_060 - Application is not authorised to use MSISDN number in fromNumber field
APPL_ERROR	EAPP_101	Zprava 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_ERROR	EAUT_001	Neplatny certifikat - EAUT_001 - Invalid certificate
AUTHORIZATION_ERROR	EAUT_002	ID neni platne nebo není autorizovano pro certifikat - EAUT_002 - BA ID not valid or not authorised for certificate
AUTHORIZATION_ERROR	EAUT_003	Ref BA ID neni autorizovano pro certifikat - EAUT_003 - Ref BA ID not authorised for certificate
FORMAT_ERROR	EFMT_004	Neplatny identifikator zpravy - EFMT_004 - Invalid message ID
FORMAT_ERROR	EFMT_005	Neplatna priorita zpravy - EFMT_005 - Invalid message priority
FORMAT_ERROR	EFMT_006	Nesoulad cisla fromNumber s BA ID - EFMT_006 - Invalid fromNumber (mismatch with BA ID)
FORMAT_ERROR	EFMT_007	Neplatny format MSISDN cisla prijemce - EFMT_007 - Invalid recipient MSISDN number format
FORMAT_ERROR	EFMT_008	Neznama hodnota pole Selector - EFMT_008 - Unknown Selector value
FORMAT_ERROR	EFMT_009	Prilis dlouhy sufix zpravy - EFMT_009 - Message suffix too long
FORMAT_ERROR	EFMT_010	Neplatny format MSISDN cisla fromNumber - EFMT_010 - Invalid MSISDN number format of fromNumber
FORMAT_ERROR	EFMT_011	Sufix zpravy musi byt ciselna hodnota - EFMT_011 - Message suffix must be numeric
FORMAT_ERROR	EFMT_012	Jen jedno z poli suffix a fromNumber muze byt vyplneno - EFMT_012 - Only one of the suffix and fromNumber fields might be filled in
FORMAT_ERROR	EFMT_013	Neplatna hodnota pole Report Level / Delivery Report - EFMT_013 - Invalid Report Level / Delivery Report
FORMAT_ERROR	EFMT_016	Neplatny format pole Validity period - EFMT-016 - Incorrect message validity format
FORMAT_ERROR	EFMT_025	SMS nemuze byt soucasne poslana jako multipart a intruder - EFMT_025 - SMS cannot be sent as multipart and intruder at the same time.
FORMAT_ERROR	EFMT_026	Nepripustna delka zpravy - EFMT_026 - Message too long
FORMAT_ERROR	EFMT_032	Pole BA ID je prazdne - EFMT_032 - BA ID empty
FORMAT_ERROR	EFMT_034	Zprava neobsahuje zadny text - EFMT_034 – Text message empty
FORMAT_ERROR	EFMT_035	Neplatny pozadavek - EFMT_035 - Bad Request
FORMAT_ERROR	EFMT_101	Neplatna hodnota pole Intruder - EFMT_101 - Invalid intruder format
FORMAT_ERROR	EFMT_102	Neplatna hodnota pole multipart - EFMT_102 - Invalid multipart format
FORMAT_ERROR	EFMT_105	Text zpravy obsahuje nepodporovane znaky - EFMT_105 - SMS text contains unsupported characters
FORMAT_ERROR	EFMT_106	Neplatna hodnota pole data coding scheme - EFMT_106 - Invalid data coding scheme
FORMAT_ERROR	EFMT_121	Neplatna hodnota pole protocolIdentifier - EFMT_121 - Invalid protocolIdentifier value
INTERNAL_ERROR	EINT_005	Zprava zamitnuta SMSC/MMSC - EINT_005 - Message rejected by SMSC/MMSC2
INTERNAL_ERROR	EINT_012	Chyba - Zprava nedorucena z technickych duvodu - EINT_012 - Message not delivered for technical reasons
INTERNAL_ERROR	EINT_102	Zprava nedorucena z technickych duvodu - EINT_102 - Message not delivered for technical reasons
SUCCESS	ISUC_001	Pozadavek Send uspesne zpracovan - ISUC_001 - Send request successfully processed
SUCCESS	ISUC_002	Pozadavek Confirm uspesne zpracovan - ISUC_002 - Confirm request successfully processed
SUCCESS	ISUC_005	Zprava byla dorucena - ISUC_005 - Message delivered
SUCCESS	ISUC_006	Zprava nebyla dorucena - ISUC_006 - Message delivery failed
SUCCESS	ISUC_010	Zprava 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: www.ipsms.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: www.ipsms.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: www.ipsms.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: www.ipsms.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