curl

Introducción


API Endpoint

/api.voze.es

Esta API está organizada usando el patrón REST. Es una API con URLs orientadas a recursos y que usa códigos de respuesta HTTP para indicar errores. Se usan los verbos HTTP, entendidos por defecto por todos los clientes HTTP. Soporta cross-origin resource sharing, permitiendo interactuar con la API desde cualquier cliente web o móvil. Cada respuesta de la API devuelve un JSON, incluyendo el tipo de error o los datos de la misma.

 Funcionamiento

Voze permite la integración de su sistema vía API. Esto quiere decir que usted (proveedor) podrá conocer cada una de las extensiones (ver sección de extensiones) de nuestra centralita para que pueda realizar interpretaciones a alguno de los idiomas que tenemos disponibles (actualmente más de 10).

A usted como proveedor le asignamos un número virtual único, al cual sus usuarios podrán llamar desde cualquier teléfono móvil o fijo. Y usted se preguntará, ¿y si cualquiera puede llamar, cómo podré controlar que clientes de otros proveedores no llamen a mi número virtual? Para ello, Voze dispone de filtros de llamada (361) 226-3256. Por defecto, usted establecerá qué teléfonos de sus clientes podrán llamar a su número virtual. Cualquier otro teléfono que no esté definido en esos filtros, cuando intente llamar automáticamente dará comunicando.

A través de un Webhook (ver sección webhook), usted podrá recibir en su servidor los avisos de cuando una llamada entrante a su número virtual finaliza. Si por el contrario, no desea conocerlo al instante, disponemos de una petición de consumo 313-545-4682, donde cuando usted lo desee podrá consultar todas las llamadas que ha recibido.

Dado que nosotros no tenemos acceso a los datos de sus clientes, usted debe ser el encargado de gestionar los cargos de la llamada (si lo desea) a su cliente. Nuestro departamento de facturación a final de mes le cobrará a usted el importe de cada una de las llamadas recibidas en su número virtual según nuestra política de precios.

 Ejemplo de uso

Este ejemplo ilustra cómo sería la integración con Voze para que un usuario pueda llamar a una extensión de Voze a través del número virtual de un proveedor.

 Pasos a seguir

  1. Configuración de webhook (OPCIONAL). Esto es requerido únicamente si desea ser notificado tras la finalización de una llamada vía HTTP POST a una URL que usted configure.
  2. Listado de extensiones disponibles. Para saber a qué extensiones pueden llamar sus usuarios.
  3. API responde con un un listado de extensiones. Cada una de ellas tiene disponible un teléfono al que sus usuarios podrán llamar.
  4. El usuario X, con teléfono Y, notifica que desea llamar a la extensión de inglés en su sistema. Para que pueda realizar la llamada, usted previamente tendrá que añadir un filtro con el nº de teléfono Y del usuario. Si no lo añade, éste no podrá llamar. Debe controlar los filtros porque como máximo dispondrá de 250.
  5. Añadir filtro con el nº de teléfono del usuario.
  6. API responde creando el filtro.
  7. El usuario llama a la extensión. Una vez que ya se dispone de un filtro de llamada para ese teléfono, el usuario ya puede realizar la llamada al teléfono que indica la extensión seleccionada. Será del tipo númerovirtual:extensión.
  8. Si usted ha configurado una URL de webhook, le enviaremos una señal indicando que la llamada del usuario X ha finalizado correctamente. También puede realizar usted mismo la petición a Voze para codist que han llegado a su número virtual.
  9. Tras la finalización de la llamada, usted involvement.
  10. API responde eliminando el filtro.
  11. Si lo desea puede notificar al usuario de que ha finalizado la llamada y realizar las acciones que crea conveniente (ejemplo: cargarle en su tarjeta de crédito el importe de la llamada, enviar notificación push interna, etc.).

Autenticación

# Autenticación vía API Key.
curl '/api.voze.es/{api_endpoint}' \
  -H 'x-api-key: {key}'

Asegúrese de reemplazar key con tu API key de desarrollador.

