Ir para o conteúdo

Introdução

Aqui são descritas as funções do VoIPstudio API, que lhe dará acesso a todos os recursos básicos do VoIPstudio.

Geral

O REST API permite a clientes do VoIPstudio acesso a uma vasta gama de recursos. Nossa API tem URLs previsíveis e orientadas a recursos, e usa códigos de resposta HTTP para indicar erros de API. Usamos recursos built-in de HTTP, como autenticação HTTP e HTTP verbs, que são facilmente entendidos por clientes HTTP. Nós suportamos compartilhamento de recursos de cross-origin, permitindo a interação de forma segura com nossa API a partir de uma aplicação web do lado do cliente. JSON é retornado por todas as respostas da API, incluindo erros.

Terminais

The base URL for the API id:

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

Autenticação

Para comunicações seguras, pode criar uma chave API para ser usada para a Autorização de API.

As comunicações entre as aplicações do cliente e o VoIPstudio's API são asseguradas através de HTTP basic authentication por SSL.

Antes de enviar pedidos para a API deve primeiro fazer o login utilizando seu endereço de e-mail e palavra-passe ou criar uma API Key para ser utilizada para a autorização. Após a autenticação bem sucedida a API irá retornar um único user_id e user_token que deve ser utilizado para o login.

E-mail e Palavra-passe

Pedido de login usando e-mail e palavra-passe:

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

Exemplo de solicitação:

POST /v1.2/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$$"}

Exemplo de resposta bem sucedida:

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

Chave REST API

Siga os passos abaixo para adicionar a chave API para um usuário. Uma vez que a API Key é criada, não há necessidade de fazer outra vez o login com e-mail / palavra-passe.

  1. Entre no painel de administração.
  2. Abra a grelha de utilizadores.
  3. Clique no ícone "Editar" na coluna direita.
  4. Abra o separador "Avançado".
  5. Insira um nome à sua escolha da sua chave API. Por exemplo, o nome da aplicação que irá utilizar esta Chave de API.
  6. Clique em "Add" (Adicionar).
  7. Clique no ícone "Wrench" e selecione "Show Details" para visualizar a "API Key" real gerada.

api-key-add.png

Figure 1.1 Add API Key.

Fazer solicitações

A autenticação para a API é realizada via HTTP Basic Auth. Este tipo de autenticação deve ser uma operação simples na maioria das linguagens de programação populares. As requisições recebidas tratadas pela nossa API devem ter um cabeçalho Authorization com um valor codificado base64 construído a partir de user_id e user_token retornado a partir de uma resposta de "login" bem sucedida, ou user_id e criado API Key. Para obter o valor base64 de Authorization, a Base64 codifica seu user_id e user_token separados por dois-pontos.

O cabeçalho Authorization é esperado no formato abaixo:

Authorization: Basic base64('user_id:user_token')

ou

Authorization: Basic base64('user_id:API_Key')

Exemplo de pedido autenticado:

using user_token returned by POST /login

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

ou usando API_Key

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

ou forma abreviada usando o parâmetro curl -u, --user <user:password>:

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

ou usando API_Key

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

Respostas HTTP

VoIPstudio API REST usa códigos de resposta HTTP convencionais para indicar o sucesso ou o fracasso de uma solicitação de API. Em geral, os códigos no intervalo 2xx indicam sucesso, os códigos no intervalo 4xx indicam um erro que falhou, dada a informação fornecida (por exemplo, um parâmetro requerido foi omitido, etc.), e os códigos no intervalo 5xx indicam um erro do servidor.

Cada resposta bem sucedida, dependendo do método HTTP, contém as seguintes propriedades:

  • GET Recolha de recursos:

    • data - um conjunto de dados de recursos
    • total - número total de recursos

  • GET recurso simples:

    • data - resources data
    • links - links para recursos relacionados

Cada resposta de erro contém as seguintes propriedades:

* `message` - mensagem de erro geral
* `errors` - uma série de mensagens de erro

Pager

Para pontos finais de recolha de dados, tais como a página 'GET https://l7api.com/v1.2/voipstudio/cdrs' pode ser utilizada para devolver um número específico de registos de uma determinada página do conjunto de dados. Para aplicar o pager, por favor anexe os seguintes parâmetros à URL ?page=N&limit=Z onde N é um número de página e Z é o número de registos a serem retornados (máximo 5000).

Filtros

Para filtrar dados, o parâmetro filtro pode ser passado como uma cadeia de consulta URL. O valor do parâmetro filtro tem que ser uma string codificada JSON no formato mostrado abaixo:

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

Os três tokens acima de _PROPERTY_NAME_,_OPERATOR_ e _VALUE_TO_SEARCH_ devem ser interpretados da seguinte forma:

  • _PROPERTY_NAME_ esta pode ser qualquer propriedade que pertença a determinado objeto endpoint. Veja a seção "Recursos" abaixo para uma explicação detalhada do modelo de dados para cada endpoint.

  • _OPERATOR_ pode ser um de:

    • eq ou = ao procurar registos com valor de "propriedade" igual a _SEARCH_VALUE_
    • ne, neq, <> ou != quando se procura registos com valor de "propriedade" NÃO é igual* a _SEARCH_VALUE_
    • lt ou < ao procurar registos com valor de "propriedade" menos que _SEARCH_VALUE_
    • lte ou <= quando se procura registos com valor de "propriedade" inexistente ou igual `SEARCH_VALUE``
    • gt ou > ao procurar registos com valor de "propriedade" mais que _SEARCH_VALUE_
    • gte ou >= quando se procura registos com valor de "propriedade" mais ou iguais _SEARCH_VALUE_
    • in quando se procura registos com valor de "propriedade" incluído em _SEARCH_VALUE_`` (Nota: o valor da busca precisa ser passado como um array, por exemplo:["foo", "bar" ]`)
    • "como" ao procurar registos com valor de "propriedade" matching pattern* de `SEARCH_VALUE``.
    • notlike quando se procura registos com valor de "propriedade" NÃO corresponde ao padrão de _SEARCH_VALUE_.

  • _SEARCH_VALUE_ o valor que quer pesquisar

Exemplo de solicitação para o endpoint /cdrs que procura por chamadas recebidas (propriedade dst_id igual a user Id) para user Id 123456 após 1 de setembro de 2018:

curl -u user_id:API_Key -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"}
  ]

Agrupamento

group_by está disponível para agrupamento de registos por propriedade específica: GET https://l7api.com/v1.2/voipstudio/cdrs?group_by=src. Este parâmetro deve ser passado como uma cadeia de consulta URL.