API v1#

V súčasnej verzii podporuje API v1 dva spôsoby komunikácie so serverom, a to HTTPS JSON a HTTPS XML. Klientské aplikácie pre posielanie svojich požiadaviek využívajú URL https://smsapi.telekom.sk. Celá komunikácia je šifrovaná cez HTTPS spojenie.

Pre využitie niektorého z API rozhraní je potrebné mať zadefinovaný aspoň jeden API kľúč. Nad API kľúčom je nutné nastaviť aj zoznam IP adries, z ktorých bude možné odosielať požiadavky na API. Požiadavky na API sú defaultne nastavené na metódu POST. V prípade, že chcete využívať metódu GET, je nutné toto nastavenie povoliť pri danom API kľúči, čo je však odporúčané iba v nevyhnutných prípadoch.

Základná URL pre komunikáciu s API#

Komunikácia s API prebieha posielaním POST(GET) požiadaviek na nižšie uvedenú url:

JSONXML

https://smsapi.telekom.sk/json

https://smsapi.telekom.sk/xml

Každý endpoint sa uvádza ako relatívna cesta k tejto základnej URL. Napr. pre autentifikáciu (/auth) bude výsledná URL pre JSON https://smsapi.telekom.sk/json/auth

Funkcia auth#

Metóda: POST, GET
Endpoint: /auth

Funkcia auth slúži na autentifikáciu používateľa. Povinným parametrom pre autentifikáciu je token, čo je vlastne API kľuč vygenerovaný vo webovej aplikácii. Výsledkom autentifikácie je získané session_id, ktoré je potrebné na posielanie akýchkoľvek ďalších požiadaviek na API rozhranie (posielanie SMS, overovanie...). Aplikácia taktiež toto session_id ukladá aj do šifrovaného cookie. Platnosť obidvoch session je 15 minút pri nečinnosti. V prípade, ak API klient nepodporuje ukladanie session_id alebo cookies, je potrebné pri každej požiadavke odosielať všetky údaje ako pri autentifikácii.

Príklad POST requestu:

JSONXML

URL: https://smsapi.telekom.sk/json/auth

Telo požiadavky:

{
  "token": "****************************************************************"
}

URL: https://smsapi.telekom.sk/xml/auth

Telo požiadavky:

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <token>****************************************************************</token>
</request>

V prípade úspešnej autentifikácie získame odpoveď v nasledujucom formáte:

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "session_id": "a1da7970-5464-11e4-867e-9d647178712c"
}

<?xml version="1.0" encoding="UTF-8" ?>
 <response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <session_id>a1da7970-5464-11e4-867e-9d647178712c</session_id>
</response>

V prípade chýb získame odpoveď s chybovou hláškou (ukážka chybovej hlášky):

JSONXML

