API

Interfejs API od Zadarma pozwala na korzystanie z serwisu dla własnych aplikacji, a także integrację z dowolnymi systemami CRM i programami dla call centrów.

Posługiwanie się API jest bardzo proste i właściwie żaden użytkownik nie powinien mieć z nim trudności.

W API dostępne są wszystkie podstawowe funkcje:

  • Wyświetlanie i zmiana ustawień SIP oraz centrali telefonicznej;
  • Wyświetlanie statystyk i stanu konta;
  • Wykonywanie połączeń (CallBack na numery wewnętrzne i zewnętrzne) oraz wysyłanie wiadomości SMS;
  • Powiadamianie serwera zewnętrznego o każdym połączeniu przychodzącym w centrali telefonicznej, a także wewnętrzne kierowanie połączeń.

Link do API: https://api.zadarma.com

Wersja API: v1

Finalny link do metody: https://api.zadarma.com/v1/METHOD/

Gotową do pracy PHP z API, można pobrać z GitHub.

Autoryzacja

Każde zapytanie, które wymaga autoryzacji, wysyłane jest z dodatkowym nagłówkiem typu:

"Authorization: klucz_użytkownika: podpis"

Klucze do autoryzacji należy pozyskać w Panelu Klienta.

Podpis tworzony jest według następującego algorytmu:

  • Szereg przekazywanych danych (GET, POST, PUT, DELETE) układa się alfabetycznie według nazwy klucza;
  • Z otrzymanego szeregu tworzy się linia zapytania (na przykład, funkcja http_build_query w PHP), przykład „from=DATEFROM&to=DATETO…”;
  • I dalej – łączy się według formuły:
    linia = imię_metoda linia_zapytania md5( linia_zapytania ),
    gdzie “imię_metoda” – linia zapytania, rozpoczynając od domeny (z zaznaczeniem wersji API), do początku wyliczenia parametrów, na przykład - /v1/sip/"
  • Otrzymana linia łączy się dzięki algorytmowi sha1 z sekretnym kluczem użytkownika:
    hash = hash( linia, sekretny klucz )
  • Następnie hash kodowany jest w base64
    podpis = base64_encode( hash )

Przykład na PHP:

ksort($params);
$paramsStr = http_build_query($params);
$sign = base64_encode(hash_hmac('sha1', $method . $paramsStr . md5($paramsStr), $secret));

$header = 'Authorization: ' . $userKey . ':' . $sign;

Gotową do pracy PHP z API, można pobrać z GitHub.

Formaty odpowiedzi: json (domyślny) i xml.

Żeby otrzymać odpowiedź od API w formacie xml, dodaje się do linii zapytania parametr "format=xml".

Ograniczenia

Odpowiedź również przedstawia informację o limitach i obecnym zapytaniu, na przykład:

X-Zadarma-Method: /v1/
X-RateLimit-Reset: 1434371160
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99

gdzie,

  • X-Zadarma-Method - obecna metoda składania zapytania;
  • X-RateLimit-Remaining - liczba pozostałych zapytań, z uwzględnieniem limitu na metodę i użytkownika;
  • X-RateLimit-Limit - łączna liczba ograniczeń zapytania na minutę;
  • X-RateLimit-Reset - czas zresetowania limitu.

Ograniczenia ogólne - 100 zapytań na minutę, na metodach statystycznych - 10 zapytań na minutę.

W przypadku blokady metoda wyświetla odpowiedź z nagłówkiem 429 "You exceeded the rate limit".

Odpowiedź składa się z obowiązkowego klucza "status" (success lub error). Następnie, w zależności od metody, przedstawiane są własne klucze z żądanymi informacjami.

W przypadku błędu wyświetla się dodatkowy klucz "message" z opisem błędu.

Również wszystkie odpowiedzi przedstawiane są z odpowiednimi nagłówkami HTTP.

Przykład odpowiedzi błędu:
JSON:

{
    "status":"error",
    "message":"Check phone's number"
}

XML:

<?xml version="1.0"?›
<answer›
    <status>error</status›
    <message>Check phone's number</message›
</answer›

Dostępne metody:

GET /v1/info/balance/ - stan konta użytkownika.

więcej

Przykład odpowiedzi:
JSON:

{
    "status":"success",
    "balance":10.34,
    "currency":"USD"
}

XML:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <balance>10.34</balance>
    <currency>USD</currency>
</answer>

GET /v1/info/price/ - cena za połączenie z uwzględnieniem obecnego planu taryfowego użytkownika.

więcej

Parametry:
  • number – numer telefonu
  • caller_id (warunkowo) – CallerID, który będzie wykorzystywany przy wykonaniu połączenia.
Przykład odpowiedzi:
JSON:

{
    "status":"success",
    "info":{
        "prefix":"4420",
        "description":"United Kingdom, London",
        "price":0.009,"
        currency":"USD"
    }
}

