Navegación API

Introducción


La interfaz API es gratuita y está disponible en todas las cuentas de Zadarma

En API están disponibles todas las funciones básicas para el funcionamiento

  • visualización y cambio de ajustes de SIP y centralita virtual;
  • 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 centralita virtual, 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, C#, Python para trabajar con API en nuestro GitHub.
Instrucciones de integración del sistema de CRM propio y telefonía de Zadarma

Ejemplos de API:
Integración del sistema de CRM propio y Zadarma
Webhook para el funcionamiento con IVR: un robot de voz hecho por ti
Creación de lead en CRM desde el formulario en la web

Autorización

Cada solicitud que requiere autorización se acompaña de un encabezado adicional, como:

"Authorization: contraseña_del usuario: firma"

Las contraseñas de autorización debes obtenerlas en el área personal.

La firma se realiza de acuerdo con el siguiente algoritmo:

  • un conjunto de parámetros transmitidos (GET, POST, PUT, DELETE) ordenados alfabéticamente por el nombre de la tecla;
  • del conjunto obtenido se genera una cadena de consulta (por ejemplo, la función http_build_query в PHP), ejemplo "from=DATEFROM&to=DATETO…";
  • etc - se une mediante la fórmula: línea = nombre_método línea_solicitud md5( línea_solicitud ), dobde "nombre_método" - línea de la solicitud, comenzando por el dominio (indicando la versión API), antes de la enumeración de parámetros, por ejemplo - '/v1/sip/'
  • la cadena resultante se transforma mediante la función de hash de acuerdo con el algoritmo sha1 con una contraseña del usuario: hash = hash( linea contraseña_secreta)
  • y a continuación hash se codifica en base64 firma = base64_encode( hash )

                                    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

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

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.

Métodos

get /v1/info/balance/

saldo del usuario

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

get /v1/info/price/

el coste de una llamada en base a la tarifa actual del usuario

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

Parámetros

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


get /v1/info/timezone/

huso horario del usuario

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

get /v1/tariff/

información sobre la tarifa actual del usuario

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

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.

get /v1/request/callback/

devolucion de llamada

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

Parámetros

  • from – tu número de teléfono o SIP, o extensión de la centralita virtual, 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 extensión de la centralita virtual (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);

post /v1/sms/send/

envío de SMS

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

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.

get /v1/request/checknumber/

confirmación del número

                                    {
    "status":"success",
    "from":442037691880,
    "to":442037691881,
    "lang":"fr",
    "time":1612779278
}

Parámetros

  • caller_id - número mostrado en llamadas, disponibles solo los números conecyados en Zadarma,
  • to - número de teléfono o SIP al que llaman,
  • code - código que se va a reproducir. Solo cifras y extensión inferior a 20 dígitos,
  • lang - idioma de texto. En su ausencia se selecciona el del área personal del cliente, se verifica la presencia en los idiomas del sistema.

post /v1/info/number_lookup/

actualización de base de clientes

Parámetros

  • numbers – listado de números para actualizar en formato internacional.

Si numbers contiene 1 número el resultado será devuelto inmediatamente, si se indica un listado de números el resultado será enviado a la dirección indicada en la página de actualización de contactos o al correo electrónico, en caso de no estar indicada la dirección.

¡Atención! los ajustes de este método se configuran en la página de actualización de base de clientes del área personal.

Ejemplo de respuesta para 1 número:

(Respuesta 1)

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

Ejemplo de respuesta para varios números:

(Respuesta 2)

                                    Respuesta 2:
{ "status":"success" }

Ejemplo del resultado enviado a la dirección indicada en la página de actualización:

(Respuesta 3)

                                    Respuesta 3:
{ "success":true, "description":"Success", "result": [ { "mcc":"250", "mnc":"01", "ported":false, "roaming":false, "errorDescription":"No Error", "mccName":"Russia", "mncName":"Mobile TeleSystems", "number":"791234567890", }, ... ] }

get /v1/info/lists/currencies/

Listado de divisas

                                    {
    "status": "success",
    "currencies": [
        "USD",
        "EUR",
        "RUB",
        "GBP",
        "PLN"
    ]
}

get /v1/info/lists/languages/

Listado de idiomas disponibles del área personal

                                    {
    "status": "success",
    "languages": [
        "en",
        "es",
        "de",
        "pl",
        "ru",
        "ua",
        "fr"
    ]
}

get /v1/info/lists/tariffs/

Listado de tarifas

                                    {
    "status": "success",
    "currency": "EUR",
    "tariffs": [
        {
            "tariff_id": 5,
            "name": "Standard",
            "cost": 0,
            "days": "30"
        },
        ...
    ],
    "package_tariffs": [
        {
            "id": 1,
            "name": "EU",
            "tariffs": [
                {
                    "tariff_id": 23,
                    "name": "Office",
                    "cost": 22,
                    "cost_annual": 216
                },
                ...
            ]
        },
        ...
    ]
}

Parámetros:

  • currency – divisa

SIP

get /v1/sip/

relación de números SIP del usuario

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

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

get /v1/sip/<SIP>/status/

estado online de número SIP del usuario

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

put /v1/sip/callerid/

cambio del CallerID

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

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

get /v1/sip/redirection/

visualización de reenvíos actuales por números SIP del usuario

                                    {
    "status":"success",
    "info": [
        {
            "sip_id":"00001",
            "status":"on",
            "condition":"always",
            "destination":"phone",
            "destination_value":"442037691880"
        },
    ...
    ]
}

Parámetros

  • id – selección (opcional) de id específico de SIP.

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 – destino para el desvío: phone – a numero de teléfono, pbx – a la centralita virtual;
  • destination_value – numero de desvío: numero de teléfono o ID de la centralita virtual.

put /v1/sip/redirection/

activación/desactivación del reenvío en base al número SIP

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

Parámetros

  • id – SIP id;
  • status – el estado que se muestra en el número SIP seleccionado.

put /v1/sip/redirection/

modificación de los parámetros de reenvío

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

Parámetros

  • id – SIP id;
  • type – tipo de reenvío: phone – al teléfono;
  • number – número de telefono.

post /v1/sip/create/

Agregar SIP

                                    {
    "status": "success",
    "sip": "123456"
}

Parámetros

  • name - nombre mostrado;
  • password - contraseña;
  • callerid - número para CallerID;
  • redirect_to_phone - parámetro opcional, desvío del SIP al teléfono;
  • user_id - parámetro opcional, disponible para ser usado por socios o usuarios creados por éstos.

Estadística

get /v1/statistics/

obtención de estadísticas generales

(Respuesta 1)

                                    Respuesta 1:
{ "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" }, … ] }

Parámetros

  • start - fecha de comienzo vista de las estadísticas (formato - YYYY-MM-DD HH:MM:SS);
  • end - fecha de final de vista de las estadísticas (formato - YYYY-MM-DD HH:MM:SS);
  • 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);
  • skip (opcional - no se tiene en cuenta para este parámetro cost_only) -el número de líneas que hay que omitir en la selección, la salida comenzará desde el salto de línea + 1 (usado para la paginación junto con el parámetro de límite, el valor predeterminado es 0); -limit(opcional - no se contabiliza para cost_only) es el límite en el número de líneas de salida (utilizado para la paginación con el parámetro de omisión, el valor máximo 1000, por defecto es 1000).

Plazo máximo para la recepción de datos estadísticos - mes. En caso de aumentar el límite de solicitud, el plazo se reduce automáticamente a 30 días. Si no se indica la fecha de inicio de la selección, se selecciona el inicio del mes en curso. Si no se indica la fecha de final de la selección, la selección se limita a la fecha y hora en curso.

Número máximo de líneas introducidas para una solicitud - 1000. Para la paginación, utiliza los parámetros skip y limit.

?type=cost_only:

(Respuesta 2)

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

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.

get /v1/statistics/pbx/

datos estadísticos sobre la centralita virtual

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

Parámetros

  • start - fecha de inicio para revisión de datos estadísticos (formato - YYYY-MM-DD HH:MM:SS);
  • end - fecha de fin para revisión de datos estadísticos (formato - YYYY-MM-DD HH:MM:SS);
  • version - formato de introducción de datos estadísticos (2 - nuevo, 1 - antiguo);
  • skip (opcional) - número de líneas omitidas en la selección, la selección empezará desde la línea skip +1 (se utiliza para la paginación conjunta con el parámetro limit que, por defecto es igual a 0);
  • limit (opcional) - límite para las líneas generadas (se utiliza para la paginación conjunta con el parámetro skip, valor máximo 1000, valor por defecto 1000);
  • call_type (opcional) - destino de llamadas ('in' para entrantes, 'out' para salientes). Si no se indica, se generarán todas las llamadas.

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 centralita virtual (no cambia al pasar scripts, menú de voz, transferencia, etc., se muestra en las estadísticas y notificaciones);

get /v1/statistics/callback_widget/

datos estadísticos del widget de devolución de llamada

                                    {
    "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"
                }
            ]
        },
        ...
    ]
}

Parámetros

  • start - fecha de comienzo de visualización de estadísticas (formato - YYYY-MM-DD HH:MM:SS);
  • end - fecha de final de visualización de estadísticas (formato - YYYY-MM-DD HH:MM:SS);
  • 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.

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').

PBX

post /v1/pbx/redirection/

modificación de parámetros de reenvío en la extension de la centralita virtual

                                    {
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer"
}

Parámetros

Para activar y configurar el reenvío:

  • pbx_number – extensión de la centralita virtual, por ejemplo 100;
  • status – on;
  • type – tipo de reenvío voicemail o phone;
  • destination – teléfono o correo electrónico, dependiendo de parámetro anterior;
  • condition – la condición de reenvío, valores posibles: siempre o bien noanswer;
  • voicemail_greeting – notificación sobre reenvío, posibles valores: no, standart, own. Se indica solo para el type = voicemail;
  • greeting_file – archivo con notificación en el formato mp3 o bien wav hasta 5 MB. Se indica solo para el type = voicemail y voicemail_greeting = own;

Para la activación del reenvío:

  • pbx_number – extensión de la centralita virtual, por ejemplo 100;
  • status – off;

get /v1/pbx/redirection/

obtención de parámetros de reenvío en la extension de la centralita virtual

                                    {
    "status":"success",
    "current_status":"on",
    "pbx_id":"1234",
    "pbx_name":"100",
    "type":"phone",
    "destination":"79123456789",
    "condition":"noanswer",
}

Parámetros

  • pbx_number – extensión de la centralita virtual, por ejemplo 100;

get /v1/pbx/record/request/

