Documentação da API REST
APIs REST de SMS e MMS
Envie mensagens aprovadas da aplicação e trate a aceitação, os eventos de entrega, a segmentação e os custos.
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.
Preparar um pedido de SMS
Use um número de envio aprovado e com SMS ativado, pertencente à conta, um destinatário que tenha consentido a mensagem e a verificação de Marca/Campanha ou de número gratuito (toll-free) exigida. O exemplo abaixo envia uma mensagem real quando preenchido com credenciais e números funcionais; não é um sandbox.
curl --fail-with-body \
--user "$MULTITEL_API_USERNAME:$MULTITEL_API_PASSWORD" \
--header "Accept: application/json" \
--request POST \
--header "Content-Type: application/json" \
--data '{"from":"YOUR_APPROVED_NUMBER","to":"YOUR_CONSENTED_RECIPIENT","text":"Your requested update is ready."}' \
"https://api.multitel.net/v3/sendsms"Substitua os marcadores do remetente e do destinatário por dígitos internacionais, incluindo o indicativo do país. Para um MMS, indique em media o URL do conteúdo multimédia suportado e acessível publicamente, e verifique antes a elegibilidade e o preço do MMS.
Aceitação não é entrega
Inspecione tanto o status externo da aplicação como o resultado de mensagens devolvido. Registe o identificador da mensagem fornecido pelo serviço e acompanhe o estado de entrega e os eventos de webhook. Um envio bem-sucedido não pode provar que o aparelho do destinatário recebeu a mensagem.
A faturação de SMS é por segmento. A codificação e o comprimento da mensagem podem produzir vários segmentos; os custos de multimédia e os encargos relacionados com operadoras podem diferir dos do SMS. Leia o preço de venda atual da conta antes de enviar. Nunca repita às cegas um envio que excedeu o tempo limite: inspecione primeiro o resultado registado.
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.