XML:

<?xml version="1.0"?>
<answer>
<status>success</status>
    <info>
        <prefix>420</prefix>
        <description>United Kingdom, London</description>
        <price>0.009</price>
        <currency>USD</currency>
    </info>
</answer>

GET /v1/tariff/ - informacja o biezącej taryfie użytkownika.

więcej

Przykłąd odpowiedzi:
JSON:

    {
        "status":"success",
        "info": {
            "tariff_id":5,
            "tariff_name":"Standart, special",
            "is_active":false,
            "cost":0,
            "currency":USD,
            "used_seconds":1643,
            "used_seconds_mobile":34,
            "used_seconds_fix":726,
            "tariff_id_for_next_period":5,
            "tariff_for_next_period":Standart, special
        }
    }

    XML:

        <?xml version="1.0"?>
        <answer>
        <status>success</status>
        <info>
            <tariff_id>5</tariff_id>
            <tariff_name>Standart, special</tariff_name>
            <is_active>false</is_active>
            <cost>0</cost>
            <currency>USD</currency>
            <used_seconds>1643</used_seconds>
            <used_seconds_mobile>726</used_seconds_mobile>
            <used_seconds_fix>726</used_seconds_fix>
            <tariff_id_for_next_period>5</tariff_id_for_next_period>
            <tariff_for_next_period>Standart, special</tariff_for_next_period>
        </info>
        </answer>
    

gdzie,

  • tariff_id – ID obecnej taryfy użytkownika;
  • tariff_name – nazwa obecnej taryfy użytkownika;
  • is_active – aktywna czy nie aktywna obecna taryfa;
  • cost – wartość taryfy;
  • currency – waluta taryfy;
  • used_seconds – ilość wykorzystanych w taryfie sekund;
  • used_seconds_mobile – ilość wykorzystanych w taryfie sekund na połączenia komórkowe;
  • used_seconds_fix – ilość wykorzystanych w taryfie sekund na połączenia stacjonarne;
  • tariff_id_for_next_period – ID taryfy użytkownika na kolejny okres;
  • tariff_for_next_period – nazwa taryfy użytkownika na kolejny okres.

GET /v1/request/callback/ - zapytanie o callback.

więcej

Parametry:
  • from – twój numer telefonu, centrali telefonicznej SIP lub numer wewnętrzny, do którego callback wezwanie;
  • to – Twój numer SIP lub wewnętrzny numer centrali telefonicznej (na przykłąd 100), z pomocą którego wykonuję sie połączenie. Będzie wykorzystane CallerID tego numeru, w statystykach będzie wyświetlać się ten numer SIP/PBX, jeżeli dla tego numeru były włączone nagranie rozmów lub prefiks, one też będą wykorzystane;
  • sip (opcjonalnie) – numer SIP użytkownika, jeśli chce on wykorzystać określony CallerID dla danego numeru SIP;
  • predicted (opcjonalnie) – jeśli pojawia się ta opcja, zapytanie występuje jako predykatywne (system początkowo dzwoni na numer „to” i tylko jeśli dodzwoni się, łączy się z Twoim numerem telefonu lub SIP);
Przykład odpowiedzi:
JSON:

{
    "status":"success",
    "from": 442037691880,
    "to": 442037691881,
    "time": 1435573082
}

XML:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <from>442037691880</from>
    <to>442037691881</to>
    <time>1435573082</time>
</answer>

GET /v1/sip/ - lista numerów SIP użytkownika.

więcej

Przykład odpowiedzi:
JSON:

{
    "status":"success",
    "sips":[
        {
            "id":"00001",
            "display_name":"SIP 1",
            "lines":3
        },
        {
            "id":"00002",
            "display_name":"SIP 2",
            "lines":3
        }
    ],
    "left":3
}

XML:

    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <sips>
        <value>
            <id>00001</id>
            <display_name>SIP 1</display_name>
            <lines>3</lines>
        <</value>
        <value>
            <id>00002</id>
            <display_name>SIP 2</display_name>
            <lines>3</lines>
        </value>
    </sips>
    <left>1</left>
    </answer>

gdzie,

  • id – SIP-id;
  • display_name – wyświetlane imię;
  • lines – liczba linii;
  • left – liczba pozostałych SIP, które można utworzyć (zależy od stanu konta użytkownika i ogólnej liczby już utworzonych SIP).

GET /v1/sip//status/ - online-status numeru SIP użytkownika.

więcej

Przykład odpowiedzi:
JSON:

    {
        "status":"success",
        "sip":"00001",
        "is_online":"false"
    }

    XML:

        <?xml version="1.0"?>
        <answer>
            <status>success</status>
            <sip>00001
            <is_online>false</is_online>
        </answer>
    

gdzie,

  • id – SIP-id;
  • is_online – online-status (true|false);

