Interfejs 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. Realizacja API jest otwarta, każdy programista poradzi sobie z nią ze względu na niski stopień skomplikowania.

W API dostępne są wszystkie niezbędne fukcję:

  • wyświetlenie ustawień SIP i centrali;
  • wyświetlenie statystyk i salda konta;
  • wysłanie połączeń (CallBack na numery zewnętrzne i wewnętrzne) oraz wiadomości SMS;
  • powiadomienia zewnętrznego serwera o połączeniu przychodzącym w centrali, a także zewnętrzne trasowanie połaczeń.

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

Wersja API: v1

Końcowy link do metody: https://api.zadarma.com/v1/METHOD/

Pobierz gotowe klasy PHP, C#, Python dla pracy z API z naszego GitHub.

Instrukcja integracji własnego systemu CRM i telefonii VoIP Zadarma

Autoryzacja

Każde żądanie, które wymaga autoryzacji, wysyłane jest z dodatkowym nagłówkiem typu:
"Authorization: klucz_użytkownika: podpis"

Klucze do autoryzacji należy wygenerować 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 (np, 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 jest haszowana 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, null, '&', PHP_QUERY_RFC1738);

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

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

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

Format odpowiedzi: json (domyślnie) i xml.

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

Ograniczenia

Odpowiedź również przedstawia informację o limitach i obecnym żądaniu, 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 żądania;
  • X-RateLimit-Remaining - ilość pozostałych żądań, 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:

  • /v1/info/balance/
    saldo użytkownika.
  • /v1/info/price/
    cena na połączenia zgodnie z wybraną taryfą użytkownika.
  • /v1/info/timezone/
    strefa czasowa użytkownika.
  • /v1/tariff/
    informacja o obecnej taryfie użytkownika.
  • /v1/request/callback/
    callback.
  • /v1/sip/
    lista loginów SIP.
  • /v1/sip/<SIP>/status/
    online status SIP loginów.
  • /v1/sip/callerid/
    zmiana CallerID.
  • /v1/sip/redirection/
    wyświetlanie obecnych przekierowań na loginach SIP użytkownika.
  • /v1/direct_numbers/
    informacja o numerach wirtualnych użytkownika.
  • /v1/sip/redirection/
    włączenie/wyłączenie przekierowania na loginie SIP.
  • /v1/sip/redirection/
    zmiana przekierowania.
  • /v1/pbx/internal/
    wyświetlanie numerów wewnętrznych wirtualnej centrali.
  • /v1/pbx/internal/<PBXSIP>/status/
    online status numeru wewnętrznego.
  • /v1/pbx/internal/recording/
    włączenie nagrywania rozmów na numerze wewnętrznym.
  • /v1/pbx/record/request/
    żądanie na pobranie nagrania rozmowy.
  • /v1/pbx/redirection/
    zmiana paramentrów przekierowania na numerze wewnętrzym centrali.
  • /v1/pbx/redirection/
    otrzymanie paramentrów przekierowania na numerze wewnętrznym.
  • /v1/sms/send/
    wysłanie SMS.
  • /v1/statistics/
    otrzymanie ogólnych statystyk.
  • /v1/statistics/pbx/
    statystyki centrali wirtualnej telefonicznej.
  • /v1/statistics/callback_widget/
    statystyki Widgetu CallBack.
  • /v1/info/number_lookup/
    aktualizacja bazy klientów.
  • /v1/speech_recognition/
    uzyskanie wyników rozpoznawania.
  • /v1/speech_recognition/
    rozpoczęcie rozpoznawania.
  • JSON
  • XML
{
    "status":"success",
    "balance":10.34,
    "currency":"USD"
}

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

Parametry:

  • number – numer telefonu
  • caller_id (nieobowiązkowy) – CallerID, jaki będzie wyświetlony przy wykonaniu połączenia.
  • JSON
  • XML
{
    "status":"success",
    "info":{
        "prefix":"4420",
        "description":"United Kingdom, London",
        "price":"0.009",
        "currency":"USD",
    }
}

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

  • JSON
  • XML
{
    "status":"success",
    "unixtime":1483228800,
    "datetime":"2017-01-01 00:00:00",
    "timezone":"UTC+0"
}

<?xml version="1.0"?>
<answer>
    <status>success</status>
    <unixtime>1483228800</unixtime>
    <datetime>2017-01-01 00:00:00</datetime>
    <timezone>UTC+0</timezone>
</answer>

  • JSON
  • XML
{
    "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 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 – czy jest aktywna obecna taryfa lub nie;
  • cost – cena taryfy;
  • currency – waluta taryfy;
  • used_seconds – ilość wykorzystanych sekund taryfy;
  • used_seconds_mobile – ilość wykorzystanych sekund taryfy na komórkowe;
  • used_seconds_fix – ilość wykorzystanych sekund taryfy na stacjonarne;
  • tariff_id_for_next_period – ID taryfy użytkownika na następny okres;
  • tariff_for_next_period – nazwa taryfy użytkownika na następny okres.

Parametry:

  • from – Twój numer telefonu lub SIP, lun numer wewnętrzny centrali, lub numer scenariuszu, na jaki jest kierowany callback;
  • to – numer telefonu lub SIP, na jaki dzwonisz;
  • sip (nieobowiązkowy) – numer SIP użytkownika numer wewnętrzny centrali (np. 100), przez który będzie kierowane połączenie. Będzie wykorzystany CallerID tego numeru, w statystkach będzie wyświetlony dany numer SIP/centrali, jeśli dla danego numeru jest włączone nagrywanie rozmów lub prefiksy na połączenia wychodzące - będzie to użyte
  • predicted (nieobowiązkowy) – jeśli podany ten parametr, żądani jest predykatywne (system wykonuje połączenia na numer "to" i tylko w przypadku odpowiedzi, następnie dzwoni na numer abonenta).
  • JSON
  • XML
{
    "status":"success",
    "from": 442037691880,
    "to": 442037691881,
    "time": 1435573082
}

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

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

<?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świetlone imię;
  • lines – ilość linii;
  • left – ilość pozostałych SIP, jaki można utworzyć (zależy od salda na koncie i ilości już utworzonych SIP).
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "is_online":"false"
}

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

Parametry:

  • id – SIP id, jakiemu zmieniasz CallerID;
  • number – numer, na jaki zmieniasz w formacie międzynarodowym (z listy numerów potwierdzonych lub wykupionych).
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "new_caller_id":"442037691880"
}

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

Parametry:

  • id – (nieobowiązkowy) wybór konkretnego SIP id.
  • JSON
  • XML
{
    "status":"success",
    "info": [
        {
        "sip_id":"00001",
        "status":"on",
        "condition":"always",
        "destination":"phone",
        "destination_value":"442037691880",
        },
    ...
    ]
}

<?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 – warunek przekierowania: always –zawsze (domyślnie), unavailable – w przypadku nie odpowiedzi lub nie dostępności;
  • destination – na jaki numer przekierowanie: phone – na numer telefonu, pbx – numer wewnętrzny centrali;
  • destination_value – na jaki numer przekierowanie: phone – na numer telefonu lub ID centrali.
  • JSON
  • XML
{
    "status":"success",
    "info": [
        {
            "number":"442037691880",
            "status":"on",
            "country":"Great Britain",
            "description":"London",
            "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 version="1.0"?>
<answer>
    <status>success</status>
    <info>
        <value>
            <number>442037691880</number>
            <status>on</status>
            <country>Великобритания</country>
            <description>Лондон</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 typu numeru parametry mogą się różnić! Opis parametrów:

  • number – podłączony numer wirtualny użytkownika;
  • status – status numeru;
  • country – kraj (dla common i revenue);
  • description – opis: miasto lub typ (dla common i revenue);
  • number_name – "imię" numeru wirtualnego (ustawione użytkownikiem);
  • sip – SIP, podpięty do numeru;
  • sip_name – "imię" SIP, podpięte do numeru;
  • start_date – data aktywacji numeru użytkownikiem;
  • stop_date – data końca ważności numeru użytkownika;
  • monthly_fee – cena za numer (dla common);
  • currency – waluta podanej ceny (dla common);
  • channels – ilość linii na numerze (dla common);
  • minutes – całkowity czas rozmów przychodzących za obecny miesiąc (dla revenue);
  • autorenew – czy jest włączone automatyczne przedłużanie numeru (dla common, revenue, rufree);
  • is_on_test – czy jest włączony "test" dla numeru;
  • type – typ numeru: common (numer wirtualny), inum (darmowy numer międzynarodowy), rufree (darmowy numer moskiewski), revenue (darmowy numer moskiewski 495)

Parametry:

  • id – SIP id;
  • status – status przekierowania na wybrany numer SIP.
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "current_status":"on"
}

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

Parametry:

  • id – SIP id;
  • type – typ przekierowania – na telefon;
  • number – numer telefonu.
  • JSON
  • XML
{
    "status":"success",
    "sip":"00001",
    "destination":"442037691880"
}

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

  • JSON
  • XML
{
    "status":"success",
    "pbx_id":1234,
    "numbers": [
        100,
        101,
        ...
    ]
}

<?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 użytkownika centrali;
  • numbers – lista numerów wewnętrznych.
  • JSON
  • XML
{
    "status":"success",
    "pbx_id":1234,
    "number":100,
    "is_online":"false"
}

<?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 – id centrali telefonicznej;
  • number – numer wewnętrzny centrali;
  • is_online – online status (true|false).

Parametry:

  • id – numer wewnętrzny centrali;
  • status – status: "on" - włączony, "off" - wyłączony, "on_email" - włącz nagranie tylko na email, "off_email" - wyłącz nagranie tylko na email, "on_store" - włącz nagranie do chmury, "off_store" - wyłącz nagranie do chmury;
  • email – (nieobowiązkowy) zmiana email, na jaki będą kierowane nagrania rozmów. Możesz podać do 3-trzech adresów email, rozdzielając przecinkiem.
  • JSON
  • XML
{
    "status":"success",
    "internal_number":100,
    "recording":"on",
    "email":"test@test.com"
}

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

Parametry:

  • call_id – indywidualny id połączenia, ten id jest podany w nazwie pliku z nagraniem (indywidualny dla każdego nagrania w statystykach);
  • pbx_call_id – stały ID zewnętrznego połączenia w ramach Centrali (nie zmienia się według scenariuszu, menu głosowego, transferu itd.,wyświetlany jest w statystykach i powiadomieniach).;
  • lifetime – (nieobowiązkowy) czas ważności linku w sekundach ( min. - 180, maks. - 5184000, domyślnie - 1800).

Uwaga: wystarczy podać jeden z dwóch paramentów (pbx_call_id или call_id), przy podaniu pbx_call_id linków w odpowiedzi na żądanie może być kilka.

  • JSON
  • XML

Przykład odpowiedzi kiedy ustawiony tylko call_id, tylko jeden link:

{
    "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"
}

Przykład odpowiedzi kiedy ustawiony tylko pbx_call_id, сlinków może być kilka:

{
    "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"
}

Przykład odpowiedzi kiedy ustawiony tylko call_id, tylko jeden link:

<?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 kiedy ustawiony tylko pbx_call_id, сlinków może być kilka:

<?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>

Parametry:

  • link – link do pobrania nagrania;
  • lifetime_till – czas ważności linku.

Parametry:

Aby włączyć i skonfigurować przekierowanie:

  • pbx_number – numer wewnętrzny centrali, np 100;
  • status – on;
  • type – typ przekierowania voicemail lub phone;
  • destination – numer telefonu lub email, w zależności od wybranej opcji wyżej;
  • condition – warunek przekierowania: always lub noanswer;
  • voicemail_greeting – powiadomienie o przekierowaniu: no, standart, own. Dostępne tylko przy type = voicemail;
  • greeting_file – audio plik w formacie mp3 lub wav do 5 MB. Dostępne przy type = voicemail i voicemail_greeting = own;

Aby wyłączyć przekierowanie:

  • pbx_number – numer wewnętrzny centrali, np 100;
  • status – off;
  • JSON
  • XML
{
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
    }

<?xml version="1.0"?>
    <answer>
    <status>success</status>
    <current_status>on</current_status>
    <pbx_id>1234</pbx_id>
    <pbx_name>100</pbx_name>
    <type>phone</type>
    <destination>79123456789</destination>
    <condition>noanswer</condition>
    </answer>

Parametry:

  • pbx_number – numer wewnętrzny centrali, np 100;
  • JSON
{
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
    }

Parametry:

  • number – numer telefonu, do jakiego będzie wysłane SMS (można podać kilka numerów, rozdzielając przecinkiem);
  • message – wiadomość (standardowe ograniczenia na ilość znaków SMS, w przypadku przekroczenia limitu – dzieli się na kilka woadmości SMS);
  • caller_id – (nieobowiązkowy) numer telefonu, od którego zostanie wysłana wiadomość SMS (można podać tylko z listy potwierdzonych numerów).
Uwaga: wysyłka SMS dostępna tylko za granicę Rosyjskiej Federacji.
  • JSON
  • XML
{
    "status":"success",
    "messages":1,
    "cost":0.24,
    "currency":"USD"
}

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

Parametry:

  • start - data początku wyświetlenia statystyk (format - YYYY-MM-DD HH:MM:SS);
  • end - data końcowa wyświetlenia statystyk (format - YYYY-MM-DD HH:MM:SS);
  • sip (nieobowiązkowy) - filtr dla konkretnego loginu SIP;
  • cost_only (nieobowiązkowy) - podgląd tylko kosztów na rozmowy za wybrany okres;
  • type (nieobowiązkowy - tylko dla wspólnych statystyk) - typ żądania: wspólny (nie zaznaczony), toll oraz ru495. (dla statystyk numerów toll free 800 oraz numeru moskiewskiego 495).
  • skip (nieobowiązkowy - za wyjątkiem parametru cost_only) - ilość linii, jakie należy pominąć, wynik zaczyna się od linii skip + 1 (używany do podziału wraz z parametrem limit, domyślnie jest równy 0);
  • limit (nieobowiązkowy - za wyjątkiem parametru cost_only) - ograniczenie na ilość linii (używany do podziału wraz z parametrem skip, maks. 1000, domyślnie 1000).

Maksymalny okres otrzymania statystyk - miesiąc. W przypadku przekroczenia limitu w żądaniu - okres automatycznie jest zmieniony na na miesiąc (do 30 dni). Jeśli nie jest podana data początku statystyk - zostanie wybrana pierwsza data obecnego miesiąca. Jeśli nie jest podana data końca - zostanie wybrana dzisiejsza data i czas.

  • JSON
  • XML
{
    "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"
        },
        …
    ]
}

