Saltar a contenido

Introducción

General

La API REST permite a los clientes de VoIPstudio acceder gran parte de los recursos. Nuestra API tiene predicción de URL, orientadas a recursos y utiliza códigos de respuesta HTTP para indicar errores de API. Utilizamos funciones HTTP integradas, como la autenticación HTTP y los HTTP verbs, que son entendidos por los clientes HTTP disponibles en el mercado. Admitimos el intercambio de recursos de origen cruzado(cross-origin resource sharing), lo que le permite interactuar de forma segura con nuestra API desde una aplicación web del lado del cliente. Todas las respuestas de la API son devueltas en JSON, incluidos los errores.

Endpoints

La URL base para la API id:

https://l7api.com/v1.1/voipstudio/

Autenticación

La comunicación entre la aplicación de cliente y la API de VoIPstudio es segura gracias a HTTP basic authentication sobre SSL.

Antes de poder mandar peticiones a la API es necesario logarse con un email y una contraseña o mediante una API Key que se utiliza para la autorización. Después de una auntenticación correcta la API devolverá un identificador de usuario único user_id y un user_token que deberán se utilizados para entrar.

E-mail y Contraseña

Solicitud de acceso usando email y contraseña:

  curl -H "Content-Type: application/json" -X POST -d '{"email":"jsmith@example.com","password":"$ecretPas$$"}' https://l7api.com/v1.1/voipstudio/login

Solicitud de ejemplo:

POST /v1.1/voipstudio/login HTTP/1.1
User-Agent: curl/7.26.0
Host: l7api.com
Accept: */*
Content-Type: application/json
Content-Length: 55
Connection: close
{"email":"jsmith@example.com","password":"$ecretPas$$"}

Ejemplo de respuesta exitosa:

  {
"message":"Login success",
"user_token":"8e9bc12575e639c993ba5dd8a0e7ce2250211b9a",
"user_id":123456
}

REST API Key

Para autenticar a un usuario con API Key no es necesario iniciar sesión. La 'clave de API' deberá agregarse para este usuario en la sección de la pestaña Avanzado del usuario (ver: https://voipstudio.mx/app/#manual.administrator.users.edit).

Esta API Key se debe usar en lugar de user_token durante el proceso de inicio de sesión.

Comunicación

La autenticación a la API se realiza a través de HTTP Basic Auth. Este tipo de autenticación debe ser una operación directa en el lenguaje que está usando. Se espera que las solicitudes entrantes manejadas por nuestra API tengan un encabezado especial con un valor codificado en base64 creado a partir de user_id y user_token devuelto por una respuesta de "inicio de sesión" exitosa, o user_id y creado API Key. Para obtener este valor base64, codifique su user_id y user_token separados por punto y coma.

La cabecera de Authorization se espera en el siguiente formato:

Authorization: Basic base64('user_id:user_token')

o 

Authorization: Basic base64('user_id:API_Key')

Ejemplo de petición de autenticación::

curl -H "Content-Type: application/json" -H "Authorization: Basic base64('user_id:user_token')"  https://l7api.com/v1.1/voipstudio/cdrs

o

curl -H "Content-Type: application/json" -H "Authorization: Basic base64('user_id:API_Key')"  https://l7api.com/v1.1/voipstudio/cdrs

o simplemente:

curl -u user_id:user_token -H "Content-Type: application/json" https://l7api.com/v1.1/voipstudio/cdrs

o

curl -u user_id:API_Key -H "Content-Type: application/json" https://l7api.com/v1.1/voipstudio/cdrs

HTTP responses

VoIPstudio REST API usa códigos de respuesta HTTP convencionales para indicar el éxito o el fracaso de una solicitud de API. En general, los códigos en el rango 2xx indican éxito, los códigos en el rango 4xx indican un error que ha fallado dada la información proporcionada (por ejemplo, se omitió un parámetro requerido, etc.) y los códigos en el rango 5xx indican un error del servidor.

Cada respuesta exitosa, según el método HTTP, contiene las siguientes propiedades:

  • GET collection of resources:

    • data - an array of resources data
    • total - total number of resources

  • GET single resource:

    • data - resources data
    • links - links to related resources

Cada respuesta de error contiene las siguientes propiedades:

* `message` - mensaje de error genérico
* `errors` - array of error messages

Buscador y filtros

Para puntos finales de recopilación de datos, como GET https://l7api.com/v1.1/voipstudio/cdrs el buscador se puede utilizar para devolver un número específico de registros de una página determinada en el conjunto de datos. Para aplicar el buscador, añada los siguientes parámetros a la URL ?page=N&limit=Z donde N es el numero de página y Z el número de entradas a devolver(máximo 5000).

Para filtrar los datos, el parámetro filter se puede pasar como una cadena en la query URL. El valor del parámetro filter debe ser cadena codificada JSON en el formato que se muestra a continuación:

[
{"operator":"like","value":"United States","property":"name"},
{"operator":"eq","value":10,"property":"price"}
]

Agrupar entradas

El parámetro group_by está disponible para agrupar registros por propiedad específica : `GET https://l7api.com/v1.1/voipstudio/cdrs?group_by=src. Este parámetro se debe pasar como cadena en la query URL.