PUT /v1/sip/callerid/ - zmiana CallerID.

więcej

Parametry:
  • id – SIP ID, dla którego powinien być zmieniony Caller ID;
  • number – numer, na który zmienia się Caller ID w międzynarodowym formacie (z listy potwierdzonych lub zakupionych numerów użytkownika).
Przykład odpowiedzi:
JSON:

{
    "status":"success",
    "sip":"00001",
    "new_caller_id":"442037691880"
}

XML:

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <sip>00001</sip>
    <new_caller_id>442037691880</new_caller_id>
</answer>

GET /v1/sip/redirection/ - przedstawienie obecnych przekierowań po numerach SIP użytkownika.

więcej

Parametry:
  • id – (opcjonalnie) wybór konkretnego SIP ID.
Przykład odpowiedzi:
JSON:
{
    "status":"success",
    "info": [
        {
            "sip_id":"00001",
            "status":"on",
            "condition":"always",
            "destination":"phone",
            "destination_value":"442037691880",
        },
        ...
    ]
}

XML:

<?xml version="1.0"?>
<answer>
<status>success</status>
<info>
    <value>
        <sip_id>00001</sip_id>
        <status>on<</status>
        <condition>always</condition>
        <destination>phone</destination>
        <destination_value>442037691880</destination_value>
    </value>
    ...
</info>
</answer>

gdzie,

  • sip_id – SIP id użytkownika;
  • status – obecny status: on lub off;
  • condition – warunki przekazywania: always – zawsze (domyślnie), unavailable – w przypadku niepodniesienia słuchawki lub braku połączenia SIP;
  • destination – dokąd przekazuje się: phone – na numer telefonu, pbx – na centralę centralę telefoniczną;
  • destination_value – numer, na który odbywa się przekazywanie: numer telefonu lub ID centrali telefonicznej.

GET /v1/direct_numbers/ - informacja o numerach telefonicznych użytkownika.

więcej

Przykład odpowiedzi:
JSON:

    {
        "status":"success",
        "info": [
            {
                "number":"442037691880",
                "status":"on",
                "country":"Zjednoczone Królestwo",
                "description":"Londyn",
                "number_name":null,
                "sip":00001,
                "sip_name":null,
                "start_date":"2015-01-01 18:14:44",
                "stop_date":"2016-02-11 18:14:40",
                "monthly_fee":2,
                "currency":USD,
                "channels":2,
                "autorenew":"true",
                "is_on_test":"false",
                "type":"common"
            },
            ...
        ]
    }

    XML:

        <?xml version="1.0"?>
        <answer>
        <status>success</status>
        <info>
            <value>
                <number>442037691880</number>
                <status>on</status>
                <country>Zjednoczone Królestwo</country>
                <description>Londyn</description>
                <number_name>null</number_name>
                <sip>00001</sip>
                <sip_name>Example</sip_name>
                <start_date>2015-01-01 18:14:44</start_date>
                <stop_date>2016-02-11 18:14:40</stop_date>
                <monthly_fee>2</monthly_fee>
                <currency>USD</currency>
                <channels>2</channels>
                <autorenew>true</autorenew>
                <is_on_test>false</is_on_test>
                <type>common</type>
            </value>
            ...
        </info>
        </answer>
    

W zależności od rodzaju pola może się róznić wybieranie numeru!Opis pola:

  • number – kupiony numer telefoniczny użytkownika;
  • status – status numeru;
  • country – karaj (dla common i revenue);
  • description – opis: kraj lub rodzaj (dla common i revenue);
  • number_name – "imie" numeru telefonicznego (ustala się użytkownikiem);
  • sip – SIP, przywiązany do numeru;
  • sip_name – "imie" SIP, przywiązanego do numeru;
  • start_date – data zakupu numeru przez użytkownika;
  • stop_date – data zakończenia terminu płatności numaru użytkownika;
  • monthly_fee – wartość numeru (dla common);
  • currency – waluta wartości numeru (dla common);
  • channels – ilość linii na numerze (dla common);
  • minutes – łączny czas trwania połączeń przychodzących w ciągu bieżącego miesiąca (dla revenue);
  • autorenew – czy automatyczne przedłużenie numeru zostało włączone (dla common, revenue, rufree);
  • is_on_test – czy numer znajduje się na etapie testowym;
  • type – rodzaj numeru: common (numer telefoniczny), inum (bezpłatny międzynarodowy numer), rufree (bezpłatny moskiewski numer), revenue (bezpłatny moskiewski numer 495)

GET /v1/sim/ - informacje o kartach SIM użytkownika.

więcej

