API

La interfaz API de Zadarma permite utilizar el servicio para aplicaciones propias, así como para la integración con cualquier sistema CRM y programas para call centers.

La implementación de API es abierta y puede modificarse por cualquier desarrollador porque no requiere un elevado nivel de conocimientos.

En API están disponibles todas las funciones principales:

  • visualización y cambio de ajustes de SIP y PBX;
  • visualización de datos estadísticos y de saldo ;
  • envío de de llamadas (CallBack a números externos e internos) y de mensajes SMS;
  • aviso sobre servidor externo sobre cada llamada entrante a la centralita PBX, así como enrutamiento exterior de las llamadas.

Enlace a API: https://api.zadarma.com

Versión API: v1

Enlace final al método: https://api.zadarma.com/v1/METHOD/

Puedes bajarte una clase preparada sobre PHP para trabajar con API, en GitHub.

Autorización

Cada consulta que requiere autorización se acompaña de un título complementario del tipo:

"Authorization: clave_de usuario: firma"

Es necesario obtener las claves de autorización en el área personal.

La firma se crea mediante el siguiente logaritmo:

  • una serie de parámetros transmitidos (GET, POST, PUT, DELETE) se seleccionan según el nombre de la clave por orden alfabético;
  • de la serie obtenida se forma la cadena de consulta (por ejemplo, la función http_build_query в PHP), ejemplo “from=DATEFROM&to=DATETO…”;
  • etc, se unifica según la fórmula:
    cadena= nombre_método cadena_consulta md5( cadena_consulta ),
    donde nombre_del método” - cadena de consulta, comenzando con el dominio (indicando la versión API), hasta el comienzo de cálculo de parámetros, por ejemplo - /v1/sip/"
  • la cadena resultante se copia en base al algoritmo sha1 con la clave personal del usuario:
    hash = hash( cadena, clave_personal )
  • y después el hash se codifica en base64
    firma = base64_encode( hash )

Ejemplo de PHP:

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

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

La clase preparada de PHP para trabajar con API, la puedes bajar en GitHub.

Formatos de respuesta: json (por defecto) и xml.

Para obtener respuesta de API en el formato xml, a la cadena de consulta se le añade el parámetro "format=xml".

Restricciones

La respuesta contiene información sobre los límites y la consulta actual, ejemplo:

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

donde,

  • X-Zadarma-Method - método actual de llamada;
  • X-RateLimit-Remaining - número de consultas que quedan, considerando el límite del método y del usuario;
  • X-RateLimit-Limit - cifra del límite general de consultas por minutos;
  • X-RateLimit-Reset - hora de establecimiento del límite.

Restricciones generales - 100 consultas por minuto, por métodos estadísticos - 10 consultas al minuto.

En caso de bloqueo, el método ofrecela respuesta con 429 el encabezamiento "You exceeded the rate limit".

La respuesta se compone de clave obligatoria "status" (success или error). Después, dependiendo de método, se ofrecen las claves con la información requerida.

En caso de error, se ofrece una clave complementaria"message" con descripción del error.

Además, todas las respuestas se acompañan de los correspondientes encabezamientos HTTP.

Ejemplo de respuesta de error:
JSON:

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

XML:

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

Métodos disponibles:

GET /v1/info/balance/ - saldo del usuario.

más información

Ejemplo de respuesta:
JSON:

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

    XML:

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

GET /v1/info/price/ - coste de la llamada considerando la tarifa actual del usuario.

más información

Parámetros:
  • number – número de teléfono
  • caller_id (opcional) – CallerID que va a utilizarse al finalizar la llamada.
Ejemplo de respuesta:
JSON:

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

    XML:

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

GET /v1/tariff/ - información sobre la tarifa actual del usuario.

más información

Ejemplo de respuesta:
JSON:

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

    XML:

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