{
    "result": {
        "status": "error",
        "description": "Prístup z ip adresy 1.2.3.4 nie je povolený",
        "code": "IP_NOT_ALLOWED"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <result>
        <status>error</status>
        <description>Prístup z ip adresy 1.2.3.4 nie je povolený</description>
        <code>IP_NOT_ALLOWED</code>
    </result>
</response>

Funkcia ping#

Metóda: POST, GET
Endpoint: /ping

Ako už bolo spomínané pri autentifikovaní získame session_id, ktoré je v prípade nečinnosti platné 15 minút. V prípade, že vyžadujeme prácu cez API pod rovnakým session_id, máme k dispozícii funkciu ping. Táto funkcia slúži na obnovovanie životnosti session_id ešte predtým, než sa jej minie platnosť.

Príklad POST requestu:

JSONXML

URL: https://smsapi.telekom.sk/json/ping

Telo požiadavky:

{
  "session_id": "92f84490-1f89-11f0-a652-9ba39c6bc33b"
}

URL: https://smsapi.telekom.sk/xml/ping

Telo požiadavky:

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <session_id>92f84490-1f89-11f0-a652-9ba39c6bc33b</session_id>
</request>

V prípade, že overenie prebehlo úspešne získame odpoveď v nasledujucom formáte:

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
</response>

V prípade chýb získame odpoveď s chybovou hláškou (ukážka chybovej hlášky):

JSONXML

{
    "result": {
        "status": "error",
        "description": "Relácia nebola nájdená alebo expirovala",
        "code": "SESSION_NOT_FOUND"
    }
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <result>
        <status>error</status>
        <description>Relácia nebola nájdená alebo expirovala</description>
        <code>SESSION_NOT_FOUND</code>
    </result>
</response>

Funkcia send_message#

Metóda: POST, GET
Endpoint: /send_message

Táto funkcia slúži na samotné odosielanie SMS správ a vyžaduje/podporuje nasledovne vstupné parametre:

* - povinný parameter

Parameter	Typ	Popis
*to	string	Číslo adresáta správy, Max. podpora 100 MSISDN oddelených čiarkou pre SMS s viacerými príjemcami.
*text	string	Text SMS správy s podporou diakritiky
*token alebo session_id	string	api token získaný z webovej aplikácie alebo session_id získané z funkcie auth
from	string	Číslo, alebo textový identifikátor odosielateľa SMS správy. Ak nebude definovaný, správa sa odošle z čísla, ktoré je priradené k účtu.
callback	bool	true - bude volať v užívateľských nastaveniach definovanú URL pre callback na poslanie delivery statusu SMS správy cez rozhranie, prostredníctvom ktorého bola správa odoslaná - (Predvolená hodnota) false - nebude volať v užívateľských nastaveniach definovanú URL pre callback Akákoľvek zadaná hodnota okrem false, 0, "0" alebo "" bude považovaná za true
delivery_time	string	[timestamp] Čas, v ktorom má byť správa odoslaná vo formáte YYYY-MM-DD HH:MM:SS
priority	integer	Priorita zasielania SMS. Možné hodnoty parametra: 1 (Nízka), 2 (Štandardná), 3 (Vysoká). (Predvolená hodnota - 2)
validity	integer	Čas platnosti SMS. Ak SMS nebude odoslaná do SMSC do tohto časového limitu, bude z queue vymazaná. Hodnota je uvádzaná v minútach. Možné hodnoty 1-1440. (Predvolená hodnota - 1440 minút)
unicode	bool	false - pošle ako štandardnú správu GSM 7bit. Ak správa obsahuje diakritiku, tá bude z textu odstránená true - pošle ako unicode [UTF-16] V prípade, že tento parameter nie je definovaný, aplikácia odošle správu na základe automatickej detekcie kódovania. Akákoľvek zadaná hodnota okrem false, 0, "0" alebo "" bude považovaná za true
type	string	standard - špecifikuje formát posielaného textu (Predvolená hodnota) flash - špecifikuje SMS, ktorá sa zobrazí okamžite po prijatí telefónom
groupId	integer	ID kadenčnej skupiny, prostredníctvom ktorej bude SMS správa odoslaná

Príklad POST requestu:

JSONXML

URL: https://smsapi.telekom.sk/json/send_message

Telo požiadavky:

{
    "to": "421XXXXXXXXX",
    "session_id": "92f84490-1f89-11f0-a652-9ba39c6bc33b",
    "text": "Text, ktorý sa zobrazí prijímateľovi",
    "unicode": false // Tento parameter zabezpečí automatické odstránenie diakritiky zo správy
}

URL: https://smsapi.telekom.sk/xml/send_message

Telo požiadavky:

<?xml version="1.0" encoding="UTF-8" ?>
<request>
    <to>421XXXXXXXXX</to>
    <session_id>92f84490-1f89-11f0-a652-9ba39c6bc33b</session_id>
    <text>Text, ktorý sa zobrazí prijímateľovi</text>
    <unicode>false</unicode> <!-- Tento parameter zabezpečí automatické odstránenie diakritiky zo správy -→
</request>

V prípade, že správa bola odoslaná úspešne získame odpoveď v nasledujucom formáte:

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "message_count": 1,
    "messages": [
        {
            "status": "success",
            "code": "OK",
            "description": "",
            "message_id": 100427,
            "parts": 1
        }
    ]
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <messages count="1">
        <message id="100427">
        <status>success</status>
        <code>OK</code>
        <description></description>
        </message>
    </messages>
</response>

V prípade chýb získame odpoveď s chybovou hláškou (ukážka chybovej hlášky):

JSONXML

{
    "result": {
        "status": "error",
        "description": "Relácia nebola nájdená alebo expirovala",
        "code": "SESSION_NOT_FOUND"
    }
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>error</status>
        <description>Relácia nebola nájdená alebo expirovala</description>
        <code>SESSION_NOT_FOUND</code>
    </result>
</response>

V prípade, že požiadavka bola prijatá úspešne, ale niektorú správu nebolo možné odoslať (príklad s konkrétnou chybou):

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "message_count": 2,
    "messages": [
        {
            "status": "success",
            "code": "OK",
            "description": "",
            "message_id": 100427,
            "parts": 1
        },
        {
            "status": "error",
            "code": "SYSTEM_ERROR",
            "description": "Vyskytla sa systémová chyba. Kontaktuje administrátora",
            "message_id": 100428
        }
    ]
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <messages count="2">
        <message id="100427">
            <status>success</status>
            <code>OK</code>
            <description></description>
        </message>
        <message id="100428">
            <status>error</status>
            <code>SYSTEM_ERROR</code>
            <description>Vyskytla sa systémová chyba. Kontaktuje administrátora</description>
        </message>
    </messages>
</response>

Funkcia check_message#

Metóda: POST, GET
Endpoint: /check_message

Táto funkcia slúži na overenie stavu správy (stav doručenia).

Príklad POST requestu:

JSONXML

URL: https://smsapi.telekom.sk/json/check_message

Telo požiadavky:

{
    "message_id":883315048,
    "session_id":"d3ccd370-114f-11f0-a1d1-0bfd5e3a9b39"
}

URL: https://smsapi.telekom.sk/xml/check_message

Telo požiadavky:

<request>
    <message_id>883315048</message_id>
    <session_id>d3ccd370-114f-11f0-a1d1-0bfd5e3a9b39</session_id>
</request>

V prípade, že overenie prebehlo úspešne:

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "message_id": "154786",
    "status": "Doručená",
    "code": "DELIVERED",
    "deliveryDateTime": "2017-01-01 10:45:00" // Tvar timestamp alebo prázdny reťazec v prípade, že správa ešte nebola doručená
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <message>
        <status>Doručená</status>
        <code>DELIVERED</code>
    <deliveryDateTime>2017-01-01 10:45:00</deliveryDateTime> <!-- Tvar imestamp alebo prádzny reťazec v prípade, že správa ešte nebola doručená. -→
    </message>
</response>

V prípade chyby (príklad s konkrétnou chybou):

JSONXML

{
    "result": {
        "status": "error",
        "description": "Relácia nebola nájdená alebo expirovala",
        "code": "SESSION_NOT_FOUND"
    }
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>error</status>
        <description>Relácia nebola nájdená alebo expirovala</description>
        <code>SESSION_NOT_FOUND</code>
    </result>
</response>

Stavy parametra status

code	status	Description
UNSENT	Neodoslaná	Správa ešte nebola spracovaná.
SCHEDULED	Plánovaná	Správa je načasovaná na neskoršie odoslanie.
QUEUED	Vo fronte	Správa bola prijatá a čaká na odoslanie.
SENDING	Odosiela sa	Správa sa aktuálne odosiela.
SENT	Odoslaná	Správa bola odoslaná do SMS centra.
DELIVERED	Doručená	Správa bola doručená adresátovi.
EXPIRED	Expirovaná	Časový limit na doručenie správy vypršal.
DELETED	Zmazaná	Správa bola odstránená z doručovacej fronty.
UNDELIVERABLE	Nedoručiteľná	Správu nie je možné doručiť.
DENIED	Zamietnutá	Správa bola zamietnutá SMS centrom.
IN_GROUP	V skupine	Správa je zaradená do kadenčnej skupiny.
BLACKLISTED	Blokovaná	Správa sa nachádza na blackliste a bola zablokovaná.
ERROR	Chyba	Správu nie je možné odoslať z dôvodu chyby. Systém sa pokúsi opätovne správu doručiť ešte 5 krát v priebehu 60 minút.
UNKNOWN	Neznámy	Správa bola odoslaná, ale nie je možné zistiť stav doručenia.

Delivery status callback#

Táto funkcia pošle požiadavku s informáciami o zmenách v delivery statuse na Callback URL (aplikácia, alebo skript na strane zákazníka) definovanú v nastaveniach API kľúča.

Parametre v callback požiadavke

Parameter	Typ	Popis
message_id	string	ID SMS správy vygenerovanej funkciou `send_message`
status	string	Status správy
addressFrom	string	Číslo odosielateľa správy
addressTo	string	Číslo adresáta správy
channel	string	Kanál cez ktorý bola správa odoslaná

Stavy parametra status:

Status	Popis
SCHEDULED	Správa je načasovaná na neskoršie odoslanie.
QUEUED	Správa bola prijatá a čaká na odoslanie.
SENDING	Správa sa aktuálne odosiela.
SENT	Správa bola odoslaná do SMS centra.
DELIVERED	Správa bola doručená adresátovi.
EXPIRED	Časový limit na doručenie správy vypršal.
DELETED	Správa bola odstránená z doručovacej fronty.
UNDELIVERABLE	Správu nie je možné doručiť.
DENIED	Správa bola zamietnutá SMS centrom.
IN_GROUP	Správa je zaradená do kadenčnej skupiny.
BLACKLISTED	Správa sa nachádza na blackliste a bola zablokovaná.
ERROR	Správu nie je možné odoslať z dôvodu chyby. Systém sa pokúsi opätovne správu doručiť ešte 5 krát v priebehu 60 minút.
UNKNOWN	Správa bola odoslaná, ale nie je možné zistiť stav doručenia.

Spätná správa#

Spätné správy služba Omnichannel preposiela na adresu definovanú v časti Konto→Profil→Priradené čísla→Callback URL pre prijaté správy. Na zavolanie tejto adresy bude v prípade, ak ju nebude možné volať ihneď pre každú doručenú SMS vykonaných týchto 6 pokusov:

Po 5 minútach od posledného pokusu
Po 15 minútach od posledného pokusu
Po 30 minútach od posledného pokusu
Po 60 minútach od posledného pokusu
Po 720 minútach od posledného pokusu
Po 1440 minútach od posledného pokusu (posledný pokus)

Potom bude nedoručená SMS zahodená. Text správy je v znakovej sade UTF-8.

Príklad:

Parameter	Typ	Popis
addressFrom	string	Číslo odosielateľa správy
addressTo	string	Číslo adresáta správy
timestamp	string	Dátum a čas prijatia SMS
text	string	Text SMS správy