Przykład odpowiedzi:
JSON:

    {
        "status":"success",
        "sims": [
            {
                "iccid":"8923416550000723980",
                "name":"My Sim",
                "sip":"00001",
                "phone_number":" 447978027321",
                "redirect_to":"simcard",
                "status":"enabled",
                "internet":"on"
            },
            ...
        ]
    }

    XML:

        <?xml version="1.0"?>
        <answer>
        <status>success</status>
        <sims>
            <value>
                <iccid>8923416550000723980</iccid>
                <name>My Sim</name>
                <sip>00001</sip>
                <phone_number> 447978027321</phone_number>
                <redirect_to>simcard</redirect_to>
                enabled</status>
                on</internet>
            </value>
            ...
        </sims>
        </answer>
    

gdzie,

  • iccid – ID karty-SIM;
  • name – "imie" karty-SIM;
  • sip – SIP, do którego przywiązana karta;
  • phone_number – numer telefiniczny karty;
  • redirect_to – gdzie są przekierowywane połączenia przychodzące na kartę (warianty: simcard, );
  • status – obecny status karty-SIM;
  • internet – wyłączony czy włączony Internet.

PUT /v1/sip/redirection/ - włączenie/wyłączenie przekazywania po numerze SIP.

więcej

Parametry:
  • id – SIP id;
  • status – ustawiony status przekazywania na wybrany numer SIP.
Przykład odpowiedzi:
JSON:

    {
        "status":"success",
        "sip":"00001",
        "current_status":"on"
    }

    XML:

    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <sip>00001</sip>
        <current_status>on</current_status>
    </answer>
    

PUT /v1/sip/redirection/ - zmiana parametrów przekazywania.

więcej

Parametry:
  • id – SIP id;
  • type – typ przekazywania: phone – na telefon;
  • number – numer telefonu.
Przykład odpowiedzi:
JSON:

    {
        "status":"success",
        "sip":"00001",
        "destination":"442037691880"
    }

    XML:

    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <sip>00001</sip>
        <destination>442037691880</destination>
    </answer>
    

GET /v1/pbx/internal/ - ​​wyświetlanie wewnętrznych numerów centrali telefonicznej.

więcej

Przykład odpowiedzi:
JSON:
    {
        "status":"success",
        "pbx_id":1234,
        "numbers": [
            100,
            101,
            ...
        ]
    }

    XML:

    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <pbx_id>1234</pbx_id>
    <numbers>
        <value>100</value>
        <value>101</value>
        ...
    </numbers>
    </answer>
    

gdzie,

  • pbx_id – id centrali telefonicznej użytkownika;
  • numbers – lista wewnętrznych numerów.

GET /v1/pbx/internal//status/ - online-status wewnętrznego numeru centrali telefonicznej

więcej

Przykład odpowiedzi:
JSON:
    {
        "status":"success",
        "pbx_id":1234,
        "number":100,
        "is_online":"false"
    }

    XML:
    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <pbx_id>1234</pbx_id>
        <number>100</number>
        <is_online>false</is_online>
    </answer>
    

gdzie,

  • pbx_id – PBX-ID;
  • number – wewnętrzny numer centrali telefonicznej;
  • is_online – online-status (true|false).

PUT /v1/pbx/internal/recording/ - włączenie nagrywania rozmów dla wewnętrznej centrali telefonicznej.

więcej

Ustawienia:
  • id – wewnętrzne numery centrali telefonicznej;
  • status – status: "on" - włączony, "off" - wyłączony;
  • email – (opcjonalnie) zmiana adres e-mail, na który będą wysłąne nagrane rozmowy. Możesz zaznaczyć do 3-ch adresów email, rozdzielają ich przecinkiem.
Przykład odpowiedzii:
JSON:

    {
        "status":"success",
        "internal_number":100,
        "recording":"on",
        "email":"test@test.com"
    }

    XML:

    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <internal_number>100</internal_number>
        <recording>on</recording>
        <email>on</email>
    </answer>
    

GET /v1/pbx/record/request/ - zapytanie co do plików z nagranymi rozmowami.

więcej

Parametry:
  • call_id – unikalny ID połączenia zapisany w nazwie pliku z nagraną rozmową (jest unikalny dla każdego zapisanego pliku w statystyce);
  • pbx_call_id – stałe ID zewnętrznego połączenia w centrali telefonicznej (niezmienny przy korzystaniu ze scenariuszu, menu głosowego, transferu i td., wyświetla się w statystykach oraz powiadomieniach);
  • lifetime – (opcjonalnie) czas dostępności linku w sekundach (minimum - 180, maksimum - 5184000, domyślnie - 1800).

Uwaga: wystarczy zaznaczyć jeden z dwóch parametrów identyfikacji (pbx_call_id lub call_id), przy określaniu pbx_call_id, linków w odpowiedź na zapytanie może być kilka

Przykład odpowiedzi przy zaznaczeniu tylko call_id, tylko jeden link:
JSON:

    {
        "status":"success",
        "link": "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
        "lifetime_till": "2016-01-01 23:56:22"
    }

    XML:

    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <link>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</link>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
    </answer>
    