donde,

  • tariff_id – ID de la tarifa actual del usuario;
  • tariff_name – nombre de la tarifa actual del usuario;
  • is_active – tarifa actual activa o no activa;
  • cost – coste de la tarifa;
  • currency – moneda de la tarifa;
  • used_seconds – cantidad de segundos de tarifa que se utilizan;
  • used_seconds_mobile – cantidad de segundos de tarifa que se utilizan en teléfonos móviles;
  • used_seconds_fix – cantidad de segundos de tarifa que se utilizan en teléfonos fijos;
  • tariff_id_for_next_period – ID de la tarifa del usuario en el periodo posterior;
  • tariff_for_next_period – nombre de la tarifa de usuario en el período posterior.

GET /v1/request/callback/ - запрос на callback.

подробнее

Parámetros:
  • from – tu número de teléfono o SIP, o número de extensión de la PBX, o número del escenario de PBX, al que es llamado callback;
  • to – número de teléfono o SIP, al que se llama;
  • sip (opcional) – número SIP-del usuario o número de extensión de la PBX (ejemplo 100), a través del cual pasará la llamada. Se va a utilizar el CallerID de este número, y en los datos estadísticos va a mostrarse dicho número SIP/PBX, si para el número indicado, está activado el registro de llamadas o los prefijos de marcado, esto también es cierto para éstos;

  • predicted (opcional) – si este símbolo está indicado, entonces la consulta es de tipo predicativo (el sistema en un principio llama “a” y solo se establece la llamada, se conecta con tu SIP o con el número de teléfono;
Ejemplo de respuesta:
JSON:

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

    XML:

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

GET /v1/sip/ - listado de los números SIP del usuario.

más información

Ejemplo de respuesta:
JSON:

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

    XML:

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

где,

  • id – SIP-id;
  • display_name – nombre mostrado;
  • lines – número/cantidad de líneas;
  • left –cantidad/número de SIP, que se pueden crear (depende del saldo del usuario y del número/cantidad total de las SIP que ya hayan sido creadas).

PUT /v1/sip/callerid/ - Cambio de CallerID.

más información

Parámetros:
  • id – SIP id, a los que modifica el Caller ID;
  • number – número al que se cambia a formato internacional (de la lista de números confirmados o de comprados por el usuario).
Ejemplo de respuesta:
JSON:

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

    XML:

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

GET /v1/sip/redirection/ - visualización de los redireccionamientos actuales en base a los números SIP del usuario.

más información

Parámetros:
  • id – (opcional) elección de un id de SIP especifico.
Ejemplo de respuestа:
JSON:
    {
        "status":"success",
        "info": [
            {
                "sip_id":"00001",
                "status":"on",
                "condition":"always",
                "destination":"phone",
                "destination_value":"442037691880",
            },
            ...
        ]
    }

    XML:

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

где,

  • sip_id – id del SIP del usuario;
  • status – estado actual: on u off;
  • condition – condiciones de redireccionamiento: always – siempre (por defecto), unavailable –en caso de no responder a la llamada o de que no exista conexión con SIP;
  • destination – adónde se redirecciona: phone – al número de teléfono, pbx – a la PBX;
  • destination_value – número al que se redirecciona: número de teléfono o ID de la PBX.

GET /v1/direct_numbers/ - información de los números directos del usuario.

más información

Ejemplo de respuesta:
JSON:

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

    XML:

        <?xml version="1.0"?>
        <answer>
        <status>success</status>
        <info>
            <value>
                <number>442037691880</number>
                <status>on</status>
                <country>Reino Unido</country>
                <description>Londres</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>

    

En función del tipo de número, ¡puede variar la selección de los campos! Descripción de los campos:

  • number – número directo del usuario que ha sido adquirido;
  • status – estado del número;
  • country – país (para common и revenue);
  • description – descripción: ciudad o tipo (para common и revenue);
  • number_name – "nombre" del número directo (se crea por parte del usuario);
  • sip – SIP, vinculado al número;
  • sip_name – "nombre" SIP, vinculado al número;
  • start_date – fecha de la compra del número por parte del usuario;
  • stop_date – fecha de finalización de plazo para el pago del número por parte del usuario;
  • monthly_fee – coste del número (para common);
  • currency – moneda de coste del número (para common);
  • channels – número de líneas en el número (para common);
  • minutes – extensión total de las llamadas entrantes durante el mes corriente (para revenue);
  • autorenew – si está activada la extensión automática del plazo (para common, revenue, rufree);
  • is_on_test – si se encuentra el número en fase de prueba;
  • type – tipo de número: common (número directo), inum (número internacional gratuito), rufree (número moscovita gratuito), revenue (número moscovita gratuito 495)

GET /v1/sim/ - información sobre las tarjetas SIM del usuario.

más información

Ejemplo de respuesta:
JSON:

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

    XML:

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

donde,

  • iccid – ID de la tarjeta SIM;
  • name – "nombre" de tarjeta SIM;
  • sip – a qué SIP está vinculada la tarjeta;
  • phone_number – número de teléfono de la tarjeta;
  • redirect_to – adónde están redireccionadas las llamadas entrantes a la tarjeta (варинат: simcard, );
  • status – estado actual de la tarjeta SIM;
  • internet – Internet activado o desactivado.

PUT /v1/sip/redirection/ - activación/desactivación del redireccionamiento por número SIP.

más información

Parámetros:
  • id – SIP id;
  • status – estado actual del redireccionamiento en el número SIP seleccionado.
Ejemplo de respuesta:
JSON:

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

    XML:

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

PUT /v1/sip/redirection/ - modificación de parámetros de redireccionamiento.

más información

Parámetros:
  • id – SIP id;
  • type – tipo de redireccionamiento: phone – al teléfono;
  • number – número de teléfono.
Ejemplo de respuesta:
JSON:

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

    XML:

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

GET /v1/pbx/internal/ - visualización de extensiones de la PBX.

más información

Ejemplo de respuesta:
JSON:
    {
        "status":"success",
        "pbx_id":1234,
        "numbers": [
            100,
            101,
            ...
        ]
    }

    XML:

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

donde,

  • pbx_id – id de la PBX del usuario;
  • numbers – listado de extensiones.

PUT /v1/pbx/internal/recording/ - activación del registro de llamadas en la extensión de la PBX.

más información

Parámtros:
  • id – extensión de la PBX;
  • status – estado: "on" - activar, "off" -desactivar;
  • email – (opcional) cambio de la dirección de correo a la que va a e viarse el registro de llamadas. Puedes indicar hasta 3 direcciones de correo seguidas de una coma.
Ejemplo de respuesta:
JSON:

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

    XML:

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

GET /v1/pbx/record/request/ - consulta de archivo de registro de llamadas.

más información

Parámetros:
  • call_id – id único de la llamada, este id está indicado en el nombre del archivo con la grabación de la llamada (es único para cada grabación en los datos estadísticos);
  • pbx_call_id – ID permanente de la llamada externa a la PBX (no cambia cuando se producen los escenarios del menú de voz, transfer, etc., se refleja en los datos estadísticos y en las notificaciones);
  • lifetime – (opcional) duración del enlace en segundos (mínimo - 180, máximo - 5184000, por defecto - 1800).

Nota: es suficiente indicar uno de los dos números de identificación (pbx_call_id или call_id), cuando se indique pbx_call_id en la respuesta a la solicitud puede haber varios enlaces.

Ejemplo de respuesta cuando se indica solo call_id, sólo un enlace:
JSON:

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

    XML:

    <?xml version="1.0"?>
    <answer>
    <status>success</status>
    <link>https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3</link>
    <lifetime_till>2016-01-01 23:56:22</lifetime_till>
    </answer>
    
Ejemplo de respuesta cuando se indica solo pbx_call_id, puede haber varios enlaces:
	JSON:
    {
        "status":"success",
        "links":[
            "https://api.zadarma.com/v1/pbx/record/download/NjM3M..NzM2Mg/1-1458313316.343456-100-2016-01-11-100155.mp3",
            "https://api.zadarma.com/v1/pbx/record/download/pw7Cj..iOzn99/1-1458313475.213487-101-2016-01-11-100211.mp3"
        ],
        "lifetime_till": "2016-01-01 23:56:22"
    }

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

donde

  • link – enlace al archivos de llamadas;
  • lifetime_till – hasta qué hora va a funcionar el enlace.

POST /v1/sms/send/ - envñio de SMS.

más información

Parámtros:
  • number – número de teléfono, de envío de SMS (se puede nombrar varios seguidos de una coma);
  • message – mensaje (restricciones estándar de la longitud de los mensajes SMS, en caso de superar el límite – se divide en varios SMS);
  • caller_id – (opcional) número de teléfono desde el que se envía el SMS (se puede enviar solo del listado de números confirmados por el usuarios).

Atención: el envío de SMS está disponible solo dentro de la FR.

Ejempo de respuesta:
JSON:

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

    XML:

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

GET /v1/statistics/ - получение общей статистики.

más información

Parámetros:
  • start - fecha de comienzo de visualización de datos estadísticos (formato - Y-m-d H:i:s);
  • end - fecha de fin de visualización de datos estadísticos (formato - Y-m-d H:i:s);
  • sip (opcional) - filtro por determinado número SIP;
  • cost_only (opcional) - visualización solo de los fondos gastados durante el período;
  • type (opcional - solo en los datos estadísticos generales) - tipo de consulta: general (no se indica en la consulta), toll y ru495. (para los datos estadísticos de los números 800 y números gratuitos 495).

Período máximo recibo de datos estadísticos - mes. En caso de superar el límite en la consulta - el período se reduce automáticamente a 30 días. Si no se indica la fecha de comienzo de la selección, se elige el comienzo del mes en curso. Si no se indica la fecha de final de la selección – la selección se limite a la fecha y hora en curso.

Ejemplo de respuesta:
JSON:

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

    XML:

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

где,

  • start – fecha de comienzo de visualización de datos estadísticos;
  • end – fecha de finalización de visualización de datos estadísticos;
  • id – id de la llamada;
  • sip – número SIP;
  • callstart – hora de comienzo de la llamadа;
  • description – descripción de destino de la llamada;
  • disposition – estad de la llamada:
    • 'answered' – llamada,
    • 'busy' – ocupado,
    • 'cancel' - cancelado,
    • 'no answer' - no responde,
    • 'failed' - no ha sido posible,
    • 'no money' - no hay fondos, se ha superado el límite,
    • 'unallocated number' - el número no existe,
    • 'no limit' - se ha superado el límite,
    • 'no day limit' - se ha superado el límite diario,
    • 'line limit' - se ha superado el límite de líneas,
    • 'no money, no limit' - se ha superado el límite;
  • billseconds – número de segundos de la llamada;
  • cost – coste de minutos de llamada a este destino;
  • billcost – coste de los minutos abonados;
  • currency – moneda de pago
  • from – desde qué número han llamado;
  • to –adónde han llamado.
?type=cost_only:
JSON:

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

    XML:

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

donde,

  • cost – coste de las llamadas en el periodo seleccionado;
  • currency –moneda de coste;
  • seconds – número de segundos

GET /v1/statistics/pbx/ - datos estadísticos de la PBX

más información

Parámetros:
  • start - fecha de comienzo de visualización de datos estadísticos (formato - Y-m-d H:i:s);
  • end - fecha de final de visualización de datos estadísticos (formato - Y-m-d H:i:s);
Ejemplo de respuesta:
JSON:

    {
        "status":"success",
        "start":"2015-06-01 00:00:00",
        "end":"2015-06-30 23:59:59",
        "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
            },
            …
        ]
    }

    XML:

    <?xml version="1.0"?>
    <answer>
        <status>success</status>
        <start>2015-06-01 00:00:00</start>
        <end>2015-06-30 23:59:59</end>
        <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>
            </value>
            …
            </stats>
    </answer>
    

