Dokumentace ke službě SMS Connect

1 ZÁKLADNÍ INFORMACE

1.1 Aktivace služby SMS Connect

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í.

1.2 Přístupové údaje

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)

1.3 Přístupový bod služby – URL adresa pro SMS Connect

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)

2 PŘIHLÁŠENÍ KE SLUŽBĚ SMS CONNECT Z VAŠÍ APLIKACE

2.1 Varianty zabezpečení přihlášení

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.

2.2 Popis GET parametrů pro přihlášení

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)

2.3 Chybové stavy přihlášení

Chybové stavy k přihlášení naleznete níže v dokumentaci v souhrnné tabulce chybových hlášení.

2.4 Nastavení požadované akce
Popis GET parametru pro určení požadované akce
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.

3 AKCE SLUŽBY SMS CONNECT

3.1 Akce send_sms - odeslání SMS

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”

numbertelefonní čí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
messagetext 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

errvý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
3.2 Akce credit_info – informace o výši zbývajícího kreditu na SMSbráně

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_info

                                
Pří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
3.3 Akce xml_queue – odeslání více SMS v jednom požadavku

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 . Jedna zpráva je definována dvojicí tagů, uvnitř kterých jsou parametry SMS (číslo, obsah zprávy,...), které jsou shodné s parametry akce ”send_sms”.

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

errvý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 . Pořadí SMS je zachováno podle pořadí v požadavku pro odeslání várky SMS.

errvý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
3.4 Akce inbox – příchozí SMS a doručenky

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”

deleteparametr 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=inbox
    
                                        

Pří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
statusstav 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

4 PUSH - PŘÍCHOZÍ SMS A DORUČENKY

4.1 Výhody PUSH zpráv

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.

4.2 GET / POST PUSH

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_idid 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_idid 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
statusstav 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

4.3 POST XML

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>
                                            

5 CHYBOVÉ KÓDY SLUŽBY SMS CONNECT

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ů