Przykład odpowiedzi przy zaznaczeniu tylko pbx_call_id, linków może być kilka:
	JSON:
    {
        "status":"success",
        "links":[
            "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
            "https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3"
        ],
        "lifetime_till": "2016-01-01 23:56:22"
    }

    XML:
    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <links>
        <value>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</value>
        <value>https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3</value>
    </links>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
    </answer>
    

gdzie,

  • link – link do pliku z rozmową;
  • lifetime_till – czas dostępności linku.

POST /v1/sms/send/ - wysyłanie SMS.

więcej

Parametry:
  • number – numer telefonu, na który wysyła się SMS (można podać kilka, oddzielając je przecinkami);
  • message – wiadomość (standardowa wiadomość SMS, w przypadku przekroczenia limitu znaczków – rozdziela się na kilka SMS-ów);
  • caller_id – (opcjonalnie) numer telefonu, z którego będzie wysyłana wiadomość SMS (można wysyłać tylko z listy potwierdzonych numerów użytkownika).

Zwróć uwagę: opcja wysyłania SMS w Rosji nie jest dostępna.

Przykład odpowiedzi:
JSON:

    {
        "status":"success",
        "messages":1,
        "cost":0.24,
        "currency":"USD"
    }

    XML:

    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <value>
            <messages>1</messages>
            <cost>0.24</cost>
            <currency>1</currency>
        </value>
    </answer>
    

GET /v1/statistics/ - otrzymanie ogólnych statystyk.

więcej

Parametry:
  • start - data rozpoczęcia wyświetlania statystyk (format - Y-m-d H:i:s);
  • end - data zakończenia wyświetlania statystyk (format - Y-m-d H:i:s);
  • sip (opcjonalnie) – filtr dla określonego numeru SIP;
  • cost_only (opcjonalnie) – podgląd tylko wykorzystanych środków za dany okres;
  • type (opcjonalnie – tylko dla ogólnej statystyki) – typ zapytania: wspólny (nie występuje w zapytaniu), toll i ru495. (dla statystyk numerów 800 i bezpłatnych numerów 495).

Maksymalny okres otrzymanych statystyk - miesiąc. W przypadku przekroczenia limitu przy zapytaniu, okres automatycznie skraca się do 30 dni. Jeśli nie jest zaznaczona data rozpoczęcia, tą datą uważa się początek obecnego miesiąca. Jeśli nie jest zaznaczona data końcowa, ustala się za nią aktualna data i czas.

Przykład odpowiedzi:
JSON:

    {
        "status":"success",
        "start":"2015-06-01 00:00:00",
        "end":"2015-06-29 13:45:23",
        "stats":[
            {
                "id":"155112249",
                "sip":"00001",
                "callstart":"2015-06-02 12:20:25",
                "from":442037691880,
                "to":442037691881,
                "description":"United Kingdom, London",
                "disposition":"busy",
                "billseconds":0,
                "cost":0.1950,
                "billcost":0.0000,
                "currency":"USD"
            },
            …
        ]
    }

    XML:

    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <start>2015-06-01 00:00:00</start>
        <end>2015-06-29 13:58:22</end>
        <stats>
            <value>
                <id>155112249</id>
                <sip>00001</sip>
                <callstart>2015-06-02 12:20:25</callstart>
                <description>United Kingdom, London</description>
                <disposition>busy</disposition>
                <billseconds>0</billseconds>
                <cost>0.195</cost>
                <billcost>0</billcost>
                <currency>USD</currency>
                <from>442037691880</from>
                <to>442037691881</to>
            </value>
            …
        </stats>
    </answer>
    

gdzie,

  • start – data rozpoczęcia wyświetlania statystyk;
  • end – data zakończenia wyświetlania statystyk;
  • id – ID połączenia;
  • sip – numer SIP;
  • callstart – czas rozpoczęcia połączenia;
  • description – opisanie kierunku połączenia;
  • disposition – stan połączenia:
    • 'answered' – rozmowa,
    • 'busy' – zajęte,
    • 'cancel' - odrzucone,
    • 'no answer' - bez odpowiedzi,
    • 'failed' - nie udało się wykonać,
    • 'no money' - brak środków, przekroczony limit,
    • 'unallocated number' - numer nie istnieje,
    • 'no limit' - przekroczony limit,
    • 'no day limit' - przekroczony dzienny limit,
    • 'line limit' - przekroczony limit linii,
    • 'no money, no limit' - przekroczony limit;
  • billseconds – liczba sekund połączenia;
  • cost – koszt za minutę połączenia na dany kierunek;
  • billcost – koszt opłaconych minut;
  • currency – waluta;
  • from – z jakiego numeru wykonane połączenie;
  • to – dokąd wykonane połączenie.
