API

La interfaz API de Zadarma te permite usar el servicio para tus propias aplicaciones, así como para conectar con cualquier sistema CRM y programas para call centers. La implementación de API es abierta, cualquier desarrollador puede trabajar con ella gracias a su sencillez.

En API están disponibles todas las funciones básicas:

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

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

Versión API: v1

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

Descarga las clases preparadas de ayuda PHP, Python para trabajar con API en nuestro GitHub.

Autorización

Cada solicitud que requiere autorización va a compañada con el título correspondiente del tipo:
"Authorization: contraseña_del usuario: firma"

Las contraseñas de autorización debes obtenerlas en .

La firma se realiza de acuerdo con el siguiente algoritmo:

Ejemplo en 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;

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

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

Para obtener respuesta en API en formato xml, se agrega un parámetro a la cadena de consulta "format=xml".

Limitaciones

La respuesta también contiene información sobre los límites y la solicitud actual, por ejemplo:

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

donde,

  • X-Zadarma-Method - método de llamada actual;
  • X-RateLimit-Remaining - número de solicitudes restantes, teniendo en cuenta el límite en el método y por usuario;
  • X-RateLimit-Limit - número total de visitas por minuto;
  • X-RateLimit-Reset - límite de tiempo de reinicio.

Limitaciones generales - 100 solicitudes por minuto, en métodos estadísticos: 10 solicitudes por minuto.

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

La respuesta se compone de la contraseña obligatoria "status" (success o bien error). Más adelante, en función del método se proporcionan sus contraseñas, con la información solicitada.

En caso de error, se proporciona una contraseña adicional "message" con la descripción del error.

Del mismo modo, todas las respuestas van acompañadas de los correspondientes encabezados HTTP.

Ejemplo de respuesta a 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:

  • /v1/info/balance/
    saldo del usuario.
  • /v1/info/price/
    el coste de una llamada en base a la tarifa actual del usuario.
  • /v1/info/timezone/
    huso horario del usuario.
  • /v1/tariff/
    información sobre la tarifa actual del usuario.
  • /v1/request/callback/
    devolucion de llamada.
  • /v1/sip/
    relación de números SIP del usuario.
  • /v1/sip/<SIP>/status/
    estado online de número SIP del usuario.
  • /v1/sip/callerid/
    cambio del CallerID.
  • /v1/sip/redirection/
    visualización de reenvíos actuales por números SIP del usuario.
  • /v1/direct_numbers/
    información sobre números directos del usuario.
  • /v1/sim/
    información sobre tarjetas SIM del usuario.
  • /v1/sip/redirection/
    activación/desactivación del reenvío en base al número SIP.
  • /v1/sip/redirection/
    modificación de los parámetros de reenvío.
  • /v1/pbx/internal/
    visualización de los números de extensión de la PBX.
  • /v1/pbx/internal/<PBXSIP>/status/
    estado online del número de extensión de la PBX.
  • /v1/pbx/internal/recording/
    activación de la grabación de llamadas en el número de extensión de la PBX.
  • /v1/pbx/record/request/
    solicitud de un archivo de grabación de la llamada.
  • /v1/sms/send/
    envío de SMS.
  • /v1/statistics/
    obtención de estadísticas generales.
  • /v1/statistics/pbx/
    datos estadísticos sobre la PBX.
  • /v1/statistics/callback_widget/
    datos estadísticos del widget de devolución de llamada.
  • 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>

Parámetros:

  • number – número de teléfono
  • caller_id (опционально) – CallerID, que va a utilizarse para realizar la llamada.

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

donde

  • tariff_id– ID de la tarifa actual del usuario;
  • tariff_name – nombre de de la tarifa actual del usuario;
  • is_active – tarifa actual activa o inactiva;
  • cost – coste de la tarifa;
  • currency – moneda de la tarifa;
  • used_seconds – número de segundos utilizados e dla tarifa;
  • used_seconds_mobile –número de segundos usados en teléfonos celulares;
  • used_seconds_fix – número de segundos utilizados de la tarifa a teléfonos fijos;
  • tariff_id_for_next_period – ID de la tarifa del usuario en el siguiente período;
  • tariff_for_next_period – nombre de la tarifa del usuario en el siguiente período.