donde,

  • start – fecha de comienzo de visualización de datos estadísticos;
  • end – fecha de final de visualización de datos estadísticos;
  • call_id – id único de la llamada, este id está indicado en el nombre del archivo con registro de la llamadа;
  • sip – número SIP;
  • callstart – hora de comienzo de la llamada;
  • clid – CallerID;
  • destination – adónde han llamado;
  • disposition – estado de la llamada:
    • 'answered' – llamada,
    • 'busy' – ocupado,
    • 'cancel' - cancelado,
    • 'no answer' - no hay respuesta,
    • 'failed' - no ha sido posible,
    • 'no money' - no hay fondos, se ha superado el límite,
    • 'unallocated number' - номер не существует,
    • 'no limit' - se ha superado el límite,
    • 'no day limit' - se ha superado el límite diario,
    • 'line limit' - se ha superado el límite de líneas,
    • 'no money, no limit' - se ha superado el límite;
  • seconds – número de segundos por llamada;
  • is_recorded – (true, false) está grabada o no la conversación;

GET /v1/statistics/callback_widget/ - estadísticas de ¨Llámame¨ widget

más información

Parámetros:
  • start - fecha de comienzo de visualización de datos estadísticos (formato - Y-m-d H:i:s);
  • end - fecha de fin de visualización de datos estadísticos (formato - Y-m-d H:i:s);
  • widget_id - (opcional) - un identificador de widget, si no hay ningún parámetro se toma estadísticas de todos los widgets);

