Documentação da API REST
APIs REST de conta e faturação
Consulte o saldo e as informações de faturação disponíveis para a sua integração aprovada.
Escolha a API e a credencial em conjunto
As contas aprovadas de Programadores e Automação, Empresas e Prestadores de Comunicações podem integrar os serviços ativados. Um programador individual não precisa de se apresentar como uma empresa. O envio de SMS/MMS por aplicações exige a aprovação de envio e o registo aplicáveis. O serviço para Particulares e famílias não tem uma API de envio de mensagens acessível ao cliente.
| Família de API | URL base | Autenticação e resultado |
|---|---|---|
| Comunicações v3 | https://api.multitel.net/v3 | Credenciais Basic aprovadas; tokens provisionados elegíveis apenas para operações que os suportem. JSON status e response. |
| Registo de emergência | https://api.multi.tel/emergency | Credenciais Basic aprovadas ou acesso bearer provisionado especificamente. JSON code, message e data. |
| Integrações REST do portal | Host e operação indicados na referência de desenvolvimento da sua conta | Use a credencial, os âmbitos (scopes) e o esquema documentados dessa operação. Os pedidos de sessão do navegador são uma superfície separada. |
Defina MULTITEL_API_USERNAME e MULTITEL_API_PASSWORD através da configuração de segredos do seu servidor antes de usar os exemplos. Nunca os incorpore em JavaScript público de navegador, em URLs ou no controlo de versões. As credenciais dedicadas são geridas em Definições de integração da API.
Primeiro pedido: ler o seu saldo
Esta leitura não compra um serviço nem origina uma chamada ou mensagem.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
"https://api.multitel.net/v3/getbalance"A API de comunicações v3 devolve o resultado da aplicação dentro do corpo JSON. Verifique o status HTTP e status.code antes de ler response; um pedido rejeitado pode não ter objeto de resposta. Os valores de código podem ser strings ou números.
{
"status": {
"code": 200,
"msg": ""
},
"response": {
"balance": "25.0000",
"currency": "USD",
"terms": "Prepaid"
}
}Este é um exemplo fictício, não o saldo de uma conta. Trate os valores monetários como montantes decimais. Guarde a mensagem de resposta do servidor ao diagnosticar um pedido rejeitado, com as credenciais removidas.
Use corretamente os dados de faturação
A resposta de saldo contém o saldo atual, a moeda e as condições de pagamento. Não indica o custo de uma chamada futura nem uma fatura completa. Use as operações de tarifas e de consumo correspondentes para essas questões. Os números existentes podem ter planos diferentes dos do catálogo atual.
Tratar erros e novas tentativas
- Falha de autenticação ou de permissão
- Verifique se a credencial da API está ativada, o serviço permitido e a restrição de IP de origem. Um cookie de sessão do portal não é uma credencial de integração.
- Crédito insuficiente ou aprovação pendente
- Resolva o saldo da conta, a aprovação de envio ou o requisito de documentos antes de repetir a operação.
- Sem resultado
- Trate um inventário vazio ou a ausência do nome do chamador como um resultado normal. Não presuma que um número sintaticamente válido tenha todos os serviços.
- Tempo limite de rede ou falha do serviço
- Use novas tentativas limitadas com espera progressiva (backoff) para leituras. Numa compra, envio ou registo, verifique primeiro o estado da operação; repetir um pedido aceite pode duplicar uma ação faturável.
O suporte a idempotência depende de cada família de API. A API de emergência suporta chaves de repetição; isso não torna idempotentes pedidos v3 arbitrários. Guarde os carimbos de data/hora, os IDs devolvidos e as respostas com dados sensíveis removidos para o suporte.
Continue com a referência da sua conta
A referência com sessão iniciada filtra as operações de acordo com as suas permissões e os serviços ativados. Utilize o respetivo host, o tipo de credencial, os campos de pedido e o esquema de resposta exatos. As consolas podem executar operações reais, incluindo compras e mensagens.