?type=cost_only:
JSON:

    {
        "status":"success",
        "start":"2015-06-01 00:00:00",
        "end":"2015-06-29 14:03:57",
        "stats":[
            {
                "cost":38.094,
                "currency":"USD",
                "seconds":9785
            }
        ]
    }

    XML:

    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <start>2015-06-01 00:00:00</start>
        <end>2015-06-29 14:03:30</end>
        <stats>
            <value>
                <cost>38.094</cost>
                <currency>USD</currency>
                <seconds>9785</seconds>
            </value>
        </stats>
    </answer>
    

gdzie,

  • cost – koszt połączeń w wybranym okresie;
  • currency – waluta;
  • seconds – liczba sekund.

GET /v1/statistics/pbx/ - statystyki centrali telefonicznej

więcej

Parametry:
  • start - data rozpoczęcia wyświetlania statystyk (format - Y-m-d H:i:s);
  • end - data zakończenia wyświetlania statystyk (format - Y-m-d H:i:s);
  • version - format wyświetlenia statystyki (2 - nowy, 1 - stary);
Przykład odpowiedzi:
JSON:

    {
        "status":"success",
        "start":"2015-06-01 00:00:00",
        "end":"2015-06-30 23:59:59",
        "version":2,
        "stats":[
            {
                "call_id":1439981389.2702773,
                "sip":200,
                "callstart":"2015-06-01 15:04:00",
                "clid":200,
                "destination":5,
                "disposition":"answered",
                "seconds":5,
                "is_recorded":true,
                "pbx_call_id":"in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d"
            },
            …
        ]
    }

    XML:

    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <start>2015-06-01 00:00:00</start>
        <end>2015-06-30 23:59:59</end>
        <version>2</version>
        <stats>
            <value>
                <call_id>1439981389.2702773</call_id>
                <sip>200</sip>
                <callstart>2015-06-01 15:04:00</date>
                <clid>200</clid>
                <destination>5</destination>
                <disposition>answered</disposition>
                <seconds>5</seconds>
                <is_recorded>true</is_recorded>
                <pbx_call_id>in_ae6b03b3b0765d127ec0b739209346bbc4f0d52d</pbx_call_id>
            </value>
            …
            </stats>
    </answer>
    

gdzie,

  • start – data rozpoczęcia wyświetlania statystyk;
  • end – data zakończenia wyświetlania statystyk;
  • version - format wyświetlenia statystyki (2 - nowy, 1 - stary);
  • call_id – unikalny id połączenia, ten id zaznacza się w nazwie pliku z nagraniem rozmowy (unikalny dla każdego nagrania w statystyce);
  • call_id – id połączenia;
  • sip – numer SIP;
  • callstart – czas rozpoczęcia połączenia;
  • clid – CallerID;
  • destination – dokąd wykonano połączenie;
  • disposition – stan połączenia:
    • 'answered' – rozmowa,
    • 'busy' – zajęte,
    • 'cancel' - odrzucone,
    • 'no answer' – bez odpowiedzi,
    • 'failed' – nie udało się wykonać,
    • 'no money' – brak środków, przekroczony limit,
    • 'unallocated number' – numer nie istnieje,
    • 'no limit' – przekroczony limit,
    • 'no day limit' – przekroczony dzienny limit,
    • 'line limit' – przekroczony limit linii,
    • 'no money, no limit' – przekroczony limit;
  • seconds – liczba sekund połączenia;
  • is_recorded – (true, false) czy rozmowa była nagrana;
  • pbx_call_id – stały ID wewnętrznego połączenia w centrali telefonicznej (stały przy wykorzystaniu scenariuszu, menu głosowego, transferu i td., wyświetla się w statystyce oraz powiadomieniach);

GET /v1/statistics/callback_widget/ - statystyki Widgetu callback

więcej

Parametry:
  • start - data rozpoczęcia wyświetlania statystyk (format - Y-m-d H:i:s);
  • end - data zakończenia wyświetlania statystyk (format - Y-m-d H:i:s);
  • widget_id - (opcjonalnie) - identyfikator widgeta, jeżeli nie ma danego identyfikatora należy sprawdzać statystykę dla wszystkich widgetów;

Maksymalny okres otrzymanych statystyk - miesiąc. W przypadku przekroczenia limitu przy zapytaniu, okres automatycznie skraca się do 30 dni. Jeśli nie jest zaznaczona data rozpoczęcia, tą datą uważa się początek obecnego miesiąca. Jeśli nie jest zaznaczona data końcowa, ustala się za nią aktualna data i czas.

