# Enviar SMS

> Dispara um SMS para um celular brasileiro e devolve o identificador da mensagem para você acompanhar a entrega.

- **Consulta:** `sms-enviar`
- **Categoria:** Mensageria
- **Preço:** R$ 0,29 por crédito de SMS (160 caracteres)
- **Endpoint:** `POST https://app.fontedata.com/api/v1/consulta/sms-enviar`
- **Autenticação:** header `X-API-Key`
- **Página:** https://fontedata.com/docs/mensageria/sms-enviar

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

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

### Python

```python
import requests

resp = requests.post(
    "https://app.fontedata.com/api/v1/consulta/sms-enviar",
    params={"numero": "SEU_TELEFONE", "mensagem": "Seu pedido 1234 saiu para entrega.", "reference": "pedido-1234-envio"},
    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-enviar");

url.search = new URLSearchParams({
  "numero": "SEU_TELEFONE",
  "mensagem": "Seu pedido 1234 saiu para entrega.",
  "reference": "pedido-1234-envio"
}).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 |
|---|---|---|---|---|
| `numero` | telefone | sim | Celular de destino com DDI e DDD, só dígitos (ex.: 5511999999999). | formato: 55DDNNNNNNNNN |
| `mensagem` | texto | sim | Texto da mensagem. Cada 160 caracteres = 1 crédito. | `Seu pedido 1234 saiu para entrega.` |
| `reference` | texto | não | Seu identificador do envio. Repetir o mesmo valor não dispara outro SMS nem cobra de novo — use no retry. | `pedido-1234-envio` |

## Resposta

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

```json
{
  "status": "sent",
  "creditos": 1,
  "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."
    },
    "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

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

---

Página em HTML: https://fontedata.com/docs/mensageria/sms-enviar
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