Pular para conteúdo

Início rápido

1. Obtenha a chave

A chave de API está no portal, em Credenciais. Ela vai no cabeçalho Authorization de toda chamada:

Authorization: Bearer <sua-chave>

Guarde a chave no servidor

Não coloque a chave em aplicativo, página web ou repositório público. Quem tem a chave envia em seu nome e consome seu saldo.

2. Envie um SMS

curl https://sms.example.com/api/v1/sms \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to": "+55 11 98888-7777", "text": "Seu codigo e 4821", "from": "MINHAMARCA"}'
const r = await fetch('https://sms.example.com/api/v1/sms', {
  method: 'POST',
  headers: { Authorization: `Bearer ${process.env.CHAVE}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ to: '5511988887777', text: 'Seu codigo e 4821' }),
});
console.log(await r.json());
import os, requests
r = requests.post('https://sms.example.com/api/v1/sms',
    headers={'Authorization': f"Bearer {os.environ['CHAVE']}"},
    json={'to': '5511988887777', 'text': 'Seu codigo e 4821'})
print(r.json())
$ch = curl_init('https://sms.example.com/api/v1/sms');
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('CHAVE'), 'Content-Type: application/json'],
  CURLOPT_POSTFIELDS => json_encode(['to' => '5511988887777', 'text' => 'Seu codigo e 4821']),
]);
echo curl_exec($ch);

Resposta:

{
  "id": "a1b2c3d4-...",
  "to": "5511988887777",
  "status": "accepted",
  "parts": 1,
  "encoding": "GSM7",
  "converted": false,
  "price": 0.075,
  "currency": "BRL"
}

Guarde o id: é por ele que você acompanha a mensagem.

3. Acompanhe a entrega

A mensagem passa por estes estados:

accepted → sent → delivered ou failed

  • accepted: a plataforma aceitou e vai enviar.
  • sent: a operadora aceitou.
  • delivered / failed: o recibo do aparelho chegou.
  • rejected: a mensagem não saiu da plataforma. O campo error diz o motivo (lista de erros).

Você pode consultar a qualquer momento:

curl https://sms.example.com/api/v1/sms/<id> -H "Authorization: Bearer $CHAVE"

Para não precisar consultar, configure um webhook: a plataforma avisa cada mudança.

Tamanho e codificação

Codificação Quando 1 SMS Por parte (mensagem longa)
GSM7 Só caracteres do alfabeto GSM 160 153
UCS2 Qualquer caractere fora dele 70 67

Um único ã, ç, á ou emoji muda a mensagem inteira para UCS2 e reduz o limite para 70 caracteres. A cobrança é por parte. Use POST /sms/estimate para saber codificação, partes e preço antes de enviar.

Se a conversão de acentos estiver ativa na sua conta, a plataforma troca ã por a, ç por c e assim por diante quando isso faz o texto caber em GSM7. A resposta traz converted: true quando isso acontece.

Remetente

  • Até 11 letras e números (MINHAMARCA), ou um número de até 15 dígitos.
  • Só remetente numérico recebe respostas.
  • Sem from, a plataforma usa o remetente padrão da sua credencial.

Destino

Formato internacional, com código do país, de 8 a 15 dígitos. Espaços, +, pontos, traços e parênteses são ignorados: +55 (11) 98888-7777 vira 5511988887777.

Limite de velocidade

Cada credencial tem um limite de mensagens por segundo. Acima dele a API responde 429 throughput_exceeded; aguarde e tente de novo. Para campanhas, use POST /sms/batch, que controla o ritmo sozinho.