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

O URL base para o API id:

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

Autenticação

Antes de enviar pedidos para VoIPstudio API é necessário obter primeiro a API Key também conhecida como user_token que será utilizada para autorizar todos os pedidos.

Pode gerar a Chave API / user_token das duas formas seguintes:

  1. Enviar o pedido POST para o endpoint /login com e-mail e palavra-passe como credenciais.
  2. Utilizar VoIPstudio Web Dashboard para criar Chave API / user_token.

Por favor, ver instruções detalhadas abaixo:

Login com correio electrónico e palavra-passe

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

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

Exemplo de pedido:

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

Exemplo de resposta bem sucedida:

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

Por defeito user_token expirará após 30 minutos de inactividade (ou seja, não são feitos pedidos API). Sempre que um pedido API é feito, o temporizador de expiração é reiniciado.

Se necessitar de fichas API com tempo de expiração mais longo, após a obtenção do pedido inicial user_token com POST /login, podem ser criadas chaves API adicionais através do envio de 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}'

Exemplo de resposta bem sucedida:

{
    "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 criar uma chave API que nunca irá expirar, utilize "expiração":0" no pedido de carga útil para POST `/apitokens'.

Painel da Web - Adicionar chave API

Siga os passos abaixo para adicionar a chave API para um utilizador:

  1. No painel de Administração editar utilizador para quem as Chaves API precisam de ser adicionadas.
  2. Ir para a secção API Keys.
  3. Introduza um nome para a sua Chave API, esta pode ser qualquer coisa que goste. Por exemplo, um nome da sua aplicação que irá utilizar esta Chave API.
  4. Clique no botão "Add" (Adicionar).
  5. Clique no ícone "Eye" para recuperar a Chave API actual / user_token.
  6. Clicar no ícone "Gear" e seleccionar "Show Details" para obter detalhes adicionais ou apagar a chave API.

api-key-add.png.

Figure 1.1 Adicionar chave API.

Fazer pedidos

Espera-se que os pedidos recebidos tratados pela nossa API tenham um cabeçalho "X-Auth-Token" com um valor "user_token" (chave API) retornado de uma resposta bem sucedida POST /login' ou POST/apitokens'.

X-Auth-Token: TOKEN

Exemplo de pedido autenticado:

curl -H "Content-Type: application/json"
     -H "X-Auth-Token: 123abc45678def3234sdfgdf3434df3444" \
     https://l7api.com/v1.2/voipstudio/cdrs

Respostas HTTP

VoIPstudio REST API utiliza códigos de resposta HTTP convencionais para indicar o sucesso ou o fracasso de um pedido 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:

  • Obter recolha de recursos:

    • data - um conjunto de dados de recursos
    • total - número total de recursos
  • Obter um único recurso:

    • data - dados dos recursos
    • 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 'GET https://l7api.com/v1.2/voipstudio/cdrs' pager pode ser utilizado para devolver um número específico de registos de uma determinada página do conjunto de dados. Para aplicar o pager, anexar os seguintes parâmetros ao URL ?page=N&limit=Z onde N é um número de página e Z é o número de registos a serem devolvidos (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 de 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_"}
   ...
]

As três fichas acima _PROPERTY_NAME_, _OPERATOR_ e _VALUE_TO_SEARCH_ devem ser interpretadas como abaixo:

  • _PROPERTY_NAME_ isto pode ser qualquer propriedade que pertença a um determinado objecto terminal. Ver secção "Recursos" abaixo para 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" sem valor _SEARCH_VALUE_
    • lte ou <= quando se procura registos com valor de "propriedade" independente ou igual _SEARCH_VALUE_
    • gt ou > ao procurar registos com valor de "propriedade" mais elevado que _SEARCH_VALUE_
    • gte ou >= quando se procura registos com valor de "propriedade" mais ou iguais _SEARCH_VALUE_
    • in ao procurar registos com valor de "propriedade" incluído em _SEARCH_VALUE_ (Nota: o valor da pesquisa precisa de ser passado como um array, por exemplo: ["foo", "bar" ])
    • like ao procurar registos com valor de "propriedade" matching pattern de _SEARCH_VALUE_
    • notlike Não é "semelhante" quando se procura registos com valor de "propriedade" NÃO corresponde ao padrão de _SEARCH_VALUE_.
  • _SEARCH_VALUE_ o valor que deseja pesquisar

Exemplo de pedido para o ponto final /cdrs de procura de chamadas recebidas (propriedade dst_id igual a user Id) a user Id 123456 após 1 de Setembro 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"}
     ]'

Agrupamento

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