🚀Quickstart

Este guia mostra, em poucos minutos, como autenticar-se e realizar seu primeiro envio de SMS através da API Oficial da SMS Funnel.

A URL de base de todos os endpoints é: https://web.smsfunnel.com.br/api/parceiros/v1

Pré-requisitos

1. Ter a API de Parceiros habilitada em sua conta. Caso ainda não tenha, entre em contato com nosso suporte.

2. Possuir uma Chave de API válida. Veja como gerá-la em Autenticação.

3. Possuir créditos de SMS disponíveis em sua conta.

---

Passo 1 — Autenticação

Todas as requisições devem conter o header Authorization com sua Chave de API no formato Bearer.

Authorization: Bearer <SUA CHAVE DE API AQUI>

ATENÇÃO: Não compartilhe sua Chave de API com terceiros. Este conteúdo é de uso confidencial e exclusivo seu.

---

Passo 2 — Enviar seu primeiro SMS

POST /sms/messages

Função: Enfileira o disparo de uma ou mais mensagens SMS. Cada chamada gera um broadcast que agrupa as mensagens enviadas.

Exemplo de requisição:

cURL

curl -X POST "https://web.smsfunnel.com.br/api/parceiros/v1/sms/messages" \
  -H "Authorization: Bearer <SUA CHAVE DE API AQUI>" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {
        "to": "5511999999999",
        "message": "Ola! Esta e sua primeira mensagem via SMS Funnel."
      }
    ]
  }'

Corpo de envio:

{
    "messages": [ // Lista de mensagens (1 a 5000)
        {
            "to": "5511999999999", // Telefone do destinatário (10 a 15 dígitos, com DDI/DDD)
            "message": "Ola! Esta e sua primeira mensagem via SMS Funnel.", // Texto (1 a 1530 caracteres)
            "reference": "pedido-123" // Opcional: seu identificador. Se omitido, geramos um automaticamente.
        }
    ]
}

Corpo de resposta — 202 Accepted:

{
    "broadcast_id": "019c7114-7c4b-77b6-8deb-12cb5c885ea5", // ID do broadcast gerado
    "messages": [
        {
            "id": "019c7114-abab-7da9-9a46-4da50bd49147", // ID da mensagem
            "reference": "pedido-123", // Sua referência (ou a gerada por nós)
            "phone": "5511999999999", // Telefone normalizado
            "status": "queued", // Status inicial: enfileirada
            "bill_factor": 1 // Quantidade de créditos consumidos por esta mensagem
        }
    ],
    "unsupported_features": [] // Recursos solicitados que não foram aplicados, se houver
}

O status 202 Accepted indica que as mensagens foram aceitas e enfileiradas para envio. O disparo ocorre de forma assíncrona — utilize o Passo 3 para acompanhar o andamento.

---

Passo 3 — Acompanhar o envio

GET /sms/broadcasts/{broadcast_id}

Função: Consulta os detalhes e as métricas de um broadcast. Utilize o broadcast_id retornado no Passo 2.

Exemplo de requisição:

cURL

curl -X GET "https://web.smsfunnel.com.br/api/parceiros/v1/sms/broadcasts/019c7114-7c4b-77b6-8deb-12cb5c885ea5" \
  -H "Authorization: Bearer <SUA CHAVE DE API AQUI>"

Corpo de resposta — 200 OK:

{
    "id": "019c7114-7c4b-77b6-8deb-12cb5c885ea5", // ID do broadcast
    "name": "Broadcast #019c7114", // Nome do broadcast
    "message": "Ola! Esta e sua primeira mensagem via SMS Funnel.", // Mensagem enviada
    "status": "completed", // Status atual do broadcast
    "scheduled_date": null, // Data de agendamento, se houver
    "leads_count": 1, // Quantidade de destinatários
    "partner_reference": null, // Referência informada por você no envio
    "flash_sms": false, // Se foi enviado como flash SMS
    "concat": false, // Se a concatenação de mensagens longas está ativa
    "from": null, // Remetente personalizado, se houver
    "idempotency_key": "019c7114-...", // Chave de idempotência do envio
    "created_at": "2026-06-30 12:00:00", // Data/hora de criação
    "metrics": {
        "sent": 1, // Mensagens enviadas
        "failed": 0, // Mensagens com falha
        "total": 1 // Total de mensagens
    }
}

---

Personalizando com "Meu Link"

Para incluir um link encurtado e rastreável em sua mensagem, utilize a variável {meu_link} no texto e informe o campo url na requisição. Nós encurtamos o link automaticamente e contabilizamos os cliques.

{
    "url": "https://minhaloja.com/promo", // Obrigatório quando a mensagem contém {meu_link}
    "messages": [
        {
            "to": "5511999999999",
            "message": "Aproveite nossa promocao! Acesse: {meu_link}"
        }
    ]
}

O campo url é obrigatório quando alguma mensagem contém {meu_link} e não deve ser enviado caso nenhuma mensagem utilize a variável.

---

Evitando envios duplicados (Idempotência)

Para garantir que um reenvio da mesma requisição (por exemplo, após um timeout de rede) não gere disparos duplicados, envie o header opcional Idempotency-Key com um valor único por operação (máx. 80 caracteres).

Idempotency-Key: pedido-123-envio-01

Se recebermos uma nova requisição com a mesma chave em até 24 horas, retornamos a mesma resposta original sem reprocessar o envio. Nesses casos, a resposta incluirá o header Idempotency-Replayed: true.

---

Código de Erros Comuns

• 401 Unauthorized: Chave de API ausente, inválida ou não foi possível identificar o parceiro.

• 402 Payment Required (INSUFFICIENT_CREDITS): Créditos de SMS insuficientes para o envio.

• 403 Forbidden: Sua conta não possui a API de Parceiros habilitada.

• 404 Not Found: Recurso (broadcast/campanha) não encontrado ou não pertence à sua conta.

• 409 Conflict: Operação não permitida no estado atual (ex.: cancelar broadcast já finalizado) ou requisição concorrente.

• 422 Unprocessable Entity (VALIDATION_ERROR): Algum campo do corpo da requisição é inválido.

• 429 Too Many Requests (RATE_LIMIT_EXCEEDED): Limite de 60 requisições por minuto excedido. Consulte o header Retry-After.

• 502 Bad Gateway (SHORTENER_UNAVAILABLE): Falha temporária ao encurtar o link de "Meu Link". Tente novamente.

• 500 Internal Server Error: Ocorreu um erro interno ao processar a requisição.

Corpo de resposta de erro:

{
    "error": {
        "code": "VALIDATION_ERROR", // Código do erro
        "message": "Mensagem descritiva do erro", // Descrição
        "details": { // Opcional: detalhes por campo (presente em erros de validação)
            "messages.0.to": [
                "O campo to e obrigatorio."
            ]
        }
    }
}