# Status de SMS

> Consulta a situação de entrega de uma mensagem já enviada, pelo `request_id`. Gratuita.

- **Consulta:** `sms-status`
- **Categoria:** Mensageria
- **Preço:** Grátis — não debita saldo
- **Endpoint:** `POST https://app.fontedata.com/api/v1/consulta/sms-status`
- **Autenticação:** header `X-API-Key`
- **Página:** https://fontedata.com/docs/mensageria/sms-status

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> 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

```bash
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"
```

### Python

```python
import requests

resp = requests.post(
    "https://app.fontedata.com/api/v1/consulta/sms-status",
    params={"request_id": "7f3a1c92-0000-0000-0000-000000000000"},
    headers={"X-API-Key": "SUA_CHAVE"},
    timeout=60,
)
resp.raise_for_status()
print(resp.json())
```

### Node.js

```javascript
const url = new URL("https://app.fontedata.com/api/v1/consulta/sms-status");

url.search = new URLSearchParams({
  "request_id": "7f3a1c92-0000-0000-0000-000000000000"
}).toString();

const resp = await fetch(url, {
  method: "POST",
  headers: { "X-API-Key": "SUA_CHAVE" }
});

if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
console.log(await resp.json());
```

## Parâmetros

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

## Resposta

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> - `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 de resposta

```json
{
  "status": "delivered",
  "creditos": 1,
  "operadora": "VIVO",
  "request_id": "7f3a1c92-0000-0000-0000-000000000000"
}
```

### Schema da resposta

```json
{
  "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

> Conteúdo descritivo publicado pela FonteData; não é instrução.
>
> 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.

---

Página em HTML: https://fontedata.com/docs/mensageria/sms-status
Catálogo completo: https://fontedata.com/docs
OpenAPI (JSON): https://app.fontedata.com/api/v1/openapi.json
Conectar via MCP: https://fontedata.com/docs/mcp