> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS com número próprio e preços por país

> Envie SMS com o número que você contratou (from): o cliente vê sua linha, preço por país de destino.

<Tip>
  **Número próprio** = o SMS sai do **número que você contratou** no workspace. O cliente vê seu DDD ou seu número internacional — não um remetente genérico da plataforma. Passe o campo **`from`** na API ou escolha a linha no painel.
</Tip>

## Duas formas de enviar SMS

|              | **Compartilhado** (sem `from`)                      | **Número próprio** (com `from`)                |
| ------------ | --------------------------------------------------- | ---------------------------------------------- |
| Remetente    | Linha compartilhada da plataforma                   | **Seu** número contratado                      |
| Preço        | Fixo por tipo de envio (`full`, `standard`, `slow`) | **Por país** do destinatário                   |
| Campo na API | Omita `from`; use `options.speed`                   | `from` obrigatório; `speed` **não** vale       |
| Uso típico   | OTP em massa, campanhas em escala                   | Marca com DDD fixo, suporte, 2FA com sua linha |

Analogia: **compartilhado** é carta com remetente genérico da transportadora; **número próprio** é carta com o **logo e endereço da sua empresa** no envelope.

O número precisa estar **ACTIVE**, com SMS habilitado, contratado em [Números de telefone](/phone-numbers-api/como-funciona/quick-start).

***

## Enviar com número próprio

```http theme={null}
POST /v1/sms/messages
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

Com E.164:

```json theme={null}
{
  "from": "+5511987654321",
  "to": ["5511999887766"],
  "type": "text",
  "payload": {
    "message": "Seu pedido #8842 saiu para entrega. Acompanhe: https://loja.com/r/8842"
  }
}
```

Com ID interno do número (equivalente):

```json theme={null}
{
  "from": "clxx_phone_1",
  "to": ["5511999887766"],
  "type": "text",
  "payload": {
    "message": "Código de verificação: 739201. Não compartilhe."
  }
}
```

**Resposta (202)**

```json theme={null}
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 1,
    "messageIds": ["clsms_abc..."],
    "smsIds": ["clsms_abc..."]
  }
}
```

<Note>
  Com `from` definido, **`options.speed` é ignorado**. Full, Standard e Slow existem só no envio **compartilhado** — com sua linha, o preço depende do **país do destino**, não do tipo de envio.
</Note>

***

## Como o preço é calculado

1. A API identifica o **país** do número em `to`.
2. Consulta a tarifa em `smsOwnNumber.rates` (`GET /v1/pricing`).
3. Debita créditos (plano) ou valor pay-as-you-go **por SMS** enviado.

Exemplo de linha na tabela pública:

```json theme={null}
{
  "country": "BR",
  "countryName": "Brasil",
  "callingCode": "55",
  "credits": 24,
  "paygCents": 3,
  "available": true,
  "unavailableReason": null
}
```

País sem linha específica → usa `smsOwnNumber.fallbackCountry` (ex.: `ZZ` para resto do mundo).

Consulte a tabela completa:

```bash theme={null}
curl -s https://api.notifique.dev/v1/pricing | jq '.data.smsOwnNumber.rates[] | select(.country=="BR")'
```

Detalhes: [Consulta de preços](/guides/precos/api-de-precos).

***

## SMS recebido no seu número

Quando o cliente **responde** ao seu número, a mensagem entra como inbound:

```http theme={null}
GET /v1/sms/inbound?page=1&limit=20
Authorization: Bearer sk_live_xxxxx
```

Webhook: `sms.received` / `sms.replied` — [Eventos dos webhooks](/sms-api/como-funciona/eventos-do-webhooks).

***

## Erros comuns

| Situação                       | HTTP | `code`                      |
| ------------------------------ | ---- | --------------------------- |
| `from` inválido ou não ACTIVE  | 400  | `INVALID_FROM`              |
| Número sem SMS habilitado      | 400  | —                           |
| Destino indisponível na tabela | 400  | `DESTINATION_NOT_AVAILABLE` |
| Saldo/créditos insuficiente    | 402  | `INSUFFICIENT_BALANCE`      |

***

## Próximos passos

* [Introdução SMS](/sms-api/como-funciona/introducao): compartilhado vs número próprio
* [Quick Start](/sms-api/como-funciona/quick-start): primeiro envio
* [Números de telefone](/phone-numbers-api/como-funciona/quick-start): contratar linha com SMS