Período máximo recibo de datos estadísticos - mes. En caso de superar el límite en la consulta - el período se reduce automáticamente a 30 días. Si no se indica la fecha de comienzo de la selección, se elige el comienzo del mes en curso. Si no se indica la fecha de final de la selección – la selección se limite a la fecha y hora en curso.

Ejemplo de respuesta:
JSON:

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

    XML:

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

                        <date>2016-09-08 16:54:35</date>
                    </value>
                </actions>
            </value>
            ...
        </stats>
    </answer>    
    

donde,

  • start – fecha de comienzo de visualización de datos estadísticos;
  • end – fecha de finalización de visualización de datos estadísticos;
  • id – id de la sesión;
  • widget_id – id del widget;
  • sip – número SIP;
  • ip – dirección IP del visitante;
  • kind – tipo de evento:
    • 'come' – el visitante ha llegado a una página con widget,
    • 'show' – se muestra la forma de widget,
    • 'call' – solicitud de devolución de llamada,
    • 'call_request' – solicitud de devolución de llamada con retraso,
    • 'rate' – el visitante ha evaluado la llamada,
    • 'fail' – el visitante señaló que no se ha producido devolución de llamada,
    • 'close' – el visitante ha cerrado la ventana de widget;
  • date – echa y hora del evento;
  • referrer_url – dirección de la página desde la que el usuario ha pasado a la página con widget (solo para los eventos 'come');
  • url – dirección de la página del widget (solo para los eventos 'come');
  • rate – para los eventos 'show' – número de puntos obtenidos , para los eventos 'rate' – valoración de la llamada;
  • request_call_date – fecha y hora preferida para la devolución de llamada que ha sido indicada por el visitante (solo para los eventos 'call_request');
  • redial – (true, false) se ha hecho otra llamada o bien no hay respuesta a la solicitud de devolución de llamada con retraso (solo para los eventos 'call_request');
  • number – número de teléfono introducido por el visitante (para los eventos 'call', 'call_request', 'rate', 'fail').