Przykład odpowiedzi:
JSON:

    {
        "status":"success",
        "start":"2016-09-01 00:00:00",
        "end":"2016-09-30 23:59:59",
        "stats":[
            {
                "id":"57d16d6a1e46c53d1f8ce323",
                "widget_id":"1",
                "sip":"00001",
                "ip":"127.0.0.1",
                "actions":[
                    {
                        "kind":"come",
                        "date":"2016-09-08 16:53:45",
                        "referrer_url":"http://test.domain.com/page1/",
                        "url":"http://home.domain.com/page2/" 
                    },
                    {
                        "kind":"show",
                        "date":"2016-09-08 16:53:46",
                        "rate":15
                    },
                    {
                        "kind":"call_request",
                        "date":"2016-09-08 16:54:07",
                        "number":"442037691880",
                        "request_call_date":"2016-09-09 10:00:00",
                        "redial":"n" 
                    },
                    {
                        "kind":"close",
                        "date":"2016-09-08 16:54:35" 
                    }
                ]
            },
            ...
        ]
    }    

    XML:

    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <start>2016-09-01 00:00:00</start>
        <end>2016-09-30 23:59:59</end>
        <stats>
            <value>
                <id>57d16d6a1e46c53d1f8ce323</id>
                <widget_id>1</widget_id>
                <sip>00001</sip>
                <ip>127.0.0.1</ip>
                <actions>
                    <value>
                        <kind>come</kind>
                        <date>2016-09-08 16:53:45</date>
                        <referrer_url>http://test.domain.com/page1/</referrer_url>
                        <url>http://home.domain.com/page2/</url>
                    </value>
                    <value>
                        <kind>show</kind>
                        <date>2016-09-08 16:53:46</date>
                        <rate>15</rate>
                    </value>
                    <value>
                        <kind>call_request</kind>
                        <date>2016-09-08 16:54:07</date>
                        <number>442037691880</number>
                        <request_call_date>2016-09-09 10:00:00</request_call_date>
                        <redial>n</redial>
                    </value>
                    <value>
                        <kind>close</kind>
                        <date>2016-09-08 16:54:35</date>
                    </value>
                </actions>
            </value>
            ...
        </stats>
    </answer>    
    

gdzie,

  • start – data rozpoczęcia wyświetlania statystyk;
  • end – data zakończenia wyświetlania statystyk;
  • id – identyfikator sesji;
  • widget_id – id widgetu;
  • sip – SIP-numer;
  • ip – IP-adres klienta;
  • kind – rodzaj wydarzenia:
    • 'come' – klient otworzył stronię z widgetem,
    • 'show' – wyświetlony panel widgetu,
    • 'call' – zamówienie połączenia,
    • 'call_request' – zamówienie zaplanowanego połączenia,
    • 'rate' – klient dodał opinię o rozmowie,
    • 'fail' – klient zaznaczył, że połączenie nie było wykonane,
    • 'close' – klient zamknął panel widgetu;
  • date – data i czas wydarzenia;
  • referrer_url – adres strony, dzięki której klient otworzył stronę z widgetem (tylko dla wydarzenia 'come');
  • url – adres strony widgetu (tylko dla wydarzenia 'come');
  • rate – dla wydarzenia 'show' - ilość łącznych kryterium, dla wydarzenia 'rate' - ocena rozmowy;
  • request_call_date – data i czas zaznaczony klientem, dla realizowania zaplanowanego połączenia (tylko dla wydarzenia 'call_request');
  • redial – (true, false) identyfikator, czy było realizowane zaplanowane połączenie (tylko dla wydarzenia 'call_request');
  • number – numer, który podał klient (dla wydarzeń 'call', 'call_request', 'rate', 'fail').

Informacja o połączeniach przychodzących

System Zadarma może wysyłać informacje o każdym połączeniu przychodzącym w wirtualnej centrali telefonicznej i przekierowywać połączenie na wymagany numer wewnętrzny, w zależności od odpowiedzi. W tym celu należy utworzyć link z ogólnie otwartym dostępem, który będzie odbierać zapytanie POST z informacjami od systemu Zadarma.

Istniejące rodzaje powiadomień:

NOTIFY_START - czas rozpoczęcia połączenia wchodzącego z centrali telefonicznej.

szczegóły

Parametry, które będą wysłane pod link dla zawiadomienia:

  • event – wydarzenia (NOTIFY_START)
  • call_start – czas rozpoczęcia rozmowy;
  • pbx_call_id – id połączenia;
  • caller_id – numer osoby dzwoniącej;
  • called_did – numer, na który było wykonane połączenie.

NOTIFY_INTERNAL - czas rozpoczęcia połączenia na wewnętrzny numer centrali telefonicznej.

szczegóły

Parametry, które będą wysłane pod link dla zawiadomienia:

  • event – wydarzenie (NOTIFY_INTERNAL)
  • call_start – czas rozpoczęcia połączenia;
  • pbx_call_id – id połączenia;
  • caller_id – numer osoby dzwoniącej;
  • called_did – numer na króty było wykonane połączenia;
  • internal – (nieobowiązkowy)wewnętrzny numer.

