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:
- Enviar o pedido POST para o endpoint
/login
com e-mail e palavra-passe como credenciais. - 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:
- No painel de Administração editar utilizador para quem as Chaves API precisam de ser adicionadas.
- Ir para a secção
API Keys
. - 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.
- Clique no botão "Add" (Adicionar).
- Clique no ícone "Eye" para recuperar a Chave API actual /
user_token
. - Clicar no ícone "Gear" e seleccionar "Show Details" para obter detalhes adicionais ou apagar a 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 recursostotal
- número total de recursos
-
Obter um único recurso:
data
- dados dos recursoslinks
- links para recursos relacionados
Cada resposta de erro contém as seguintes propriedades:
message
- mensagem de erro geralerrors
- 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.