Información sobre las llamadas entrantes

El sistema Zadarma puede enviar información de cada llamada entrante a la PBX virtual y dirigir la llamada al número de extensión adecuado en función de la respuesta. Para ello es necesario crear un enlace abierto de acceso general, el cal va a recibir las consultas POST-con información del sistema Zadarma.

Los tipos existentes de notificaciones:

NOTIFY_START - comienzo de la llamada entrante en la PBX.

más en detalle

Parámetros que se envían al enlace para notificación:

  • event – evento (NOTIFY_START)
  • call_start – hora del inicio de la llamada;
  • pbx_call_id – id de la llamada;
  • caller_id –número del llamante;
  • called_did – número del destino de la llamada.

NOTIFY_INTERNAL - inicio de la llamada entrante al número de extensión de la PBX.

más en detalle

Parámetros que se envían al enlace para notificación:

  • event – событие (NOTIFY_INTERNAL)
  • call_start – hora de inicio de la llamada;
  • pbx_call_id – id de la llamada;
  • caller_id – número del llamante;
  • called_did – número del destino de la llamada;
  • internal – (opcional) número de extensión.

NOTIFY_END - final de la llamada entrante al número de extensión de la PBX.

más en detalle

Parámetros que se envían al enlace para notificación:

  • event – событие (NOTIFY_END)
  • call_start – hora de inicio de la llamada;
  • pbx_call_id – id de la llamada;
  • caller_id – número del llamante;
  • called_did – número del destinatario;
  • internal – (opcional) número de extensión;
  • duration –duración en segundos;
  • disposition – estado de la llamada:
    • 'answered' – llamada,
    • 'busy' – ocupado,
    • 'cancel' - cancelado,
    • 'no answer' - no hay respuesta,
    • 'failed' - no ha sido posible,
    • 'no money' - no hay fondos, se ha superado el límite,
    • 'unallocated number' - номер не существует,
    • 'no limit' - se ha superado el límite,
    • 'no day limit' - se ha superado el límite diario,
    • 'line limit' - se ha superado el límite de líneas,
    • 'no money, no limit' - se ha superado el límite;
  • status_code – código del estado de la llamada Q.931;
  • is_recorded – 1 - hay grabación de la llamada, 0 - no hay grabación;
  • call_id_with_rec – id de la llamada con grabación.

