Nastavení služby je možné na portálu SMSbrána (www.smsbrana.cz) po přihlášení do zóny pro registrované uživatele. V sekci Nastavení služeb zvolte položku SMS Connect a aktivujte si službu zaškrtnutím checkboxu. Otevře se formulářové pole s předvyplněnými údaji pro standardní nastavení služby. Tyto údaje si kdykoliv můžete změnit dle vašich požadavků.
Při úvodním nastavení doporučujme vyplnit vaše přístupové IP adresy ke službě, pro povolení všech IP adres zachovejte přednastavenou hodnotu *. Pro potvrzení aktivace služby zvolte tlačítko Uložit nastavení.
Při aktivaci služby se ve formulářovém poli zobrazí váš unikátní login a heslo (”password”). Tyto údaje jsou odlišné od přihlašovacích údajů do webové administrace a budete je potřebovat dále pro přístup ke službě SMS Connect z vaší aplikace.
POZN.: Pokud by jste měli specifické požadavky na fungování služby SMS Connect oslovte nás na adrese podpora@smsbrana.cz a vše se vám pokusíme nastavit na míru. Příkladem může být více přístupových bodů pod jedním účtem, pro rozdělení statistik SMS na jednotlivé přístupové body (integrace SMS Connect do více e-shopů z možností odlišení pro statistiky)
https://api.smsbrana.cz/smsconnect/http.php
https://api-backup.smsbrana.cz/smsconnect/http.php
(můžete použít v případě nedostupnosti hlavního serveru)
Služba SMS Connect nabízí 2 možnosti přihlášení.
Jednoduché přihlášení
Slouží pro rychlou a jednoduchou integraci, ”password” je zasílán otevřenou formou.
Pokročilé přihlášení se zabezpečením (doporučené)
Jedná se o pokročilejší metodu z hlediska bezpečnosti využívání služby SMS Connect proti zneužití služby třetí osobou. Aplikace neodesílá ”password” otevřenou formou, ale jako součást HASH řetězce, který má v sobě integrovanou časovou známku platnosti a soli pro unikátnost požadavku.
Jednoduché přihlášení
login | uživatelské jméno pro službu SMS Connect |
password | heslo pro službu SMS Connect |
Pokročilé přihlášení se zabezpečením (doporučené)
login | uživatelské jméno pro službu SMS Connect |
time | čas zapsaný ve formátu YYYYMMDDTHHMMSS, příklad zápisu parametru time pro datum a čas 1. 10. 2017 22:27:20 – 20171001T222720, kde T je oddělovač |
salt | náhodný řetězec několika znaků, max 50, během dne může být daná kombinace použita maximálně jednou |
auth | výpočet hash kódu provedete z řetězců zapsaných za sebou metodou MD5 (password + time + salt) |
Chybové stavy k přihlášení naleznete níže v dokumentaci v souhrnné tabulce chybových hlášení.
action | název prováděné akce (send_sms, inbox, credit_info, xml_queue) |
Výše uvedené parametry jsou společné pro všechny následující dostupné akce služby SMS Connect.
Tato akce slouží pro odeslání jedné SMS v jednom požadavku. Pro hromadné rozeslání více SMS se využívá akce ”xml_queue” viz. níže.
Popis GET parametrů pro akci ”send_sms”
number | telefonní číslo v národním (např. 736339339) nebo mezinárodním tvaru (např. +420736339339), zahraniční čísla musí být vždy v mezinárodním tvaru s předvolbou státu |
message | text zprávy bez diakritiky (”7bit”) Délka SMS: 1 SMS do 160 znaků, 2 SMS do 306 znaků, 3 SMS do 459 znaků. Pro SMS s diakritikou použijte kódování ”ucs2”. |
when (volitelné) | kdy nejdříve odeslat konkrétní SMS, formát zápisu je stejný jako v parametru ”time” definovaném výše (YYYYMMDDTHHMMSS) POZN. Pro oddělení dnů a hodin je použito ”T” |
delivery_report (volitelné) | 1 = s doručenkou (defaultní) , 0 = bez doručenky |
sender_id (volitelné) | ID odesílatele naleznete po aktivaci služby SMS Connect po přihlášení do zóny pro registrované v sekci Nastavení služeb – Číslo odesílatele, u jednotlivých autorizovaných čísel je vždy zobrazeno i jejich ID |
sender_phone (volitelné) | číslo odesílatele, pokud jej chcete nastavit přímo, číslo musí být v seznamu vašich autorizovaných čísel |
user_id (volitelné) | vlastní označení SMS pomocí varchar(50) hodnoty, systém akceptuje pouze jednu SMS se stejným user_id - nejedená se ale o 100% ochranu proti multi zaslání jedné zprávy pokud další SMS odejde přes jiný náš server, na který nedoběhla synchronizace prvotní SMS |
data_code (volitelné) | "7bit" (default) - standardní 160znaková SMS "ucs2" - unicode (zprávy s diakritikou/spec. znaky), 70 znaků/sms, 67 znaků vícepartové SMS (2 SMS = 134 znaků) |
answer_mail (volitelné) | e-mail, na který zaslat odpovědní SMS |
delivery_mail (volitelné) | e-mail, na který zaslat doručenky |
Příklad požadavku na vyvolání akce ”send_sms”
https://api.smsbrana.cz/smsconnect/http.php?login=<váš_login>&password=<vaše_heslo>&action=send_sms&number=736339339&message=test
Příklad odpovědi na GET požadavek akce ”send_SMS”
<result> <err>0</err> <price>1.1</price> <sms_count>1</sms_count> <credit>1523.32</credit> <sms_id>377351</sms_id> </result>
Vysvětlení parametrů XML kódu
err | výsledek akce, nabývá hodnot 0 – 12, 0 = bez chyby, hodnoty jsou vysvětleny v tabulce chybových hodnot níže v kapitole 5 |
price | cena za poslední SMS v Kč |
sms_count | počet odeslaných SMS |
sms_id | ID odeslané SMS, slouží jako vazba pro doručenku SMS |
Vyvoláním této akce zjistíte aktuální výši zbývajícího kreditu na portálu SMSbrána.
Příklad požadavku na vyvolání akce ”send_sms”
https://api.smsbrana.cz/smsconnect/http.php?login=<váš_login>&password=<vaše_heslo>&action=credit_infoPříklad odpovědi na GET požadavek akce ”credit_info”
<result> <err>0</err> <price>1.1</price> <sms_count>1</sms_count> <credit>1523.32</credit> <sms_id>377351</sms_id> </result> <result> <err>0</err> <credit>1523.32</credit> <user_id>123</user_id> </result>Vysvětlení parametrů XML kódu
credit | výše zbývajícího kreditu |
Zasílání SMS ve formátu XML, předávání probíhá metodou raw POST. Předchozí GET parametry pro přihlášení a název akce jsou zachovány.
Popis struktury XML – odeslání SMS
Várka SMS je definována tagy
Příklad XML kódu pro akci ”xml_queue” – odeslání SMS
<queue> <sms> number>736339339</number> <message>test</message> <when></when> <sender_id></sender_id> </sms> <sms> {ukázka chybné sms} <number>1234</number> <message>test</message> <when></when> <sender_id></sender_id> </sms> <sms> <number>+420733781178</number> <message>test</message> <when></when> <sender_id></sender_id> </sms> </queue>Příklad XML kódu pro akci ”xml_queue” – odpověď na požadavek SMS
<result> <err>0</err> <price>2.2</price> <sms_count>2</sms_count> <credit>1501.32</credit> <result_sms> <item> <err>0</err> <number>+420736339339</number> <sms_id>377450</sms_id> </item> <item> <err>10</err> <number>+4201234</number> </item> <item> <err>0</err> <number>+420733781178</number> <sms_id>377451</sms_id> </item> </result_sms> </result>Vysvětlení parametrů XML kódu – odpověď na požadavek odeslání SMS
Celkový výsledek akce ”xml_queue” je shrnutý v tagu
err | výsledek akce, nabývá hodnot 0 – 12, 0 = bez chyby, hodnoty jsou vysvětleny v tabulce chybových hodnot v kapitole 5 |
price | cena za odeslání SMS v Kč |
sms_count | počet odeslaných SMS |
credit | zbývající kredit v Kč |
result_count | tento tag obsahuje informace k jednotlivým SMS |
Vysvětlení obsahu tagu ”result_sms”
Každá SMS je definována v tagu
err | výsledek konkrétní SMS, nabývá hodnot 0, 10, 11, 12, 0 = bez chyby, hodnoty jsou vysvětleny v tabulce chybových hodnot v kapitole 5 |
number | číslo příjemce v mezinárodním tvaru, např. +420123456789 |
sms_id | ID odeslané SMS, slouží jako vazba pro doručenku SMS |
Tato akce slouží pro zpětnou vazbu na akci ”send_sms”. Díky ní si můžete do vašeho systému stáhnout doručenky odeslaných SMS.
Váš skript, který vyvolá tuto akci, si můžete nechat od nás zavolat automaticky v případě, že máte nějaké SMS, či doručenky ke stažení. Adresu vašeho skriptu zadáte v nastavení SMS Connectu u nás na webu.
Příchozí SMS a doručenky si můžete také nechat zasílat v reálném čase metodou PUSH. Více informací v kapitole 4.
Popis GET parametrů pro akci ”inbox”
delete | parametr pro smazání již zobrazených SMS z inboxu přijatých zpráv, tento parametr je testován na to, zda je přítomen. Příklad použití - delete = 1 |
Příklad požadavku na vyvolání akce ”inbox”
https://api.smsbrana.cz/smsconnect/http.php?login=<váš_login>&password=<vaše_heslo>&action=inboxPříklad odpovědi na GET požadavek akce ”inbox”
<inbox> <delivery_sms> <item> <number>+420736339339</number> <time>20091020T164508</time> <message>test</message> </item> </delivery_sms> <delivery_report> <item> <idsms>377339</idsms> <number>+420736339339</number> <time>20091020T132528</time> <status>1</status> </item> <item> <idsms>377340</idsms> <number>+420736339339</number> <time>20091020T181102</time> <status>1</status> </item> </delivery_report> </inbox> </result>
Vysvětlení parametrů XML kódu
Formát předaných doručených SMS – část
number | číslo, ze kterého byla SMS doručena |
time | čas doručení SMS |
message | text přijaté SMS |
Formát doručenek – potvrzení o doručení SMS – část
id_sms | identifikátor SMS zprávy, který jste obdrželi při odeslání SMS |
number | číslo, na které byla SMS doručena |
time | čas doručení SMS |
status | stav doručení, 0 = odesláno, 1 = doručeno, 2 = uloženo u operátora, 3 = nedoručeno, 5 = expirováno, 6 = odmítnuto |
user_id (volitelné) | pokud jste SMS označili vlastní identifikátorem, je uveden i u doručenky |
Díky PUSH zprávám získáte přijaté SMS a doručenky v reálném čase a nemusíte pravidelně metodou ”inbox” z minulé kapitoly kontrolovat, zda dorazila nějaká data. Data zasíláme metodou https, v případě, že váš webserver neodpoví statusem 200 OK, je notifikace zasílána později znovu.
Tyto dvě možnosti se liší pouze v tom, jestli k vám data zasíláme metodou POST nebo GET.
Předávané GET / POST parametry
Příchozí SMS
income_id | id záznamu (pokud váš server neodpoví 200 OK, tak je zpráva zasílána k vám znovu se stejným ”income_id” - tento parametr tedy může sloužit pro kontrolu, zda jste zprávu již nezpracovali) |
number | telefonní číslo odesílatele SMS |
message | text přijaté SMS |
time | timestamp příjaté SMS (2018-01-20 18:11:02) |
receiver (volitelné) | číslo, na které SMS dorazila |
Doručenka
income_id | id záznamu (pokud váš server neodpoví 200 OK, tak je zpráva zasílána k vám znovu se stejným ”income_id” - tento parametr tedy může sloužit pro kontrolu, zda jste zprávu již nezpracovali) |
number | telefonní číslo příjemce SMS |
status | stav doručení, 0 = odesláno, 1 = doručeno, 2 = uloženo u operátora, 3 = nedoručeno, 5 = expirováno, 6 = odmítnuto |
time | timestamp přijetí doručenky (2018-01-20 18:11:02) |
sms_id | identifikátor SMS zprávy, který jste obdrželi při odeslání SMS |
user_id (volitelné) | pokud jste SMS označili vlastní identifikátorem, tak je tento identifikátor uveden i u doručenky |
V tomto případě získáváte data formátovaná v podobě XML a jsou doručena metodou RAW POST. V XML datech získáváte stejné položky jako v předchozí metodě. Jediný rozdíl je v tom, že můžete získat více čekajících položek zaráz (pokud se za poslední vteřinu od posledního PUSHe nahromadilo více položek k odeslání).
U XML response se očekává kromě http statusu 200 OK také xml odpověď s potvrzením, které zprávy byly zpracované.
Příklad přijatého XML<?xml version="1.0" encoding="UTF-8"?> <inbox> <delivery_report> <item> <income_id>11</income_id> <number>+420737602602</number> <status>1</status> <time>2014-10-10 21:28:23</time> <sms_id>101002641</sms_id> </item> <item> <income_id>15</income_id> <number>+420790542000</number> <status>1</status> <time>2014-10-10 21:37:20</time> <sms_id>101002657</sms_id> </item> </delivery_report> <delivery_sms> <item> <income_id>16</income_id> <number>+420774884136</number> <message>test</message> <time>2014-10-10 21:42:08</time> <receiver>6633</receiver> </item> </delivery_sms> </inbox>Očekávaná XML response
<?xml version="1.0" encoding="UTF-8"?> <inbox_confirm> <income_id> <item>11</item> <item>15</item> <item>16</item> </income_id> </inbox_confirm>
err=-1 | duplicitní ”user_id” - stejně označená SMS byla odeslaná již v minulosti |
err=1 | neznámá chyba |
err=2 | neplatný login |
err=3 | neplatný ”hash” nebo ”password” (podle varianty zabezpečení přihlášení) |
err=4 | neplatný ”time”, větší odchylka času mezi servery než maximální akceptovaná v nastavení služby SMS Connect |
err=5 | nepovolená IP, viz nastavení služby SMS Connect |
err=6 | neplatný název akce |
err=7 | tato ”salt” byla již jednou za daný den použita |
err=8 | nebylo navázáno spojení s databází |
err=9 | nedostatečný kredit |
err=10 | neplatné číslo příjemce SMS |
err=11 | prázdný text zprávy |
err=12 | SMS je delší než povolených 459 znaků |