Casos de uso

Como combinar o envio, os webhooks e as consultas da API SMS em fluxos práticos. Os cenários abaixo usam apenas comportamentos descritos na documentação da API.

1. Envio em lote de uma campanha

Objetivo: enviar a mesma comunicação para vários números em uma única requisição.

Monte o lote

Inclua até 1.000 mensagens em arraySms, cada uma com number, message e um filter_value para conciliar depois.

Escolha a rota

Use route_type: 2 (Básico) para campanhas que não precisam acompanhar respostas, ou route_type: 1 (Exclusivo) quando quiser receber respostas.

Guarde os identificadores

A resposta traz um id_sms por mensagem. Armazene-os para acompanhar status e respostas.

POST /sms/v3/send — lote

curl -X POST \
  "https://api.assertivasolucoes.com.br/sms/v3/send" \
  -H "Authorization: Bearer SEU_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "can_receive_status": true,
    "can_receive_answer": false,
    "webhook_status_url": "https://suaempresa.com.br/webhooks/sms/status",
    "route_type": 2,
    "arraySms": [
      { "number": "11912345678", "message": "Sua fatura vence amanhã.", "filter_value": "fatura-001" },
      { "number": "11987654321", "message": "Sua fatura vence amanhã.", "filter_value": "fatura-002" }
    ]
  }'

const accessToken = process.env.ASSERTIVA_ACCESS_TOKEN;

const corpo = {
  can_receive_status: true,
  can_receive_answer: false,
  webhook_status_url: "https://suaempresa.com.br/webhooks/sms/status",
  route_type: 2,
  arraySms: [
    { number: "11912345678", message: "Sua fatura vence amanhã.", filter_value: "fatura-001" },
    { number: "11987654321", message: "Sua fatura vence amanhã.", filter_value: "fatura-002" }
  ]
};

const resposta = await fetch("https://api.assertivasolucoes.com.br/sms/v3/send", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${accessToken}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify(corpo)
});
const enviados = await resposta.json();
console.log(enviados);

import os
import requests

access_token = os.environ["ASSERTIVA_ACCESS_TOKEN"]

corpo = {
    "can_receive_status": True,
    "can_receive_answer": False,
    "webhook_status_url": "https://suaempresa.com.br/webhooks/sms/status",
    "route_type": 2,
    "arraySms": [
        {"number": "11912345678", "message": "Sua fatura vence amanhã.", "filter_value": "fatura-001"},
        {"number": "11987654321", "message": "Sua fatura vence amanhã.", "filter_value": "fatura-002"},
    ],
}

resposta = requests.post(
    "https://api.assertivasolucoes.com.br/sms/v3/send",
    headers={"Authorization": f"Bearer {access_token}"},
    json=corpo,
)
resposta.raise_for_status()
print(resposta.json())

2. Receber status de entrega por webhook

Objetivo: ser notificado automaticamente quando o status de entrega de cada SMS mudar.

Defina can_receive_status como true;
Informe a URL em webhook_status_url;
Garanta que a URL aceite requisições POST.

A API envia para a sua URL um corpo com:

Exemplo de status recebido (dados fictícios)

{
  "id_sms": "ID_DA_MENSAGEM",
  "number": "11912345678",
  "filter_value": "pedido-12345",
  "status": 1,
  "status_detail": "Mensagem entregue no celular"
}

O endpoint de callback deve usar HTTPS, aceitar POST, validar o JSON, armazenar o id_sms, atualizar o status de forma idempotente e responder rapidamente.

3. Receber respostas dos destinatários

Objetivo: capturar a resposta que o destinatário envia ao SMS (por exemplo, uma confirmação).

Defina can_receive_answer como true;
Informe a URL em webhook_answer_url;
Garanta que a URL aceite requisições POST.

Exemplo de resposta recebida (dados fictícios)

{
  "id_sms": "ID_DA_MENSAGEM",
  "number": "11912345678",
  "filter_value": "pedido-12345",
  "reply": "SIM"
}

Use o filter_value para relacionar a resposta ao pedido, cliente ou processo correspondente.

4. Consultar status e resposta sob demanda

Objetivo: quando você não usa webhooks (ou quer reconciliar), consultar diretamente pelo id_sms.

Status

GET /sms/v3/status retorna status e status_detail da mensagem.

Resposta

GET /sms/v3/answer retorna o reply do destinatário. Se ainda não houver resposta, a API poderá informar que nenhuma foi encontrada.

Ambas as consultas usam o id_sms. Conforme a documentação, confirme na Referência técnica o formato final da URL, pois a especificação associa o parâmetro ao endpoint sem explicitá-lo no caminho.

5. Tratamento de status "Não enviado"

Objetivo: reagir corretamente quando a mensagem não é entregue.

Código	Situação	Ação sugerida
`3`	Blacklist — número em lista de bloqueio.	Não reenviar; respeitar o bloqueio.
`10`	Não me ligue (Procon-SP).	Não reenviar; respeitar o cadastro.
`11`	Número inválido.	Corrigir o número antes de qualquer novo envio.
`13`	Cancelado por ausência de saldo.	Repor saldo antes de reenviar.
`14`	Link inválido (não validado previamente).	Validar o link antes de reenviar.

Recomendações

Boas práticas

Evite duplicidade

Não reenvie mensagens sem validar o resultado da requisição anterior. Implemente idempotência no processamento de status e respostas.

Valide antes de enviar

Confira número (11 dígitos com DDD), conteúdo e limite de 600 caracteres por mensagem.

Use o filter_value

Relacione cada SMS a um pedido ou processo interno pelo filter_value.

Proteja os dados

Use HTTPS nos webhooks, não exponha tokens em logs e evite dados sensíveis no conteúdo da mensagem.