Sobre esta API

Envie códigos de verificação (OTP) e avisos transacionais por SMS, sem contrato com operadora.

Envie um JSON com to em formato internacional (+5511999999999) e message, até 1600 caracteres. A cobrança é por unidade de mensagem: 160 caracteres por unidade, ou 70 quando o texto tem acento fora do alfabeto GSM ou emoji, e mensagem com link soma 1 unidade. O bloco billing mostra a conta.

Mensagem não entregue não é cobrada.

Fonte de envio

Provedores parceiros · Atualização: tempo real

Requisição

POST /api/v1/messenger/sms

Autenticação HTTP Basic: public_key:secret_key em Base64. Guarde a chave secreta no servidor.

Cabeçalho	Descrição
`Authorization` Obrigatório	Chave de API em Basic: `public_key:secret_key` em Base64.
`X-Project-Id` Opcional	Projeto que recebe a chamada. Sem ele, vale o projeto padrão da conta.
`Idempotency-Key` Opcional	Repetir a mesma chave em até 24 horas devolve a resposta anterior, sem executar nem cobrar de novo.

Parâmetros

Campo	Tipo e local	Descrição
`to` Obrigatório	stringbody	Destinatário em E.164, com DDI. A pontuação é ignorada. Exemplo: `+5511999999999`
`message` Obrigatório	stringbody	Texto da mensagem, até 1600 caracteres. Exemplo: `Seu código de verificação é 123456.`

1curl --request POST 'https://api.apifordevs.com/api/v1/messenger/sms' \
2  --user "afd_live_pk_...:$AFD_SECRET_KEY" \
3  --header "X-Project-Id: $AFD_PROJECT_ID" \
4  --header 'Content-Type: application/json' \
5  --data '{"to":"+5511999999999","message":"Seu código de verificação é 123456."}'

1import os
2import requests
3
4response = requests.request(
5    "POST",
6    "https://api.apifordevs.com/api/v1/messenger/sms",
7    auth=("afd_live_pk_...", os.environ["AFD_SECRET_KEY"]),
8    headers={"X-Project-Id": os.environ["AFD_PROJECT_ID"]},
9    json={"to": "+5511999999999", "message": "Seu código de verificação é 123456."},
10    timeout=30,
11)
12response.raise_for_status()
13print(response.json())

1const response = await fetch("https://api.apifordevs.com/api/v1/messenger/sms", {
2  method: "POST",
3  headers: {
4    Authorization: "Basic " + Buffer.from(
5      "afd_live_pk_...:" + process.env.AFD_SECRET_KEY
6    ).toString("base64"),
7    "X-Project-Id": process.env.AFD_PROJECT_ID,
8    "Content-Type": "application/json",
9  },
10  body: JSON.stringify({"to":"+5511999999999","message":"Seu código de verificação é 123456."}),
11  signal: AbortSignal.timeout(30000),
12});
13if (!response.ok) throw new Error(`HTTP ${response.status}`);
14console.log(await response.json());

Campos de resposta

Campos e tipos publicados no catálogo desta API.

Statusstatusstring
Detalhedetailstring
Destinatário (mascarado)tostring: Destinatário mascarado — o número não volta inteiro.
ID da mensagemmessage_idstring
Composição da cobrançabillingobject
Caracteresbilling.charactersinteger: Tamanho do texto enviado.
Alfabetobilling.encodingstring: gsm-7 cabe 160 caracteres por unidade; ucs-2 (acento, emoji), 70.
Caracteres por unidadebilling.characters_per_unitinteger
Unidades do textobilling.segmentsinteger: Unidades que o texto consome.
Unidades por linkbilling.link_surcharge_unitsinteger: Unidades somadas por conter URL. Zero quando não há link.
Unidades cobradasbilling.billable_unitsinteger: segments + link_surcharge_units. É o tokens_in.

Exemplo de resposta

1{
2  "success": true,
3  "code": 200,
4  "code_message": "A requisição foi processada com sucesso.",
5  "errors": [],
6  "header": null,
7  "data_count": 1,
8  "data": [
9    {
10      "status": "success",
11      "detail": "Mensagem enviada.",
12      "to": "+55119****4321",
13      "message_id": "9182736",
14      "billing": {
15        "characters": 38,
16        "encoding": "gsm-7",
17        "characters_per_unit": 160,
18        "segments": 1,
19        "link_surcharge_units": 0,
20        "billable_units": 1
21      }
22    }
23  ]
24}

Respostas e cobrança

HTTP	Descrição	Cobrança
`200`	Sucesso.	Sujeita à cobrança
`400` `bad_request` `live_key_cannot_use_dev_mode`	Arquivo ou parâmetro que a rota não consegue processar, projeto inválido, ou `dev_mode=true` com chave de produção.	Sem cobrança
`401` `unauthorized`	Credencial ausente, inválida ou revogada.	Sem cobrança
`402` `payment_required`	Saldo insuficiente ou limite de gasto diário atingido.	Sem cobrança
`403` `forbidden` `ip_not_allowed` `test_key_cannot_run_live`	E-mail da conta não verificado, chave sem escopo para o serviço, IP fora da allowlist do projeto ou chave de teste sem `dev_mode=true`.	Sem cobrança
`409` `conflict`	Requisição com a mesma `Idempotency-Key` ainda em andamento.	Sem cobrança
`422` `validation_error`	Parâmetro obrigatório ausente ou fora do formato, ou `Idempotency-Key` repetida com outro conteúdo.	Sem cobrança
`429` `rate_limit_exceeded`	Limite de requisições por minuto da chave atingido.	Sem cobrança
`500` `internal_error`	Falha interna.	Sem cobrança
`503` `service_unavailable` `upstream_error`	Serviço desativado (`service_unavailable`), ou a mensagem não pôde ser entregue agora (`upstream_error`). Não é cobrada; com `upstream_error`, pode ser repetida.	Sem cobrança

Casos de uso

Código de verificação

Enviar o código de login ou de confirmação de uma operação por SMS.

Aviso transacional

Confirmar pedido, entrega ou cobrança sem manter contrato com operadora.

Notas de integração

O número do destinatário nunca volta inteiro na resposta.
tokens_in no bloco header é o número de unidades de SMS: é por elas que a mensagem é cobrada.

Envio de SMS