?type=cost_only:
{
    "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 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>

?type=cost_only:
<?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

  • start – data początku wyświetlenia statystyk;
  • end – data końcowa wyświetlenia statystyk;
  • id – id połączenia;
  • sip – SIP login;
  • callstart – czas rozpoczęcia połączenia;
  • description – opis kierunki połaczenia;
  • disposition – stan połączenia:
    • 'answered' – rozmowa,
    • 'busy' – zajęte,
    • 'cancel' - odrzucone,
    • 'no answer' - brak odpowiedzi,
    • 'failed' - nieudane,
    • '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 – czas trwania w sekundach;
  • cost – cena za minutę na sany kierunek;
  • billcost – cena opłaconych minut;
  • currency – waluta;
  • from – numer osoby dzwoniącej;
  • to – numer na który było wykonane połączenia.

Parametry:

  • start - data początku wyświetlenia statystyk (format - YYYY-MM-DD HH:MM:SS);
  • end - data końcowa wyświetlenia statystyk (format - YYYY-MM-DD HH:MM:SS);
  • version - format wyświetlenia (2 - nowy, 1 - stary);
  • skip (nieobowiązkowy - za wyjątkiem parametru cost_only) - ilość linii, jakie należy pominąć, wynik zaczyna się od linii skip + 1 (używany do podziału wraz z parametrem limit, domyślnie jest równy 0);
  • limit (nieobowiązkowy - za wyjątkiem parametru cost_only) - ograniczenie na ilość linii (używany do podziału wraz z parametrem skip, maks. 1000, domyślnie 1000).
  • call_type (nieobowiązkowy) - kierunek połączeń ('in' dla przychodzących, 'out' dla wychodzących). Jeśli nie jest zawarty, zostaną wyświetlone wszystkie połączenia.
  • JSON
  • XML
{
    "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 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 początku wyświetlenia statystyk;
  • end – data początku wyświetlenia statystyk;
  • version - format wyświetlenia (2 - nowy, 1 - stary);
  • call_id – indywidualny id połączenia, ten id jest podany w nazwie pliku z nagraniem (indywidualny dla każdego nagrania w statystykach);
  • sip – SIP login;
  • callstart – czas rozpoczęcia połączenia;
  • clid – CallerID;
  • destination – numer na który było wykonane połączenia;
  • disposition – stan połączenia:
    • 'answered' – rozmowa,
    • 'busy' – zajęte,
    • 'cancel' - odrzucone,
    • 'no answer' - brak odpowiedzi,
    • 'failed' - nieudane,
    • '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 – czas trwania w sekundach;
  • is_recorded – (true, false) czy jest nagranie rozmowy lub nie;
  • pbx_call_id – stały ID zewnętrznego połączenia w ramach Centrali (nie zmienia się według scenariuszu, menu głosowego, transferu itd.,wyświetlany jest w statystykach i powiadomieniach);

Parametry:

  • start - data początku wyświetlenia statystyk (format - YYYY-MM-DD HH:MM:SS);
  • end - data końcowa wyświetlenia statystyk (format - YYYY-MM-DD HH:MM:SS);
  • widget_id - (nieobowiązkowy) - identyfikator widgetu, w przypadku braku tego parametru - statystyki dla wszystkich widgetów;
  • type (nieobowiązkowy - tylko dla wspólnych statystyk) - typ żądania: wspólny (nie zaznaczony), toll oraz ru495. (dla statystyk numerów toll free 800 oraz numeru moskiewskiego 495).
Maksymalny okres otrzymania statystyk - miesiąc. W przypadku przekroczenia limitu w żądaniu - okres automatycznie jest zmieniony na na miesiąc (do 30 dni). Jeśli nie jest podana data początku statystyk - zostanie wybrana pierwsza data obecnego miesiąca. Jeśli nie jest podana data końca - zostanie wybrana dzisiejsza data i czas.
  • JSON
  • XML
{
    "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 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 początku wyświetlenia statystyk;
  • end – data końcowa wyświetlenia statystyk;
  • id – id secji;
  • widget_id – id widgetu;
  • sip – SIP login;
  • ip – IP adres użytkownika;
  • kind – typ wydarzenia:
    • 'come' – użytkownik odwiedził stronę z widgetem,
    • 'show' – otwarty formularz widgetu,
    • 'call' – zamówienie połączenia,
    • 'call_request' – zamówienie zaplanowanego połączenia,
    • 'rate' – użytkownik ocenił rozmowę,
    • 'fail' – użytkownik zaznaczył opcję, że rozmowa się nie odbyła,
    • 'close' – użytkownik zamknął formularz widgetu;
  • date – data i czas wydarzenia;
  • referrer_url – adres strony, z jakiej użytkownik odwiedził stronę z widgetem (tylko dla wydarzenia 'come');
  • url – adres strony widgeu (tylko dla wydarzenia 'come');
  • rate – dla wydarzenia 'show' - ilość uzyskanych punktów, dla wydarzenia 'rate' - ocena rozmowy;
  • request_call_date – data i czas zaznaczony użytkownikiem, jako wygodny termin odebrania połaczenia (tylko dla wydarzenia 'call_request');
  • redial – (true, false) czy zostało zrealizowane połączenie zwrotne lub nie (tylko dla wydarzenia 'call_request');
  • number – numer podany użytkownikiem (dla wydarzeń 'call', 'call_request', 'rate', 'fail').

Parametry:

  • numbers – lista numerów w formacie międzynarodowym.

Jeśli numbers zawiera 1 numer, wynik będzie wysłany od razu, jeśli podana jest lista numerów, wynik zostanie wysłany mailowo, lub na podany adres url

Zwróć uwagę: ustawienia danej metody można zmieniać tylko w Panelu klienta na stronie aktualizacji.

Przykład odpowiedzi dla 1 numeru:


{
    "status":"success",
    "info":{
        'mcc' : '250',
        'mnc': '01',
        'mccName': 'Russia',
        'mncName': 'Mobile TeleSystems',
        'ported': false,
        'roaming': false,
        'errorDescription': 'No Error'
    }
}

Przykład odpowiedzi dla kliku numerów:


{
    "status":"success"
}

Przykład wyniku, wysłanego na adres, podany na stronie aktualizacji:


{
    'success': true,
    'description': 'Проверено успешно',
    'result': [
        {
            'mcc': '250',
            'mnc': '01',
            'ported': false,
            'roaming': false,
            'errorDescription': 'No Error',
            'mccName': 'Russia',
            'mncName': 'Mobile TeleSystems',
            'number': '791234567890',
        }, ...
    ]
}

Parametry:

  • call_id – unikalny id połączenia, ten id jest wskazany w nazwie pliku z nagraniem połączenia (unikalny dla każdego nagrania w statystykach);
  • lang - język rozpoznawania (opcjonalnie);
  • return - zwrócony wynik. Opcje: words - słowa, phrases - zwroty. (opcjonalny. domyślnie phrases);
  • alternatives - czy zwracać alternatywne opcje. Opcje: 0 - nie, 1 - tak. (opcjonalny. domyślnie 0).
  • JSON
{
    "status": "success",
    "lang": "en-EN",
    "recognitionStatus": "in progress",
    "otherLangs": ["es-ES"],
    "words": [
        {
            "result": [
                {
                        "s": 0.02,
                        "e": 0.22,
                        "w": "word",
                },
                {
                        "s": 0.31,
                        "e": 0.56,
                        "w": "one",
                }
            ],
            "channel": 1
        }
    ],
    "phrases": [
        {
            "result": "word one",
            "channel": 1
        }
    ]
}

gdzie

  • lang – język;
  • recognitionStatus: status rozpoznania. Opcje:
    • in progress - w procesie rozpoznania,
    • error - wystąpił błąd podczas rozpoznawania,
    • recognized - rozpoznano,
    • ready for recognize - nagranie gotowe do rozpoznania,
    • not available for recognize - nagranie nie jest dostępne do rozpoznania
  • result:
    • words - tablica:
      • result - lista słów (tablica):
        • s - czas rozpoczęcia słowa
        • e - czas rozpoczęcia słowa
        • w - słowo
      • channel - numer kanału
    • phrases - tablica:
      • result - fraza
      • channel - numer kanału

Parametry:

  • call_id – unikalny id połączenia, ten id jest wskazany w nazwie pliku z nagraniem połączenia (unikalny dla każdego nagrania w statystykach);
  • lang - język rozpoznawania (opcjonalnie).
  • JSON
{
    'status' => 'success'
}

Dostępne metody API ZCRM:

 

  • Klienci
  • customers
    Zwraca listę klientów
  • customers/<c_id>
    Zwraca klienta według jego identyfikatora.
  • customers
    Tworzy nowego klienta z określonymi danymi.
  • customers/<c_id>
    Aktualizuje istniejącego klienta o określonym ID.
  • customers/<c_id>
    Usuwa klienta według jego ID.
  • Tagi
  • customers/labels
    Zwraca listę wszystkich tagów i statystyk według nich.
  • customers/labels
    Tworzy nowy tag.
  • customers/labels/<l_id>
    Usuwa tag z systemu według jego ID.
  • Dodatkowe właściwości
  • customers/custom-properties
    Zwraca wszystkie dodatkowe właściwości.
  • Kanał klienta
  • customers/<c_id>/feed
    Zwraca wpisy z kanału klienta.
  • customers/<c_id>/feed
    Dodaje notatkę tekstową do kanału klienta z możliwością dołączania plików.
  • customers/<c_id>/feed/<i_id>
    Aktualizuje zawartość istniejącej notatki tekstowej według jej ID.
  • customers/<c_id>/feed/<i_id>
    Usuwa notatkę z kanału klienta według jej ID.
  • Pracownicy
  • customers/<c_id>/employees
    Zwraca listę pracowników klienta według jego ID.
  • customers/<c_id>/employees/<e_id>
    Zwraca pracownika klienta według jego ID.
  • customers/<c_id>/employees
    Tworzy i zapisuje nowego pracownika dla danego klienta.
  • customers/<c_id>/employees/<e_id>
    Aktualizuje istniejącego pracownika o określonym ID.
  • customers/<c_id>/employees/<e_id>
    Usuwa pracownika według jego ID.
  • Zadania
  • events
    Zwraca listę zadań.
  • events/<event_id>
    Zwraca zadanie według jego ID.
  • events
    Tworzy nowe zadanie z określonymi danymi.
  • events/<event_id>
    Aktualizuje istniejące zadanie o określonym identyfikatorze.
  • events/<event_id>/close
    Kończy (zamyka) zadanie.
  • events/<event_id>
    Usuwa zadanie według jej ID.
  • Leads
  • leads
    Zwraca listę leads.
  • leads/<lead_id>
    Zwraca lead według jego ID.
  • leads
    Tworzy nowy lead z określonymi danymi.
  • leads/<lead_id>
    Aktualizuje istniejący lead o określonym ID.
  • leads/<lead_id>
    Usuwa lead według jego ID.
  • Użytkownicy
  • users
    Zwraca listę użytkowników.
  • users/<user_id>
    Zwraca użytkownika według jego ID.
  • users/<user_id>/working-hours
    Zwraca godziny pracy użytkownika.
  • users/groups
    Zwraca grupy i prawa użytkownika dla każdej z nich.
  • Połączenia
  • calls
    Zwraca listę połączeń.
  • Uogólnione kontakty
  • contacts
    Zwraca listę wszystkich kontaktów (klientów, pracowników, leads, użytkowników) z numerami telefonów.
  • contacts/identify
    Identyfikuje kontakt (klient, pracownik, lead, użytkownik) według numeru telefonu.
  • Pliki
  • files/<file_id>
    Zwraca plik według jego ID.

GET /v1/zcrm/customers

Zwraca listę klientów

Parametry

  • search (opcjonalnie) — ciąg wyszukiwania. Wyszukiwanie odbywa się w oparciu na:
    • nazwa klienta
    • numery telefonów klientów
    • opis klienta
    • adres i kod pocztowy
    • strona internetowa
    • adresy e-mail
    • messengery
    • nazwiska pracowników
    • numery telefonów pracowników
    • opisy pracowników
    • adresy e-mail pracowników
    • messengery pracowników
  • filter (opcjonalnie) — filtr klientów. Filtr działa tylko na określonych polach. Struktura filtra:
    {
    "status": "company",
    "type": "client",
    "country": "GB",
    "city": "London",
    "label": 12,
    "employees_count": "50",
    "responsible": 20
    }
    
    gdzie:
    • status — status klienta. Prawidłowe wartości:
      • individual — osoba prywatna
      • company — firma
    • type — typ klienta. Prawidłowe wartości:
      • potential — potencjalny klient
      • client — klient
      • reseller — reseller
      • partner — partner
    • country — kraj klienta. Dwuliterowy kod (PL, US itd.)
    • city — miejscowość klienta (ciąg)
    • label — tag (identyfikator)
    • employees_count — liczba pracowników. Prawidłowe wartości:
      • 50 — mniej niż 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • responsible — odpowiedzialny (identyfikator użytkownika)
    Dowolny z parametrów filtra można pominąć, tj. jest opcjonalny.
  • sort (opcjonalnie) — sortowanie klientów. Struktura parametru:
    {
      "attr": "name",
      "desc": 0
    }
    
    gdzie:
    • attr — pole sortowania. Prawidłowe wartości:
      • name — imię klienta
      • status — status klienta
      • type — typ klienta
    • desc — kierunek sortowania. Prawidłowe wartości:
      • 0 — rosnąco
      • 1 — malejąco
  • take (w przypadku paginacji) - ilu klientów zwrócić (domyślnie 20)
  • skip (w przypadku paginacji) — ilu klientów pominąć (domyślnie 0)

Odpowiedź

{
  "totalCount": 82,
  "customers": [
    {
      "id": 65,
      "name": "Good company",
      "status": "company",
      "type": "client",
      "responsible_user_id": 20,
      "employees_count": "50",
      "comment": "",
      "country": "GB",
      "city": "London",
      "address": "",
      "zip": "",
      "website": "",
      "created_at": "2020-04-28 05:47:47",
      "created_by": 20,
      "lead_source": "manual",
      "lead_created_at": null,
      "lead_created_by": null,
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "good_company@example.com"
        }
      ],
      "labels": [
        {
          "id": 12,
          "label": "Best clients"
        }
      ]
    }
  ]
}

gdzie:

  • totalCount — całkowita liczba klientów (w tym ciąg wyszukiwania i filtr)
  • customers — tablica klientów (z uwzględnieniem podziału na strony). Każdy element tablicy zawiera następujące parametry:
    • id — identyfikator klienta
    • name — imię klienta
    • status — status klienta. Prawidłowe wartości:
      • individual — osoba prywatna
      • company — firma
    • type — typ klienta. Prawidłowe wartości:
      • potential — potencjalny klient
      • client — klient
      • reseller — reseller
      • partner — partner
    • country — kraj klienta. Dwuliterowy kod (RU, US itd.)
    • city — miejscowość klienta (ciąg)
    • label — tag (identyfikator)
    • employees_count — liczba pracowników. Prawidłowe wartości:
      • 50 — mniej niż 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — komentarz
    • country - kraj klienta. Dwuliterowy kod (PL, US itp.)
    • city — miasto klienta
    • address — adres klienta
    • zip — kod pocztowy
    • website — witryna klienta
    • created_at — data i godzina utworzenia klienta (w formacie YYYY-MM-DD HH:mm:ss)
    • created_by — przez kogo został utworzony (identyfikator użytkownika)
    • lead_source — źródło. Prawidłowe wartości:
      • manual — ręcznie
      • call_incoming — przychodzące połączenie
      • call_outgoing — wychodzące połączenie
      • form — formularz
    • lead_created_at — data i godzina utworzenia lead, jeśli klient został utworzony z leadów (w formacie YYYY-MM-DD HH:mm:ss)
    • lead_created_by — przez kogo został utworzony lead, jeśli klient został utworzony z leadów (identyfikator użytkownika)
    • phones — tablica numerów telefonów klientów. Każdy numer zawiera następujące pola:
      • type — typ numeru. Prawidłowe wartości:
        • work — stacjonarny
        • personal — prywatny
      • phone — wartość numeru
    • contacts — tablica kontaktów z klientami. Każdy kontakt zawiera następujące pola:
      • type — typ kontaktu. Prawidłowe wartości:
        • email_work — stacjonarny e-mail
        • email_personal — prywatny e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — wartość kontaktu
    • labels — tablica tagów przypisanych do klienta. Każdy tag zawiera następujące pola:
      • id — identyfikator tagu
      • label — wartość tagu

GET /v1/zcrm/customers/<c_id>

Zwraca klienta według jego identyfikatora.

Parametry adresu

  • c_id — identyfikator klienta

Odpowiedź

{
  "id": 65,
  "name": "Good company",
  "status": "company",
  "type": "client",
  "responsible_user_id": 20,
  "employees_count": "50",
  "comment": "",
  "country": "GB",
  "city": "London",
  "address": "",
  "zip": "",
  "website": "",
  "created_at": "2020-04-28 05:47:47",
  "created_by": 20,
  "lead_source": "manual",
  "lead_created_at": null,
  "lead_created_by": null,
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "good_company@example.com"
    }
  ],
  "labels": [
    {
      "id": 12,
      "label": "Best clients"
    }
  ],
  "custom_properties": [
    {
      "id": 18,
      "key": "loyalty",
      "title": "Loyalty",
      "value": "high"
    }
  ]
}