Parámetros:

  • from – tu número de teléfono o SIP, o el número de extensión de la PBX, o el número de secuencia de comandos PBX al que se realiza la devolución de llamada;
  • 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 (por ejemplo 100), a través del que se realiza la llamada. Se va a utilizar el CallerID de este número, en los datos estadísticos se va a mostrar este número SIP/АТС, si el número especificado incluye grabación de llamadas o prefijos de marcación, también se usarán;

  • predicted (opcional) – si se especifica este indicador, entonces la solicitud es predicativa (el sistema llama inicialmente al número "to" y solo si se termina de marcar, se conecta a tu SIP o número de teléfono);
  • 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>

donde

  • id– SIP-id;
  • display_name – nombre en pantalla;
  • lines – número de líneas;
  • left – número de SIP restantes que se puede crear (depende del saldo del usuario y del número total de SIP ya creados).
  • 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>

Parámetros:

  • id – ID SIP al cual cambian los CallerID;
  • number – número, que se cambia en formato internacional (de la lista de números de usuarios confirmados o comprados).
  • 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>

Parámetros:

  • id – selección (opcional) de id específico de SIP.
  • 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>

donde

  • sip_id– Id de SIP del usuario;
  • status – estado actual: on o bien off;
  • condition – condiciones de reenvío: always – siempre (por defecto), unavailable – en el caso de no levantar el auricular o en caso de ausencia de una conexión SIP;
  • destination – куда переадресовывается: phone – на номер телефона, pbx – на АТС;
  • destination_value – номер, куда переадресовывать: номер телефона или ID АТС.
  • 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>

Dependiendo del tipo de número, ¡el conjunto de campos puede diferir! Descripción de los campos:

  • number – número comprado del usuario;
  • status – estado del número;
  • country – país (para common y revenue);
  • description – descripción: ciudad o tipo (para common y revenue);
  • number_name – "nombre" de número virtual (se crea por el usuario);
  • sip – SIP vinculado al número;
  • sip_name – "nombre" SIP, vinculado al número;
  • start_date – fecha de compra del número por parte del usuario;
  • stop_date – fecha de finalización del plazo de 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 – duración general de las llamadas entrantes en el mes actual (para revenue);
  • autorenew – si está activado la extensión del plazo de vigencia del número (para common, revenue, rufree);
  • is_on_test – si el número se encuentra en fase de pruebas;
  • type – tipo de número: common (número virtual), inum (número internacional gratuito), rufree (número moscovita gratuito), revenue (número moscovita gratuito 495)
  • JSON
  • XML
{
    "status":"success",
    "sims": [
        {
            "iccid":"8923416550000723980",
            "name":"My Sim",
            "sip":"00001",
            "phone_number":" 447978027321",
            "redirect_to":"simcard",
            "status":"enabled",
            "internet":"on"
        },
    ...
    ]
}

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

donde

  • iccid – ID de la tarjeta SIM;
  • name – "nombre" de la tarjeta SIM;
  • sip – a qué SIP está vinculada la tarjeta;
  • phone_number – número de teléfono de la tarjeta;
  • redirect_to – adonde se redirigen las llamadas entrantes a la tarjeta (opción: simcard, );
  • status – estado actual de la tarjeta SIM;
  • internet – Internet activado o desactivado.

Parámetros:

  • id – SIP id;
  • status – el estado que se muestra en el número SIP seleccionado.
  • 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>

Parámetros:

  • id – SIP id;
  • type – tipo de reenvío: phone – al teléfono;
  • number – número de telefono.
  • 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>

donde

  • pbx_id – id de la PBX del usuario;
  • numbers –listado de números de extensión.
  • 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>

donde

  • pbx_id – PBX-id;
  • number – número de extensión de la PBX;
  • is_online – estado online (true|false).