solicitud de un archivo de grabación de la llamada

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 centralita virtual (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.

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

(Respuesta 1)

                                    Respuesta 1:
{ "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:

(Respuesta 2)

                                    Respuesta 2:
{ "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" }

Parámetros

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

post /v1/pbx/waitmelody/upload

cargar melodía

Parámetros:

  • file - el archivo

put /v1/pbx/waitmelody/switch

act/desact melodía para la centralita

Parámetros:

  • state - estado (on - act, off - desact);
  • melody - tipo de melodía (none - por defecto, sin melodía, mymelody - la melodía cargada por el usuario antes.

delete /v1/pbx/waitmelody/delete

eliminar melodía

get /v1/pbx/callinfo/

obtener ajustes de pbx call info

                                    {
    "status": "success",
    "url": "",
    "notifications": {
        "notify_start": "true",
        "notify_internal": "false",
        "notify_end": "true",
        "notify_out_start": "false",
        "notify_out_end": "false",
        "notify_answer": "false"
    }
}

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste.

post /v1/pbx/callinfo/url/

cambiar url para pbx call info

                                    {
    "status": "success",
    "url": ""
}

Parámetros:

  • url - enlace;
  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste.

post /v1/pbx/callinfo/notifications/

modificar la reacción para el evento NOTIFY_* para pbx call info

                                    {
    "status": "success",
    "notifications": {
        "notify_start": "true",
        "notify_internal": "false",
        "notify_end": "true",
        "notify_out_start": "false",
        "notify_out_end": "false",
        "notify_answer": "false"
    }
}

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste;
  • notify_start - "true" o "false" parámetro opcional;
  • notify_internal - "true" o "false" parámetro opcional
  • notify_end - "true" o "false" parámetro opcional;
  • notify_out_start - "true" o "false" parámetro opcional;
  • notify_out_end - "true" o "false" parámetro opcional;
  • notify_answer - "true" o "false" parámetro opcional.

delete /v1/pbx/callinfo/url/

eliminar url para pbx call info

                                    {
    "status": "success",
    "url": ""
}

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste.

post /v1/pbx/create/

crear centralita virtual

                                    {
    "status": "success",
    "stop_datetime": "2021-12-31 23:59:59"
}

Parámetros:

  • sip_id - SIP para vincular a la centralita, si no se asigna se selecciona el SIP libre (parámetro opcional);
  • password - contraseña para la primera extensión de la centralita '100';
  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste.

get /v1/pbx/webhooks/

obtener ajustes de pbx webhooks

                                    {
    "status": "success",
    "url": "",
    "hooks": {
        "number_lookup": "true",
        "call_tracking": "false",
        "sms": "true",
        "speech_recognition": "true"
    }
}

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste.

post /v1/pbx/webhooks/url/

cambiar url para pbx webhooks

                                    {
    "status": "success",
    "url": ""
}

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste;
  • url - enlace.

post /v1/pbx/webhooks/hooks/

modificar reacción para el evento para pbx webhooks

                                    {
    "status": "success",
    "hooks": {
        "number_lookup": "true",
        "call_tracking": "false",
        "sms": "true",
        "speech_recognition": "true"
    }
}

Parámetros:

  • user_id - parámetro opcional, disponible para el uso de socios o usuarios creados por éste;
  • number_lookup - "true" o "false" parámetro opcional;
  • call_tracking - "true" o "false" parámetro opcional;
  • sms - "true" o "false" parámetro opcional;
  • speech_recognition - "true" o "false" parámetro opcional.

delete /v1/pbx/webhooks/url/

elimianr url para pbx webhooks

                                    {
    "status": "success",
    "url": ""
}

Параметры:

  • user_id - parámetro opcional, disponible para el uso de socios o usuarios creados por éste.

Centralita virtual (extensiones)

get /v1/pbx/internal/

visualización de las extensiones de la centralita virtual

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

donde

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

get /v1/pbx/internal/<PBXSIP>/status/

estado online de las extensiones de la centralita virtual

                                    {
    "status":"success",
    "pbx_id":1234,
    "number":100,
    "is_online":"false"
}

donde

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

put /v1/pbx/internal/recording/

activación de la grabación de llamadas en la extension de la centralita virtual

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

Parámetros

  • id – extensión de la centralita virtual;
  • 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.

post /v1/pbx/internal/create/

crear extensión de centralita

                                    {
    "status": "success",
    "numbers": [
        {
            "number": 200,
            "password": "PASSWORD"
        },
        {
            "number": 201,
            "password": "PASSWORD"
        }
    ]
}

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste;
  • start_number - número de inicio 100 ...999 o "any" comenzar desde cualquier número disponible dentro de 100-999;
  • quantity - cantidad de extensiones creadas;
  • return_password - parámetro opcional, si 'true' en respuesta aparecerán contraseñas para extensiones ya creadas.

get /v1/pbx/internal/<SIP>/password/

solicitud de contraseña para la extensión de la centralita, contraseña mostrada disponible por un periodo de tiempo determinado

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste.

Ejemplo de respuesta:

                                    {
    "status": "success",
    "pbx_id": 114,
    "number": 200,
    "password": "PASSWORD"
}

donde

  • password - puede tener el valor de hidden si la contraseña no está disponible para mostrar

put /v1/pbx/internal/<SIP>/password/

cambiar contraseña de la extensión

                                    {
    "status": "success",
    "pbx_id": 114,
    "number": 200
}

Parámetros:

  • value - nueva contraseña;
  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste.

Centralita virtual (IVR)

get /v1/pbx/ivr/sounds/list

listado de archivos guardados en la centralita

post /v1/pbx/ivr/sounds/upload

cargar archivo

Parámetros:

  • name - nombre del archivo,
  • file - el archivo.

delete /v1/pbx/ivr/sounds/delete

eliminar archivo por id

Parámetros:

  • id - identificador del archivo

get /v1/pbx/ivr/

listado de IVR

                                    {
    "status": "success",
    "pbx_id": 114,
    "ivrs": [
        {
            "menu_id": "0",
            "title": "",
            "type": "file",
            "status": "on",
            "waitexten": 5,
            "auto_responder": {
                "status": "on",
                "waitexten": 1,
                "working_days": [
                    {
                        "day": "mon",
                        "is_active": true,
                        "begin": {
                            "hour": 9,
                            "minute": 0
                        },
                        "end": {
                            "hour": 18,
                            "minute": 0
                        }
                    },
                    {
                        "day": "tue",
                        "is_active": true,
                        "begin": {
                            "hour": 9,
                            "minute": 0
                        },
                        "end": {
                            "hour": 18,
                            "minute": 0
                        }
                    },
                    ...
                    {
                        "day": "sun",
                        "is_active": false
                    }
                ]
            },
            "dinner_status": "on",
            "dinner_time": {
                "begin": {
                    "hour": 12,
                    "minute": 0
                },
                "end": {
                    "hour": 13,
                    "minute": 0
                }
            }
        },
        {
            "menu_id": "1",
            "title": "Menu 1",
            "type": "readtext",
            "status": "off",
            "waitexten": 5,
            "auto_responder": {
                "status": "off",
                "waitexten": 1
            }
        },
        ...
    ]
}

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste.

post /v1/pbx/ivr/create/

crear IVR

                                    {
    "status": "success",
    "menu_id": 2
}

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste;
  • buy - 'true' - crear menú de pago.

delete /v1/pbx/ivr/delete/

eliminar IVR

                                    {
    "status": "success"
}

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste;
  • menu_id - ha de ser > 0.

get /v1/pbx/ivr/scenario/

listado de escenarios del IVR

                                    {
    "status": "success",
    "scenarios": [
        {
            "id": "132",
            "title": "-1",
            "push_button": -1,
            "first_sips": [
                "102"
            ],
            "second_sips": [],
            "second_sips_delay": 10,
            "third_sips": [],
            "third_sips_delay": 20
        },
        ...
    ]
}

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste;
  • menu_id - ID menú/IVR.

post /v1/pbx/ivr/scenario/create/

crear escenario IVR

                                    {
    "status": "success",
    "menu_id": 0,
    "scenario_id": 2
}

Parámetros:

  • push_button - aplicar el escenario al pulsar el botón: si el llamante no pulsa ningún botón responde el escenario sin pulsar, 0-9 - botones, 10 - contestador automático, 11-30 - escenarios adicionales;
  • title - nombre;
  • extension - extensión o extensiones separados por espacios o "fax";
  • menu_id - ID menú/IVR;
  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste.

delete /v1/pbx/ivr/scenario/delete/

eliminar escenario de IVR

                                    {
    "status": "success"
}

Parámetros:

  • scenario_id - ID de escenario;
  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste.

Reconocimiento de voz

get /v1/speech_recognition/

obtener resultado de reconocimiento

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

Parámetros:

  • call_id – id único de la llamada, este ID se indica en el nombre del archivo con grabación de llamada (único para cada grabación en la estadística);;
  • lang - idioma de reconocimiento (opcional);
  • return - resultado a devolver. Opciones: words - palabras, phrases - frases. (opcional. por defecto phrases);
  • alternatives - si devolver opciones alternativas. Opciones: 0 - no, 1 - sí. (не obligatorio. por defecto 0).

donde

  • lang – idioma;
  • recognitionStatus: estado de reconocimiento. Opciones:
    • in progress - en proceso de reconocimiento,
    • error - se ha producido un error en el reconocimiento,
    • recognized - reconocido
    • ready for recognize - grabación lista para el reconocimiento,
    • not available for recognize - grabación no disponible para el reconocimiento.
  • result:
    • words - conjunto:
      • result - listado de palabras (conjunto):
        • s - hora inicio de palabra
        • e - hora fin de palabra
        • w - palabra
      • channel - número de canal
    • phrases - conjunto:
      • result - frase
      • channel - número de canal

put /v1/speech_recognition/

ejecutar reconocimiento

                                    {
    "status":"success"
}

Parámetros:

  • call_id – id único de llamada, este id se indica en el nombre del archivo con grabación de llamada (único para cada grabación en la estadística);
  • lang - idioma de reconocimiento (opcional).

Números virtuales

get /v1/direct_numbers/

información sobre números directos del usuario

                                    {
    "status":"success",
    "info": [
        {
            "number":"442030000000",
            "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"
        },
    ...
    ]
}

Parámetros

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), rufree (número moscovita gratuito), revenue (número moscovita gratuito 495)

get /v1/direct_numbers/number/

información sobre el número conectado

                                    {
    "status": "success",
    "info": {
    "number": "35924913550",
        "status": "on",
        "country": "Bulgaria",
        "description": "Sofia",
        "number_name": "TT",
        "sip": "00004",
        "sip_name": "SIP",
        "start_date": "2016-06-08 14:32:17",
        "stop_date": "2016-06-29 10:52:18",
        "monthly_fee": 2,
        "currency": "USD",
        "channels": "2",
        "autorenew": "true",
        "receive_sms": null,
        "is_on_test": "false"
    }
}

Parámetros

  • type - puede contener uno de 3 valores:
    • 'revenue' - Número gratuito 495 de Moscú;
    • 'common' - Número general, el resto de números;
  • number - número;

get /v1/direct_numbers/autoprolongation/

estado de autorenovación

                                    {
    "status": "success",
    "number": "35924913550",
    "autoprolongation": "on"
}

Parámetos

  • type - puede contener uno de 2 valores:
    • 'revenue' - Número gratuito 495 de Moscú;
    • 'common' - Número general, el resto de números;
  • number - número.

put /v1/direct_numbers/autoprolongation/

modificar el estado de autorenovación

                                    {
    "status": "success",
    "number": "35924913550",
    "autoprolongation": "off"
}

Paámetros

  • type - puede contener uno de 2 valores:
    • 'revenue' - Número gratuito 495 de Moscú;
    • 'common' - Número general, el resto de números;
  • number - número;
  • value - nuevo estado de autorenovación, on o off.

get /v1/direct_numbers/countries/

listado de países en los que se puede conectar el número

                                    {
    "status": "success",
    "info": [
        {
            "countryCode": "61",
            "countryCodeIso": "AU",
            "name": "Australia"
        },
        ...
    ]
}

Parámetros

  • language - opcional, si no está establecido devolverá en el idioma del área personal.

get /v1/direct_numbers/country/

listado de destinos en el país en el que se puede conectar el número

                                    {
    "status": "success",
    "info": [
        {
            "id": "3753",
            "countryCode": "49",
            "areaCode": "800",
            "name": "Номер 800 (Toll-free)",
            "connect_fee": 0,
            "monthly_fee": 15,
            "currency": "USD",
            "restrictions": {
                "upload": [
                    "Certificate of registration copy or passport or ID copy (both sides)",
                    "Proof of address (a copy of utility bill no older than of 6 months) - 
                    your current address (city, street, number and postal code). 
                    The address must be located in the country of ordered phone number"
                ]
            },
            "receive_sms": "false",
            "is_toll": "true",
            "feature": "Available from all networks"
            "connect_time": "0"
        },
        {
            "id": "3766",
            "countryCode": "49",
            "areaCode": "821",
            "name": "Аугсбург",
            "connect_fee": 3,
            "monthly_fee": 3,
            "currency": "USD",
            "restrictions": {
                "upload": [
                    "Passport or ID copy (both sides)"
                ],
                "specify": [
                    "You current address (city, street, number and postal code). 
                    The address must be located in the region of the city 
                    where you ordered the phone number"
                ]
            },
            "receive_sms": "false",
            "is_toll": "false",
            "feature": null,
            "connect_time": "0"
        },
        ...
    ]
}

Parámetros

  • language - opcional, si no está estableciso devolverá en el idioma del área personal;
  • country - código iso del país (ISO 3166-1 alpha-2).

put /v1/direct_numbers/set_caller_name/

configuración del Nombre del Número (caracteres latinos y hasta 30 dígitos)

                                    {
    "status": "success",
    "number": "74990000000",
    "caller_name": "test"
}

Parámetros

  • type - puede contener uno de 2 valores:
    • 'revenue' - Número gratuito de Moscú 495;
    • 'common' - Número general, el resto de números;
  • number - número;
  • caller_name - para eliminar simplemente pasar el campo vacío.

put /v1/direct_numbers/set_sip_id/

vinculación del número al sip o activación del modo de pruebas

                                    {
    "status": "success",
    "number": "74990000000",
    "sip_id": "00001"
}

Parámetros

  • type - puede contener uno de 3 valores:
    • 'revenue' - Número gratuito de Moscú 495;
    • 'common' - Número general, el resto de números;
  • number - número;
  • sip_id - sip o dirección del servidor externo (SIP URI);
  • test_mode - opcional, (on|off) - para activar el modo de pruebas.

get /v1/direct_numbers/available/<DIRECTION_ID>/

números disponibles para conectar

                                    {
    'status': 'success',
    'numbers': [
        {
            'id': 1712p0D1643D0t42r198658,
            'direction_id': 13755,
            'number': '74990000001'
        },
        {
            'id': 184bdf85006c3f1676be200,
            'direction_id': 13755,
            'number': '74990000000'
        },
        ...
    ]
}

Parámetros:

  • DIRECTION_ID - ru495 o ID del destino;
  • mask - parámetro opcional, para la búsqueda de coincidencia por números.

post /v1/direct_numbers/order/

pedido/compra del número

                                    {
    'status': 'success',
    'number': '74990000000',
    'is_reserved': 'false',
    'is_activated': 'true'
}

Parámetros:

  • number_id - ID del número solicitado;
  • direction_id - ID destino/ciudad;
  • documents_group_id - ID del grupo de documentos del usuario;
  • purpose - descripción de texto del propósito del uso del número (solo si se requiere);
  • receive_sms - 1 - activación de recepción de SMS (solo si el número soporta la recepción de SMS);
  • period - 'month' - un mes, '3month' - tres meses (parámetro opcional, la recepción de SMS se activa en números conectados por un periodo mínimo de 3 meses);
  • user_id - parámetro opcional, disponible para el uso de socios o usuarios creados por éste.

post /v1/direct_numbers/prolong/

extensión del número por un determinado periodo de meses

                                    {
    'status': 'success',
    'number': '74990000000',
    'stop_date': '2021-05-01 12:00:00',
    'total_paid': {
        'amount': 2,
        'currency': 'USD'
    }
}

Parámetros:

  • number - número a extender;
  • months - cantidad de meses;
  • user_id - parámetro opcional, disponible para el uso de socios o usuarios creados por éste.

Grupos de documentos

get /v1/documents/files

listado de archivos/documentos en el grupo de documentos

                                    {
    "status": "success",
    "documents": [
        {
            "type": "passport",
            "is_verified": "true",
            "source": "upload",
            "name": "file1.jpg"
        },
        {
            "type": "receipt",
            "is_verified": "false",
            "source": "upload",
            "name": "file2.jpg"
        }
    ]
}

Parámetros:

  • user_id - parámetro opcional, disponible para el uso de socios o usuarios creados por éste;
  • group_id - parámetro opcional, ID del grupo de documentos, (0 o si no está determinado - grupo de documentos principal).

get /v1/documents/groups/list/

listado de grupo de documentos

                                    {
    "status": "success",
    "groups": [
        {
            "id": 0,
            "email": "email@server.com",
            "salutation": 'MR',
            "nationality": null,
            "first_name": "John",
            "middle_name": "Richard",
            "last_name": "Smith",
            "organization": "Company",
            "organization_description": null,
            "organization_reg_number": null,
            "country": "DE",
            "region": "",
            "city": "Berlin",
            "address": "Brudden Strasse 8, 76611",
            "zip_code": '76611',
            "street": 'Brudden Strasse',
            "street_code": null,
            "municipality_code": null,
            "building_number": "8",
            "building_letter": null,
            "phone": "4900000000",
            "type_of_id": "",
            "id_number": "123000099",
            "issuing_authority": null,
            "issuing_date": null,
            "is_readonly": true
        }
    ]
}

Parámetros:

  • user_id - parámetro opcional, disponible para el uso de socios o usuarios creados por éste.

get /v1/documents/groups/get/<ID>/

datos de un grupo determinado

                                    {
    "status": "success",
    "group": {
        "id": 0,
        "email": "email@server.com",
        "salutation": 'MR',
        "nationality": null,
        "first_name": "John",
        "middle_name": "Richard",
        "last_name": "Smith",
        "organization": "Company",
        "organization_description": null,
        "organization_reg_number": null,
        "country": "DE",
        "region": "",
        "city": "Berlin",
        "address": "Brudden Strasse 8, 76611",
        "zip_code": '76611',
        "street": 'Brudden Strasse',
        "street_code": null,
        "municipality_code": null,
        "building_number": "8",
        "building_letter": null,
        "phone": "4900000000",
        "type_of_id": "",
        "id_number": "123000099",
        "issuing_authority": null,
        "issuing_date": null,
        "is_readonly": true
    }            
}

Parámetros:

  • ID - ID de grupo, 0 - grupo de documentos principal;
  • user_id - parámetro opcional, disponible para el uso de socios o usuarios creados por éste.

get /v1/documents/groups/valid/<ID>/

verificación: si el grupo de documentos sirve para una determinada ciudad/destino

                                    {
    "status": "success",
    "is_information_match": "true",
    "is_documents_uploaded": "true",
    "is_documents_verified": "true",
    "is_address_match": "true"
}

Parámetros:

  • ID - ID de grupo, 0 - grupo de documentos principal;
  • user_id - parámetro opcional, disponible para el uso de socios o usuarios creados por éste;
  • direction_id - ID de destino/ciudad.

post /v1/documents/groups/create/

crear un nuevo grupo de documentos

                                    {
    "status": "success",
    "group": {
        "id": 0,
        "email": "email@server.com",
        "salutation": 'MR',
        "nationality": null,
        "first_name": "John",
        "middle_name": "Richard",
        "last_name": "Smith",
        "organization": "Company",
        "organization_description": null,
        "organization_reg_number": null,
        "country": "DE",
        "region": "",
        "city": "Berlin",
        "address": "Brudden Strasse 8, 76611",
        "zip_code": '76611',
        "street": 'Brudden Strasse',
        "street_code": null,
        "municipality_code": null,
        "building_number": "8",
        "building_letter": null,
        "phone": "4900000000",
        "type_of_id": "",
        "id_number": "123000099",
        "issuing_authority": null,
        "issuing_date": null,
        "is_readonly": true
    }            
}

Parámetros:

  • user_id - parámetro opcional, disponible para el uso de socio o usuarios creados por éste.
  • email - email;
  • salutation - saludo 'MR', 'MS', 'COMPANY';
  • nationality - nacionalidad, código iso2 del país;
  • first_name - nombre;
  • middle_name - parámetro opcional, segundo apellido;
  • last_name - primer apellido;
  • date_of_birth - parámetro opcional, fecha de nacimiento;
  • organization - parámetro opcional, nombre de empresa/organización;
  • organization_description - parámetro opcional, descripción de actividad de empresa;
  • organization_reg_number - parámetro opcional, número de registro de empresa;
  • country - país, código iso2 del país;
  • region - parámetro opcional, provincia/región;
  • city - ciudad;
  • address - dirección completa;
  • zip_code - código postal;
  • street - calle;
  • street_code - parámetro opcional, código de calle, solo para Dinamarca;
  • municipality_code - parámetro opcional, código de municipio, solo para Dinamarca;
  • building_number - número;
  • building_letter - parámetro opcional, letra;
  • phone - número de teléfono de contacto;
  • type_of_id - parámetro opcional, tipo de documento: "PASSPORT", "DNI", "NIE", "RESIDENCE_PERMIT", "NATIONAL_ID_CARD", "BUSINESS_REGISTRATION";
  • id_number - parámetro opcional, número del documento;
  • issuing_authority - parámetro opcional, autoridad de expedición;
  • issuing_date - parámetro opcional, fecha de expedición;
  • direction_id - parámetro opcional, ID de destino/ciudad para verificar el cumplimiento.

put /v1/documents/groups/update/<GROUPID>/

actualización de datos de grupos de documentos

                                    {
    "status": "success",
    "group": {
        "id": 0,
        "email": "email@server.com",
        "salutation": 'MR',
        "nationality": null,
        "first_name": "John",
        "middle_name": "Richard",
        "last_name": "Smith",
        "organization": "Company",
        "organization_description": null,
        "organization_reg_number": null,
        "country": "DE",
        "region": "",
        "city": "Berlin",
        "address": "Brudden Strasse 8, 76611",
        "zip_code": '76611',
        "street": 'Brudden Strasse',
        "street_code": null,
        "municipality_code": null,
        "building_number": "8",
        "building_letter": null,
        "phone": "4900000000",
        "type_of_id": "",
        "id_number": "123000099",
        "issuing_authority": null,
        "issuing_date": null,
        "is_readonly": true
    }            
}

Parámetros:

  • user_id - parámetro opcional, disponible para el uso de socio o usuarios creados por éste.
  • email - email;
  • salutation - saludo 'MR', 'MS', 'COMPANY';
  • nationality - nacionalidad, código iso2 del país;
  • first_name - nombre;
  • middle_name - parámetro opcional, segundo apellido;
  • last_name - primer apellido;
  • date_of_birth - parámetro opcional, fecha de nacimiento;
  • organization - parámetro opcional, nombre de empresa/organización;
  • organization_description - parámetro opcional, descripción de actividad de empresa;
  • organization_reg_number - parámetro opcional, número de registro de empresa;
  • country - país, código iso2 del país;
  • region - parámetro opcional, provincia/región;
  • city - ciudad;
  • address - dirección completa;
  • zip_code - código postal;
  • street - calle;
  • street_code - parámetro opcional, código de calle, solo para Dinamarca;
  • municipality_code - parámetro opcional, código de municipio, solo para Dinamarca;
  • building_number - número;
  • building_letter - parámetro opcional, letra;
  • phone - número de teléfono de contacto;
  • type_of_id - parámetro opcional, tipo de documento: "PASSPORT", "DNI", "NIE", "RESIDENCE_PERMIT", "NATIONAL_ID_CARD", "BUSINESS_REGISTRATION";
  • id_number - parámetro opcional, número del documento;
  • issuing_authority - parámetro opcional, autoridad de expedición;
  • issuing_date - parámetro opcional, fecha de expedición;
  • direction_id - parámetro opcional, ID de destino/ciudad para verificar el cumplimiento.

post /v1/documents/upload/

cargar archivo para el grupo de documentos

Parámetros:

  • user_id - parámetro opcional, disponible para uso de socios o usuarios creados por éste. ;
  • group_id - ID de grupo, 0 - grupo de documentos principal;
  • document_type - tipo de documento: 'certificate', 'contract', 'company_letter', 'inn_ua', passport', 'phone_bill', 'photo_with_doc', 'photo_with_passport', 'receipt', 'driver_id_us_ca', 'driver_id_other';
  • file - uploaded file.

Ejemplo de solicitud:

                                    $zd = new \Zadarma_API_Test\Api(KEY, SECRET);
$zd->request(
    'documents/upload',
    [
        'group_id' => 0,
        'document_type' => 'passport',
        'file' => new CURLFile('passport.jpg', 'image/jpeg', 'passport.jpg')
    ],
    'post'
);

Ejemplo de respuesta:

                                    {
    "status": "success",
    "message": "The File passport.jpg has been successfully uploaded to the website.",
    "doc_name": "passport.jpg"
}

Socio

get /v1/reseller/account/info/

información sobre la cuenta de socio

                                    {
    "status": "success",
    "balance": 123,
    "credit": 0,
    "currency": "USD",
    "reseller_fee": 10,
    "user_fee": 10
}

post /v1/reseller/account/money_transfer/

Transferir saldo desde la cuenta del socio al balance de otra cuenta relacionada o viceversa

                                    {
    "status": "success",
    "user": {
        "balance": "62.0000",
        "currency": "EUR"
    },
    "reseller": {
        "balance": "94.825",
        "currency": "USD"
    }
}

Parámetros

  • amount - importe;
  • currency - divisa;
  • type - destino de transferencia "to_reseller" y "to_user".

get /v1/reseller/users/phones/

Listado de números de teléfono de contacto de usuario

                                    {
    "status": "success",
    "list": [
        {
            "id": 0,
            "number": "49025000897",
            "is_proved": false
        }
    ]
}

Parámetros

  • user_id - id de usuario;

post /v1/reseller/users/phones/add/

Añadir número de teléfono de contacto de usuario

                                    {
    "status": "success",
    "id": 98,
    "number": "359000000001",
    "is_proved": true
}

Parámetros

  • user_id - id usuario;
  • number - número.

post /v1/reseller/users/phones/update/

Editar número de teléfono de usuario

                                    {
    "status": "success",
    "id": 99,
    "number": "359000000002",
    "is_proved": false
}

Parámetros

  • user_id - id usuario;
  • id - ID del número, 0 - número de teléfono principal del perfil;
  • number - número.

post /v1/reseller/users/phones/prove_by_sms

Solicitud de confirmación del número de teléfono de contacto de usuario

                                    {
    "number": "359000000002",
    "status": "success",
    "message": "You were sent an SMS message with a code. Code is valid for 1 hour."
}

Parámetros

  • user_id - id usuario;
  • number - número.

post /v1/reseller/users/phones/confirm

Confirmación del número de contacto por código de SMS

                                    {
    "status": "success",
    "message": "Your number confirmed!",
    "number": "35900000019"
}

Parámetros

  • user_id - id de usuario;
  • number - número.
  • code - código de confirmación.

post /v1/reseller/users/registration/new/

Registro de usuario

                                    {
    "status": "success",
    "user_id": 12345,
    "message": "You registered a new user in the system."
},{
    "status": "success",
    "message": "You registered a new user in the system. A registration confirmation link was sent to the email address you provided. To activate the account the user needs to click on that link, after which they can log in on the website."
},{
    "status": "success",
    "message": "You registered a new user in the system. A registration confirmation code was sent to the email address you provided. To activate the account the user needs to send code to you, after which you can confirm registration using API."
}

Parámetros

  • email - correo electrónico del cliente;
  • first_name - nombre del cliente;
  • last_name - parámetro opcional;
  • middle_name - parámetro opcional;
  • organization - parámetro opcional;
  • country - código ISO2 del país;
  • city;
  • address - parámetro opcional;
  • phone - parámetro opcional;
  • password - parámetro opcional;
  • tariff - ID de la tarifa;
  • tariff_period - parámetro opcional, periodo de tarifa month | year;
  • language - parámetro opcional, código de idioma, en;
  • currency - parámetro opcional, código de divisa, USD;
  • promocode - parámetro opcional, código promocional;
  • gmt - parámetro opcional, GMT;
  • id_card - parámetro opcional, número del documento de DNI, pasaporte.

post /v1/reseller/users/registration/confirm/

Confirmar registro de usuario

                                    {
    "status": "success",
    "user_id": 12345
}

Parámetros

  • code - código desde el email;
  • email - dirección de email.

get /v1/reseller/users/list/

Listado de usuarios de socio por página (50)

                                    {
    "status": "success",
    "total": 205,
    "total_pages": 5,
    "page": 1,
    "users": [
        {
            "id": "1234",
            "email": "test@domain.com",
            "first_name": "Test",
            "last_name": "Test",
            "organization": "",
            "phone": "74990000001",
            "created": "2021-01-26 14:21:04",
            "last_login": "2021-01-30 09:46:31",
            "balance": "0.4000",
            "currency": "GBP",
            "sips_count": "1",
            "is_active": true,
            "allow_topup": true
        },
        ...
    ]
}

Parámetros

  • page - número de página.

get /v1/reseller/users/find/

Buscar una cuenta por criterios (uno de los id, email, sip)

                                    {
    "status": "success",
    "user": {
        "id": "1234",
        "email": "test@domain.com",
        "first_name": "Test",
        "last_name": "Test",
        "organization": "",
        "phone": "74990000001",
        "created": "2021-01-26 14:21:04",
        "last_login": "2021-01-30 09:46:31",
        "balance": "0.4000",
        "currency": "GBP",
        "sips_count": "1",
        "is_active": true,
        "allow_topup": true
    }
}

Parámetros

  • id - optional;
  • sip - optional;
  • email - optional.

get /v1/reseller/users/topup/

Transferir saldo del socio al balance de usuario de la cuenta

                                    {
    "status": "success",
    "user_topup": {
        "amount": 10,
        "currency": "GBP"
    },
    "reseller_withdraw": {
        "amount": 10,
        "currency": "GBP"
    }
}

Parámetros

  • user_id - id del usuario;
  • amount- importe;
  • currency - divisa.

get /v1/reseller/users/api_key/

Obtener actuales claves de acceso de usuario para API

                                    {
    "status": "success",
    "user_id": 1234,
    "last_request_datetime": "2021-02-18 10:45:01",
    "allow_reset": true,
    "key": "hidden",
    "secret": "hidden"
},{
    "status": "success",
    "user_id": 1234,
    "last_request_datetime": "2021-02-26 15:59:50",
    "allow_reset": false,
    "key": "abscd",
    "secret": "12345"
}

Parámetros

  • user_id id del usuario.

post /v1/reseller/users/api_key/

Obtener nuevas claves de acceso de usuario para API

                                    {
    "status": "success",
    "user_id": 1234,
    "key": "abscd",
    "secret": "12345"
}

Parámetros

  • user_id - id del usuario.

Интеграция WebRTC виджета

get /v1/webrtc/get_key/

obtener clave para el widget webrtc. Tiempo de vida de clave - 72 horas.

                                    {
    "status":"success",
    "key": YOUR_KEY
}

Parámetros:

  • sip – login del SIP o de la extensión de la centralita.

post /v1/webrtc/create/

Crear integración del widget WebRTC

                                    {
    "status": "success"
}

Parámetros

  • user_id - parámetro opcional, disponible para ser usado por socios o usuarios creados por éstos;
  • domain - nombre del dominio.

put /v1/webrtc/

Modificar ajustes la integración del widget WebRTC

                                    {
    "status": "success"
}

Parámetros

  • user_id - parámetro opcional, disponible para ser usado por socios o usuarios creados por éstos;
  • shape - valores posibles: 'square', 'rounded';
  • position - valores posibles: 'top_left', 'top_right', 'bottom_right', 'bottom_left'.

get /v1/webrtc/

Datos de la integración del widget WebRTC

                                    {
    "status": "success",
    "is_exists": true,
    "domains": [
        "test.domain.com"
    ],
    "settings": {
        "shape": "square",
        "position": "top_right"
    }
}

Параметры

  • user_id - parámetro opcional, disponible para ser usado por socios o usuarios creados por éstos;

post /v1/webrtc/domain/

Añadir dominio de la integración del widget WebRTC

                                    {
   "status": "success"
}

Parámetros

  • user_id - parámetro opcional, disponible para ser usado por socios o usuarios creados por éstos;
  • domain - nombre del dominio.

delete /v1/webrtc/domain/

Eliminar dominio de la integración del widget WebRTC

                                    {
   "status": "success"
}

Parámetros

  • user_id - parámetro opcional, disponible para ser usado por socios o usuarios creados por éstos;
  • domain - nombre del dominio.

delete /v1/webrtc/

Eliminar la integración del widget WebRTC

                                    {
   "status": "success"
}

Parámetros

  • user_id - parámetro opcional, disponible para ser usado por socios o usuarios creados por éstos.

Métodos ZCRM

Clientes

get /v1/zcrm/customers

Devuelve el listado de clientes

Parámetros

  • search (opcional) - barra de búsqueda. La búsqueda se realiza de forma combinada por:
    • del nombre de cliente
    • a números de teléfono de cliente
    • descripción del cliente
    • dirección y código postal
    • sitio web
    • e-mail
    • Messengers
    • nombres de empleados
    • números de teléfono de empleados
    • descripción de empleados
    • e-mail de empleados
    • Messengers de empleados
  • filter (opcional) — filtro de clientes. Estructura del filtro:

(Respuesta 1)

                                    Respuesta 1:
{ "status": "company", "type": "client", "country": "GB", "city": "London", "label": 12, "employees_count": "50", "responsible": 20 }

donde:

  • status — estado del cliente. Valores disponibles:
    • individual — persona física
    • company — empresa
  • type — tipo de cliente. Valores posibles:
    • potential — cliente potencial
    • client — cliente
    • reseller — реселлер
    • partner — colaborador
  • country — país del cliente. Código de dos letras (ES, US, etc)
  • city — ciudad del cliente (línea)
  • label — etiqueta (identificador)
  • employees_count — número de empleados. Valores posibles:
    • 50 — inferior a 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • responsible — responsable (identificador del usuario)

Cualquiera de los parámetros del filtro se puede omitir, es decir, es opcional.

  • sort (opcional) — clasificación de clientes. Estructura del parámetro:

(Respuesta 2)

                                    Respuesta 2:
{ "attr": "name", "desc": 0 }

donde:

  • attr — campo de clasificación. Valores disponibles:
    • name — nombre del cliente
    • status — estado del cliente
    • type — tipo del cliente
  • desc — sentido de clasificación. Valores disponibles:
    • 0 — crecientes
    • 1 — decrecientes
    • take (para la muestra por página) — cuántos clientes devolver (por defecto 20)
    • skip (para la muestra por página) - cuántos clientes saltarse (por defecto 0)

Respuesta

(Respuesta 3)

                                    Respuesta 3:
{ "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" } ] } ] }