gdzie:

  • id — identyfikator klienta
  • name — imię klienta
  • status — status klienta. Prawidłowe wartości:
    • individual — osoba prywatna
    • company — firma
  • type — typ klienta. Prawidłowe wartości:
    • potential — potencjalny klient
    • client — klient
    • reseller — reseller
    • partner — partner
  • responsible_user_id — odpowiedzialny (identyfikator użytkownika)
  • employees_count — liczba pracowników. Prawidłowe wartości:
    • 50 — mniej niż 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • country — kraj klienta. Dwuliterowy kod (PL, US itp.)
  • city — miasto klienta
  • address — adres klienta
  • zip — kod pocztowy
  • website — witryna klienta
  • created_at — data i godzina utworzenia klienta (w formacie YYYY-MM-DD HH:mm:ss)
  • created_by — przez kogo został utworzony (identyfikator użytkownika)
  • lead_source — źródło. Prawidłowe wartości:
    • manual — ręcznie
    • call_incoming — przychodzące połączenie
    • call_outgoing — wychodzące połączenie
    • form — formularz
  • lead_created_at — data i godzina utworzenia lead, jeśli klient został utworzony z leadów (w formacie YYYY-MM-DD HH:mm:ss)
  • lead_created_by — przez kogo został utworzony lead, jeśli klient został utworzony z leadów (identyfikator użytkownika)
  • phones — tablica numerów telefonów klientów. Każdy numer zawiera następujące pola:
    • type — typ numeru. Prawidłowe wartości:
      • work — stacjonarny
      • personal — prywatny
    • phone — wartość numeru
  • contacts — tablica kontaktów z klientami. Każdy kontakt zawiera następujące pola:
    • type — typ kontaktu. Prawidłowe wartości:
      • email_work — stacjonarny e-mail
      • email_personal — prywatny e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — wartość kontaktu
  • labels — tablica tagów przypisanych do klienta. Każdy tag zawiera następujące pola:
    • id — identyfikator tagu
    • label — wartość tagu
  • custom_properties — tablica dodatkowych właściwości. Każda dodatkowa właściwość zawiera następujące pola:
    • id — identyfikator dodatkowej właściwości
    • key — unikalne imię dodatkowej właściwości
    • title — wyświetlona nazwa dodatkowej właściwości
    • value — wartość dodatkowej właściwości

POST /v1/zcrm/customers

Tworzy nowego klienta z określonymi danymi.

  • customer — dane nowego klienta. Struktura klienta:

Parametry

{
    "name": "Good company",
    "status": "company",
    "type": "client",
    "responsible_user_id": 20,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 12 },
      { "id": 13 }
  ],
    "custom_properties": [
    {
        "id": 18,
        "value": "high"
      }
    ]
}

gdzie:

  • name — nazwa klienta
  • status — status klienta. Prawidłowe wartości:
    • individual — osoba prywatna
    • company — firma
  • type — typ klienta. Prawidłowe wartości:
    • potential — potencjalny klient
    • client — klient
    • reseller — reseller
    • partner — partner
  • responsible_user_id — odpowiedzialny (identyfikator użytkownika)
  • employees_count — liczba pracowników. Prawidłowe wartości:
    • 50 — mniej niż 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — komentarz
  • country — kraj klienta. Dwuliterowy kod (PL, US и т.д.)
  • city — miejscowość klienta
  • address — adres klienta
  • zip — kod pocztowy
  • website — witryna klienta
  • lead_source — źródło. Prawidłowe wartości:
    • manual — ręcznie
    • call_incoming — przychodzące połączenie
    • call_outgoing — wychodzące połączenie
    • form — formularz
  • phones — tablica numerów telefonów. Każdy numer musi zawierać następujące pola:
    • type — typ numeru. Prawidłowa wartość:
      • work — stacjonarny
      • personal — prywatny
    • phone — wartość numeru
  • contacts — tablica kontaktów klienta. Każdy kontakt musi zawierać następujące pola:
    • type — typ kontaktu. Prawidłowa wartość:
      • email_work — stacjonarny e-mail
      • email_personal — prywatny e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — wartość kontaktu
  • labels — tablica tagów dodanych do klienta. Każdy element musi zawierać:
    • id — identyfikator istniejącego tagu
  • custom_properties — tablica dodatkowych właściwości. Każdy element musi zawierać:
    • id — identyfikator dodatkowej właściwości
    • key — unikalne imię dodatkowej właściwości
    • value — wartość dodatkowej właściwości

Odpowiedź:

{
"id": 65
}

gdzie:

  • id — identyfikator utworzonego klienta

PUT /v1/zcrm/customers/<c_id>

Aktualizuje istniejącego klienta o określonym ID.

Parametry adresu

  • c_id — identyfikator klienta

Parametry

  • customer — nowe dane klientów. Struktura klienta:
{
    "name": "Good company",
    "status": "company",
    "type": "client",
    "responsible_user_id": 20,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 12 },
      { "id": 13 }
  ],
    "custom_properties": [
    {
        "id": 18,
        "value": "high"
      }
    ]
}

gdzie:

  • name — nazwa klienta
  • status — status klienta. Prawidłowe wartości:
    • individual — osoba prywatna
    • company — firma
  • type — typ klienta. Prawidłowe wartości:
    • potential — potencjalny klient
    • client — klient
    • reseller — reseller
    • partner — partner
  • responsible_user_id — odpowiedzialny (identyfikator użytkownika)
  • employees_count — liczba pracowników. Prawidłowe wartości:
    • 50 — mniej niż 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — komentarz
  • country — kraj klienta. Dwuliterowy kod (PL, US и т.д.)
  • city — miejscowość klienta
  • address — adres klienta
  • zip — kod pocztowy
  • website — witryna klienta
  • lead_source — źródło. Prawidłowe wartości:
    • manual — ręcznie
    • call_incoming — przychodzące połączenie
    • call_outgoing — wychodzące połączenie
    • form — formularz
  • phones — tablica numerów telefonów. Każdy numer musi zawierać następujące pola:
    • type — typ numeru. Prawidłowa wartość:
      • work — stacjonarny
      • personal — prywatny
    • phone — wartość numeru
  • contacts — tablica kontaktów klienta. Każdy kontakt musi zawierać następujące pola:
    • type — typ kontaktu. Prawidłowa wartość:
      • email_work — stacjonarny e-mail
      • email_personal — prywatny e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — wartość kontaktu
  • labels — tablica tagów dodanych do klienta. Każdy element musi zawierać:
    • id — identyfikator istniejącego tagu
  • custom_properties — tablica dodatkowych właściwości. Każdy element musi zawierać:
    • id — identyfikator dodatkowej właściwości
    • key — unikalne imię dodatkowej właściwości
    • value — wartość dodatkowej właściwości

DELETE /v1/zcrm/customers/<c_id>

Usuwa klienta według jego ID.

Parametry adresu

  • c_id — identyfikator klienta

GET /v1/zcrm/customers/labels

Zwraca listę wszystkich tagów i statystyk według nich.

Odpowiedź

{
  "totalCount": 5,
  "labels": [
    {
      "id": 12,
      "label": "Best clients",
      "count": 14
    }
  ]
}

gdzie:

  • totalCount — całkowita liczba tagów w systemie
  • labels — tablica tagów. Każdy tag ma następujące pola:
    • id — identyfikator tagu
    • label — imię tagu
    • count — liczba klientów i leads korzystających z tego tagu

POST /v1/zcrm/customers/labels

Tworzy nowy tag.

Parametry

  • name — imię nowego tagu

Odpowiedź

{
  "id": 13,
  "label": "Best clients",
  "count": 0
}

gdzie:

  • id — identyfikator utworzonego tagu
  • label — nazwa tagu
  • count — liczba klientów i leads korzystających z tego tagu (tutaj zawsze jest to 0)

DELETE /v1/zcrm/customers/labels/<l_id>

Usuwa tag z systemu według jego ID.

Parametry adresu

  • l_id — identyfikator tagu

GET /v1/zcrm/customers/custom-properties

Zwraca wszystkie dodatkowe właściwości.

Odpowiedź

{
  "totalCount": 8,
  "customProperties": [
    {
      "id": 18,
      "key": "loyalty",
      "title": "Loyalty"
    }
  ]
}

gdzie:

  • totalCount — całkowita liczba dodatkowych właściwości.
  • customProperties — tablica dodatkowych właściwości. Każda dodatkowa właściwość zawiera następujące pola:
    • id — identyfikator dodatkowej właściwości
    • key — unikalne imię dodatkowej właściwości
    • title — wyświetlona nazwa dodatkowej właściwości

GET /v1/zcrm/customers/<c_id>/feed

Zwraca wpisy z kanału klienta.

Parametry adresu

  • c_id — identyfikator klienta

Odpowiedź

{
  "totalCount": 17,
  "items": [
    {
      "id": 37825,
      "type": "note",
      "content": "Call to client",
      "time": "2020-06-08 06:55:02",
      "user_id": 20,
      "user_name": "John Smith",
      "call_id": null,
      "call_type": null,
      "call_status": null,
      "call_phone": null,
      "call_duration": null,
      "call_record": null,
      "call_contact_name": null,
      "attached_files": [
        {
          "file_id": 576,
          "original_filename": "filename.doc"
        }
      ]
    }
  ]
}

gdzie:

  • totalCount — całkowita liczba wpisów
  • items — tablica wpisów. Każdy wpis zawiera następujące atrybuty:
    • id — identyfikator wpisu
    • type — typ wpisu. Możliwa wartość:
      • event — wydarzenie
      • note — tekstowa notatka
      • call — połączenie
    • content — treść wpisu. Jeśli typem wpisu jest notatka, ten atrybut zawiera tekstową treść notatki. Jeśli typ wpisu to zdarzenie, ten atrybut zawiera identyfikator zdarzenia, na przykład:
      • CUSTOMER_CREATED — zdarzenie tworzenia klienta
      • LEAD_CREATED — zdarzenie tworzenia potencjalnego klienta
    • time — czas wpisu w formacie `YYYY-MM-DD hh:mm:ss`
    • user_id — identyfikator użytkownika, który utworzył notatkę
    • user_name — nazwa użytkownika, który utworzył notatkę
    • call_id — identyfikator połączenia (jeśli typem wpisu jest połączenie)
    • call_type — typ połączenia. Możliwa wartość:
      • incoming — połączenie przychodzące
      • outgoing — połączenie wychodzące
    • call_status — status połączenia. Prawidłowa wartość
      • answer — udane połączenie
      • noanswer — brak odpowiedzi
      • cancel — anulowano
      • busy — zajęty
      • failed — nie powiodło się
    • call_phone — numer telefonu
    • call_duration — czas trwania w sekundach
    • call_record — czy nagrywanie rozmów jest włączone
    • call_contact_name — imię kontaktu połączenia
    • attached_files — tablica plików dołączonych do notatki (jeśli typ wpisu to notatka). Każdy element tablicy zawiera następujące atrybuty:
      • file_id — identyfikator pliku
      • original_filename — oryginalna nazwa pliku

