Enviar SMS

Name: FonteData
Author: FonteData

POST https://app.fontedata.com/api/v1/consulta/sms-enviar

R$ 0,29 por crédito de SMS (160 caracteres)

Debitado do seu saldo a cada chamada cobrada. Autenticação pelo header X-API-Key. Veja como obter a chave.

Envia um SMS para um celular brasileiro. A mensagem entra na fila da operadora na hora, e a resposta devolve um request_id para você acompanhar a entrega em Status de SMS.

O remetente exibido na mensagem é a identidade da sua conta: ele é definido por nós e injetado no servidor — você não envia esse campo. Para alterar o remetente, fale com a gente.

Cobrança por crédito: 1 crédito a cada 160 caracteres. O texto é normalizado antes da contagem (a rede de SMS remove os acentos), então 160 caracteres valem sempre 1 crédito e uma mensagem de 400 caracteres custa 3 créditos. O remetente entra no início do texto e conta no total — reserve o tamanho dele no seu orçamento de caracteres. Você é cobrado quando a mensagem é aceita para envio; a entrega no aparelho depende da operadora e não é refaturada.

O campo reference é opcional e existe para uma coisa: tornar o retry seguro. Se a chamada deu timeout e você não sabe se o SMS saiu, repita com o mesmo reference — devolvemos o resultado original (duplicado: true, sem nova cobrança) e nunca disparamos um segundo SMS. O identificador vale para sempre, sem janela de expiração, e o único estado que reabre para nova tentativa é o de falha não cobrada. Sem reference, cada chamada é um envio novo — e é cobrada como tal.

Requisição

curl -X POST -H "X-API-Key: SUA_CHAVE" \
  "https://app.fontedata.com/api/v1/consulta/sms-enviar?numero=SEU_TELEFONE&mensagem=Seu+pedido+1234+saiu+para+entrega.&reference=pedido-1234-envio"

Parâmetros

Nome	Tipo	Descrição	Exemplo
numero obrigatório	telefone	Celular de destino com DDI e DDD, só dígitos (ex.: 5511999999999).	55DDNNNNNNNNN
mensagem obrigatório	texto	Texto da mensagem. Cada 160 caracteres = 1 crédito.	Seu pedido 1234 saiu para entrega.
reference opcional	texto	Seu identificador do envio. Repetir o mesmo valor não dispara outro SMS nem cobra de novo — use no retry.	pedido-1234-envio

Resposta

request_id — Identificador da mensagem no nosso lado. Use-o em Status de SMS.
status — Situação no momento da resposta (sent = aceita para envio).
creditos — Créditos de 160 caracteres desta mensagem. Num replay (duplicado: true) ele repete o total do envio original, que já foi cobrado na primeira vez — nada é cobrado de novo.
duplicado — Só aparece, com o valor true, quando o reference já havia sido usado: nada foi enviado, nada foi cobrado, e o corpo repete o resultado original. Em um envio novo o campo é omitido.

Os créditos cobrados em cada envio ficam registrados no seu painel, em Uso e no Extrato.

Exemplo — 200 OK

{
  "status": "sent",
  "creditos": 1,
  "request_id": "7f3a1c92-0000-0000-0000-000000000000"
}

Schema da resposta (JSON Schema)

JSON Schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": [
        "string",
        "null"
      ]
    },
    "creditos": {
      "type": [
        "integer",
        "null"
      ],
      "description": "Créditos de 160 caracteres cobrados neste envio."
    },
    "duplicado": {
      "type": [
        "boolean",
        "null"
      ]
    },
    "request_id": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": true
}

Códigos de erro

Código	Mensagem	Quando acontece
400	Parâmetros inválidos para o envio.	O corpo enviado não bate com o contrato (campo ausente, tipo errado).
402	Saldo insuficiente.	A conta não tem saldo para cobrir o envio.
403	Número em opt-out.	A pessoa pediu para sair (respondeu SAIR) ou a operadora bloqueou o número. Nada é enviado e nada é cobrado.
422	Número inválido ou não aceito pela operadora.	O telefone informado não é um celular válido para SMS no Brasil.
429	Muitas requisições. Tente novamente em instantes.	O limite por telefone (10 por hora) ou por conta (60 por minuto) foi atingido. O cabeçalho `Retry-After` diz quanto falta.
503	Serviço de envio temporariamente indisponível.	A plataforma de envio está instável; repita a chamada com o mesmo `reference`.

Quando usar

Use para notificações transacionais: confirmação de pedido, aviso de entrega, alerta de vencimento, código de acesso avulso. Para autenticação por código, prefira Enviar código OTP, que gera, guarda e valida o código para você — aqui o código ficaria por sua conta.

Quem responder SAIR (ou STOP, CANCELAR, DESCADASTRAR, entre outras) sai da sua base na hora e passa a ser recusado em todos os seus envios: a próxima tentativa para esse número devolve 403, sem enviar e sem cobrar. Em mensagem de divulgação, escreva a instrução de saída no próprio texto — é obrigação regulatória, e aqui ela não é acrescentada por nós.

Integrar

OpenAPI (JSON) ↗ — importe a URL no Postman ou no Insomnia para gerar a coleção com todos os endpoints. Também dá para consultar pelo chat: conecte via MCP. Esta página em Markdown.