donde:

  • totalCount — número total de clientes (incluyendo la barra de búsqueda y el filtro)
  • customers — conjunto de clientes (teniendo en cuenta la muestra por página). Cada elemento del conjunto contiene los siguientes parámetros:
    • id — identificador del cliente
    • name — nombre del cliente
    • status — estado del cliente. Valores posibles:
      • individual — persona física
      • company — empresa
    • type — tipo de cliente. Valores posibles:
      • potential — cliente potencial
      • client — cliente
      • reseller — agente
      • partner — colaborador
    • responsible_user_id — responsable (identificador del usuario)
    • employees_count — cantidad de empleados. Valores posibles:
      • 50 — inferior a 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — descripción del cliente
    • country — país del cliente. Código de dos letras (ES, US, etc.)
    • city — ciudad del cliente
    • address — domicilio del cliente
    • zip — código postal
    • website — página web del cliente
    • created_at — fecha y hora de creación del cliente (en formato YYYY-MM-DD HH:mm:ss)
    • created_by — creado por (identificador del usuario)
    • lead_source — fuente. Valores posibles:
      • manual — manual
      • call_incoming — llamada entrante
      • call_outgoing — llamada saliente
      • form — forma
    • lead_created_at — fecha y hora de la creación del lead si el cliente ha sido creado a través del lead (en formato YYYY-MM-DD HH:mm:ss)
    • lead_created_by — por quien ha sido creado el lead si el cliente ha sido creado a través del lead (identificador del usuario)
      • type — tipo de número. Valores posibles:
        • work — de trabajo
        • personal — personal
      • phone — valor del número
    • contacts — conjunto de contactos del cliente. Cada contacto debe contener los siguientes campos:
      • type — tipo de contacto. Valores posibles:
        • email_work — e-mail de trabajo
        • email_personal — e-mail personal
        • skype
        • telegram
        • viber
        • whatsapp
      • value — valor del contacto
    • labels — conjunto de etiquetas asignadas al cliente. Cada etiqueta contiene los siguientes campos:
      • id — identificador de la etiqueta
      • label — valor de la etiqueta