Puedes autenticarte con tu cuenta cuando usas la API incluyendo tu API key secreta en la cabecera de la petición. Para conseguir un API key de desarrollador debes hablar con nuestro departamento de ventas vía email o por teléfono. Decir que un API key conlleva la obtención de acceso a diferentes partes del sistema de Voze, por lo que te aconsejamos que la mantengas segura y en secreto. No la compartas en zonas públicas, como podrían ser Github, códigos en clientes y demás.

Para autenticarte vía API key, debes enviar lo siguiente en la cabecera de la petición

-H "x-api-key: test_BQokikJOvBiI2HlWgH4olfQ2"

Errores

Esta API usa los códigos de respuesta del protocolo HTTP para indicar cuando ha sido una respuesta exitosa o fallida. Por lo general, los códigos 2xx indican éxito, los códigos 4xx indican que ha habido un error (ej. parámetros requeridos, operación fallida, etc.), y los códigos 5xx indican un error con los servidores que gestionan la API.

 HTTP Status codes

Código Título Descripción
200 OK La petición fue exitosa.
201  Creado  Un recurso fue creado correctamente.
202 Creado asínc.  Un recurso fue creado asíncronamente.
400 Petición incorrecta Petición errónea.
401  No autorizada  La API key enviada no es válida.
404  No encontrado Este recurso no se encuentra.
422  Error de validación Ha ocurrido un error de validación.
50X Interno Error interno a nivel de servidor.

 Tipos de error

Ejemplo de respuesta de error.

{
  "error": {
    "type": "params_invalid",
    "message": "Name is required"
  }
}

Todos los errores son devueltos en formato JSON con un tipo y con un mensaje opcional. Este mensaje y este tipo vienen en inglés.

Tipo Descripción
params_invalid Parámetros no válidos.
not_found Recurso no encontrado.
unknown_route URL no encontrada.
queued Se ha puesto en cola. Intenta la petición más tarde.
rate_limit Se ha limitado la petición.
api_error API Error interno.

Webhooks

curl "/api.voze.es/webhook" \
  -H "x-api-key: {key}" \
  -X POST \
  -d "{ 'webhook_url': '/www.yourdomain.com/webhook_url' }"

Respuesta JSON estructurada de la siguiente forma:

{
  "webhook_url": "/www.yourdomain.com/webhook_url"
}

Algunas peticiones pueden requerir respuestas asíncronas del servidor (algunas tienen procesos complejos que tienen que hacerse en segundo plano). Para estas peticiones, lo normal es usar una URL de aviso donde enviemos la respuesta al finalizar la petición.

Para los proveedores, la URL de Webhook se tiene que definir si desean recibir una notificación cuando se finalice una llamada telefónica perteneciente a dicho proveedor (llamada entrante a su número virtual). Enviaremos los datos en formato JSON, y en caso de recibir un código diferente a HTTP 2XX, seguiremos intentándolo un máximo de 5 veces en intervalos de tiempo crecientes.

Petición HTTP

POST /api.voze.es/webhook o también PUT /api.voze.es/webhook

Parámetros de la petición

Parámetro Descripción
webhook_url String URL de su server donde quiere que le avisemos tras finalizar una llamada recibida a su número virtual.

Extensiones

Listado de extensiones

Este endpoint devuelve una lista de extensiones a las que usted (o sus clientes) podrá llamar.

curl "/api.voze.es/extensions" \
  -H "x-api-key: {key}"

Respuesta JSON estructurada de la siguiente forma:

{
  "pagination": {
    "current": 1,
    "next": null,
    "previous": null,
    "first_page": true,
    "last_page": true,
    "total_pages": 1,
    "total_items": 1
  },
  "data": [
    {
      "ext_code": 11,
      "phone": "911033338:11",
      "language_from": {
        "title_es": "Español",
        "title_de": "Spanisch",
        "title_ar": "الأسبانية",
        "title_zh": "西班牙語",
        "title_fr": "Espagnol",
        "title_en": "Spanish",
        "title_it": "Spagnolo",
        "title_ru": "испанский",
        "title_pt": "Espanhol",
        "title_ro": "Spaniolă",
        "country_code": "es",
        "image": {
          "square_url": "/assets.voze.es/languages/images/000/000/001/square-a12.png?1474391622"
        }
      },
      "language_to": {
        "title_es": "Alemán",
        "title_de": "Deutsch",
        "title_ar": "ألماني",
        "title_zh": "德國",
        "title_fr": "Allemand",
        "title_en": "German",
        "title_it": "Tedesco",
        "title_ru": "немецкий",
        "title_pt": "Alemão",
        "title_ro": "Germană",
        "country_code": "de",
        "image": {
          "square_url": "/assets.voze.es/languages/images/000/000/004/square-a6.png?1474391628"
        }
      }
    }
  ]
}