NOTIFY_OUT_START - inicio de la llamada entrante desde la PBX.

más en detalle

Parámetros que se envían al enlace para notificación:

  • event – evento (NOTIFY_OUT_START)
  • call_start – hora del inicio de la llamada;
  • pbx_call_id – id de la llamada;
  • destination – número al que se llama;
  • internal – (opcional) número de extensión.

NOTIFY_OUT_END - final de la llamada saliente desde la PBX.

más en detalle

Parámetros que se envían al enlace para notificación:

  • event – evento (NOTIFY_OUT_END)
  • call_start – hora del inicio de la llamada;
  • pbx_call_id – id de la llamada;
  • caller_id – número del llamante;
  • destination – número del destinatario de la llamada;
  • internal – (opcional) número de extensión;
  • duration – duración en segundos;
  • disposition – estado de la llamada:
    • 'answered' – llamada,
    • 'busy' – ocupado,
    • 'cancel' - cancelado,
    • 'no answer' - no hay respuesta,
    • 'failed' - no ha sido posible,
    • 'no money' - no hay fondos, se ha superado el límite,
    • 'unallocated number' - номер не существует,
    • 'no limit' - se ha superado el límite,
    • 'no day limit' - se ha superado el límite diario,
    • 'line limit' - se ha superado el límite de líneas,
    • 'no money, no limit' - se ha superado el límite;
  • status_code – código del estado de la llamada Q.931;
  • is_recorded – 1 - hay grabación de la llamada, 0 - no hay grabación;
  • call_id_with_rec – id de la llamada con grabación.

Puedes crear el enlace para notificaciones y activar/desactivar cada tipo de notificación en la sección AP del área privada.

Para que el sistema acepte el enlace, es necesario añadir un código de verificación al comienzo del script.

Ejemplo en PHP:

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

Para aumentar la seguridad, recomendamos ampliar el acceso a tu enlace solo desde IP 185.45.152.42.

Por otro lado, si has liberado las claves de acceso a API, cada consulta a tu enlace irá acompañamiento adicional "Signature", por la cual podrás verificar la integridad y la autenticidad de los datos.

Elaboración de firma de verificación, ejemplo en PHP:

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

Para casa consulta se puede cambiar «sobre la marcha» los escenarios de trabajo de una llamada en curso, enviando esto en respuesta a la información:

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

donde,

  • redirect – escenarios id del redireccionamiento o de la extensión PBX, "blacklist" - en este caso la llamada será rechazada con la señal de ocupado;
  • caller_name – puede nombrarse el número de la llamada entrante.

La duración máxima de la respuesta con información sobre el redireccionamiento y nombre del número - menos de 2 segundos

Un ejemplo de script se puede visualizar en nuestro repositorio en GitHub.