get /v1/zcrm/customers/<c_id>

Devuelve al cliente por su ID

Parámetros de dirección

  • c_id — identificador del cliente

Respuesta

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

donde:

  • name — nombre del cliente
  • status — estado del cliente. Valores posibles:
    • individual — persona física
    • company — empresa
  • type — tipo de cliente. Valores posibles:
    • potential — cliente potencial
    • client — cliente
    • reseller — agente
    • partner — colaborador
  • responsible_user_id — responsable (identificador del usuario)
  • employees_count — cantidad de empleados. Valores posibles:
    • 50 — inferior a 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — descripción del cliente
  • country — país del cliente. Código de dos letras (ES, US, etc.)
  • city — ciudad del cliente
  • address — domicilio del cliente
  • zip — código postal
  • website — página web del cliente
  • lead_source — fuente. Valores posibles:
    • manual — manual
    • call_incoming — llamada entrante
    • call_outgoing — llamada saliente
    • form — forma
  • lead_created_at — fecha y hora de la creación del lead si el cliente ha sido creado a través del lead (en formato YYYY-MM-DD HH:mm:ss)
  • lead_created_by — por quien ha sido creado el lead si el cliente ha sido creado a través del lead (identificador del usuario)
  • phones — conjunto de números de teléfono del cliente. Cada número debe contener los siguientes campos:
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
    • phone — valor del número
  • contacts — conjunto de contactos del cliente. Cada contacto debe contener los siguientes campos:
    • type — tipo de contacto. Valores posibles:
      • email_work — e-mail de trabajo
      • email_personal — e-mail personal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor del contacto
  • labels — conjunto de etiquetas vinculadas al cliente. Cada etiqueta contiene los siguientes campos:
    • id — identificador de la etiqueta
    • label — valor de la etiqueta
  • custom_properties — conjunto de propiedades adicionales. Cada propiedad adicional contiene los siguientes campos:
    • id — identificador de la propiedad adicional o:
    • key — nombre único de la propiedad adicional
    • value — valor de la propiedad adicional

post /v1/zcrm/customers

Crea un nuevo cliente con los datos indicados

Parámetros

  • customer — datos de nuevo cliente. Estructura de cliente:

(Respuesta 1)

                                    Respuesta 1:
{ "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" } ] }

donde:

  • name — nombre del cliente
  • status — estado del cliente. Valores posibles:
    • individual — persona física
    • company — empresa
  • type — tipo de cliente. Valores posibles:
    • potential — cliente potencial
    • client — cliente
    • reseller — agente
    • partner — colaborador
  • responsible_user_id — responsable (identificador del usuario)
  • employees_count — cantidad de empleados. Valores posibles:
    • 50 — inferior a 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — descripción del cliente
  • country — país del cliente. Código de dos letras (ES, US, etc.)
  • city — ciudad del cliente
  • address — domicilio del cliente
  • zip — código postal
  • website — página web del cliente
  • lead_source — fuente. Valores posibles:
    • manual — manual
    • call_incoming — llamada entrante
    • call_outgoing — llamada saliente
    • form — forma
  • phones — conjunto de números de teléfono. Cada número debe contener los siguientes campos:
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
    • phone — valor del número
  • contacts — conjunto de contactos del cliente. Cada contacto debe contener los siguientes campos:
    • type — tipo de contacto. Valores posibles:
      • email_work — e-mail de trabajo
      • email_personal — e-mail personal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor del contacto
  • labels — conjunto de etiquetas añadidas al clientes. Cada elemento debe contener:
    • id — identificador de la etiqueta existente
  • custom_properties — conjunto de propiedades adicionales. Cada elemento debe contener:
    • id — identificador de la propiedad adicional o:
    • key — nombre único de la propiedad adicional
    • value — valor de la propiedad adicional

Respuesta:

(Respuesta 2)

                                    Respuesta 2:
{ "id": 65 }

donde:

  • id — Identificador del cliente creado.

put /v1/zcrm/customers/<c_id>

Actualiza al cliente existente con el ID indicado

Parámetros de dirección

  • c_id — identificador del cliente

Parámetros

  • customer — nuevos datos del cliente. Estructura del cliente:

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

donde:

  • name — nombre del cliente
  • status — estado del cliente. Valores posibles:
    • individual — persona física
    • company — empresa
  • type — tipo del cliente. Valores posibles:
    • potential — cliente potencial
    • client — cliente
    • reseller — agente
    • partner — colaborador
  • responsible_user_id — responsable (identificador del usuario)
  • employees_count — número de empleados. Valores posibles:
    • 50 — inferior a 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — descripción del cliente
  • country — país del cliente. Código de dos letras (ES, US, etc.)
  • city — ciudad del cliente
  • address — domicilio del cliente
  • zip — código postal
  • website — página web del cliente
  • lead_source — fuente. Valores posibles:
    • manual — manual
    • call_incoming — llamada entrante
    • call_outgoing — llamada saliente
    • form — forma
  • phones — conjunto de números de teléfono. Cada número debe contener los siguientes campos:
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
    • phone — valor del número
  • contacts — conjunto de contactos del cliente. Cada contacto contiene los siguientes campos:
    • type — tipo de contacto. Valores posibles:
      • email_work — e-mail de trabajo
      • email_personal — e-mail personal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor del contacto
  • labels — conjunto de etiquetas añadidas al cliente. Cada elemento debe contener:
    • id — identificador de la etiqueta existente
  • custom_properties — conjunto de parámetros adicionales. Cada elemento debe contener:
    • id — identificador de la propiedad adicional o:
    • key — nombre único de la propiedad adicional
    • value — valor de la propiedad adicional

delete /v1/zcrm/customers/<c_id>

Elimina el cliente por su ID

Parámetros de dirección

  • c_id — identificador del cliente

Etiquetas

get /v1/zcrm/customers/labels

Devuelve el listado de todas las etiquetas y su estadística

Respuesta

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

donde:

  • totalCount — número total de etiquetas en el sistema
  • labels — conjunto de etiquetas. Cada etiqueta contiene los siguientes campos:
    • id — identificador de la etiqueta
    • label — nombre de la etiqueta
    • count — número de clientes y leads que usan esta etiqueta

post /v1/zcrm/customers/labels

Crea una nueva etiqueta

Parámetros

  • name — nombre de etiqueta nueva

Respuesta

                                    {
  "id": 13,
  "label": "Very best clients",
  "count": 0
}

donde:

  • id — identificador de la etiqueta creada
  • label — nombre de la etiqueta
  • count — número de clientes y leads que usan esta etiqueta (siempre igual a 0)

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

Elimina la etiqueta del sistema por su ID

Parámetros de dirección

  • l_id — identificador de la etiqueta

Propiedades adicionales

get /v1/zcrm/customers/custom-properties

Devuelve todos los parámetros adicionales

Respuesta

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

donde:

  • totalCount — cantidad de propiedades adicionales.
  • customProperties — matriz de propiedades adicionales. Cada propiedad adicional contiene los siguientes parámetros:
    • id — identificador de la propiedad adicional
    • key — nombre único de la propiedad adicional
    • title — nombre visualizado de la propiedad adicional

Flujo de actividad del cliente

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

Devuelve notas en el flujo de actividad del cliente

Parámetros de dirección

  • c_id — identificador del cliente

Respuesta

                                    {
  "totalCount": 17,
  "items": [
    {
      "id": 37825,
      "type": "note",
      "content": "Call to the client",
      "time": "2020-06-08 06:55:02",
      "user_id": 20,
      "user_name": "John Beam",
      "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": "document.doc"
        }
      ]
    }
  ]
}