POST /v1/zcrm/customers/<c_id>/feed

Dodaje notatkę tekstową do kanału klienta z możliwością dołączania plików.

Parametry adresu

  • c_id — identyfikator klienta

Parametry

  • content — wartość tekstowa notatki
  • files — tablica załączników

Odpowiedź

{
  "id": 37825,
  "type": "note",
  "content": "Call to client",
  "time": "2020-06-08 06:55:02",
  "user_id": 20,
  "user_name": "John Smith",
  "attached_files": [
    {
      "file_id": 576,
      "original_filename": "filename.doc"
    }
  ]
}

gdzie:

  • id - identyfikator wpisu
  • type - typ wpisu. W takim przypadku jest to równe:
    • note - notatka tekstowa
  • content - treść tekstu notatki
  • time - czas notatki w formacie `YYYY-MM-DD hh:mm:ss`
  • user_id - identyfikator użytkownika, który utworzył notatkę
  • user_name - nazwa użytkownika, który utworzył notatkę
  • attached_files - tablica plików dołączonych do notatki (jeśli typ wpisu to notatka). Każdy element tablicy zawiera następujące atrybuty:
    • file_id — identyfikator pliku
    • original_filename — oryginalna nazwa pliku

PUT /v1/zcrm/customers/<c_id>/feed/<i_id>

>Aktualizuje zawartość istniejącej notatki tekstowej według jej ID.

Parametry adresu

  • c_id — identyfikator klienta
  • i_id — identyfikator notatki tekstowej

Parametry

  • content — nowy tekst notatki

DELETE /v1/zcrm/customers/<c_id>/feed/<i_id>

Usuwa notatkę z kanału klienta według jej ID.

Parametry adresu

  • c_id — identyfikator klienta
  • i_id — identyfikator notatki tekstowej

GET /v1/zcrm/customers/<c_id>/employees

Zwraca listę pracowników klienta według jego ID.

Parametry adresu

  • c_id — identyfikator klienta

Odpowiedź

{
  "totalCount": 5,
  "employees": [
    {
      "id": 23,
      "customer_id": 11,
      "name": "John Smith",
      "position": "manager",
      "position_title": "",
      "comment": "",
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "john@example.com"
        }
      ]
    }
  ]
}

gdzie:

  • totalCount — liczba pracowników klienta
  • employees — tablica pracowników klientów. Każdy element tablicy zawiera następujące atrybuty:
    • id — identyfikator pracownika
    • customer_id — identyfikator klienta, z którym związany jest pracownik
    • name — imię pracownika
    • position — stanowisko pracownika. Prawidłowe wartości:
      • ceo — prezes zarządu
      • director — wiceprezes zarządu
      • manager — menadżer
      • sales_manager — kierownik sprzedaży
      • hr — HR
      • support — obsługa klienta
      • custom — dowolne
    • position_title — nazwa dowolnej pozycji (dla position = custom)
    • comment — komentarz
    • phones — tablica numerów telefonów pracowników. Każdy numer zawiera następujące pola:
      • type — typ numeru. Prawidłowe wartości:
        • work — stacjonarny
        • personal — prywatny
      • phone — wartość numeru
    • contacts — tablica kontaktów z klientami. Każdy kontakt zawiera następujące pola:
      • type — typ kontaktu. Prawidłowe wartości:
        • email_work — stacjonarny e-mail
        • email_personal — prywatny e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — wartość kontaktu

GET /v1/zcrm/customers/<c_id>/employees/<e_id>

Zwraca pracownika klienta według jego ID.

Parametry adresu

  • c_id — identyfikator klienta
  • e_id — identyfikator pracownika

Odpowiedź

{
  "id": 23,
  "customer_id": 11,
  "name": "John Smith",
  "position": "manager",
  "position_title": "",
  "comment": "",
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "john@example.com"
    }
  ]
}

gdzie:

  • id — identyfikator pracownika
  • customer_id — identyfikator klienta, z którym związany jest pracownik
  • name — imię pracownika
  • position — stanowisko pracownika. Prawidłowe wartości:
    • ceo — prezes zarządu
    • director — wiceprezes zarządu
    • manager — menadżer
    • sales_manager — kierownik sprzedaży
    • hr — HR
    • support — obsługa klienta
    • custom — dowolne
  • position_title — nazwa dowolnej pozycji (dla position = custom)
  • comment — komentarz
  • phones — tablica numerów telefonów pracowników. Każdy numer zawiera następujące pola:
    • type — typ numeru. Prawidłowe wartości:
      • work — stacjonarny
      • personal — prywatny
    • phone — wartość numeru
  • contacts — tablica kontaktów z klientami. Każdy kontakt zawiera następujące pola:
    • type — typ kontaktu. Prawidłowe wartości:
      • email_work — stacjonarny e-mail
      • email_personal — prywatny e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — wartość kontaktu

POST /v1/zcrm/customers/<c_id>/employees

Tworzy i zapisuje nowego pracownika dla danego klienta.

Parametry adresu

  • c_id — identyfikator klienta

Parametry

  • employee — nowe dane pracowników. Struktura pracowników:
{
    "name": "John Smith",
    "position": "manager",
    "position_title": "",
    "comment": "",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "john@example.com"
      }
    ]
  }

gdzie:

  • name — imię pracownika
  • position — stanowisko pracownika. Prawidłowe wartości:
    • ceo — prezes zarządu
    • director — wiceprezes zarządu
    • manager — menadżer
    • sales_manager — kierownik sprzedaży
    • hr — HR
    • support — obsługa klienta
    • custom — dowolne
  • position_title — nazwa dowolnej pozycji (dla position = custom)
  • comment — komentarz
  • phones — tablica numerów telefonów pracowników. Każdy numer zawiera następujące pola:
    • type — typ numeru. Prawidłowe wartości:
      • work — stacjonarny
      • personal — prywatny
    • phone — wartość numeru
  • contacts — tablica kontaktów z klientami. Każdy kontakt zawiera następujące pola:
    • type — typ kontaktu. Prawidłowe wartości:
      • email_work — stacjonarny e-mail
      • email_personal — prywatny e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — wartość kontaktu

Odpowiedź

{
  "id": 23
}

gdzie:

  • id — identyfikator nowego pracownika

PUT /v1/zcrm/customers/<c_id>/employees/<e_id>

Aktualizuje istniejącego pracownika o określonym ID.

Parametry adresu

  • c_id — identyfikator klienta
  • e_id — identyfikator pracownika

Parametry

  • employee — nowe dane pracownika. Struktura:
{
    "name": "John Smith",
    "position": "manager",
    "position_title": "",
    "comment": "",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "john@example.com"
      }
    ]
}

gdzie:

  • name — imię pracownika
  • position — stanowisko pracownika. Prawidłowe wartości:
    • ceo — prezes zarządu
    • director — wiceprezes zarządu
    • manager — menadżer
    • sales_manager — kierownik sprzedaży
    • hr — HR
    • support — obsługa klienta
    • custom — dowolne
  • position_title — nazwa dowolnej pozycji (dla position = custom)
  • comment — komentarz
  • phones — tablica numerów telefonów pracowników. Każdy numer zawiera następujące pola:
    • type — typ numeru. Prawidłowe wartości:
      • work — stacjonarny
      • personal — prywatny
    • phone — wartość numeru
  • contacts — tablica kontaktów z klientami. Każdy kontakt zawiera następujące pola:
    • type — typ kontaktu. Prawidłowe wartości:
      • email_work — stacjonarny e-mail
      • email_personal — prywatny e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — wartość kontaktu

DELETE /v1/zcrm/customers/<c_id>/employees/<e_id>

Usuwa pracownika według jego ID.

Parametry adresu

  • c_id — identyfikator klienta
  • e_id — identyfikator pracownika

GET /v1/zcrm/events

Zwraca listę zadań.

Parametry

  • search (opcjonalnie) - ciąg wyszukiwania. Wyszukiwanie odbywa się w oparciu:
    • tytuł zadania
    • opis zadania
    • komentarze ukończonych zadań
  • filter (opcjonalnie) - filtr zadań. Struktura filtra:
    {
        "responsible": 456,
        "createdBy": 456,
        "start": "2020-06-03 02:56:00",
        "end": "2020-06-12 02:56:00",
        "completed": 1
    }

    gdzie:

    • responsible — odpowiedzialny (identyfikator użytkownika)
    • createdBy — utworzono (identyfikator użytkownika)
    • start — pokaż zadania rozpoczynające się *po* określonym czasie (format `YYYY-MM-DD hh:mm:ss`)
    • end — pokaż zadania kończące się *przed* określonym czasem (format `YYYY-MM-DD hh:mm:ss`)
    • completed — ustaw na 1, aby w tym wyświetlać ukończone zadania
  • sort (opcjonalnie) - zadania sortowania. Struktura parametrów:
    {
        "attr": "start",
        "desc": 0
    }

    gdzie:

    • attr — pole sortowania. Prawidłowe wartości:
      • responsible — odpowiedzialny użytkownik
      • title — tytuł zadania
      • start — czas rozpoczęcia zadania
      • end — czas zakończenia zadania
    • desc — kierunek sortowania. Prawidłowe wartości:
      • 0 — rosnąco
      • 1 — malejąco

Odpowiedź

{
  "totalCount": 4,
  "events": [
    {
      "id": 40,
      "type": "task",
      "title": "Call to GoodCompany",
      "description": "",
      "start": "2020-05-26 09:00:00",
      "end": "2020-05-26 12:30:00",
      "allDay": false,
      "created_by": 234,
      "responsible_user": 234,
      "phone": "",
      "call_done": 0,
      "completed": 0,
      "completed_comment": "",
      "members": [234, 235],
      "customers": [
        {
          "id": 3486,
          "name": "GoodCompany",
          "status": "company",
          "type": "client",
          "lead_source": "manual",
          "lead_status": "not_processed",
          "contact_type": "customer"
        }
      ]
    }
  ]
}

