Status de SMS

Name: FonteData
Author: FonteData

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

Grátis não debita saldo

Autenticação pelo header X-API-Key. Veja como obter a chave.

Devolve a situação de entrega de uma mensagem já enviada. Esta consulta é gratuita — você pode acompanhar o mesmo request_id quantas vezes quiser.

A situação evolui sozinha conforme a operadora confirma: a mensagem sai como aceita, passa a entregue e pode terminar em erro definitivo (número bloqueado, aparelho inexistente). Um estado final de erro não gera estorno: o envio já foi cobrado pela operadora.

Requisição

curl -X POST -H "X-API-Key: SUA_CHAVE" \
  "https://app.fontedata.com/api/v1/consulta/sms-status?request_id=7f3a1c92-0000-0000-0000-000000000000"

Parâmetros

Nome	Tipo	Descrição	Exemplo
request_id obrigatório	texto	Identificador devolvido no envio.	7f3a1c92-0000-0000-0000-000000000000

Resposta

request_id — Identificador da mensagem.
status — Situação normalizada da entrega, em valores estáveis:
- sent — Aceita pela operadora e a caminho; ainda sem confirmação de entrega.
- delivered — Confirmada como entregue.
- failed — Recusa definitiva (número em lista de bloqueio, cancelada, erro da operadora).
- unknown — A operadora não confirmou nem recusou dentro de 24 horas. Estado terminal: não vai mudar mais.
operadora — Operadora que recebeu a mensagem, quando informada. null enquanto a confirmação não chega.

Exemplo — 200 OK

{
  "status": "delivered",
  "creditos": 1,
  "operadora": "VIVO",
  "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."
    },
    "operadora": {
      "type": [
        "string",
        "null"
      ]
    },
    "request_id": {
      "type": [
        "string",
        "null"
      ]
    }
  },
  "additionalProperties": true
}

Códigos de erro

Código	Mensagem	Quando acontece
404	Mensagem não encontrada.	O `request_id` não existe ou pertence a outra conta.
503	Serviço de envio temporariamente indisponível.	A plataforma de envio está instável; tente novamente em instantes.

Quando usar

Use para auditoria de entrega e para telas de acompanhamento. Consulte alguns minutos depois do envio: a confirmação da operadora costuma levar de segundos a poucos minutos, e no primeiro envio para um número novo pode passar de três minutos.

Esta consulta é sobre a entrega da sua mensagem. Para receber as respostas dos destinatários (inclusive os pedidos de saída), registre um webhook no painel: é por ele que elas chegam.

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.