donde:

  • totalCount — cantidad total de las grabaciones
  • items — conjunto de grabaciones. Cada grabación contiene los siguientes atributos:
    • id — identificador de la grabación
    • type — tipo de grabación. Valores posibles:
      • event — evento
      • note — nota de texto
      • call — llamada
    • content — contenido de la grabación. Si el tipo de la grabación es nota, este atributo contiene un contenido de nota de texto. Si el tipo de la grabación es evento, este atributo contiene el identificador, por ejemplo:
      • CUSTOMER_CREATED — evento de creación de cliente
      • LEAD_CREATED — evento de creación de lead
    • time — hora de grabación en formato YYYY-MM-DD hh:mm:ss
    • user_id — identificador del usuario creador de la grabación
    • user_name — nombre de usuario creador de la grabación
    • call_id — identificador de llamada (si el tipo de grabación es llamada)
    • call_type — tipo de llamada. Valores posibles:
      • incoming — llamada entrante
      • outgoing — llamada saliente
    • call_status — estado de llamada. Valores posibles:
      • answer — llamada de éxito
      • noanswer — sin respuesta
      • cancel — cancelada
      • busy — ocupado
      • failed — no se ha podido realizar
    • call_phone — número de teléfono de la llamada
    • call_duration — duración de la llamada en segundos
    • call_record — si está activada la grabación de llamadas
    • call_contact_name — nombre del contacto de la llamada
    • attached_files — conjunto de archivos adjuntados a la nota (si el tipo de la grabación es nota). Cada elemento del conjunto contiene los siguientes atributos:
      • file_id — identificador del archivo
      • original_filename — nombre original del archivo

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

Añade nota de texto en el flujo de actividad del cliente con capacidad de adjuntar archivos

Parámetros de dirección

  • c_id — identificador del cliente

Parámetros

  • content — contenido en texto de la nota
  • files — matriz de los archivos adjuntos

Respuesta

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

donde:

  • id — identificador de la grabación
  • type — tipo de grabación. En este caso es igual:
    • note — nota de texto
  • content — contenido en texto de la nota
  • time — hora de la grabación en formato YYYY-MM-DD hh:mm:ss
  • user_id — identificador del usuario creador de la grabación
  • user_name — nombre del usuario creador de la grabación
  • attached_files — matriz de archivos adjuntos a una nota (si el tipo de grabación es una nota). Cada elemento de la matriz contiene los siguientes atributos:
    • file_id — identificador del archivo
    • original_filename — nombre original del archivo

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

Actualiza el contenido de la nota de texto existente por su ID

Parámetros de dirección

  • c_id — identificador del cliente
  • i_id — identificador de nota de texto

Parámetros

  • content — nuevo texto de la nota

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

Elimina la nota en el flujo de actividad del cliente por su ID

Parámetros de dirección

  • c_id — identificador del cliente
  • i_id — identificador de nota de texto

Empleados

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

Devuelve el listado de empleados del cliente por su ID

Parámetros de dirección

  • c_id — identificador del cliente

Respuesta

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

donde:

  • totalCount — cantidad de empleados del cliente
  • employees — matriz de empleados del cliente. Cada elemento contiene los siguientes atributos:
    • id — identificador del empleado
    • customer_id — identificador del cliente vinculado al empleado
    • name — nombre del empleado
    • position — cargo del empleado. Valores posibles:
      • ceo — director general
      • director — directir
      • manager — agente
      • sales_manager — comercial
      • hr — RRHH
      • support — soporte
      • custom — otro
    • position_title — nombre de otros cargos (paraposition = custom)
    • comment — descripción del empleado
    • phones — matriz de números de teléfono del empleado. Cada número contiene los siguientes campos:
      • type — tipo de número. Valores posibles:
        • work — de trabajo
        • personal — personal
      • phone — valor del número
    • contacts — matriz de contactos del empleado. Cada contacto contiene los siguientes campos:
      • type — tipo de contacto. Valores posibles:
        • email_work — e-mail de trabajo
        • email_personal — e-mail personal
        • skype
        • telegram
        • viber
        • whatsapp
      • value — valor del contacto

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

Devuelve al empleado del cliente por su ID

Parámetros de dirección

  • c_id — identificador del cliente
  • e_id — identificador del empleado

Respuesta

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

donde:

  • id — identificador del empleado
  • customer_id — identificador del cliente vinculado al empleado
  • name — nombre del empleado
  • position — cargo del empleado. Valores posibles:
    • ceo — director general
    • director — director
    • manager — agente
    • sales_manager — comercial
    • hr — RRHH
    • support — soporte
    • custom — otro
  • position_title — nombre del cargo propio (para position = custom)
  • comment — descripción del empleado
  • phones — conjunto de números de teléfono del empleado. Cada número contiene los siguientes campos:
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
    • phone — valor del número
  • contacts — conjunto de contactos del cliente. Cada contacto contiene los siguientes campos:
    • type — tipo de contacto. Valores posibles:
      • email_work — e-mail de trabajo
      • email_personal — e-mail personal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valores de contacto

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

Crea y guarda a nuevo empleado para el cliente seleccionado

Parámetros de dirección

  • c_id — identificador del cliente

Parámetros

  • employee — datos del empleado nuevo. Estructura del empleado:

(Respuesta 1)

                                    Respuesta 1:
{ "name": "Steven Knight", "position": "manager", "position_title": "", "comment": "", "phones": [ { "type": "work", "phone": "+44123456789" } ], "contacts": [ { "type": "email_work", "value": "s.knight@example.com" } ] }

donde:

  • name — nombre del empleado
  • position — cargo del empleado. Valores posibles:
    • ceo — director general
    • director — director
    • manager — agente
    • sales_manager — comercial
    • hr — RRHH
    • support — soporte
    • custom — otro
  • position_title — nombre del cargo propio (para position = custom)
  • comment — descripción del empleado
  • phones — conjunto de números de teléfono del empleado. Cada número contiene los siguientes campos:
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
    • phone — valor del número
  • contacts — conjunto de contactos del cliente. Cada contacto contiene los siguientes campos:
    • type — tipo de contacto. Valores posibles:
      • email_work — e-mail de trabajo
      • email_personal — e-mail personal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor de contacto

Respuesta

(Respuesta 2)

                                    Respuesta 2:
{ "id": 23 }

donde:

  • id — identificador de nuevo empleado

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

Actualiza al empleado existente con ID indicado

Parámetros de dirección

  • c_id — identificador del cliente
  • e_id — identificador del empleado

Parámetros

  • employee — nuevos datos del empleado. Estructura:

                                    {
    "name": "Steven Knight",
    "position": "manager",
    "position_title": "",
    "comment": "",
    "phones": [
      {
        "type": "work",
        "phone": "+44123456789"
      }
    ],
    "contacts": [
      {
        "type": "email_work",
        "value": "john@example.com"
      }
    ]
}

donde:

  • name — nombre del empleado
  • position — cargo del empleado. Valores posibles:
    • ceo — director general
    • director — director
    • manager — agente
    • sales_manager — comercial
    • hr — RRHH
    • support — soporte
    • custom — otro
  • position_title — nombre del cargo propio (para position = custom)
  • comment — descripción del empleado
  • phones — conjunto de números de teléfono del empleado. Cada número contiene los siguientes campos:
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
    • phone — valor del número
  • contacts — conjunto de contactos del cliente. Cada contacto contiene los siguientes campos:
    • type — tipo de contacto. Valores posibles:
      • email_work — e-mail de trabajo
      • email_personal — e-mail personal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor de contacto

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

Elimina al empleado por su ID

Parámetros de dirección

  • c_id — identificador del cliente
  • e_id — identificador del empleado

Tareas

get /v1/zcrm/events

Devuelve el listado de tareas

Parámetros

  • search (opcional) — barra de búsqueda. La búsqueda se realiza de forma combinada por:
    • nombre de tareas
    • descripción de tareas
    • comentarios de tareas finalizadas
  • filter (opcional) - filtro de tareas. Estructura del filtro:

(Respuesta 1)

                                    Respuesta 1:
{ "responsible": 456, "createdBy": 456, "start": "2020-06-03 02:56:00", "end": "2020-06-12 02:56:00", "completed": 1 }

donde:

  • responsible — responsable (identificador de usuario)
  • createdBy — creado por (identificador de usuario)
  • start — mostrar tareas empezadas después del periodo seleccionado (en formato YYYY-MM-DD hh:mm:ss)
  • end — mostrar tareas empezadas antes del periodo seleccionado (en formato YYYY-MM-DD hh:mm:ss)
  • completed — seleccione en 1 para ver también las tareas finalizadas
  • sort (opcional) - clasificación de tareas. Estructura del parámetro:

(Respuesta 2)

                                    Respuesta 2:
{ "attr": "start", "desc": 0 }

donde:

  • attr — campo de clasificación. Valores posibles:
    • responsible — usuario responsable
    • title — nombre de tarea
    • start — hora inicio de tarea
    • end — hora fin de tarea
  • desc — sentido de clasificación. Valores posibles:
    • 0 — creciente
    • 1 — decreciente

Respuesta

(Respuesta 3)

                                    Respuesta 3:
{ "totalCount": 4, "events": [ { "id": 40, "type": "task", "title": "Create text for Good Company", "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": "Good Company", "status": "company", "type": "client", "lead_source": "manual", "lead_status": "not_processed", "contact_type": "customer" } ] } ] }

donde

  • totalCount — cantidad total de tareas
  • events — conjunto de tareas. Cada tarea contiene los siguientes atributos:
    • id — identificador de tarea
    • type — tipo de tarea. Valores posibles:
      • task — tarea
      • call — llamada
    • title — nombre de tarea
    • description — descripción de tarea (en formato Quill Delta)
    • start — fecha y hora inicio de tarea (en formato YYYY-MM-DD hh:mm:ss)
    • end — fecha y hora fin de tarea (en formato YYYY-MM-DD hh:mm:ss)
    • allDay — tarea para todo el día (true o false) — la fecha se determina por el parámetro start
    • created_by — identificador de usuario creador de tarea
    • responsible_user — identificador de usuario responsable de tarea
    • phone — número de teléfono para llamada (si el tipo de tarea es llamada)
    • call_done — muestra si se ha realizado la llamada
    • completed — muestra que la tarea está marcada como finalizada
    • completed_comment — comentario para la tarea finalizada
    • members — conjunto de participantes de la tarea (solo identificadores de usuarios)
    • customers — conjunto de clientes y leads adjuntados a la tarea. Cada elemento de conjunto contiene los siguientes campos:
      • id — identificador de cliente / lead
      • name — nombre de cliente / lead
      • status — estado de cliente. Valores posibles:
        • individual — persona física
        • company — empresa
    • type — tipo de cliente. Valores posibles:
      • potential — cliente potencial
      • client — cliente
      • reseller — agente
      • partner — colaborador
    • lead_source — fuente del lead. Valores posibles:
      • manual — manual
      • call_incoming — llamada entrante
      • call_outgoing — llamada saliente
      • form — forma
    • lead_status — estado del lead. Valores posibles:
      • not_processed — no gestionado
      • in_progress — en proceso
      • finished — finalizado
    • contact_type — tipo de contacto. Valores posibles:
      • customer — cliente
      • lead — lead

get /v1/zcrm/events/<event_id>

Devuelve la tarea por su ID

Respuesta

                                    {
  "id": 40,
  "type": "task",
  "title": "Create text for Good Company",
  "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": "Good Company",
      "status": "company",
      "type": "client",
      "lead_source": "manual",
      "lead_status": "not_processed",
      "contact_type": "customer"
    }
  ]
}

donde

  • id — identificador de tarea
  • type — tipo de tarea. Valores posibles:
    • task — tarea
    • call — llamada
  • title — nombre de tarea
  • description — descripción de tarea (en formato Quill Delta)
  • start — fecha y hora de inicio de tarea (en formato YYYY-MM-DD hh:mm:ss)
  • end — fecha y hora de fin de tarea (en formato YYYY-MM-DD hh:mm:ss)
  • allDay — tarea para todo el día (true o false)
  • created_by — identificador de usuario creador de tarea
  • responsible_user — identificador de usuario responsable de tarea
  • phone — número de teléfono para llamada (si el tipo de tarea es llamada)
  • call_done — muestra si se ha realizado la llamada
  • completed — muestra que la tarea está marcada como finalizada
  • completed_comment — comentario para la tarea finalizada
  • members — conjunto de participantes de la tarea (identificadores de usuarios solo)
  • customers — conjunto de clientes y leads adjuntados a la tarea. Cada elemento del conjunto contiene los siguientes campos:
    • id — identificador del lead / cliente
    • name — nombre del lead / cliente
    • status — estado del cliente. Valores posibles:
      • individual — persona física
      • company — empresa
    • type — tipo de cliente. Valores posibles:
      • potential — cliente potencial
      • client — cliente
      • reseller — agente
      • partner — colaborador
    • lead_source — fuente del lead. Valores posibles:
      • manual — manual
      • call_incoming — llamada entrante
      • call_outgoing — llamada saliente
      • form — forma
    • lead_status — estado del lead. Valores posibles:
      • not_processed — no gestionado
      • in_progress — en proceso
      • finished — finalizado
    • contact_type — tipo de contacto. Valores posibles:
      • customer — cliente
      • lead — lead

post /v1/zcrm/events

Crea una nueva tarea con los datos indicados

Parámetros

  • event — datos de nueva tarea. Estructura:

(Respuesta 1)

                                    Respuesta 1:
{ "type": "task", "title": "Create text for Good Company", "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] }

donde

  • type — tipo de tarea. Valores posibles:
    • task — tarea
    • call — llamada
  • title — nombre de tarea
  • description — descripción de tarea (en formato Quill Delta)
  • start — fecha y hora de inicio de tarea (en formato YYYY-MM-DD hh:mm:ss)
  • end — fecha y hora de fin de tarea (en formato YYYY-MM-DD hh:mm:ss)
  • allDay — tarea para todo el día (true o false)
  • responsible_user — identificador de usuario responsable de tarea
  • phone — número de teléfono para llamada (si el tipo de tarea es llamada)
  • members — conjunto de participantes de la tarea (identificadores de usuarios solo)
  • customers — conjunto de clientes y leads adjuntados a la tarea (solo identificadores de clientes y leads)

Respuesta

(Respuesta 2)

                                    Respuesta 2:
{ "id": 7216 }

donde

  • id — identificador de tarea creada

put /v1/zcrm/events/<event_id>

Actualiza la tarea existente con el ID indicado

Parámetros

  • event — nuevos datos de la tarea. Estructura:

                                    {
    "title": "Create text for Good Company",
    "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]
}

donde

  • title — nombre de tarea
  • description — descripción de tarea (en formato Quill Delta)
  • start — fecha y hora de inicio de tarea (en formato YYYY-MM-DD hh:mm:ss)
  • end — fecha y hora de fin de tarea (en formato YYYY-MM-DD hh:mm:ss)
  • allDay — tarea para todo el día (true o false)
  • responsible_user — identificador de usuario responsable de tarea
  • phone — número de teléfono para llamada (si el tipo de tarea es llamada)
  • members — conjunto de participantes de la tarea (identificadores de usuarios solo)
  • customers — conjunto de clientes y leads adjuntados a la tarea (solo identificadores de clientes y leads)

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

Finaliza (cierra) la tarea

Parámetros

  • comment (opcional) - comentario

delete /v1/zcrm/events/<event_id>

Elimina la tarea por su ID

Leads

get /v1/zcrm/leads

Devuelve el listado de leads

Parámetros

  • search (opcional) - barra de búsqueda. La búsqueda se realiza de forma combinada por:
    • nombre del lead
    • números de teléfono del lead
    • descripción del lead
    • domicilio y código postal
    • página web
    • e-mail
    • Messengets
  • filter (opcional) - filtro de leads. Estructura del filtro:

(Respuesta 1)

                                    Respuesta 1:
{ "source": "call_incoming", "responsible": 32, "label": 12, "createdAfter": "2020-06-11 12:24:00", "createdBefore": "2020-06-26 12:24:00" }

donde

  • source — fuente del lead. Valores posibles:
    • manual — añadido manualmente
    • call_incoming — llamada entrante
    • call_outgoing — llamada saliente
    • form — forma de contactar
  • responsible — responsable (identificador de usuario). El parámetro permite símbolos especiales:
    • null — devuelve todos los leads asignados
    • –1 — devuelve leads no gestionados
    • –2 — devuelve todos los leads (y asignados y no gestionados)
  • label — etiqueta (identificador)
  • createdAfter — mostrar solo leads creados después del periodo seleccionado (formato: YYYY-MM-DD hh:mm:ss)
  • createdBefore — mostrar solo leads creados hasta del periodo seleccionado (formato: YYYY-MM-DD hh:mm:ss)

Cualquiera de los parámetros del filtro se puede omitir, es decir, es opcional.

  • sort (opcional) - clasificación de leads. Estructura del parámetro:

(Respuesta 2)

                                    Respuesta 2:
{ "attr": "name", "desc": 0 }

donde

  • attr — campo de clasificación. Valores posibles:
    • name — nombre de lead
    • lead_source — fuente de lead
    • lead_status — estado de lead
    • responsible_user_id — usuario responsable
    • lead_created_at — fecha creación del lead
  • desc — sentido de clasificación. Valores posibles:
    • 0 — creciente
    • 1 — decreciente
    • take (para la muestra por página) - cuántos leads devolver (por defecto 20)
    • skip (para la muestra por página) - cuántos leads saltarse (por defecto 0)

Respuesta

(Respuesta 3)

                                    Respuesta 3:
{ "totalCount": 100, "uncategorizedCount": 10, "leads": [ { "id": 3486, "name": "Good Company", "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" } ] } ] }

donde

  • totalCount — total de leads encontrados (incluyendo los de barra de búsqueda y filtros)
  • uncategorizedCount — total de leads no gestionados (teniendo en cuenta la barra de búsqueda y filtros)
  • leads — conjunto de leads (teniendo en cuenta la muestra por página). Cada elemento de conjunto contiene los siguientes parámetros:
    • id — identificador de lead
    • name — nombre de lead
    • responsible_user_id — responsable (identificador de usuario)
    • employees_count — total de empleados. Valores posibles:
      • 50 — inferior a 50
      • 50_250 — 50 – 250
      • 250_500 — 250 – 500
    • comment — descripción del lead
    • country — país del lead. Código de dos letras (ES, US, etc.)
    • city — ciudad del lead
    • address — domicilio del lead
    • zip — código postal
    • website — página web del lead
    • lead_status — estado del lead. Valores posibes:
      • not_processed — no gestionado
      • in_progress — en proceso
      • finished — finalizado
    • lead_source — fuente del lead. Valores posibles:
      • manual — manual
      • call_incoming — llamada entrante
      • call_outgoing — llamada saliente
      • form — forma
    • lead_created_at — fecha y hora de creación del lead (en formato YYYY-MM-DD HH:mm:ss)
    • lead_created_by — creador del lead (identificador de usuario)
    • phones — conjunto de números de teléfono de lead. Cada número contiene los siguientes campos:
      • type — tipo de número. Valores posibles:
        • work — de trabajo
        • personal — personal
      • phone — valor del número
    • contacts — conjunto de contactos del lead. Cada contacto debe contener los siguientes campos:
      • type — tipo de contacto. Valores posibles:
        • email_work — e-mail de trabajo
        • email_personal — e-mail personal
        • skype
        • telegram
        • viber
        • whatsapp
      • value — valor de contacto
    • labels — conjunto de etiquetas asignadas al lead. Cada etiqueta contiene los siguientes campos:
      • id — identificador de la etiqueta
      • label — valor de la etiqueta

get /v1/zcrm/leads/<lead_id>

Devuelve el lead por su ID

Respuesta

                                    {
  "id": 3486,
  "name": "Good Company",
  "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": "Лучшие клиенты"
    }
  ],
  "custom_properties": [
    {
      "id": 12,
      "key": "loyalty",
      "title": "Лояльность",
      "value": "high"
    }
  ]
}

donde

  • id — identificador del lead
  • name — nombre de lead
  • responsible_user_id — responsable (identificador de usuario)
  • employees_count — número de empleados. Valores posibles:
    • 50 — inferior a 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — descripción de lead
  • country — país del lead. Código de dos letras (ES, US, etc.)
  • city — ciudad del lead
  • address — domicilio del lead
  • zip — código postal
  • website — página web del lead
  • lead_status — estado del lead. Valores posibles:
    • not_processed — no gestionado
    • in_progress — en proceso
    • finished — finalizado
  • lead_source — fuente del lead. Valores posibles:
    • manual — manual
    • call_incoming — llamada entrante
    • call_outgoing — llamada saliente
    • form — forma
  • lead_created_at — fecha y hora de la creación del lead (en formato YYYY-MM-DD HH:mm:ss)
  • lead_created_by — por quien ha sido creado el lead (identificador del usuario)
  • phones — conjunto de números de teléfono del lead. Cada número debe contener los siguientes campos:
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
    • phone — valor del número
  • contacts — conjunto de contactos del lead. Cada contacto debe contener los siguientes campos:
    • type — tipo de contacto. Valores posibles:
      • email_work — e-mail de trabajo
      • email_personal — e-mail personal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor de contacto
  • labels — conjunto de etiquetas asignadas al lead. Cada etiqueta contiene los siguientes campos:
    • id — identificador de etiqueta
    • label — valor de etiqueta

post /v1/zcrm/leads

Crea un nuevo lead con los datos indicados

Parámetros

  • convert — convertir lead en cliente. Valores posibles:
    • 0 — no convertir, crear lead
    • 1 — crear cliente
    • 2 — inadecuado (la operación será cancelada — no serán creados ni el lead ni el cliente)
  • lead — datos del nuevo lead. Estructura del lead:

(Respuesta 1)

                                    Respuesta 1:
{ "name": "Good Company", "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" } ] }

donde

  • name — nombre de lead
  • responsible_user_id — responsable (identificador de usuario)
  • employees_count — cantidad de empleados. Valores posibles:
    • 50 — inferior a 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — descripción del lead
  • country — país del lead. Código de dos letras (ES, US, etc.)
  • city — ciudad del lead
  • address — domicilio del lead
  • zip — código postal
  • website — página web del lead
  • lead_source — fuente del lead. Valores posibles:
    • manual — manual
    • call_incoming — llamada entrante
    • call_outgoing — llamada saliente
    • form — forma
  • lead_status — estado del lead. Valores posibles:
    • not_processed — no gestionado
    • in_progress — en proceso
    • finished — finalizado
  • phones — conjunto de números de teléfono. Cada contacto debe contener los siguientes campos:
    • type — tipo de números. Valores posibles:
      • work — de trabajo
      • personal — personal
    • phone — valor del número
  • contacts — conjunto de contactos del lead. Cada contacto debe contener los siguientes campos:
    • type — tipo de contacto. Valores posibles:
      • email_work — e-mail de trabajo
      • email_personal — e-mail personal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor de contacto
  • labels — conjunto de etiquetas asignadas al lead. Cada etiqueta contiene los siguientes campos:
    • id — identificador de la etiqueta
    • custom_properties — conjunto de propiedades adicionales. Cada elemento debe contener:
      • id — identificador de la propiedad adicional o:
      • key — nombre único de la propiedad adicional
      • value — valor de la propiedad adicional

Respuesta

(Respuesta 2)

                                    Respuesta 2:
{ "id": 123 }

donde

  • id — identificador del lead creado

put /v1/zcrm/leads/<lead_id>

Actualiza el lead existente con el ID indicado

Parámetros

  • convert — convertir lead en cliente. Valores posibles:
    • 0 — no convertir
    • 1 — crear cliente
    • 2 — inadecuado (eliminar lead)
  • lead — nuevos datos del lead. Estructura del lead:

                                    {
    "name": "Good Company",
    "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"
      }
    ]
}

donde

  • name — nombre de lead
  • responsible_user_id — responsable (identificador de usuario)
  • employees_count — cantidad de empleados. Valores posibles:
    • 50 — inferior a 50
    • 50_250 — 50 – 250
    • 250_500 — 250 – 500
  • comment — descripción del lead
  • country — país del lead. Código de dos letras (ES, US, etc.)
  • city — ciudad del lead
  • address — domicilio del lead
  • zip — código postal
  • website — página web del lead
  • lead_source — fuente del lead. Valores posibles:
    • manual — manual
    • call_incoming — llamada entrante
    • call_outgoing — llamada saliente
    • form — forma
  • lead_status — estado del lead. Valores posibles:
    • not_processed — no gestionado
    • in_progress — en proceso
    • finished — finalizado
  • phones —conjunto de números de teléfono. Cada contacto debe contener los siguientes campos:
    • type — tipo de números. Valores posibles:
      • work — de trabajo
      • personal — personal
    • phone — valor del número
  • contacts — conjunto de contactos del lead. Cada contacto debe contener los siguientes campos:
    • type — tipo de contacto. Valores posibles:
      • email_work — e-mail de trabajo
      • email_personal — e-mail personal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor de contacto
  • labels — conjunto de etiquetas asignadas al lead. Cada etiqueta contiene los siguientes campos:
    • id — identificador de la etiqueta
  • custom_properties — conjunto de propiedades adicionales. Cada elemento debe contener:
    • id — identificador de la propiedad adicional o:
    • key — nombre único de la propiedad adicional
    • value — valor de la propiedad adicional

delete /v1/zcrm/leads/<lead_id>

Elimina el lead por su ID

Usuarios

get /v1/zcrm/users

Devuelve el listado de usuarios

Respuesta)

                                    {
  "totalCount": 2,
  "users": [
    {
      "id": 234,
      "email": "john@example.com",
      "name": "John Beam",
      "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": "ivanov@example.com"
        }
      ]
    }
  ]
}

donde

  • totalCount — total de usuarios
  • users — conjunto de usuarios. Cada elemento del conjunto contiene los siguientes parámetros:
    • id — identificador de usuario
    • email — e-mail de la cuenta de usuario
    • name — nombre de usuario
    • group_id — identificador de grupo de usuario
    • is_superadmin — muestra si el usuario es súper administrador (1 o 0)
    • enabled — si está desbloqueado el usuario (1 o 0)
    • created_at — fecha y hora de creación de usuario (en formato YYYY-MM-DD hh:mm:ss)
    • avatar — avatar de usuario (identificador de archivo)
    • role — cargo de usuario
    • status — estado de usuario
    • language — idioma de la interfaz de usuario. Alternativas posibles:
      • de — alemán
      • en — inglés
      • es — español
      • pl — polaco
      • ru — ruso
      • ua — ucraniano
    • color — color de usuario en la interfaz ZCRM (solo valor hue — del 0 al 359)
    • color_hex — color de usuario en la interfaz de ZCRM (hex-presentación)
    • internal_number — extensión de la centralita del usuario
    • timezone — huso horario de usuario
    • first_day — determina qué día es el inicio de la semana:
      • 0 — domingo
      • 1 — lunes
    • device — qué usa para las llamadas. Valores posibles:
      • webphone — teléfono web
      • softphone — softphone externo
    • phone_widget_location — ubicación del widget de teléfono web. Valores posibles:
      • left — ubicar el widget del teléfono a la izquierda
      • right — ubicar el widget del teléfono a la derecha
    • phones — conjunto de números de teléfono de usuario. Cada número contiene los siguientes campos:
      • phone — valor de número
      • type — tipo de número. Valores posibles:
        • work — de trabajo
        • personal — personal
    • contacts — conjunto de contactos de usuario. Cada contacto contiene los siguientes campos:
      • type — tipo de contacto. Valores posibles:
        • email_work — e-mail de trabajo
        • email_personal — e-mail personal
        • skype
        • telegram
        • viber
        • whatsapp
      • value — valor de contacto