NOTIFY_END - czas zakończenia połączenia wchodzącego na wewnętrzny numer centrali telefonicznej.

szczegóły

Parametry, które będą wysłane pod link dla zawiadomienia:

  • event – wydarzenie (NOTIFY_END)
  • call_start – czas rozpoczęcia połączenia;
  • pbx_call_id – id połączenia;
  • caller_id – numer osoby dzwoniącej;
  • called_did – numer na króty było wykonane połączenia;
  • internal – (nieobowiązkowy) wewnętrzny numer;
  • duration – czas trwania w sekundach;
  • disposition – stan połączenia:
    • 'answered' – rozmowa,
    • 'busy' – zajęte,
    • 'cancel' - odrzucone,
    • 'no answer' - bez odpowiedzi,
    • 'failed' - nie udało się wykonać,
    • 'no money' - brak środków, przekroczony limit,
    • 'unallocated number' - numer nie istnieje,
    • 'no limit' - przekroczony limit,
    • 'no day limit' - przekroczony dzienny limit,
    • 'line limit' - przekroczony limit linii,
    • 'no money, no limit' - przekroczony limit;
  • status_code – kod statusu połączenia Q.931;
  • is_recorded – 1 - nagrywanie połaczenia, 0 - bez nagrywania;
  • call_id_with_rec – id połączenia z funkcją nagrywania.

NOTIFY_OUT_START - czas rozpoczęcia połączenia wychodzącego z centrali telefonicznej.

szczegóły

Parametry, które będą wysłane pod link dla zawiadomienia:

  • event – wydarzenie (NOTIFY_OUT_START)
  • call_start – czas rozpoczęcia połączenia;
  • pbx_call_id – id połączenia;
  • destination – numer na który było wykonane połączenie;
  • internal – (nieobowiązkowy) wewnętrzny numer.

NOTIFY_OUT_END - czas zakończenia połączenia wychodzącego z centrali telefonicznej.

szczegóły

Parametry, które będą wysłane pod link dla zawiadomienia:

  • event – wydarzenie (NOTIFY_OUT_END)
  • call_start – czas rozpoczęcia połączenia;
  • pbx_call_id – id połączenia;
  • caller_id – numer osoby dzwoniącej;
  • destination – numer na króty było wykonane połączenia;
  • internal – (nieobowiązkowy) wewnętrzny numer;
  • duration – czas trwania w sekundach;
  • disposition – stan połączenia:
    • 'answered' – rozmowa,
    • 'busy' – zajęte,
    • 'cancel' - odrzucone,
    • 'no answer' - bez odpowiedzi,
    • 'failed' - nie udało się wykonać,
    • 'no money' - brak środków, przekroczony limit,
    • 'unallocated number' - numer nie istnieje,
    • 'no limit' - przekroczony limit,
    • 'no day limit' - przekroczony dzienny limit,
    • 'line limit' - przekroczony limit linii,
    • 'no money, no limit' - przekroczony limit;
  • status_code – kod statusu połączenia Q.931;
  • is_recorded – 1 - nagrywanie połaczenia, 0 - bez nagrywania;
  • call_id_with_rec – id połączenia z funkcją nagrywania.

Zaznaczyć link dla powiadomień jak również włączyć/wyłąćzyć każdy rodzaj powiadomienia możesz na stronie Swojej API.

Aby system zaakceptował link, należy na początku skryptu koniecznie dodać kod weryfikacyjny.

Przykład w PHP:

<?php if (isset($_GET['zd_echo'])) exit($_GET['zd_echo']); ?>

W celu zwiększenia bezpieczeństwa rekomendujemy zezwolić dostęp do Twojego linku tylko z IP 185.45.152.42.

Również, jeżeli udostępniłeś klucze dostępu do API, w każdym zapytaniu o Twóim linku będzie wyświetlał się dodatkowy nagłowek "Signature", zgodnie z którym również możesz zweryfikować integralność i autentyczność danych.

Ustawienie podpisu do sprawdzenia, przykład na PHP:

$signatureTest = base64_encode(hash_hmac('sha1', $_POST['caller_id'] . $_POST['called_did'] . $_POST['call_start'], API_SECRET));

Dla każdego zapytania możesz łatwo zmienić scenariusz pracy dla obecnego połączenia, wysyłając w ramach odpowiedzi na informację:

{
    "redirect": ID,
    "caller_name": NAME
}

где,

  • redirect – ID scenariusza przekierowania lub wirtualny numer centrali telefonicznej, "blacklist" - w tym przypadku połączenie zostanie odrzucone z sygnał zajętości;
  • caller_name – można nadać nazwę numerowi połączenia przychodzącego.

Maksymalny czas odpowiedzi z informacją o przekierowaniu , a nazwa hotelu - 2 sekundy.

Przykładowy skrypt może wyglądać w naszym repozytorium na GitHub.