Parámetros:

  • id – número de extensión de la PBX;
  • estado – estado: "on" - habilitar, "off" - deshabilitar, "on_email" - conectar solo la grabación al correo, "off_email" - deshabilitar solo la grabación al correo, "on_store" - habilitar solo la grabación al repositorio, "off_store" - deshabilitar solo la grabación al repositorio;
  • email – (opcional) cambio de la dirección de correo electrónico a la que se envían las grabaciones de las llamadas. Puedes indicar hasta 3 direcciones de correo electrónico seguidas por comas.
  • 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>

Parámetros:

  • call_id – id único de llamada, este id está indicado en el nombre del archivo con la grabación de la llamada (ú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 pasa de escenario, menú de voz, transferencia etc., se refleja en los datos estadísticos y en las notificaciones);
  • lifetime – (opcional) duración de vida del enlace en segundos (mínimo - 180, máximo - 5184000, por defecto - 1800).

Atención: es suficiente indicar uno de dos parámetros de identificación (pbx_call_id o bien call_id), al indicar pbx_call_id del enlace en una consulta, puede haber varias.

  • JSON
  • XML

Ejemplo de respuesta cuando solo se especifica call_id, solo hay un enlace:

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

Ejemplo de respuesta cuando solo se especifica pbx_call_id, puede haber varias referencias:

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

Ejemplo de respuesta cuando solo se especifica call_id, solo hay un enlace:

<?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 solo se especifica pbx_call_id, puede haber varias referencias:

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

Parámetros:

  • link – enlace al archivo de la conversación;
  • lifetime_till – hasta qué día seguirá funcionando el enlace.

Parámetros:

  • number – número de teléfono para enviar SMS (se pueden enumerar varios separados por comas);
  • message – mensaje (restricciones estándar sobre la longitud de los SMS, en caso de exceder el límite, dividido en varios SMS);
  • caller_id – (opcional) número de teléfono del que se envía el SMS (solo se puede enviar desde la lista de números de usuarios confirmados).
Atención: el envío de SMS es posible dentro de los límites de la FR.
  • 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>

Parámetros:

  • start - fecha de comienzo vista de las estadísticas (formato - Y-m-d H:i:s);
  • end - fecha de final de vista de las estadísticas (formato - Y-m-d H:i:s);
  • sip (opcional) - filtro en función de determinado número SIP;
  • cost_only (opcional) - vista solo del monto gastado para el período;
  • type (opcional - solo en las estadísticas generales) - tipo de consulta: general (no se indica en la solicitud), toll y ru495. (para estadísticas de los números 800 y números libres 495).

Plazo máximo para recibir los datos estadísticos - mes. En el caso de superar el límite en la solicitud - el plazo se reduce automáticamente a 30 días. Si no se especifica la fecha de inicio de la selección, se selecciona el comienzo del mes actual. Si no se especifica la fecha de finalización de la selección, la selección está limitada a la fecha y hora actuales.

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

donde

  • start – fecha de comienzo de visualización de estadísticas;
  • end – fecha de final de visualización de estadísticas;
  • id – id de llamada;
  • sip – número SIP;
  • callstart – hora del inicio de la llamada;
  • description – descripción del destino de la llamada;
  • disposition – estado de la llamada:
    • 'answered' – разговор,
    • 'busy' – ocupado,
    • 'cancel' - cancelado,
    • 'no answer' - sin respuesta,
    • 'failed' - no ha sido posible,
    • 'no money' - no hay saldo, 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 la línea,
    • 'no money, no limit' - se ha superado el límite;
  • billseconds – número de los segundos de la llamada;
  • cost – coste del minuto de llamada a este destino;
  • billcost –coste de los minutos abonados;
  • currency – moneda del pago de la llamada;
  • from – desde qué número se ha llamado;
  • to – adónde se ha llamado.

Parámetros:

  • start - fecha de inicio para revisión de datos estadísticos (formato - Y-m-d H:i:s);
  • end - fecha de fin para revisión de datos estadísticos (formato - Y-m-d H:i:s);
  • version - formato de introducción de datos estadísticos (2 - nuevo, 1 - viejo);
  • 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>