get /v1/zcrm/users/<user_id>

Devuelve al usuario por su ID

Respuesta

                                    {
  "id": 234,
  "email": "john@example.com",
  "name": "John Beam",
  "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": "simpson@example.com"
    }
  ],
  "pending_email_change_request": false
}

donde

  • id — identificador de usuario
  • email — e-mail de la cuenta de usuario
  • name — nombre de usuario
  • group_id — identificador de grupo de usuario
  • is_superadmin — muestra si el usuario es súper administrador (1 o 0)
  • enabled — si está desbloqueado el usuario (1 o 0)
  • created_at — fecha y hora de creación de usuario (en formato YYYY-MM-DD hh:mm:ss)
  • avatar — avatar de usuario (identificador de archivo)
  • role — cargo de usuario
  • status — estado de usuario
  • language — idioma de la interfaz de usuario. Alternativas posibles:
    • de — alemán
    • en — inglés
    • es — español
    • pl — polaco
    • ru — ruso
    • ua — ucraniano
  • color — color de usuario en la interfaz ZCRM (solo valor hue — del 0 al 359)
  • color_hex — color de usuario en la interfaz de ZCRM (hex-presentación)
  • internal_number — extensión de la centralita del usuario
  • timezone — huso horario de usuario
  • first_day — determina qué día es el inicio de la semana:
    • 0 — domingo
    • 1 — lunes
  • device — qué usa para las llamadas. Valores posibles:
    • webphone — teléfono web
    • softphone — softphone externo
  • phone_widget_location — ubicación del widget de teléfono web. Valores posibles:
    • left — ubicar el widget del teléfono a la izquierda
    • right — ubicar el widget del teléfono a la derecha
  • phones — conjunto de números de teléfono de usuario. Cada número contiene los siguientes campos:
    • phone — valor de número
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
  • contacts — conjunto de contactos de usuario. Cada contacto contiene los siguientes campos:
    • type — tipo de contacto. Valores posibles:
      • email_work — e-mail de trabajo
      • email_personal — e-mail personal
      • skype
      • telegram
      • viber
      • whatsapp
    • value — valor de contacto
  • pending_email_change_request — si ha sido enviada la solicitud de cambio de email de la cuenta pero no ha sido confirmada aún, este parámetro será establecido como true

get /v1/zcrm/users/<user_id>/working-hours

Devuelve horario laboral del usuario

Respuesta

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

donde

  • schedulePeriod — periodicidad del horario "cómo" se repite. Para la semana laboral ordinaria son 7 días, para horarios "día sí día no" son dos días y así sucesivamente.
  • scheduleWorkingHours — conjunto de periodos laborales. Cada periodo laboral contiene los siguientes atributos:
    • time_start — inicio de jornada laboral en formato YYYY-MM-DD hh:mm:ss
    • time_end — fin de jornada laboral en formato YYYY-MM-DD hh:mm:ss
  • scheduleFixes — conjunto de modificaciones introducidas en la jornada laboral determinado en el parámetro scheduleWorkingHours. Cada elemento del conjunto contiene los siguientes atributos:
    • index — índice del elemento en scheduleWorkingHours, es decir qué periodo ha sido modificado
    • repeat_index — índice de repetición de horario en el que se produce el cambio de jornada laboral
    • time_start — nuevo inicio de jornada laboral YYYY-MM-DD hh:mm:ss
    • time_end — nuevo fin de jornada laboral YYYY-MM-DD hh:mm:ss
    • deleted — si es igual a 1, el periodo laboral ha sido eliminado por completo
  • customWorkingHours — conjunto de períodos de trabajo personalizados y únicos. Cada período de trabajo contiene los siguientes atributos:
    • time_start — inicio de jornada laboral YYYY-MM-DD hh:mm:ss
    • time_end — inicio de jornada laboral YYYY-MM-DD hh:mm:ss

get /v1/zcrm/users/groups

Devuelve grupos y derechos de usuario de cada uno

Respuesta

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

donde

  • totalCount — número total de grupos
  • groups — conjunto de grupos. Cada grupo contiene los siguientes atributos:
    • id — identificador de grupos
    • type — tipo de grupos. Valores posibles:
      • admin — administradores
      • manager — agentes
      • chat_operator — operadores
      • trainee — becarios
      • custom — personalizado
    • title — nombre del grupo personalizado (paratype = custom)
    • permissions — derechos de los usuarios del grupo. Los administradores tienen el acceso total, por lo que para los administradores este objeto permanecerá vacío. El resto de grupos contienen los siguientes atributos (cada uno de éstos puede ser igual a true o false):
      • customers_create — permitir creación de clientes
      • customers_edit — permitir editar clientes
      • customers_delete — permitir eliminar clientes
      • customers_import_export — permitir importación y exportación de clientes
      • customers_view_all — permitir ver a todos los clientes incluso los asignados a otros usuarios
      • calendar_other_users_access — permitir ver tareas de otros usuarios
      • calls_other_users_access — permitir acceso a llamadas de otros usuarios
      • leads_view — permitir ver leads de otros usuarios
      • leads_edit — permitir redactar leads de otros usuarios
      • leads_delete — permitir eliminar leads de otros usuarios
      • leads_import_export — permitir importación y exportación de leads
      • team_add — permitir invitar y agregar a otros usuarios al grupo
      • team_edit — permitir editar usuarios

Llamadas

get /v1/zcrm/calls

Devuelve el listado de llamadas

Parámetros

  • search (opcional) — barra de búsqueda. La búsqueda se realiza de forma combinada por:
    • de número de teléfono
    • de números de contactos (clientes, empleados, leads o usuarios)
  • filter (opcional) — filtro de llamadas. Estructura del filtro:

(Respuesta 1)

                                    Respuesta 1:
{ "user": 23, "type": "incoming", "status": "answer", "dateFrom": "2020-06-03 14:56:00", "dateTo": "2020-06-26 14:56:00" }

donde

  • user — usuario (identificador)
  • type — tipo de llamada. Valores posibles:
    • incoming — llamada entrante
    • outgoing — llamada saliente
  • status — estado de la llamada. Valores posibles:
    • answer — llamada de éxito
    • noanswer — sin respuesta
    • cancel — cancelada
    • busy — ocupado
    • failed — no se ha podido realizar
  • dateFrom — ver solo llamadas realizadas después de la hora seleccionada (formato: YYYY-MM-DD hh:mm:ss)
  • dateTo — ver solo llamadas realizadas antes de la hora seleccionada (formato: YYYY-MM-DD hh:mm:ss)

Cualquiera de los parámetros del filtro se puede omitir, es decir, es opcional.

  • sort (opcional) — filtro de llamadas. Estructura del parámetro:

(Respuesta 2)

                                    Respuesta 2:
{ "attr": "time", "desc": 0 }

donde

  • attr — campo de clasificación. Valores posibles:
    • phone — número de teléfono
    • status — estado de llamada
    • duration — duración de llamada
    • time — hora de llamada
  • desc — sentido de clasificación. Valores posibles:
    • 0 — creciente
    • 1 — descreciente
    • take (para la muestra por página) - cuántas llamadas devolver (por defecto 20)
    • skip (para la muestra por página) - cuántas llamadas saltarse (por defecto 0)

Respuesta

(Respuesta 3)

                                    Respuesta 3:
{ "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": "Good Company", "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" } ] } ] }

donde

  • totalCount — número total de llamadas (incluyendo la barra de búsqueda y el filtro)
  • calls — conjunto de llamadas (teniendo en cuenta la muestra por página). Cada elemento del conjunto contiene los siguientes parámetros:
    • id — identificador de llamada
    • type — tipo de llamada. Valores posibles:
      • incoming — llamada entrante
      • outgoing — llamada saliente
    • status — estado de la llamada. Valores posibles:
      • answer — llamada de éxito
      • noanswer — sin respuesta
      • cancel — cancelada
      • busy — ocupado
      • failed — no se ha podido realizar
    • phone — número de teléfono
    • user_id — usuario realizador o receptor de la llamada
    • time — hora de la llamada en formato YYYY-MM-DD hh:mm:ss
    • duration — duración de la llamada en segundos
    • pbx_call_id — identificador de la llamada en la centralita Zadarma
    • record — si está activada la grabación de llamadas
    • record_url_till — tiempo durante el que funcionará el enlace enlace de grabación de llamada
    • contact_type — tipo de contacto. Valores posibles:
      • customer — cliente o lead (ver parámetro is_lead)
      • employee — empleado del cliente
      • user — usuario
    • contact_name — nombre del contacto
    • contact_customer_id — identificador del cliente o lead (si la llamada está vinculada al cliente)
    • contact_employee_id — identificador del empleado (si la llamada está vinculada al empleado)
    • employee_customer_id — identificador del cliente matriz (si la llamada está relacionada con el empleado)
    • contact_user_id — identificador del usuario (si la llamada está relacionada con el usuario)
    • is_lead — muestra si la llamada está relacionada con el lead
    • record_urls — conjunto de grabaciones de llamadas (puede faltar ya que se ha de solicitar expresamente). Cada elemento del conjunto - objeto que contiene el siguiente campo:
      • url — enlace a la grabación de llamada

Contactos generalizados

get /v1/zcrm/contacts

Devuelve el listado de todos los contactos (clientes, empleados, leads, usuarios) con números de teléfono

Parámetros

  • search (opcional) - barra de búsqueda. La búsqueda se realiza de forma combinada por:
    • a los nombres y números de clientes, leads, empleados y usuarios
    • a las extensiones de los usuarios de la centralita
  • take (para la muestra por página) - cuántos contactos devolver (por defecto 20)
  • skip (para la muestra por página) - cuántos contactos saltarse (por defecto 0)

Respuesta

(Respuesta 1)

                                    Respuesta 1:
{ "totalCount": 128, "contacts": [ { "contact_type": "customer", }, { "contact_type": "employee", }, { "contact_type": "lead", }, { "contact_type": "user", } ] }

donde

  • totalCount — número total de contactos (incluyendo la barra de búsqueda)
  • contacts — conjunto de contactos. Cada uno de los contactos depende de su tipo (cliente, empleado, lead, usuario) contendrá su propio conjunto de atributos.

Cliente