Petición HTTP

GET /api.voze.es/extensions

Objeto de la respuesta

Campo Descripción
ext_code Integer Código único de extensión
phone  String Teléfono asignado a usted donde podrá llamar para hablar con un intérprete de esa extensión.
language_from Object Idioma origen
language_to Object Idioma destino
title_es  String Título en español
title_de String Título en alemán
title_ar String Título en árabe
title_zh String Título en chino
title_fr String Título en francés
title_en  String Título en inglés
title_it String Título en italiano
title_ru  String Título en ruso
title_pt  String Título en portugués
title_ro  String Título en rumano
country_code String Código de país para ese idioma
image Object Imagen que representa la bandera del idioma
square_url String Imagen en formato cuadrado
Tal y como mencionamos en el funcionamiento de la API, antes de poder realizar una llamada al teléfono de la extensión, debes añadir un filtro con el teléfono de tu cliente. Ver la sección de filtros.

Consumo

Listado de llamadas

Este endpoint devuelve el listado de llamadas recibidas por ese proveedor, es decir, las llamadas entrantes al número virtual asignado al proveedor.

curl "/api.voze.es/calls" \
  -H "x-api-key: {key}"

Respuesta JSON estructurada de la siguiente forma:

{
  "pagination": {
    "current": 1,
    "next": null,
    "previous": null,
    "first_page": true,
    "last_page": true,
    "total_pages": 1,
    "total_items": 1
  },
  "data": [
    {
      "id": 12,
      "notified_at": "2016-09-14 15:08:43+0200",
      "started_at": "2016-09-14 15:08:22+0200",
      "missed": false,
      "daily": true,
      "caller": "610203050",
      "called": "911013338",
      "duration": {
        "seconds": 3,
        "formatted": "00:03"
      },
      "billing": {
        "minutes_billed": 0,
        "price": 0
      },
      "user_rating": 0,
      "helpful": 0
    }
  ]
}

Petición HTTP

GET /api.voze.es/calls

Objeto de la respuesta

Campo Descripción
ID Integer Identificador de llamada.
notified_at  DateTime Fecha cuando se recibió notificación de finalización de llamada en nuestra centralita.
started_at DateTime Fecha cuando comenzó la llamada.
missed Boolean Devuelve true o false si ha sido llamada perdida o no.
daily  Boolean Devuelve true o false si es una llamada de día.
caller String Teléfono del llamante.
called String Teléfono del llamado (generalmente su número virtual).
duration Object Duración de la llamada (en distintos formatos).
billing Object Información sobre facturación de la llamada.
user_rating  Integer Valoración de llamada por el usuario (de 1 a 5 y de muy malo a muy bueno). Por defecto es 0, debido a que nadie ha valorado la llamada aún.
helpful Integer Valoración de si le ha ayudado la interpretación (0 es un no, 1 es un sí).

Ver detalle de llamada

Este endpoint devuelve los detalles de una llamada.

curl "/api.voze.es/calls/12" \
  -H "x-api-key: {key}"

Respuesta JSON estructurada de la siguiente forma:

{
  "data": {
    "id": 12,
    "notified_at": "2016-09-14 15:08:43+0200",
    "started_at": "2016-09-14 15:08:22+0200",
    "missed": false,
    "daily": true,
    "caller": null,
    "called": "911013338",
    "duration": {
      "seconds": 3,
      "formatted": "00:03"
    },
    "billing": {
      "minutes_billed": 0,
      "price": 0
    },
    "user_rating": 0,
    "helpful": 0
  }
}

