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.

* - povinný parameter

Parameter	Typ	Popis
*token	string	Vygenerovaný api kľúč

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

* - povinný parameter

Parameter	Typ	Popis
*session_id	string	Session id

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 vo formáte `4219xxxxxxxx` pre SMS. Pokiaľ chcete odoslať správu typu RCS, číslo je potrebné zadať vo formáte `+4219xxxxxxxx` alebo `09xxxxxxxx`. Pre odoslanie rovnakej správy viacerým príjemcom je čísla možné oddeliť čiarkou.
*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) a podporuje nasledujúce parametre.

* - povinný parameter

Parameter	Typ	Popis
*token alebo session_id	string	API token alebo session_id vrátené pomocou metódy auth.
*message_id	string	ID správy vygenerovanej funkciou send_message

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	Popis
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á na cieľovú platformu (SMS Centrum, RBM, Viber)
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á cieľovou platformou.
IN_GROUP	V skupine	Správa je zaradená do kadenčnej skupiny.
BLACKLISTED	Blokovaná	Správa sa nachádza na blackliste a bola zablokovaná.
READ	Prečítaná	Správa bola prečítaná.
PROCESSING	Spracúva sa	Správa je v procese spracovania.
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.

Funkcia sms-groups (Kadenčné skupiny)#

Metóda: POST, GET
Endpoint: /sms-groups

Funkcia slúži na získanie zoznamu všetkých SMS kadenčných skupín.

* - povinný parameter

Parameter	Typ	Popis
*token alebo session_id	string	API token alebo session_id vrátené pomocou metódy auth.
limit	integer	Počet záznamov, ktoré budú vrátené.
startFrom	integer	Vráti záznamy od zadanej hodnoty.

Príklad POST requestu:

JSONXML

URL: https://smsapi.telekom.sk/json/sms-groups

Telo požiadavky:

{
    "token": "****************************************************************",
    "limit": 5,
    "startFrom": 5
}

URL: https://smsapi.telekom.sk/xml/sms-groups

Telo požiadavky:

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

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

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "exists": true,
    "operator": "Telekom"
}

<?xml version="1.0" encoding="UTF-8" ?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <groups count="1">
        <number>
            <id>1000</id> // ID skupiny
            <name>success</name> // Názov skupiny
            <isPaused>false</isPaused> // Odosielanie pozastavené
            <note>Text</note> // Poznámka
        </number>
    </groups>
</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 check_phone_number#

Metóda: POST, GET
Endpoint: /check_phone_number

Funkcia slúži na overenie existencie telefónneho čísla a operátora.

* - povinný parameter

Parameter	Typ	Popis
*token alebo session_id	string	API token alebo session_id vrátené pomocou metódy auth.
*phone_number	string	Telefónne číslo

Príklad POST requestu:

JSONXML

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

Telo požiadavky:

{
    "phone_number":"0900000001",
    "token": "****************************************************************"
}

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

Telo požiadavky:

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

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

JSONXML

{
    "result": {
        "status": "success",
        "description": "",
        "code": "OK"
    },
    "exists": true,
    "operator": "Telekom"
}

<?xml version="1.0" encoding="UTF-8"?>
<response>
    <result>
        <status>success</status>
        <description></description>
        <code>OK</code>
    </result>
    <phone_number>
        <exists>false</exists>
        <operator>Telekom</operator>
    </phone_number>
</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>

API v1#

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

Funkcia auth#

Funkcia ping#

Funkcia send_message#

Funkcia check_message#

Stavy parametra status

Funkcia sms-groups (Kadenčné skupiny)#

Funkcia check_phone_number#

Delivery status callback#