donde

  • start – fecha de comienzo de visualización de estadísticas;
  • end – fecha de final de visualización de estadísticas;
  • version - formato de introducción de estadísticas (2 - nuevo, 1 - antiguo);
  • call_id – id único de llamada, este id está indicado en el nombre del archivo con la grabación de la llamada (único para cada grabación en los datos estadísticos);
  • sip – número SIP;
  • callstart – hora de inicio de la llamada;
  • clid – CallerID;
  • destination – adónde se ha llamada;
  • disposition – estado de la llamada:
    • 'answered' – conversación,
    • 'busy' – ocupado,
    • 'cancel' - cancelado,
    • 'no answer' - sin respuesta,
    • 'failed' - no ha sido posible,
    • 'no money' - no hay saldo, 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 la línea,
    • 'no money, no limit' - se ha superado el límite;
  • seconds – número de segundos de la llamada;
  • is_recorded – (true, false) se ha grabado o no hay conversación;
  • pbx_call_id – ID permanente de la llamada externa a la PBX (no cambia al pasar scripts, menú de voz, transferencia, etc., se muestra en las estadísticas y notificaciones);

Parámetros:

  • start - fecha de comienzo de visualización de estadísticas (formato - Y-m-d H:i:s);
  • end - fecha de final de visualización de estadísticas (formato - Y-m-d H:i:s);
  • widget_id - (opcional) - la ID del widget, en caso de ausencia de un parámetro, se toman estadísticas para todos los widgets;
Plazo máximo para recibir estadísticas mes.En caso de exceder el límite en la solicitud, el plazo se reduce automáticamente a 30 días. Si no se especifica la fecha de inicio de la muestra, se selecciona el comienzo del mes actual. Si no se especifica la fecha de finalización de la muestra, la muestra está limitada a la fecha y hora actuales.
  • 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>

donde

  • start – fecha de inicio de visualización de estadísticas;
  • end – fecha de fin de visualización de estadísticas;
  • 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 llegó a la página con el widget,
    • 'show' – se indica la forma del widget,
    • 'call' – solicitud de devolución de llamada,
    • 'call_request' – solicitud de devolución de llamada diferida,
    • 'rate' – el visitante ha valorado la llamada,
    • 'fail' – el visitante ha señalado que no ha habido devolución de llamada,
    • 'close' – el visitante ha cerrado el icono de widget;
  • date – fecha y hora del evento;
  • referrer_url – dirección de la página desde la que el visitante ha llegado a la página mediante el widget (solo para el evento 'come');
  • url – dirección de la página del widget (solo para el evento 'come');
  • rate – para el evento 'show' - número de puntos, para el evento 'rate' - valoración de la conversación;
  • request_call_date – fecha y hora especificadas por el visitante, según sea conveniente para la devolución de la llamada (solo para el evento) 'call_request');
  • redial – (true, false) devuelto o no en respuesta a una solicitud de devolución diferida (solo para un evento) 'call_request');
  • number – número introducido por el visitante (para el evento 'call', 'call_request', 'rate', 'fail').

Parámetros:

    support_api_page_methods_21_params_text
support_api_page_methods_21_1_text

support_api_page_methods_21_1_title


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

support_api_page_methods_21_2_title


{
    "status":"success"
}

support_api_page_methods_21_3_title


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

Información sobre las llamadas entrantes

El sistema Zadarma puede enviar información de cada llamada entrante a la oficina virtual PBX y enviar las llamadas al número de extensión necesario en función de la respuesta. Para ello es necesario crear un enlace abierto para acceso general y que acepte las consultas POST con información desde el sistema de Zadarma.

Tipos de notificación existentes:

Métodos disponibles:

  • NOTIFY_START
    comienzo de la llamada entrante a la PBX.
  • NOTIFY_INTERNAL
    comienzo de la llamada entrante al número de extensión de la PBX.
  • NOTIFY_ANSWER
    respuesta en caso de llamada al número interno o externo.
  • NOTIFY_END
    final de la llamada entrante al número interno de extensión de la PBX.
  • NOTIFY_OUT_START
    comienzo de la llamada salientes desde la PBX.
  • NOTIFY_OUT_END
    final de la llamada salientes desde la PBX.
  • NOTIFY_RECORD
    la grabación de la llamada está lista para descargarse.

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

  • event – evento (NOTIFY_START)
  • call_start – duración del comienzo de la llamada;
  • pbx_call_id – id de la llamada;
  • caller_id – número del llamante;
  • called_did – número al que se realiza la llamada.

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

  • event – evento (NOTIFY_INTERNAL)
  • call_start – duración del comienzo de la llamada;
  • pbx_call_id – id de la llamada;
  • caller_id – número del llamante;
  • called_did –número al que se realiza la llamada;
  • internal – (opcional) número de extensión.

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

  • event – evento (NOTIFY_ANSWER)
  • caller_id – número del llamante;
  • destination – número al que se realiza la llamada;
  • call_start – hora del comienzo de la llamada;
  • pbx_call_id – id звонка;
  • internal – (opcional) número de extensión.

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

  • event – evento (NOTIFY_END)
  • call_start – hora del comienzo de la llamada;
  • pbx_call_id – id de la llamada;
  • caller_id – número del llamante;
  • called_did – número al que se realiza la llamada;
  • internal – (opcional) número de extensión;
  • duration – duración en segundos;
  • disposition – estado de la llamada:
    • 'answered' – conversación,
    • 'busy' – ocupado,
    • 'cancel' - cancelado,
    • 'no answer' - sin respuesta,
    • 'failed' - no ha sido posible,
    • 'no money' - no hay saldo 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 la línea,
    • '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 (recomendamos cargar el archivo de la grabación no antes de 40 segundos porque para guardar el archivo se requiere tiempo).

Parámetros que se envían al enlace para la 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 realiza la llamada;
  • internal – (opcional) número de extensión.

Parámetros que se envían al enlace para la 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 al que se realiza la llamada;
  • internal – (opcional) número de extensión;
  • duration – duración en segundos;
  • disposition – estado de la llamada:
    • 'answered' – conversación,
    • 'busy' – ocupadо,
    • 'cancel' - cancelado,
    • 'no answer' - sin respuesta,
    • 'failed' - no ha sido posible,
    • 'no money' - no hay saldo, 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 la línea,
    • '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 (recomendamos cargar el archivo de la grabación no antes de 40 segundos después de la notificación porque para guardar el archivo se requiere tiempo).

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

  • event – evento(NOTIFY_RECORD)
  • call_id_with_rec – id único de la llamada con grabación de la conversación;
  • pbx_call_id – ID permanente de la llamada externa a la PBX (no cambia al pasar de scripts, menú de voz, transferencia, etc., que se muestran en estadísticas y notificaciones).

Para especificar un enlace sobre el cual notificar, y también para habilitar o deshabilitar todos los tipos de notificaciones, puedes hacerlo en la sección de la API del área personal.

Para que el sistema acepte el enlace, debes agregar un código de verificación al comienzo de la secuencia de comandos.

Ejemplo en PHP:

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

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

Además, si has lanzado la contraseña de acceso al API, en cada solicitud de tu enlace recibirás un encabezado adicional "Signature", mediante el también puedes verificar la integridad, así como la autenticidad de los datos.

Crear una firma de verificación para la notificación de llamadas entrantes, un ejemplo en PHP:

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

Para NOTIFY_OUT_START y NOTIFY_OUT_END:

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

Para NOTIFY_RECORD:

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

Para NOTIFY_ANSWER:

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

Para la consulta NOTIFY_START es posible "sobre la marcha" cambiar el escenario de trabajo en la llamada actual, enviando en respuesta a la información:

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

donde,

  • redirect – id del script de reenvío (en el formato 0-1 donde 0 es el número del script del número de voz del menú 1) o el número interno del intercambio, "blacklist" - en este caso, la llamada será rechazada con la señal de ocupado;
  • caller_name – se puede dar un nombre al número entrante.

Tiempo máximo de respuesta con información sobre la redirección y el nombre del número es de hasta 2 segundos.

Puedes mirar un ejemplo de script en en nuestro repositorio en GitHub.