gdzie

  • totalCount — całkowita liczba zadań
  • events — tablica zadań. Każde zadanie zawiera następujące atrybuty:
    • id — identyfikator zadania
    • type — typ zadania. Możliwa wartość:
      • task — zadanie
      • call — połączenie
    • title — tytuł zadania
    • description — opis zadania (w formacie Quill Delta: https://quilljs.com/docs/delta/)
    • start — data i godzina rozpoczęcia zadania (w formacie `YYYY-MM-DD hh:mm:ss`)
    • end — data i godzina zakończenia zadania (w formacie `YYYY-MM-DD hh:mm:ss`)
    • allDay — zadanie na cały dzień (`true` lub `false`) — datę określa się parametrem start
    • created_by — identyfikator użytkownika, który utworzył zadanie
    • responsible_user — identyfikator użytkownika odpowiedzialnego za zadanie
    • phone — numer telefonu dla połączenia (jeśli typ zadania to połączenie)
    • call_done — wskazuje, czy połączenie zostało wykonane
    • completed — wskazuje, że zadanie jest oznaczone jako ukończone
    • completed_comment — komentarz na ukończone zadanie
    • members — tablica uczestników zadania (tylko identyfikatory użytkowników)
    • customers — tablica klientów i potencjalnych klientów dołączonych do zadania. Każdy element tablicy zawiera następujące pola:
      • id — identyfikator klienta / lead
      • name — imię klienta / lead
      • status — status klienta. Możliwa wartość:
        • individual — osoba prywatna
        • company — firma
      • type — typ klienta. Prawidłowe wartości:
        • potential — potencjalny klient
        • client — klient
        • reseller — reseller
        • partner — partner
      • lead_source — źródło lead. Prawidłowe wartości:
        • manual — ręcznie
        • call_incoming — przychodzące połączenie
        • call_outgoing — wychodzące połączenie
        • form — formularz
      • lead_status — status lead. Możliwa wartość:
        • not_processed — niesortowany
        • in_progress — w przetwarzaniu
        • finished — zakończony
      • contact_type — typ kontaktu. Możliwa wartość:
        • customer — klient
        • lead — lead

GET /v1/zcrm/events/<event_id>

Zwraca zadanie według jego ID.

Odpowiedź

{
  "id": 40,
  "type": "task",
  "title": "Call to GoodCompany",
  "description": "",
  "start": "2020-05-26 09:00:00",
  "end": "2020-05-26 12:30:00",
  "allDay": false,
  "created_by": 234,
  "responsible_user": 234,
  "phone": "",
  "call_done": 0,
  "completed": 0,
  "completed_comment": "",
  "members": [234, 235],
  "customers": [
    {
      "id": 3486,
      "name": "GoodCompany",
      "status": "company",
      "type": "client",
      "lead_source": "manual",
      "lead_status": "not_processed",
      "contact_type": "customer"
    }
  ]
}

gdzie

  • id — identyfikator zadania
  • type — typ zadania. Możliwa wartość:
    • task — zadanie
    • call — połączenie
  • title — tytuł zadania
  • description — opis zadania (w formacie Quill Delta: https://quilljs.com/docs/delta/)
  • start — data i godzina rozpoczęcia zadania (w formacie `YYYY-MM-DD hh:mm:ss`)
  • end — data i godzina zakończenia zadania (w formacie `YYYY-MM-DD hh:mm:ss`)
  • allDay — zadanie na cały dzień (`true` lub `false`) — datę określa się parametrem start
  • created_by — identyfikator użytkownika, który utworzył zadanie
  • responsible_user — identyfikator użytkownika odpowiedzialnego za zadanie
  • phone — numer telefonu dla połączenia (jeśli typ zadania to połączenie)
  • call_done — wskazuje, czy połączenie zostało wykonane
  • completed — wskazuje, że zadanie jest oznaczone jako ukończone
  • completed_comment — komentarz na ukończone zadanie
  • members — tablica uczestników zadania (tylko identyfikatory użytkowników)
  • customers — tablica klientów i potencjalnych klientów dołączonych do zadania. Każdy element tablicy zawiera następujące pola:
    • id — identyfikator klienta / lead
    • name — imię klienta / lead
    • status — status klienta. Możliwa wartość:
      • individual — osoba prywatna
      • company — firma
    • type — typ klienta. Prawidłowe wartości:
      • potential — potencjalny klient
      • client — klient
      • reseller — reseller
      • partner — partner
    • lead_source — źródło lead. Prawidłowe wartości:
      • manual — ręcznie
      • call_incoming — przychodzące połączenie
      • call_outgoing — wychodzące połączenie
      • form — formularz
    • lead_status — status lead. Możliwa wartość:
      • not_processed — niesortowany
      • in_progress — w przetwarzaniu
      • finished — zakończony
    • contact_type — typ kontaktu. Możliwa wartość:
      • customer — klient
      • lead — lead

POST /v1/zcrm/events

Tworzy nowe zadanie z określonymi danymi.

Parametry

  • event — dane nowego zadania. Struktura:
{
    "type": "task",
    "title": "Call to GoodCompany",
    "description": "",
    "start": "2020-05-26 09:00:00",
    "end": "2020-05-26 12:30:00",
    "allDay": false,
    "responsible_user": 234,
    "phone": "",
    "members": [234, 235],
    "customers": [3486, 3487]
}

gdzie

  • type — typ zadania. Możliwa wartość:
    • task — zadanie
    • call — połączenie
  • title — tytuł zadania
  • description — opis zadania (w formacie Quill Delta: https://quilljs.com/docs/delta/)
  • start — data i godzina rozpoczęcia zadania (w formacie `YYYY-MM-DD hh:mm:ss`)
  • end — data i godzina zakończenia zadania (w formacie `YYYY-MM-DD hh:mm:ss`)
  • allDay — zadanie na cały dzień (`true` lub `false`) — datę określa się parametrem start
  • responsible_user — identyfikator użytkownika odpowiedzialnego za zadanie
  • phone — numer telefonu dla połączenia (jeśli typ zadania to połączenie)
  • members — tablica uczestników zadania (tylko identyfikatory użytkowników)
  • customers — tablica klientów i potencjalnych klientów (tylko identyfikatory użytkowników)

Odpowiedź

{
  "id": 7216
}

gdzie

  • id — identyfikator utworzonego zadania

PUT /v1/zcrm/events/<event_id>

Aktualizuje istniejące zadanie o określonym identyfikatorze.

>

Parametry

  • event — nowe dane zadania. Struktura:
{
    "title": "Call to GoodCompany",
    "description": "",
    "start": "2020-05-26 09:00:00",
    "end": "2020-05-26 12:30:00",
    "allDay": false,
    "created_by": 234,
    "responsible_user": 234,
    "phone": "",
    "members": [234, 235],
    "customers": [3486, 3487]
}

gdzie

  • title — tytuł zadania
  • description — opis zadania (w formacie Quill Delta: https://quilljs.com/docs/delta/)
  • start — data i godzina rozpoczęcia zadania (w formacie `YYYY-MM-DD hh:mm:ss`)
  • end — data i godzina zakończenia zadania (w formacie `YYYY-MM-DD hh:mm:ss`)
  • allDay — zadanie na cały dzień (`true` lub `false`) — datę określa się parametrem start
  • responsible_user — identyfikator użytkownika odpowiedzialnego za zadanie
  • phone — numer telefonu dla połączenia (jeśli typ zadania to połączenie)
  • members — tablica uczestników zadania (tylko identyfikatory użytkowników)
  • customers — tablica klientów i potencjalnych klientów (tylko identyfikatory użytkowników)

POST /v1/zcrm/events/<event_id>/close

Kończy (zamyka) zadanie.

Parametry

  • comment (opcjonalnie) - komentarz

DELETE /v1/zcrm/events/<event_id>

Usuwa zadanie według jej ID.

Brak parametrów

GET /v1/zcrm/leads

Zwraca listę leads.

Parametry

  • search (opcjonalnie) - ciąg wyszukiwania. Wyszukiwanie odbywa się w oparciu:
    • imię lead
    • numery telefonów lead
    • opis potencjalnego klienta
    • adres i kod pocztowy
    • strona internetowa
    • adresy e-mail
    • messengery
  • filter (opcjonalnie) - filtr leads. Struktura filtra:
    {
        "source": "call_incoming",
        "responsible": 32,
        "label": 12,
        "createdAfter": "2020-06-11 12:24:00",
        "createdBefore": "2020-06-26 12:24:00"
    }

gdzie

  • source — źródło lead. Prawidłowe wartości:
    • manual — dodany ręcznie
    • call_incoming — połączenie przychodzące
    • call_outgoing — połączenie wychodzące
    • form — formularz callback
  • responsible — odpowiedzialny (identyfikator użytkownika). Ten parametr dopuszcza również wartości specjalne:
    • null — zwróci wszystkie leads przypisane do kogoś
    • –1 — zwróci nieprzetworzone leads
    • –2 — zwróci wszystkie leads (zarówno przypisane, jak i niesortowane)
  • label — tag (identyfikator)
  • createdAfter — pokaż tylko utworzone leads *po* określonym czasie (format: `YYYY-MM-DD hh:mm:ss`)
  • createdBefore — pokaż tylko leads utworzone *przed* określonym czasem (format: `YYYY-MM-DD hh:mm:ss`)
Dowolny z parametrów filtra można pominąć, tj. jest opcjonalny.
  • sort (opcjonalnie) - sortowanie leads. Struktura parametrów:
    {
        "attr": "name",
        "desc": 0
    }

    gdzie

    • attr — pole sortowania. Prawidłowe wartości:
      • name — imię lead
      • lead_source — źródło lead
      • lead_status — status lead
      • responsible_user_id — odpowiedzialny użytkownik
      • lead_created_at — czas utworzenia lead
    • desc — kierunek sortowania. Prawidłowe wartości:
      • 0 — rosnąco
      • 1 — malejąco
  • take (w przypadku paginacji) - ile zwrócić leads (domyślnie 20)
  • skip (w przypadku paginacji) - ile pominąć leads (domyślnie 0)

Odpowiedź

{
  "totalCount": 100,
  "uncategorizedCount": 10,
  "leads": [
    {
      "id": 3486,
      "name": "GoodCompany",
      "responsible_user_id": 234,
      "employees_count": "50",
      "comment": "",
      "country": "GB",
      "city": "London",
      "address": "",
      "zip": "",
      "website": "",
      "lead_status": "not_processed",
      "lead_source": "manual",
      "lead_created_at": "2020-04-28 05:47:47",
      "lead_created_by": 234,
      "phones": [
        {
          "type": "work",
          "phone": "+44123456789"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "good_company@example.com"
        }
      ],
      "labels": [
        {
          "id": 22,
          "label": "Best clients"
        }
      ]
    }
  ]
}

gdzie

  • totalCount — całkowita liczba znalezionych leads (w tym ciąg wyszukiwania i filtr)
  • uncategorizedCount —łączna liczba nie analizowanych leads (w tym wyszukiwanie i filtrowanie)
  • leads — tablica potencjalnych klientów (z uwzględnieniem podziału na strony). Każdy element tablicy zawiera następujące parametry:
    • id — identyfikator lead
    • name — imię lead
    • responsible_user_id — odpowiedzialny (identyfikator użytkownika)
    • employees_count — liczba pracowników. Możliwa wartość:
      • 50 — mniej niż 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — komentarz
    • country — kraj klienta. Dwuliterowy kod (PL, US itp.)
    • city — miasto klienta
    • address — adres klienta
    • zip — kod pocztowy
    • website — witryna klienta
    • lead_status — status lead. Możliwa wartość:
      • not_processed — niesortowany
      • in_progress — w przetwarzaniu
      • finished — zakończony
    • lead_source — źródło. Prawidłowe wartości:
      • manual — ręcznie
      • call_incoming — przychodzące połączenie
      • call_outgoing — wychodzące połączenie
      • form — formularz
    • lead_created_at — data i godzina utworzenia lead, jeśli klient został utworzony z leadów (w formacie YYYY-MM-DD HH:mm:ss)
    • lead_created_by — przez kogo został utworzony lead, jeśli klient został utworzony z leadów (identyfikator użytkownika)
    • phones — tablica numerów telefonów lead. Każdy numer zawiera następujące pola:
      • type — typ numeru. Prawidłowe wartości:
        • work — stacjonarny
        • personal — prywatny
      • phone — wartość numeru
    • contacts — tablica kontaktów z leads. Każdy kontakt zawiera następujące pola:
      • type — typ kontaktu. Prawidłowe wartości:
        • email_work — stacjonarny e-mail
        • email_personal — prywatny e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — wartość kontaktu
    • labels — tablica tagów przypisanych do klienta. Każdy tag zawiera następujące pola:
      • id — identyfikator tagu
      • label — wartość tagu

GET /v1/zcrm/leads/<lead_id>

Zwraca lead według jego ID.

Odpowiedź

{
  "id": 3486,
  "name": "GoodCompany",
  "responsible_user_id": 234,
  "employees_count": "50",
  "comment": "",
  "country": "GB",
  "city": "London",
  "address": "",
  "zip": "",
  "website": "",
  "lead_status": "not_processed",
  "lead_source": "manual",
  "lead_created_at": "2020-04-28 05:47:47",
  "lead_created_by": 234,
  "phones": [
    {
      "type": "work",
      "phone": "+44123456789"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "good_company@example.com"
    }
  ],
  "labels": [
    {
      "id": 22,
      "label": "Best clients"
    }
  ],
  "custom_properties": [
    {
      "id": 12,
      "key": "loyalty",
      "title": "Loyalty",
      "value": "high"
    }
  ]
}

gdzie

  • id — identyfikator potencjalnego klienta
  • name — imię lead
  • responsible_user_id — odpowiedzialny (identyfikator użytkownika)
  • employees_count — liczba pracowników. Możliwa wartość:
    • 50 — mniej niż 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — komentarz
  • country - kraj klienta. Dwuliterowy kod (PL, US itp.)
  • city - miasto klienta
  • address - adres klienta
  • zip - kod pocztowy
  • website - witryna klienta
  • lead_status — status lead. Możliwa wartość:
    • not_processed — niesortowany
    • in_progress — w przetwarzaniu
    • finished — zakończony
  • lead_source — źródło. Prawidłowe wartości:
    • manual — ręcznie
    • call_incoming — przychodzące połączenie
    • call_outgoing — wychodzące połączenie
    • form — formularz
  • lead_created_at — data i godzina utworzenia lead, jeśli klient został utworzony z leadów (w formacie YYYY-MM-DD HH:mm:ss)
  • lead_created_by — przez kogo został utworzony lead, jeśli klient został utworzony z leadów (identyfikator użytkownika)
  • phones — tablica numerów telefonów lead. Każdy numer zawiera następujące pola:
    • type — typ numeru. Prawidłowe wartości:
      • work — stacjonarny
      • personal — prywatny
    • phone — wartość numeru
  • contacts — tablica kontaktów z leads. Każdy kontakt zawiera następujące pola:
    • type — typ kontaktu. Prawidłowe wartości:
      • email_work — stacjonarny e-mail
      • email_personal — prywatny e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — wartość kontaktu
  • labels — tablica tagów przypisanych do klienta. Każdy tag zawiera następujące pola:
    • id — identyfikator tagu
    • label — wartość tagu

POST /v1/zcrm/leads

Tworzy nowy lead z określonymi danymi.

Parametry

  • convert — konwertować lead w klienta. Prawidłowe wartości:
    • 0 - nie konwertować, utwórz lead
    • 1 - utwórz klienta
    • 2 - niedocelowy (operacja zostanie anulowana - nie zostanie utworzony lead ani klient)
  • lead — dane nowego lead. Struktura lead:
    {
        "name": "GoodCompany",
        "responsible_user_id": 234,
        "employees_count": "50",
        "comment": "",
        "country": "RU",
        "city": "Москва",
        "address": "",
        "zip": "",
        "website": "",
        "lead_source": "manual",
        "lead_status": "in_progress",
        "phones": [
          {
            "type": "work",
            "phone": "+44123456789"
          }
        ],
        "contacts": [
          {
            "type": "email_work",
            "value": "good_company@example.com"
          }
        ],
        "labels": [
          { "id": 22 },
          { "id": 23 }
      ],
        "custom_properties": [
        {
            "id": 12,
            "value": "high"
          }
        ]
    }

    gdzie

    • name — imię lead
    • responsible_user_id — odpowiedzialny (identyfikator użytkownika)
    • employees_count — liczba pracowników. Możliwa wartość:
      • 50 — mniej niż 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — komentarz
    • country - kraj lead. Dwuliterowy kod (PL, US itp.)
    • city - miasto lead
    • address - adres lead
    • zip - kod pocztowy
    • website - witryna
    • lead_status — status lead. Możliwa wartość:
      • not_processed — niesortowany
      • in_progress — w przetwarzaniu
      • finished — zakończony
    • lead_source — źródło. Prawidłowe wartości:
      • manual — ręcznie
      • call_incoming — przychodzące połączenie
      • call_outgoing — wychodzące połączenie
      • form — formularz
    • phones — tablica numerów telefonów lead. Każdy numer zawiera następujące pola:
      • type — typ numeru. Prawidłowe wartości:
        • work — stacjonarny
        • personal — prywatny
      • phone — wartość numeru
    • contacts — tablica kontaktów z leads. Każdy kontakt zawiera następujące pola:
      • type — typ kontaktu. Prawidłowe wartości:
        • email_work — stacjonarny e-mail
        • email_personal — prywatny e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — wartość kontaktu
    • labels — tablica tagów dodana do potencjalnej szansy. Każdy element musi zawierać:
      • id — identyfikator istniejącego tagu
      • custom_properties — tablica dodatkowych właściwości. Każdy element musi zawierać:
        • id — identyfikator dodatkowej właściwości albo:
        • key — unikalna nazwa dodatkowej właściwości
        • value — wartość dodatkowej właściwości

Odpowiedź

{
  "id": 123
}

gdzie

  • id — identyfikator utworzonego leadu

PUT /v1/zcrm/leads/<lead_id>

Aktualizuje istniejący lead o określonym ID.

Parametry

  • convert — konwertować lead w klienta. Prawidłowe wartości:
    • 0 - nie konwertuj
    • 1 - utwórz klienta
    • 2 - niedocelowy (usuń lead)
  • lead — dane nowego lead. Struktura lead:
{
    "name": "GoodCompany",
    "responsible_user_id": 234,
    "employees_count": "50",
    "comment": "",
    "country": "GB",
    "city": "London",
    "address": "",
    "zip": "",
    "website": "",
    "lead_source": "manual",
    "lead_status": "in_progress",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "good_company@example.com"
      }
    ],
    "labels": [
      { "id": 22 },
      { "id": 23 }
  ],
    "custom_properties": [
    {
        "id": 12,
        "value": "high"
      }
    ]
}

gdzie

  • name — imię lead
  • responsible_user_id — odpowiedzialny (identyfikator użytkownika)
  • employees_count — liczba pracowników. Możliwa wartość:
    • 50 — mniej niż 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — komentarz
  • country - kraj lead. Dwuliterowy kod (PL, US itp.)
  • city - miasto lead
  • address - adres lead
  • zip - kod pocztowy
  • website - witryna
  • lead_status — status lead. Możliwa wartość:
    • not_processed — niesortowany
    • in_progress — w przetwarzaniu
    • finished — zakończony
  • lead_source — źródło. Prawidłowe wartości:
    • manual — ręcznie
    • call_incoming — przychodzące połączenie
    • call_outgoing — wychodzące połączenie
    • form — formularz
  • phones — tablica numerów telefonów lead. Każdy numer zawiera następujące pola:
    • type — typ numeru. Prawidłowe wartości:
      • work — stacjonarny
      • personal — prywatny
    • phone — wartość numeru
  • contacts — tablica kontaktów z leads. Każdy kontakt zawiera następujące pola:
    • type — typ kontaktu. Prawidłowe wartości:
      • email_work — stacjonarny e-mail
      • email_personal — prywatny e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — wartość kontaktu
  • labels — tablica tagów dodana do potencjalnej szansy. Każdy element musi zawierać:
    • id — identyfikator istniejącego tagu
    • custom_properties — tablica dodatkowych właściwości. Każdy element musi zawierać:
      • id — identyfikator dodatkowej właściwości albo:
      • key — unikalna nazwa dodatkowej właściwości
      • value — wartość dodatkowej właściwości

DELETE /v1/zcrm/leads/<lead_id>

Usuwa lead według jego ID.

Brak parametrów

GET /v1/zcrm/users

Zwraca listę użytkowników.

Odpowiedź

{
  "totalCount": 2,
  "users": [
    {
      "id": 234,
      "email": "john_smith@example.com",
      "name": "John Smith",
      "group_id": 653,
      "is_superadmin": 1,
      "enabled": 1,
      "created_at": "2020-04-27 01:01:31",
      "avatar": 2457,
      "role": "",
      "status": "",
      "language": "en",
      "color": "220",
      "color_hex": "5678BD",
      "internal_number": "100",
      "timezone": "Europe/London",
      "first_day": 1,
      "device": "webphone",
      "phone_widget_location": "right",
      "phones": [
        {
          "phone": "+44123456789",
          "type": "work"
        }
      ],
      "contacts": [
        {
          "type": "email_work",
          "value": "smith@example.com"
        }
      ]
    }
  ]
}

gdzie

  • totalCount — całkowita liczba użytkowników
  • users — tablica użytkowników. Każdy element tablicy zawiera następujące atrybuty:
    • id — identyfikator użytkownika
    • email — konto e-mail użytkownika
    • name — nazwa użytkownika
    • group_id — identyfikator grupy użytkowników
    • is_superadmin — wskazuje, czy użytkownik jest superadministratorem (1 czy 0)
    • enabled — czy użytkownik jest odblokowany (1 czy 0)
    • created_at — data i godzina utworzenia użytkownika (format `YYYY-MM-DD hh:mm:ss`)
    • avatar — awatar użytkownika (identyfikator pliku)
    • role — stanowisko użytkownika
    • status — status użytkownika
    • language — język interfejsu użytkownika. Możliwe opcje:
      • pl — polski
      • de — niemiecki
      • en — angielski
      • es — hiszpański
      • ru — rosyjski
      • ua — ukraiński
    • color — kolor zadań użytkownika w interfejsie ZCRM (tylko wartość odcienia - od 0 do 359)
    • color_hex — kolor zadań użytkownika w interfejsie ZCRM (hex-reprezentacja)
    • internal_number — wewnętrzny numer centrali PBX użytkownika
    • timezone — strefa czasowa użytkownika
    • first_day — określa, który dzień tygodnia jest początkiem tygodnia:
      • 0 — niedziela
      • 1 — poniedziałek
    • device — co używa się do połączeń. Możliwa wartość:
      • webphone — web-telefon
      • softphone — softphone(aplikacja)
    • phone_widget_location — lokalizacja widgetu web telefonu. Możliwa wartość:
      • left — umieść widget telefonu po lewej
      • right — umieść widget telefonu po prawej
    • phones — tablica numerów telefonów użytkowników. Każdy numer zawiera następujące pola:
      • phone — numer
      • type — typ numeru. Możliwa wartość:
        • work — stacjonarny
        • personal — prywatny
    • contacts — tablica kontaktów użytkownika. Każdy kontakt zawiera następujące pola:
      • type — typ kontaktu. Możliwa wartość:
        • email_work — stacjonarny e-mail
        • email_personal — prywatny e-mail
        • skype
        • telegram
        • viber
        • whatsapp
      • value — wartość kontaktu

GET /v1/zcrm/users/<user_id>

Zwraca użytkownika według jego ID.

Odpowiedź

{
  "id": 234,
  "email": "john_smith@example.com",
  "name": "John Smith",
  "group_id": 653,
  "is_superadmin": 1,
  "enabled": 1,
  "created_at": "2020-04-27 01:01:31",
  "avatar": 2457,
  "role": "",
  "status": "",
  "language": "ru",
  "color": "220",
  "color_hex": "5678BD",
  "internal_number": "100",
  "timezone": "Europe/London",
  "first_day": 1,
  "device": "webphone",
  "phone_widget_location": "right",
  "phones": [
    {
      "phone": "+44123456789",
      "type": "work"
    }
  ],
  "contacts": [
    {
      "type": "email_work",
      "value": "smith@example.com"
    }
  ],
  "pending_email_change_request": false
}

gdzie

  • id — identyfikator użytkownika
  • email — konto e-mail użytkownika
  • name — nazwa użytkownika
  • group_id — identyfikator grupy użytkowników
  • is_superadmin — wskazuje, czy użytkownik jest superadministratorem (1 czy 0)
  • enabled — czy użytkownik jest odblokowany (1 czy 0)
  • created_at — data i godzina utworzenia użytkownika (format `YYYY-MM-DD hh:mm:ss`)
  • avatar — awatar użytkownika (identyfikator pliku)
  • role — stanowisko użytkownika
  • status — status użytkownika
  • language — język interfejsu użytkownika. Możliwe opcje:
    • pl — polski
    • de — niemiecki
    • en — angielski
    • es — hiszpański
    • ru — rosyjski
    • ua — ukraiński
  • color — kolor zadań użytkownika w interfejsie ZCRM (tylko wartość odcienia - od 0 do 359)
  • color_hex — kolor zadań użytkownika w interfejsie ZCRM (hex-reprezentacja)
  • internal_number — wewnętrzny numer centrali PBX użytkownika
  • timezone — strefa czasowa użytkownika
  • first_day — określa, który dzień tygodnia jest początkiem tygodnia:
    • 0 — niedziela
    • 1 — poniedziałek
  • device — co używa się do połączeń. Możliwa wartość:
    • webphone — web-telefon
    • softphone — softphone(aplikacja)
  • phone_widget_location — lokalizacja widgetu web telefonu. Możliwa wartość:
    • left — umieść widget telefonu po lewej
    • right — umieść widget telefonu po prawej
  • phones — tablica numerów telefonów użytkowników. Każdy numer zawiera następujące pola:
    • phone — numer
    • type — typ numeru. Możliwa wartość:
      • work — stacjonarny
      • personal — prywatny
  • contacts — tablica kontaktów użytkownika. Każdy kontakt zawiera następujące pola:
    • type — typ kontaktu. Możliwa wartość:
      • email_work — stacjonarny e-mail
      • email_personal — prywatny e-mail
      • skype
      • telegram
      • viber
      • whatsapp
    • value — wartość kontaktu
  • pending_email_change_request — jeśli wysłano prośbę o zmianę konta e-mail, ale prośba nie została jeszcze potwierdzona, parametr ten zostanie ustawiony na true
  • GET /v1/zcrm/users/<user_id>/working-hours

    Zwraca godziny pracy użytkownika.

    Odpowiedź

    {
      "schedulePeriod": 7,
      "scheduleWorkingHours": [
        {
          "time_start": "2020-06-15 09:00:00",
          "time_end": "2020-06-15 18:00:00"
        }
      ],
      "scheduleFixes": [
        {
          "index": 2,
          "repeat_index": 1,
          "time_start": "2020-06-24 09:00:00",
          "time_end": "2020-06-24 13:00:00",
          "deleted": 0
        }
      ],
      "customWorkingHours": [
        {
          "time_start": "2020-06-27 11:00:00",
          "time_end": "2020-06-27 15:00:00"
        }
      ]
    }

    gdzie

    • schedulePeriod — częstotliwość harmonogramu, * jak * to się powtarza. W przypadku normalnego tygodnia pracy jest to 7 dni, w przypadku codziennego harmonogramu - 2 dni itd.
    • scheduleWorkingHours — tablica okresów pracy. Każdy okres roboczy zawiera następujące atrybuty:
      • time_start — początek czasu pracy w formacie `YYYY-MM-DD hh:mm:ss`
      • time_end — koniec czasu pracy w formacie `YYYY-MM-DD hh:mm:ss`
    • scheduleFixes — tablica zmian wprowadzonych do okresów pracy zdefiniowanych w parametrze scheduleWorkingHours. Każdy element tablicy zawiera następujące atrybuty:
      • index — indeks elementu w harmonogramie Godziny pracy, tj. jaki okres pracy został zmieniony
      • repeat_index — indeks powtórki harmonogramu, w którym zmienia się okres pracy
      • time_start — nowy początek czasu pracy w formacie `YYYY-MM-DD hh:mm:ss`
      • time_end — nowy koniec czasu pracy w formacie `YYYY-MM-DD hh:mm:ss`
      • deleted — jeśli jest równe 1, okres pracy jest całkowicie usuwany
    • customWorkingHours — tablica niestandardowych, pojedynczych okresów roboczych. Każdy okres roboczy zawiera następujące atrybuty:
      • time_start — początek czasu pracy w formacie `YYYY-MM-DD hh:mm:ss`
      • time_end — koniec czasu pracy w formacie `YYYY-MM-DD hh:mm:ss`

    GET /v1/zcrm/users/groups

    Zwraca grupy i prawa użytkownika dla każdej z nich.

    Odpowiedź

    {
      "totalCount": 4,
      "groups": [
        {
          "id": 45,
          "type": "manager",
          "title": "",
          "permissions": {
            "customers_create": true,
            "customers_edit": true,
            "customers_delete": true,
            "customers_import_export": true,
            "customers_view_all": false,
            "calendar_other_users_access": false,
            "calls_other_users_access": false,
            "leads_view": false,
            "leads_edit": false,
            "leads_delete": false,
            "leads_import_export": false,
            "team_add": false,
            "team_edit": false
          }
        }
      ]
    }

    gdzie

    • totalCount — całkowita liczba grup
    • groups — tablica grup. Każda grupa zawiera następujące atrybuty:
      • id — identyfikator grupy
      • type — typ grupy. Możliwa wartość:
        • admin — administratorzy
        • manager — menadżery
        • chat_operator — operatorzy
        • trainee — stażyści
        • custom — niestandardowy
      • title — nazwa grupy użytkowników (dla type = custom)
      • permissions — prawa użytkownika do grupy. Administratorzy mają pełny dostęp, więc dla administratorów ten obiekt będzie pusty. Pozostałe grupy zawierają następujące atrybuty (z których każda może być równa „true” lub „false”):
        • customers_create — dozwolone tworzenie klientów
        • customers_edit — dozwolona edycja klientów
        • customers_delete — dozwolone usuwanie klientów
        • customers_import_export — dozwolony import i eksport klientów
        • customers_view_all — dozwolone wyświetlanie wszystkich klientów, w tym tych przypisanych do innych użytkowników
        • calendar_other_users_access — dozwolone zadania przeglądania innych użytkowników
        • calls_other_users_access — dozwolony dostęp do połączeń innych użytkowników
        • leads_view — dozwolone przeglądanie leadów innych użytkowników
        • leads_edit — dozwolona edycja leadów innych użytkowników
        • leads_delete — dozwolone usuwanie potencjalnych klientów innych użytkowników
        • leads_import_export — import i eksport leadów jest dozwolony
        • team_add — dozwolone dodawanie i zapraszanie użytkowników do zespołu
        • team_edit — dozwolona edycja użytkowników

    GET /v1/zcrm/calls

    Zwraca listę połączeń.

    Parametry

    • search (opcjonalnie) - ciąg wyszukiwania. Wyszukiwanie odbywa się w oparciu:
      • numery telefonów
      • nazwiska kontaktów (klientów, pracowników, leads lub użytkowników)
    • filter (opcjonalnie) - filtr połączeń. Struktura filtra:
      {
          "user": 23,
          "type": "incoming",
          "status": "answer",
          "dateFrom": "2020-06-03 14:56:00",
          "dateTo": "2020-06-26 14:56:00"
      }

      gdzie

      • user — użytkownik (identyfikator)
      • type — typ połączenia. Prawidłowe wartości:
        • incoming — przychodzące połączenie
        • outgoing — wychodzące połączenie
      • status — status połączenia. Prawidłowe wartości:
        • answer — udane połączenie
        • noanswer — brak odpowiedzi
        • cancel — anulowano
        • busy — zajęty
        • failed — nie powiodło się
      • dateFrom — pokazuje tylko połączenia wykonane *po* określonym czasie (format: `YYYY-MM-DD hh:mm:ss`)
      • dateTo — pokaż tylko połączenia wykonane *przed* określonym czasem (format: `YYYY-MM-DD hh:mm:ss`)
    Dowolny z parametrów filtra można pominąć, tj. jest opcjonalny.
    • sort (opcjonalnie) - sortuj połączenia. Struktura parametru:
        {
          "attr": "time",
          "desc": 0
        }

      gdzie

      • attr — pole sortowania. Prawidłowe wartości:
        • phone — numer telefonu
        • status — status połączenia
        • duration — czas trwania połączenia
        • time — czas połączenia
      • desc — kierunek sortowania. Prawidłowe wartości:
        • 0 — rosnąco
        • 1 — malejąco
    • take (w przypadku paginacji) - ile połączeń zwrócić (domyślnie 20)
    • skip (w przypadku paginacji) - ile połączeń pominąć (domyślnie 0)

    Odpowiedź

    {
      "totalCount": 233,
      "calls": [
        {
          "id": 127,
          "type": "outgoing",
          "status": "answer",
          "phone": "+44123456789",
          "user_id": 179,
          "time": "2019-07-31 17:58:40",
          "duration": 9,
          "pbx_call_id": "out_807ghh1h7f09fa7a188dbf8a6998b1c9ghg4ij06",
          "record": 1,
          "record_url_till": "2020-07-24 20:08:10",
          "contact_type": "customer",
          "contact_name": "GoodCompany",
          "contact_customer_id": 3486,
          "contact_employee_id": null,
          "employee_customer_id": null,
          "contact_user_id": null,
          "is_lead": 1,
          "record_urls": [
            {
              "url": "https://api.zadarma.com/v1/pbx/record/download/[...]/[...]/[...].mp3"
            }
          ]
        }
      ]
    }

    gdzie

    • totalCount — łączna liczba połączeń (w tym ciąg wyszukiwania i filtr)
    • calls — tablica połączeń (z uwzględnieniem podziału na strony). Każdy element tablicy zawiera następujące parametry:
      • id - identyfikator połączenia
      • type - typ połączenia. Prawidłowe wartości:
        • incoming — przychodzące połączenie
        • outgoing — wychodzące połączenie
      • status — status połączenia. Prawidłowe wartości:
        • answer — udane połączenie
        • noanswer — brak odpowiedzi
        • cancel — anulowano
        • busy — zajęty
        • failed — nie powiodło się
      • phone - numer telefonu
      • user_id - użytkownik, który zainicjował lub odebrał połączenie
      • time - czas połączenia w formacie `YYYY-MM-DD hh:mm:ss`
      • duration - czas trwania połączenia w sekundach
      • pbx_call_id - identyfikator połączenia w Zadarma PBX
      • record - czy nagrywanie rozmów jest włączone
      • record_url_till - czas, do którego link do nagrania rozmowy będzie działał
      • contact_type - typ kontaktu. Prawidłowa wartość:
        • customer - klient lub potencjalny klient (patrz parametr is_lead)
        • employee - pracownik klienta
        • user - użytkownik
      • contact_name - nazwa kontaktu
      • contact_customer_id - identyfikator klienta lub potencjalnego klienta (jeśli połączenie jest powiązane z klientem)
      • contact_employee_id - identyfikator pracownika (jeśli połączenie jest powiązane z pracownikiem)
      • employee_customer_id - identyfikator klienta nadrzędnego (jeśli połączenie jest powiązane z pracownikiem)
      • contact_user_id - identyfikator użytkownika (jeśli połączenie jest powiązane z użytkownikiem)
      • is_lead - pokazuje, czy połączenie jest związane z potencjalnym klientem
      • record_urls - tablica nagrań rozmowy (może nie być wyświetlona, bo trzeba specjalnie wywołać). Każdy element tablicy jest obiektem zawierającym pole:
        • URL - link do nagrania rozmowy

    GET /v1/zcrm/contacts

    Zwraca listę wszystkich kontaktów (klientów, pracowników, leads, użytkowników) z numerami telefonów.

    Parametry

    • search (opcjonalnie) - ciąg wyszukiwania. Wyszukiwanie odbywa się w oparciu:
      • nazwiska i numery telefonów klientów, potencjalnych klientów, pracowników i użytkowników
      • Numery wewnętrzne użytkowników PBX
    • take (w przypadku paginacji) - ile kontaktów zwrócić (domyślnie 20)
    • skip (w przypadku paginacji) - ile kontaktów pominąć (domyślnie 0)

    Odpowiedź

    {
      "totalCount": 128,
      "contacts": [
        {
          "contact_type": "customer",
          // clients attributes...
        },
        {
          "contact_type": "employee",
          // employee attributes...
        },
        {
          "contact_type": "lead",
          // leads attributes...
        },
        {
          "contact_type": "user",
          // users attributes...
        }
      ]
    }

    gdzie

    • totalCount — łączna liczba kontaktów (w tym ciąg wyszukiwania)
    • contacts — tablica kontaktów. Każdy kontakt, w zależności od jego typu (klient, pracownik, lead, użytkownik), będzie miał swój własny zestaw atrybutów.

      Klient

      {
          "contact_type": "customer",
          "id": 3486,
          "name": "GoodCompany",
          "status": "company",
          "type": "client",
          "phone": {
            "phone": "+44123456789",
            "type": "work"
          },
          "responsible": {
            "id": 234,
            "name": "John Smith",
            "ext_num": "100"
          }
      }

      gdzie

      • contact_type — rodzaj kontaktu:
        • customer — klient
      • id — identyfikator klienta
      • name — imię klienta
      • status — status klienta. Możliwa wartość:
        • individual — osoba prywatna
        • company — firma
      • type — typ klienta. Możliwa wartość:
        • potential — potencjalny klient
        • client — klient
        • reseller — reseller
        • partner — partner
      • phone — numer telefonu. Zawiera następujące pola:
        • phone — numer
        • type — typ numeru. Możliwa wartość:
          • work — sracjonarny
          • personal — prywatny
      • responsible — odpowiedzialny użytkownik. Zawiera następujące pola:
        • id — identyfikator użytkownika
        • name — nazwa użytkownika
        • ext_num — wewnętrzny numer PBX użytkownika

      Pracownik klienta

      {
              "contact_type": "employee",
              "id": 8,
              "name": "John Smith",
              "phone": {
                "phone": "+44123456789",
                "type": "work"
              },
              "position": {
                "position": "manager",
                "title": ""
              },
              "customer": {
                "id": 3486,
                "name": "GoodCompany"
              },
              "responsible": {
                "id": 234,
                "name": "John Smith",
                "ext_num": "100"
              }
      }

      gdzie

      • contact_type — rodzaj kontaktu:
        • employee — pracownik
      • id — identyfikator pracownika
      • name — imię pracownika
      • phone — numer telefonu. Zawiera następujące pola:
        • phone — numer
        • type — typ numeru. Możliwa wartość:
          • work — stacjonarny
          • personal — prywatny
      • position — stanowisko pracownika. Zawiera następujące pola:
        • position — rodzaj stanowiska. Prawidłowe wartości:
        • ceo — prezes zarządu
        • director — wiceprezes zarządu
        • manager — menadżer
        • sales_manager — kierownik sprzedaży
        • hr — HR
        • support — obsługa klienta
        • custom — dowolne
      • title — nazwa dowolnej pozycji (dla position = custom)
    • customer — klient, do którego pracownik jest przywiązany. Zawiera następujące pola:
      • id — identyfikator klienta
      • name — imię klienta
    • responsible — użytkownik odpowiedzialny za klienta nadrzędnego. Zawiera następujące pola:
      • id — identyfikator użytkownika
      • name — imię użytkownika
      • ext_num — numer wewnętrzny centrali PBX użytkownika

    Lead

    {
    "contact_type": "lead",
    "id": 3486,
    "name": "GoodCompany",
    "phone": {
      "phone": "+44123456789",
      "type": "work"
    },
    "responsible": {
      "id": 234,
      "name": "John Smith",
      "ext_num": "100"
    }
    }

    gdzie

    • contact_type — rodzaj kontaktu:
      • lead — lead
    • id — identyfikator lead
    • name — imię lead
    • phone — numer telefonu. Zawiera następujące pola:
      • phone — numer
      • type — typ numeru. Możliwa wartość:
        • work — stacjonarny
        • personal — prywatny
    • responsible — odpowiedzialny użytkownik. Zawiera następujące pola:
      • id — identyfikator użytkownika
      • name — imię użytkownika
      • ext_num — numer wewnętrzny centrali PBX użytkownika

    Użytkownik

    {
        "contact_type": "user",
        "id": 234,
        "name": "John Smith",
        "avatar": 2457,
        "role": "",
        "status": "",
        "phone": {
          "phone": "100",
          "type": "internal"
        },
        "group": {
          "type": "admin",
          "title": ""
        }
      }

    gdzie

    • contact_type — typ kontakta:
      • user — użytkownik
    • id — identyfikator użytkownika
    • name — imię użytkownika
    • avatar — awatar użytkownika (identyfikator pliku)
    • role — rola użytkownika
    • status — status użytkownika
    • phone — numer telefonu. Zawiera następujące pola:
      • phone — numer
      • type — typ numeru. Prawidłowa wartość:
        • work — stacjonarny
        • personal — prywatny
        • internal — numer wewnętrzny centrali PBX
    • group — grupa użytkownika
      • type — typ grupy. Zawiera następujące pola:
        • admin — administratorzy
        • manager — menadżery
        • chat_operator — operatorzy
        • trainee — stażyści
        • custom — niestandardowe
      • title — imię użytkowników grupy (dla type = custom)

    GET /v1/zcrm/contacts/identify

    Identyfikuje kontakt (klient, pracownik, lead, użytkownik) według numeru telefonu.

    Parametry

    • phone — numer telefonu

    Odpowiedź

    Odpowiedź będzie zależeć od rodzaju znalezionego kontaktu (klient, pracownik, lead, użytkownik).

    Klient

    {
      "contact_type": "customer",
      "id": 3486,
      "name": "GoodCompany",
      "status": "company",
      "type": "client",
      "phone": {
        "phone": "+44123456789",
        "type": "work"
      },
      "responsible": {
        "id": 234,
        "name": "Jim Beam",
        "ext_num": "100"
      }
    }

    gdzie

    • contact_type — rodzaj kontaktu:
      • customer — klient
    • id — identyfikator klienta
    • name — imię klienta
    • status — status klienta. Możliwa wartość:
      • individual — osoba prywatna
      • company — firma
    • type — typ klienta. Możliwa wartość:
      • potential — potencjalny klient
      • client — klient
      • reseller — reseller
      • partner — partner
    • phone — numer telefonu. Zawiera następujące pola:
      • phone — numer
      • type — typ numeru. Prawidłowa wartość:
        • work — stacjonarny
        • personal — prywatny
    • responsible — odpowiedzialny użytkownik. Zawiera następujące pola:
      • id — identyfikator użytkownika
      • name — imię użytkownika
      • ext_num — numer wewnętrzny centrali PBX użytkownika

    Pracownik klienta

    {
      "contact_type": "employee",
      "id": 8,
      "name": "John Smith",
      "phone": {
        "phone": "+44123456789",
        "type": "work"
      },
      "position": {
        "position": "manager",
        "title": ""
      },
      "customer": {
        "id": 3486,
        "name": "GoodCompany"
      },
      "responsible": {
        "id": 234,
        "name": "Jim Beam",
        "ext_num": "100"
      }
    }

    gdzie

    • contact_type — rodzaj kontaktu:
      • employee — pracownik
    • id — identyfikator pracownika
    • name — imię pracownika
    • phone — numer telefonu. Zawiera następujące pola:
      • phone — numer
      • type — typ numeru . Możliwa wartość:
        • work — stacjonarny
        • personal — prywatny
    • position — stanowisko pracownika. Prawidłowe wartości:
      • position — rodzaj stanowiska. Prawidłowe wartości:
      • ceo — prezes zarządu
      • director — wiceprezes zarządu
      • manager — menadżer
      • sales_manager — kierownik sprzedaży
      • hr — HR
      • support — obsługa klienta
      • custom — dowolne
    • title — nazwa dowolnej pozycji (dla position = custom)
  • customer — klient, do którego pracownik jest przywiązany. Zawiera następujące pola:
    • id — identyfikator klienta
    • name — imię klienta
  • responsible — użytkownik odpowiedzialny za klienta nadrzędnego. Zawiera następujące pola:
    • id — identyfikator użytkownika
    • name — imię użytkownika
    • ext_num — numer wewnętrzny centrali PBX użytkownika
  • Lead

    {
      "contact_type": "lead",
      "id": 3486,
      "name": "GoodCompany",
      "phone": {
        "phone": "+44123456789",
        "type": "work"
      },
      "responsible": {
        "id": 234,
        "name": "Jim Beam",
        "ext_num": "100"
      }
    }

    gdzie

    • contact_type — rodzaj kontaktu:
      • customer — klient
    • id — identyfikator lead
    • name — imię lead
    • status — status klienta. Możliwa wartość:
      • individual — osoba prywatna
      • company — firma
    • type — typ klienta. Możliwa wartość:
      • potential — potencjalny klient
      • client — klient
      • reseller — reseller
      • partner — partner
    • phone — numer telefonu. Zawiera następujące pola:
      • phone — numer
      • type — typ numeru. Prawidłowa wartość:
        • work — stacjonarny
        • personal — prywatny
    • responsible — odpowiedzialny użytkownik. Zawiera następujące pola:
      • id — identyfikator użytkownika
      • name — imię użytkownika
      • ext_num — numer wewnętrzny centrali PBX użytkownika

    Użytkownik

    {
      "contact_type": "user",
      "id": 234,
      "name": "John Smith",
      "avatar": 2457,
      "role": "",
      "status": "",
      "phone": {
        "phone": "100",
        "type": "internal"
      },
      "group": {
        "type": "admin",
        "title": ""
      }
    }

    gdzie

    • contact_type — typ kontakta:
      • user — użytkownik
    • id — identyfikator użytkownika
    • name — imię użytkownika
    • avatar — awatar użytkownika (identyfikator pliku)
    • role — rola użytkownika
    • status — status użytkownika
    • phone — numer telefonu. Zawiera następujące pola:
      • phone — numer
      • type — typ numeru. Prawidłowa wartość:
        • work — stacjonarny
        • personal — prywatny
        • internal — numer wewnętrzny centrali PBX
    • group — grupa użytkownika
      • type — typ grupy. Zawiera następujące pola:
        • admin — administratorzy
        • manager — menadżery
        • chat_operator — operatorzy
        • trainee — stażyści
        • custom — niestandardowe
      • title — imię użytkowników grupy (dla type = custom)

    GET /v1/zcrm/files/<file_id>

    Zwraca plik według jego ID.

    Brak parametrów

     

    Informacja o połączeniach przychodzących

    System Zadarma może wysyłać informację o każdym połączeniu przychodzącym na centralę telefoniczną i kierować połączenia na odpowiedni numer wewnętrzny w zależności od odpowiedzi. Aby to zrobić, należy utworzyć otwarty publicznie dostępny link, jaki będzie otrzymywał POST-żądania z informacjami od systemu Zadarma.

    Dostępne metody:

    • NOTIFY_START
      czas rozpoczęcia połączenia przychodzącego na centralę.
    • NOTIFY_INTERNAL
      czas rozpoczęcia połączenia na wewnętrzny numer centrali.
    • NOTIFY_ANSWER
      odpowiedź przy połączeniu na numer wewnętrzny lub numer zewnętrzny.
    • NOTIFY_END
      czas zakończenia połączenia przychodzącego na wewnętrzny numer centrali.
    • NOTIFY_OUT_START
      czas rozpoczęcia połączenia wychodzącego z centrali.
    • NOTIFY_OUT_END
      czas zakończenia połączenia wychodzącego z centrali.
    • NOTIFY_RECORD
      nagranie rozmowy jest gotowe do pobrania.
    • NOTIFY_IVR
      odpowiedź abonenta na określone żądanie.
    • SPEECH_RECOGNITION
      wynik rozpoznawania głosu.

    Parametry, jakie są wysyłane do linku dla powiadomień:

    • event – wydarzenie (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.

    Sporządzanie weryfikacyjnego podpisu dla powiadamienia o połączeniach przychodzących, przykład na PHP:

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

    Dla żądania NOTIFY_START i NOTIFY_IVR istnieje możliwość na bieżąco zmiany działania scenariuszu dla obecnego połączenia wysyłając w odpowiedzi informację:

    Odtwarzać plik:

    {
        "ivr_play": "ID"
    }

    gdzie,

    • ivr_play – wartość kolumny ID na liście nagranych/przesłanych plików.

    Odtwarzaj popularny komunikat:

    {
        "ivr_saypopular": 1,
        "language": "en"
    }

    gdzie,

    • ivr_saypopular – numer komunikatu na liście;

    Odtwarzaj cyfry:

    {
        "ivr_saydigits": "12",
        "language": "en"
    }

    Odtwarzaj cyfry (zgodnie z zasadami liczb zespolonych):

    {
        "ivr_saynumber": "123",
        "language": "en"
    }

    gdzie,

    • language może zawierać jedno z parametrów: ru, ua, en, es, pl;

    Jeśli zostałe zawarte ivr_saydigits lub ivr_saynumber,przy następnym zdarzeniu NOTIFY_IVR będzie dodany parametr:

    "ivr_saydigits": "COMPLETE" lub"ivr_saynumber": "COMPLETE"

    W każdym z powyższych żądań może wystąpić żądanie wprowadzenia numerów od abonenta:

    {
        "wait_dtmf": {
            "timeout": TIMEOUT,
            "attempts": ATTEMPTS,
            "maxdigits": MAXDIGITS,
            "name": NAME,
            "default": DEFAULT,
        }
    }

    gdzie,

    • timeout - czas oczekiwania na wybieranie cyfr w sekundach;
    • attempts - ilość prób wybierania cyfr od abonenta;
    • maxdigits - maks. liczba cyfr, wybieranie których oczekiwać;
    • name - nazwa, jaka będzie w odpowiedzi;
    • default - żądanie, jeśli nic nie wybrano. Możliwe warianty:
      • id scenariuszu przekierowania (w formacie 0-1 gdzie 0 numer menu głosowego, 1 numer scenariuszu);
      • menu głosowego 0-main, gdzie 0 - to id menu;
      • numer wewnętrzny centrali (trzycyfrowy numer);
      • hangup - zakończ rozmowę.

    W następnym żądaniu NOTIFY_IVR będzie dodatkowy parametr:

    {
      	"wait_dtmf": {
    	    "name": NAME,
    	    "digits": DIGITS,
    	    "default_behaviour": "1"
        }
    }

    gdzie,

    • name - nazwa, podana w poprzedniej odpowiedzi;
    • digits - cyfry, wybrane abonentem;
    • default_behaviour - podane, jeśli abonent nic nie wybrał i zadziałało domyślne zachowanie;

    Przekierowanie połączenia:

    {
        "redirect": ID,
        "return_timeout": TIMEOUT (nieobowiązkowe)
    }

    gdzie,

    • redirect - id scenariuszu przekierowania (w formacie 0-1 gdzie 0 numer menu głosowego, 1 numer scenariuszu); lub menu głosowego 0-main, gdzie 0 - to id menu; lub numer wewnętrzny centrali (trzycyfrowy numer); lub "blacklist" - w tym przypadku połączenie zostanie odrzucone z sygnałem zajętości;
    • return_timeout - Parametr w sekundach. Możliwe warianty:
      • 0, połączenie nie zostanie zwrócone do menu;
      • >= 3 - czas próby łączenia z numerem wewnętrznym, przed zwróceniem na menu;
    • default_behaviour - podane, jeśli abonent nic nie wybrał i zadziałało domyślne zachowanie;

    Zakończ rozmowę:

    {
        "hangup": 1
    }

    W każdej odpowiedzi możesz opcjonalnie dodać:

    Nazwę lun nazwę przychodzącego numeru:

    {
    	"caller_name": NAME
    }

    gdzie,

    • caller_name - nazwa numeru.

    Lista popularnych komunikatów:

    Parametry, jakie są wysyłane do linku dla powiadomień:
    • event – wydarzenie (NOTIFY_INTERNAL)
    • 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.
    • internal – (nieobowiązkowy) wewnętrzny numer.

    Sporządzanie weryfikacyjnego podpisu dla powiadamienia o połączeniach przychodzących, przykład na PHP:

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

    Parametry, jakie są wysyłane do linku dla powiadomień:

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

    Sporządzanie weryfikacyjnego podpisu dla powiadamienia o połączeniach przychodzących, przykład na PHP:

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

    Parametry, jakie są wysyłane do linku dla powiadomień:

    • event – wydarzenie (NOTIFY_END)
    • 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;
    • internal – (nieobowiązkowy) wewnętrzny numer;
    • duration – czas trwania w sekundach;
    • disposition – stan połączenia:
      • 'answered' – rozmowa,
      • 'busy' – zajęte,
      • 'cancel' - odrzucone,
      • 'no answer' - brak odpowiedzi,
      • 'failed' - nieudane,
      • '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;
    • last_internal – numer wewnętrzny, ostatni uczestnik połączenia (po przekierowaniu lub przechwytywaniu);
    • status_code – kod statusu połączenia Q.931;
    • is_recorded – 1 - nagrywanie połączenia, 0 - bez nagrywania;
    • call_id_with_rec – id połączenia z funkcją nagrywania (polecamy ściągać pliki z nagraniami nie wcześniej jak 40 sekund po zawiadomieniu, bo dla prawidłowego zapisania nagrania potrzebny jest czas).

    Sporządzanie weryfikacyjnego podpisu dla powiadamienia o połączeniach przychodzących, przykład na PHP:

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

    Parametry, jakie są wysyłane do linku dla powiadomień:

    • event – wydarzenie (NOTIFY_OUT_START)
    • call_start – czas rozpoczęcia połączenia;
    • pbx_call_id – id połączenia;
    • caller_id – numer ustawiony na numerze wewnętrznym lub ustawiony w zasadach wybierania zgodnie z kierunkiem. Jeśli numer nie jest ustawiony, wyświetla się 0;
    • destination – numer na który było wykonane połączenie;
    • internal – (nieobowiązkowy) wewnętrzny numer.

    Sporządzanie weryfikacyjnego podpisu dla powiadamienia o połączeniach przychodzących, przykład na PHP:

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

    Parametry, jakie są wysyłane do linku dla powiadomień:

    • event – wydarzenie (NOTIFY_OUT_END)
    • call_start – czas rozpoczęcia połączenia;
    • pbx_call_id – id połączenia;
    • caller_id – numer ustawiony na numerze wewnętrznym lub ustawiony w zasadach wybierania zgodnie z kierunkiem. Jeśli numer nie jest ustawiony, wyświetla się 0;
    • destination – numer na który 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' - brak odpowiedzi,
      • 'failed' - nieudane,
      • '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łączenia, 0 - bez nagrywania;
    • call_id_with_rec –id połączenia z funkcją nagrywania (polecamy ściągać pliki z nagraniami nie wcześniej jak 40 sekund po zawiadomieniu, bo dla prawidłowego zapisania nagrania potrzebny jest czas).

    Sporządzanie weryfikacyjnego podpisu dla powiadamienia o połączeniach przychodzących, przykład na PHP:

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

    Parametry, jakie są wysyłane do linku dla powiadomień:

    • event – wydarzenie (NOTIFY_RECORD)
    • call_id_with_rec – indywidualny id z nagraniem rozmowy;
    • pbx_call_id – stały ID zewnętrznego połączenia w ramach Centrali (nie zmienia się według scenariuszu, menu głosowego, transferu itd.,wyświetlany jest w statystykach i powiadomieniach).

    Sporządzanie weryfikacyjnego podpisu dla powiadamienia o połączeniach przychodzących, przykład na PHP:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['pbx_call_id'] . $_POST['call_id_with_rec'], API_SECRET));

    Parametry, jakie są wysyłane do linku dla powiadomień:

    • event – wydarzenie (NOTIFY_IVR)
    • 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.

    Sporządzanie weryfikacyjnego podpisu dla powiadomienia o połączeniach przychodzących, przykład na PHP:

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

    Możliwe wysyłane odpowiedzi są odpowiednie do żądań NOTIFY_START

    Parametry, jakie są wysyłane do linku dla powiadomień:

    • event – wydarzenie (SPEECH_RECOGNITION)
    • lang – język;
    • result:
      • words - tablica:
        • result - lista słów (tablica):
          • s - czas rozpoczęcia słowa
          • e - czas rozpoczęcia słowa
          • w - słowo
        • channel - numer kanału
      • phrases - tablica:
        • result - fraza
        • channel - numer kanału

    Ustawić link do powiadomień, a także włączyć/wyłączyć rodzaje powiadomień możesz w zakładce API panelu klienta.

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

    Przykład na PHP:

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

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

    Również, jeśli utworzyłeś klucze dostępu API, w każdym żądaniu na Twój link będzie wysłany dodatkowy nagłówek "Signature", po jakim możesz zweryfikować integralność i autentyczność danych.

    Przykładowy skrypt możesz sprawdzić w naszym repozytorium na GitHub.

    Inne powiadomienia:

    Parametr "result" w tych powiadomieniach jest w formacie JSON. Możesz otrzymać go w formacie XML zaznaczając w linku format=xml.

    • NUMBER_LOOKUP
      wynik sprawdzenia numerów.
    • CALL_TRACKING
      raport połączeń na numery, podłączone do calltracking
    • SMS
      informacja o wiadomościach SMS.

    Parametry, jakie są wysyłane do linku do powiadomień:

    • event – wydarzenie (NUMBER_LOOKUP)
    • success – status sukcesu sprawdzenia;
    • description – tekstowy opis zakończenia sprawdzenia;
    • result – dane wyniku;
      • number – sprawdzony numer;
      • mcc – kod kraju;
      • mnc – kod operatora;
      • ported – znak przeniesienia numeru do innego operatora;
      • roaming – znak przebywania w roamingu;
      • error – status błędu;
      • errorDescription – tekstowy opis błędu;
      • mccName – nazwa kraju;
      • mncName – nazwa operatora;

    Sporządzenie weryfikacji podpisu:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

    Wysyłany co 15 minut, przy otrzymaniu nowych połączeń.

    Parametry, jakie są wysyłane do linku do powiadomień:

    • event – wydarzenie (CALL_TRACKING)
    • result - tablica
      • tracker - ID tracking (można sprawdzić na stronię kopiowania kodu);
      • start - czas rozpoczęcia rozmowy;
      • duration - czas trwania rozmowy w sek.;
      • caller_id - numer osoby dzwoniącej;
      • caller_did - numer, na jaki dzwonili;
      • country - (opcjonalnie) kraj, do którego było wykonane połączenie;
      • ga_id - (opcjonalnie, jeśli w ustawieniach jest ID Google Analytics) id użytkownika Google Analytics;
      • metrika_id - (opcjonalnie, jeśli w ustawieniach jest ID Yandex.Metrika) id użytkownika Yandex.Metrika;
      • url - adres strony, z której było połączenie;
      • utm_source, utm_medium, utm_campaign, utm_term, utm_content - (opcjonalnie, jeśli określono tagi utm podczas przejścia na stronę) tagi utm, za pomocą których użytkownik odwiedził witrynę po raz ostatni;
      • first_utm - (opcjonalnie, jeśli witryna została odwiedzona po raz pierwszy z tagami utm innymi niż te po raz ostatni) lista tagów utm wskazanych powyżej, kiedy użytkownik po raz pierwszy odwiedził stronę;

    Sporządzenie weryfikacji podpisu:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));

    Parametry, jakie są wysyłane do linku do powiadomień:

    • event – zdarzenie (SMS)
    • result – tablica;
    • caller_id – numer nadawcy;
    • caller_did – numer odbiorcy;
    • text – tekst wiadomości.

    Sporządzenie weryfikacji podpisu:

    $signatureTest = base64_encode(hash_hmac('sha1', $_POST['result'], API_SECRET));