Petición HTTP

GET /api.voze.es/calls/<ID>

Parámetros de la petición

Parámetro Descripción
ID Integer Identificador de llamada

Valorar una llamada

Usted podrá hacer que sus usuarios valoren la llamada que ha finalizado. Este endpoint se usa para ello.

curl "/api.voze.es/calls/12/rate" \
  -H "x-api-key: {key}"
  -X POST
  -d "{ 'call': { 'user_rating': 5, 'helpful': 1 } }"

Petición HTTP

POST /api.voze.es/calls/<ID>/rate

Parámetros de la petición

Parámetro Descripción
ID Integer Identificador de llamada.
call  Object Objeto con los campos de valoración.
user_rating  Integer Valor de valoración de usuario (1 es muy mala y 5 muy buena).
helpful  Integer Si ha servido de ayuda la interpretación (0 es no y 1 es sí).

 Respuesta

Si la valoración se recibe correctamente, se devuelve HTTP 201 creado correctamente..

Filtros

Cada uno de los teléfonos que aparecen en el listado de filtros, serán los teléfonos que podrán realizar una llamada al número virtual del proveedor. Como máximo, se almacenarán 250 por número virtual.

Recomendamos que si tienes un volumen de usuarios alto, cuando tu usuario quiera realizar una llamada, añadas un filtro con su teléfono. Y al finalizar la llamada, lo elimines.

Listado de filtros

Este endpoint devuelve un listado de filtros aplicados al número virtual del proveedor.

curl "/api.voze.es/filters" \
  -H "x-api-key: {key}"

Respuesta JSON estructurada de la siguiente forma:

{
  "pagination": {
    "current": 1,
    "next": null,
    "previous": null,
    "first_page": true,
    "last_page": true,
    "total_pages": 1,
    "total_items": 2
  },
  "data": [
    {
      "id": 1,
      "phone": "610203040",
      "comment": "Rainieri Santos",
      "created_at": "2016-10-04 11:27:06+0200",
      "virtual_number": "911033338"
    },
    {
      "id": 2,
      "phone": "611213141",
      "comment": "Juan Marcos",
      "created_at": "2016-10-04 11:27:37+0200",
      "virtual_number": "911033338"
    }
  ]
}

Petición HTTP

GET /api.voze.es/filters/

Objecto de la respuesta

Campo Descripción
ID  Integer Identificador de filtro
phone String Teléfono de tu usuario
comment  String Comentario asociado a tu usuario.
created_at  DateTime Fecha cuando fue aplicado el filtro.
virtual_number  String Número virtual asociado al filtro.

 Añadir un filtro

curl "/api.voze.es/filters" \
  -H "x-api-key: {key}"
  -X POST \
  -d "{ 'call_filter': { 'phone': '610203040', 'comment': '2053' } }"

Este endpoint añade un filtro de llamada para este proveedor.

 Petición HTTP

POST /api.voze.es/filters

Parámetros de la petición

Parámetro Descripción
call_filter  Object Objeto con los campos del filtro.
phone  String Teléfono que podrá llamar a su número virtual al crear el filtro.
comment  String Comentario asociado al filtro. Puede guardar si lo desea el ID del usuario o cualquier otro dato.

 Respuesta

Si la respuesta es exitosa, se devuelve HTTP 201 Creado correctamente.

Eliminar un filtro

Este endpoint elimina un filtro de llamada para este proveedor.

curl "/api.voze.es/filters/<ID>" \
  -H "x-api-key: {key}"
  -X DELETE

Petición HTTP

DELETE /api.voze.es/filters/<ID>

 Respuesta

Si la respuesta es exitosa, se devuelve HTTP 200 Ok.

Eliminar todos los filtros

Este endpoint elimina todos los filtros aplicados al número virtual del proveedor. Esto hará que ningún teléfono pueda llamar a este número virtual.

curl "/api.voze.es/filters/destroy_all" \
  -H "x-api-key: {key}"
  -X DELETE

Petición HTTP

DELETE /api.voze.es/filters/destroy_all

 Respuesta

Si la respuesta es exitosa, se devuelve HTTP 200 Ok.