(Respuesta 2)

                                    Respuesta 2:
{ "contact_type": "customer", "id": 3486, "name": "Good Company", "status": "company", "type": "client", "phone": { "phone": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John Beam", "ext_num": "100" } }

donde

  • contact_type — tipo de contacto:
    • customer — cliente
  • id — identificador de cliente
  • name — nombre de cliente
  • status — estado de cliente. Valores posibles:
    • individual — persona física/li>
    • company — empresa
  • type — tipo de cliente. Valores posibles:
    • potential — cliente potencial
    • client — cliente
    • reseller — agente
    • partner — colaborador
  • phone — número de teléfono. Contiene los siguientes campos:
    • phone — solo número
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
  • responsible — usuario responsable. Contiene los siguientes campos:
    • id — identificador de usuario
    • name — nombre de usuario
    • ext_num — extensión de la centralita virtual de usuario

Empleado del cliente

(Respuesta 3)

                                    Respuesta 3:
{ "contact_type": "employee", "id": 8, "name": "Michael Simpson", "phone": { "phone": "+44123456789", "type": "work" }, "position": { "position": "manager", "title": "" }, "customer": { "id": 3486, "name": "Good Company" }, "responsible": { "id": 234, "name": "John Beam", "ext_num": "100" } }

donde

  • contact_type — tipo de contacto:
    • employee — empleado
  • id — identificador de empleado
  • name — nombre de empleado
  • phone — número de teléfono. Contiene los siguientes campos:
    • phone — solo número
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
  • position — cargo del empleado. Contiene los siguientes campos:
    • position — valor del cargo. Valores posibles:
      • ceo — director general
      • director — director
      • manager — agente
      • sales_manager — comercial
      • hr — RRHH
      • support — soporte
      • custom — otro
    • title — nombre de otro cargo (paraposition = custom)
  • customer — cliente asignado al empleado. Contiene los siguientes campos:
    • id — identificador de cliente
    • name — nombre de cliente
    • responsible — usuario responsable por el cliente matriz. Contiene los siguientes campos:
      • id — identificador de usuario
      • name — nombre de usuario
      • ext_num — extensión de la centralita del usuario

Lead

(Respuesta 4)

                                    Respuesta 4:
{ "contact_type": "lead", "id": 3486, "name": "Good Company", "phone": { "phone": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John Beam", "ext_num": "100" } }

donde

  • contact_type — tipo de contacto:
    • lead — lead
  • id — identificador de lead
  • name — nombre de lead
  • phone — número de teléfono. Contiene los siguientes campos:
    • phone — solo número
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
  • responsible — usuario responsable. Contiene los siguientes campos:
    • id — identificador de usuario
    • name — nombre de usuario
    • ext_num — extensión de la centralita del usuario

Usuario

(Respuesta 5)

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

donde

  • contact_type — tipo de contacto:
    • user — usuario
  • id — identificador de usuario
  • name — nombre de usuario
  • avatar — avatar de usuario (identificador de archivo)
  • role — rol de usuario
  • status — estado de usuario
  • phone — número de teléfono. Contiene los siguientes campos:
    • phone — solo número
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
      • internal — extensión de la centralita del usuario
  • group — grupo del usuario. Contiene los siguientes campos:
    • type — tipo de grupo. Valores posibles:
      • admin — administradores
      • manager — agentes
      • chat_operator — operadores
      • trainee — becarios
      • custom — personalizado
    • title — nombre del grupo personalizado (para type = custom)

get /v1/zcrm/contacts/identify

Identifica el contacto (cliente, empleado, lead, usuario) por número de teléfono

Parámetros

  • phone — número de teléfono

Respuesta

La respuesta dependerá del tipo de contacto encontrado (cliente, empleado, lead, usuario).

Cliente

(Respuesta 1)

                                    Respuesta 1:
{ "contact_type": "customer", "id": 3486, "name": "Good Company", "status": "company", "type": "client", "phone": { "phone": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John Beam", "ext_num": "100" } }

donde

  • contact_type — tipo de contacto:
    • customer — cliente
  • id — identificador de cliente
  • name — nombre de cliente
  • status — estado de cliente. Valores posibles:
    • individual — persona física
    • company — empresa
  • type — tipo de cliente. Valores posibles:
    • potential — cliente potencial
    • client — cliente
    • reseller — agente
    • partner — colaborador
  • phone — número de teléfono. Contiene los siguientes campos:
    • phone — solo número
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
  • responsible — usuario responsable. Contiene los siguientes campos:
    • id — identificador de usuario
    • name — nombre de usuario
    • ext_num — extensión de la centralita de usuario

Empleado del cliente

(Respuesta 2)

                                    Respuesta 2:
{ "contact_type": "employee", "id": 8, "name": "Michael Simpson", "phone": { "phone": "+44123456789", "type": "work" }, "position": { "position": "manager", "title": "" }, "customer": { "id": 3486, "name": "Good Company" }, "responsible": { "id": 234, "name": "John Beam", "ext_num": "100" } }

donde

  • contact_type — tipo de contacto:
    • employee — empleado
  • id — identificador de empleado
  • name — nombre de empleado
  • phone — número de teléfono. Contiene los siguientes campos:
    • phone — solo número
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
  • position — cargo del empleado. Contiene los siguientes campos:
    • position — valor del cargo. Valores posibles:
      • ceo — director general
      • director — director
      • manager — agente
      • sales_manager — comercial
      • hr — RRHH
      • support — soporte
      • custom — otro
    • title — nombre del cargo propio (paraposition = custom)
  • customer — cliente al que se ha vinculado el empleado. Contiene los siguientes campos:
    • id — identificador de cliente
    • name — nombre de cliente
  • responsible — usuario responsable por el cliente matriz. Contiene los siguientes campos:
    • id — identificador de usuario
    • name — nombre de usuario
    • ext_num — extensión de la centralita del usuario

Lead

(Respuesta 3)

                                    Respuesta 3:
{ "contact_type": "lead", "id": 3486, "name": "Good Company", "phone": { "phone": "+44123456789", "type": "work" }, "responsible": { "id": 234, "name": "John Beam", "ext_num": "100" } }

donde

  • contact_type — tipo de contacto:
    • lead — lead
  • id — identificador de lead
  • name — nombre de lead
  • phone — número de teléfono. Contiene los siguientes campos:
    • phone — solo número
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
  • responsible — usuario responsable. Contiene los siguientes campos:
    • id — identificador de usuario
    • name — nombre de usuario
    • ext_num — extensión de la centralita del usuario

Usuario

(Respuesta 4)

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

donde

  • contact_type — tipo de contacto:
    • user — usuario
  • id — identificador de usuario
  • name — nombre de usuario
  • avatar — avatar de usuario (identificador de archivo)
  • role — rol de usuario
  • status — estado de usuario
  • phone — número de teléfono. Contiene los siguientes campos:
    • phone — solo número
    • type — tipo de número. Valores posibles:
      • work — de trabajo
      • personal — personal
      • internal — extensión de la centralita del usuario
  • group — grupo de usuario. Contiene los siguientes campos:
    • type — tipo de grupo. Valores posibles:
      • admin — administradores
      • manager — agentes
      • chat_operator — operadores
      • trainee — becarios
      • custom — personalizado
    • title — nombre de grupo personalizado (para type = custom)

Archivos

get /v1/zcrm/files/<file_id>

Devuelve el archivo por su ID

Información sobre las llamadas entrantes


El sistema Zadarma puede enviar información de cada llamada entrante a la centralita virtual y enviar las llamadas a la extensión necesaria en función de la respuesta. Para ello hay que crear un enlace abierto para acceso general que acepte las consultas POST con información desde el sistema de Zadarma.

NOTIFY_START

inicio de llamada entrante a la centralita virtual

Parámetros que se envían al enlace para las notificaciones:

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

Redacción de la firma de verificación para la notificación de llamadas entrantes, ejemplo en PHP:

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

Para las solicitudes NOTIFY_START y NOTIFY_IVR se puede modificar "sobre la marcha" el escenario de la llamada en curso, enviando como respuesta una de las siguientes alternativas:

Reproducir el archivo:

(Respuesta 1)

                                    Respuesta 1:
{ "ivr_play": "ID" }

donde,

  • ivr_play – valor de la columna ID en el listado de archivos cargados/insertados del archivo requerido.

Reproducir una frase popular:

(Respuesta 2)

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

donde,

  • ivr_saypopular – número de la frase del listado;

Reproducir cifras:

(Respuesta 3)

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

Reproducir el número (de acuerdo con las reglas numéricas complejas):

(Respuesta 4)

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

donde,

  • language puede tomar uno de los valores: ru, ua, en, es, pl;

Si se han indicado ivr_saydigits o ivr_saynumber, en el siguiente evento NOTIFY_IVR se añadirá el parámetro: "ivr_saydigits": "COMPLETE" o "ivr_saynumber": "COMPLETE"

En cada una de las solicitudes anteriores puede haber una solicitud de entrada de dígitos de la persona que llama:

(Respuesta 5)

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

donde,

  • timeout - tiempo de espera de entrada de dígitos en segundos;
  • attempts - número de intento de entrada de dígitos de la persona que llama;
  • maxdigits - número máximo de entrada de dígitos;
  • name - el nombre que se devolverá en la respuesta;
  • default - acción si no se ha escrito ningún dígito. Valores posibles:
    • id del escenario del desvío (en formato 0-1, donde 0 es el menú de voz, 1 es el número del escenario);
    • menú de la centralita virtual en formato 0-main, donde 0 es el id del menú;
    • extensión de la centralita virtual (número de 3 dígitos);
    • hangup - terminar la llamada.

En el siguiente evento NOTIFY_IVR se indicará el parámetro adicional:

(Respuesta 6)

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

donde,

  • name - nombre indicado en la anterior respuesta;
  • digits - dígitos introducidos por la persona que llama;
  • default_behaviour - indicado si el usuario no ha apretado ningún botón y ha funcionado el comportamiento por defecto;

Transferir la llamada:

(Respuesta 7)

                                    Respuesta 7:
{ "redirect": ID, "return_timeout": TIMEOUT (необязательное) }

donde,

  • redirect - id del escenario de desvío (en formato 0-1, donde 0 es el número del menú de voz, 1 es el número del escenario); o en formato 1 donde q es el escenario (número del menú de voz es 0 en este caso); o menú de la centralita virtual 0-main, donde 0 es el id del menú; o extensión de la centralita virtual (número de 3 dígitos); o "blacklist" - en este caso la llamada será rechazada con el tono de ocupado;
  • return_timeout - Valores en segundos. Posibles valores:
    • 0, la llamada no será devuelta al menú;
    • >= 3 - duración de la llamada antes de ser devuelta al menú;

Terminar la llamada:

(Respuesta 8)

                                    Respuesta 8:
{ "hangup": 1 }

En cada respuesta se puede indicar adicionalmente:

Establecer un nombre para el número entrante:

(Respuesta 9)

                                    Respuesta 9:
{ "caller_name": NAME }

donde,

  • caller_name - nombre del número.

Listado de frases populares:

  • Buenos días
  • Desvío de llamadas
  • Llamada desde la web
  • Bienvenidos
  • Mensaje de prueba
  • Permanezca en la línea
  • Ha llamado en horario no laboral
  • Todos nuestros operadores están ocupados. Le responderá el primer operador disponible.
  • Introduzca el número de extensión del abonado
  • Introduzca el número de extensión del operador
  • Introduzca el número de extensión
  • Por favor, permanezca a la espera
  • Introduzca el número de extensión o espere a ser atendido por un operador
  • Por favor, deje su mensaje
  • Deje su mensaje después de la señal
  • Por favor, vuelva a llamar en horario laboral
  • Gracias por contactar con nosotros.
  • Gracias por su llamada.
  • Espere a ser atendido por un operador
  • Su llamada es muy importante para nosotros
  • La llamada está siendo grabada
  • En estos momentos no estamos en la oficina
  • le devolveremos la llamada a la mayor brevedad posible.
  • Estamos de día de descanso.
  • Hola!

NOTIFY_INTERNAL

inicio de llamada entrante a la extensión de la centralita virtual

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

  • event – evento (NOTIFY_INTERNAL)
  • call_start – duración del inicio 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) extensión.

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

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

NOTIFY_ANSWER

respuesta de llamada al número interno o externo

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 inicio de la llamada;
  • pbx_call_id – id звонка;
  • internal – (opcional) extensión.

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

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

NOTIFY_END

fin de llamada entrante a la extensión de la centralita virtual

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

  • event – evento (NOTIFY_END)
  • 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 al que se realiza la llamada;
  • internal – (opcional) 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 líneas,
    • 'no money, no limit' - se ha superado el límite;
  • last_internal – extensión, último partícipe de la llamada (después de la transferencia o recogida de llamada);
  • 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 puesto que se requiere tiempo para guardar el archivo).

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

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

NOTIFY_OUT_START

inicio de llamada saliente desde la centralita virtual

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;
  • caller_id – número establecido en la extensión de la centralita virtual o en la regla de determinación en función del destino. Si el número no está establecido se se transmite 0;
  • internal – (opcional) número de extensión.

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

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

NOTIFY_OUT_END

fin de llamada salientes desde la centralita virtual

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 establecido en la extensión de la centralita virtual o en la regla de determinación en función del destino. Si el número no está establecido se se transmite 0;
  • destination – número al que se realiza la llamada;
  • internal – (opcional) 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' - 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 las 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 (recomendamos cargar el archivo de la grabación no antes de 40 segundos después de la notificación puesto que se requiere tiempo para guardar el archivo).

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

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

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_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 centralita virtual (no cambia al pasar de escenarios, menú de voz, transferencia, etc., se muestra en estadísticas y notificaciones).

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

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

NOTIFY_IVR

respuesta de la persona que llama a la acción asignada

Parámetros que se envían al enlace de notificaciones:

  • event – evento (NOTIFY_IVR)
  • call_start – hora inicio de la llamada;
  • pbx_call_id – id de la llamada;
  • caller_id – número del llamante;
  • called_did – número al que se ha llamado.

Redacción de la firma de verificación para la notificación de llamadas entrantes, ejemplo en PHP:

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

Las posibles respuestas enviadas son similares a las respuestas de las solicitudes NOTIFY_START

SPEECH_RECOGNITION

resultado de reconocimiento de voz

Parámetros que se envían al enlace de notificaciones:

  • event – evento (SPEECH_RECOGNITION)
  • lang – idioma;
  • result:
    • words - conjunto:
      • result - conjunto de palabras (conjunto):
        • s - hora inicio de palabra
        • e - hora fin de palabra
        • w - palabra
      • channel - número de canal
    • phrases - conjunto:
      • result - frase
      • channel - número de canal

Ejemplo en PHP:

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

Para aumentar la seguridad recomendamos permitir el acceso a tu enlace únicamente desde la dirección IP 185.45.152.42.

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

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

Otras notificaciones


Parámetro "result" estas notificaciones emplean el formato JSON. Puede recibirlas en formato XML indicando en el enlace el parámetro format=xml.

NUMBER_LOOKUP

informe sobre verificación de números

Parámetros enviados al enlace para las notificaciones:

  • event – evento (NUMBER_LOOKUP)
  • success – indicador de éxito de validación;
  • description – descripción del estado de finalización de la validación;
  • result – datos del informe;
    • number – número comprobado;
    • mcc – prefijo móvil del país;
    • mnc – prefijo del operador móvil;
    • ported – indicador de transferencia a otro operador;
    • roaming – indicador de estar en roaming;
    • error – estado del error;
    • errorDescription – descripción del error;
    • mccName – nombre del país;
    • mncName – nombre del operado;

Redacción de la suscripción de verificación:

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

CALL_TRACKING

información sobre llamadas a los números conectados en call tracking

Se envía una vez cada 15 minutos si hay nuevas llamadas.

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

  • event – evento (CALL_TRACKING)
  • result - área
    • tracker - ID del tracker (se puede averiguar en la página donde se inserta el código);
    • start - hora de inicio de la llamada;
    • duration - duración de la llamada en segundos;
    • caller_id - número del llamante;
    • caller_did - número al que se ha llamado;
    • country - (opcional) país desde el que se realiza la llamada;
    • ga_id - (opcional, si en los ajustes está indicado Id Google Analytics) id del visitante en Google Analytics;
    • metrika_id - (opcional, si en los ajustes está indicado Id Yandex.Metrika) id del visitante en Yandex.Metrika;
    • url - dirección de la página desde la que se realizó la llamada;
    • utm_source, utm_medium, utm_campaign, utm_term, utm_content - (opcional, si al visitar el sitio web estaban indicadas las etiquetas utm) etiquetas utm a través de las cuales ha llegado el usuario a la web la última vez;
  • first_utm - (opcional, si al visitar por primera vez el sitio web estaban indicadas las etiquetas utm diferentes a las que se ha visitado por última vez) matriz con las etiquetas utm indicadas más arriba a través de las cuales el usuario ha visitado la web por primera vez;

Redacción de la suscripción de verificación:

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

SMS

información sobre SMS recibidos

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

  • event – evento (SMS)
  • result – área;
  • caller_id – número del remitente;
  • caller_did – número del destinatario;
  • text – texto del mensasje.

Redacción de la suscripción de verificación:

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