API de SMS para desenvolvedores

A SMSKit é uma API de SMS para o Brasil. Uma requisição HTTP e a mensagem chega no celular do destinatário: um código de acesso, um aviso de pedido a caminho ou uma campanha para a base inteira.

Todo envio tem um tipo, declarado no campo kind. O tipo autenticação cobre códigos de acesso, confirmação de identidade e recuperação de conta, com entrega em até 15 segundos e até 100 destinatários por requisição. O tipo utilidade cobre avisos transacionais e campanhas de marketing, com até 2.000 destinatários por requisição.

A integração tem três passos: criar uma chave, trocar a chave por um token e chamar POST /v1/sms. A entrega é para números brasileiros (+55), o preço é em reais por segmento e as respostas vêm em JSON.

Quando a integração for escrita por um agente, no Cursor ou no Claude Code, comece em Agentes. Essa página reúne o prompt pronto, o índice da documentação em llms.txt e a configuração do servidor MCP.

Envie seu primeiro SMS

1. Crie uma chave

   Abra o console em IntegraçõesChaves de API e gere uma chave sk_test_. Chaves de teste usam os mesmos endpoints, sem entregar mensagem e sem consumir crédito. A chave é exibida uma única vez; guarde-a no gerenciador de segredos do projeto.

   O console entra por celular brasileiro com código por SMS, e na primeira vez a conta pede o CPF do titular. É uma vez só, e vale saber antes de começar.

   export SMSKIT_KEY="sk_test_…"
   

2. Troque a chave por um token

   Envie a chave no header X-API-Key para POST /v1/auth/token. A resposta traz um token Bearer válido por 48 horas, que autentica as demais rotas. Os SDKs fazem essa troca na primeira chamada e pedem um token novo quando o atual expira.

   curl -X POST https://api.smskit.dev/v1/auth/token \
     -H "X-API-Key: $SMSKIT_KEY"
   

3. Envie o SMS

   POST /v1/sms aceita um destinatário ou uma lista, com o texto livre em text ou um modelo aprovado em template. Escreva sem acento e sem emoji: a operadora não os entrega, e a API recusa a requisição antes de cobrar.

   Toda mensagem abre com o nome de quem envia. O campo from define esse nome; sem ele, entra o nome da empresa no workspace. O que chega ao celular é Studio: seu texto, e os 160 caracteres contam os dois. Quando o texto já começa com esse nome, ele não é repetido.

   Em um modelo, o mesmo nome preenche a variável empresa sozinho: você manda from e as outras variáveis, e não precisa repetir a empresa em variables.

   cURLTypeScriptPython

   curl -X POST https://api.smskit.dev/v1/sms \
     -H "Authorization: Bearer $SMSKIT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "to": "+5511999990123",
       "from": "Studio",
       "text": "Seu pedido saiu para entrega. Chega em 30 minutos."
     }'
   

O que acontece depois do 202

A resposta 202 confirma que o envio entrou na fila. A entrega acontece depois, e cada destinatário tem um status próprio: queued, sent, delivered ou failed.

Antes da fila, o texto passa por uma análise de risco automática que procura spam, golpe, phishing e links suspeitos. Com risco baixo, o envio segue direto. Quando a análise não aprova um texto livre, a resposta é 409 review_required, sem cobrar nada: você corrige o texto, usa um modelo aprovado ou repete com accept_review: true para aceitar a espera pela revisão humana.

O resultado pode ser acompanhado de duas formas. GET /v1/sms/{id} devolve o envio com a situação de cada destinatário. Um webhook entrega esse mesmo resultado no seu servidor assim que a operadora confirma, e é o caminho recomendado em produção.

Regras que valem para todo envio

• 160 caracteres, contando o remetente. Acima disso, a resposta é 422. Como um segmento GSM-7 cabe exatamente 160, na prática é um crédito por destinatário.
• Texto em ASCII. Acentos e emojis são recusados com 422 validation_error, antes de qualquer cobrança.
• Texto livre não precisa de modelo. Ele passa pelas mesmas validações do console, incluindo a análise de risco. Um modelo aprovado, por outro lado, entra na fila mesmo quando a análise não aprova o texto: a redação já foi lida por uma pessoa. Os modelos ficam em Modelos.
• Produção exige o titular cadastrado. Sem isso, chaves sk_live_ respondem identity_required. O cadastro fica em ConfiguraçõesTitular da conta, e em modo de teste a exigência não se aplica.
• Idempotency-Key evita envio duplicado. Repetir a requisição com a mesma chave devolve o resultado da primeira.

Próximos passos