Saltar a contenido

Introducción

Aquí encontrará la descripción de la API VoIPstudio, que da acceso a todos los recursos de la plataforma.

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 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 es:

https://l7api.com/v1.2/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 de VoIPstudio es necesario obtener la API Key o user_token que será utilizado para autenticar las peticiones.

Puede generar API Key / user_token de las dos maneras siguientes:

  1. Envíe una solicitud POST al punto final /login con el correo electrónico y la contraseña como credenciales.
  2. Utilice el panel de administrador de VoIPstudio para crear API Key / user_token.

Consulte las instrucciones detalladas a continuación:

E-mail y Contraseña

Solicitud de acceso usando email y contraseña:

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

Solicitud de ejemplo:

POST /v1.2/voipstudio/login HTTP/1.1
Host: l7api.com
Content-Type: application/json
{"email":"jsmith@example.com","password":"$ecretPas$$"}

Ejemplo de respuesta exitosa:

{
    "message":"Login success",
    "user_token":"123456abc993ba5dd8a0e7ce9876543",
    "user_id":123456
}

Por defecto el user_token expirará a los 30 minutos de inactividad. Cada vez que se hace una peticón a la API el contador se reinicia.

Si requiere un tiempo de expiración mayor, una vez obtenido el user_token inicial con la llamada API POST /login, puede crear nuevas calves API con la llamada POST /apitokens:

curl -X POST -H "Content-Type: application/json" \
     -H "X-Auth-Token: 123456abc993ba5dd8a0e7ce9876543" \
     https://l7api.com/v1.2/voipstudio/apitokens \
     -d '{"name":"Example API App","expiry":604800}'

Ejemplo de respuesta exitosa:

{
    "data":{
        "user_id":123456,
        "token":"9843211cb48787655cddb080ebdabced",
        "customer_id":521156,
        "name":"Example API App",
        "host":"8.8.8.8",
        "user_agent":"curl/7.58.0",
        "expiry":604800,
        "last_request_at":null,
        "created_at":"2023-02-09 17:20:01"
    },
    "links":{}
}

Nota: para crear claves API que no expiren utilice "expiry":0 en el payload del POST /apitokens

Obtener claves API desde el panel de administración web

Siga los pasos que se indican a continuación para añadir una clave API a un usuario:

  1. En el panel de administración, edite el usuario para el que desea añadir claves de API.
  2. Vaya a la sección API Keys.
  3. Introduzca un nombre para su API Key, puede ser cualquier cosa que desee. Por ejemplo, el nombre de la aplicación que utilizará esta Clave API.
  4. Haga clic en el botón "Añadir".
  5. Haga clic en el icono "Ojo" para recuperar la clave de API / user_token.
  6. Haga clic en el icono "Engranaje" y seleccione "Mostrar detalles" para obtener detalles adicionales o eliminar la clave de API.

api-key-add.png

Figure 1.1 Add API Key.

Comunicación

Se espera que las solicitudes entrantes gestionadas por nuestra API tengan un encabezado X-Auth-Token con un valor user_token (clave de API) devuelto por una respuesta POST /login o POST /apitokens correcta. 

X-Auth-Token: TOKEN

Example of authenticated request:

curl -H "Content-Type: application/json"
     -H "X-Auth-Token: 123abc45678def3234sdfgdf3434df3444" \
     https://l7api.com/v1.2/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

Páginador

Para puntos finales de recopilación de datos, como GET https://l7api.com/v1.2/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).

Filtros

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:

[
   {"property":"_PROPERTY_NAME_","operator":"_OPERATOR_","value":"_SEARCH_VALUE_"},
   {"property":"_PROPERTY_NAME_","operator":"_OPERATOR_","value":"_SEARCH_VALUE_"}
   ...
]

Los tokens anterionres _PROPERTY_NAME_, _OPERATOR_ y _VALUE_TO_SEARCH_ se deben interpretar como se muestra:

  • _PROPERTY_NAME_ puede ser cualquier propiedad del objeto. Consulte la sección "Recursos" a continuación para obtener una explicación detallada del modelo de datos para cada punto final.

  • _OPERATOR_ puede ser::

    • eq o = al buscar registros con valor de "propiedad" igual a _SEARCH_VALUE_
    • ne, neq, <> o != al buscar registros con valor de "propiedad" NO igual a _SEARCH_VALUE_
    • lt o < al buscar registros con valor de "propiedad" inferior a _SEARCH_VALUE_. _SEARCH_VALUE_
    • lte o <= cuando se buscan registros con valor de "propiedad" inferior o igual. _SEARCH_VALUE_
    • gt o > al buscar registros con valor de "propiedad" mayor que. _SEARCH_VALUE_
    • gte o >= al buscar registros con valor de "propiedad" mayor o igual. _SEARCH_VALUE_
    • in al buscar registros con valor de "propiedad" incluida en _SEARCH_VALUE_ (Nota: el valor de búsqueda debe pasarse como una matriz, por ejemplo: ["foo", "bar" ])
    • like al buscar registros con valor de "propiedad" patrón de coincidencia de _SEARCH_VALUE_
    • notlike cuando se buscan registros cuyo valor de "propiedad" NO coincide con el patrón de _SEARCH_VALUE_

  • _SEARCH_VALUE_ el valor que desea buscar

Ejemplo de solicitud al punto final /cdrs en busca de llamadas entrantes (la propiedad dst_id es igual al Id de usuario) al Id de usuario 123456 después del 1 de septiembre de 2018:

curl -H "X-Auth-Tokeb: TOKEN" -H "Content-Type: application/json"
     'https://l7api.com/v1.2/voipstudio/cdrs?filter=[
       {"property":"dst_id","operator":"eq","value":"123456"},
       {"property":"calldate","operator":"gt","value":"2018-09-01 00:00:00"}
     ]'

Agrupar entradas

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