# Documentação da API da SMS Nitro

Tudo o que você precisa para comprar um número temporário, ler o código de verificação e encerrar o pedido pelo seu próprio código. JSON sobre HTTPS, uma chave de API, os mesmos preços e a mesma regra de cobrança do painel.

## Como funciona a API da SMS Nitro?

Você envia POST /v1/orders com o app e o país e recebe um número de telefone. Depois consulta GET /v1/orders/{id} a cada 3 a 5 segundos até o SMS aparecer em messages e chama finish. Se o SMS não chegar, cancele e o valor reservado volta para o saldo: você só paga pelos códigos que chegam.

## Começo rápido em quatro chamadas

1. **Gere a chave** Faça a primeira recarga, abra Painel > API e gere sua chave. Envie no cabeçalho X-Api-Key.
2. **Compre um número** POST /v1/orders com product e country. O preço fica reservado no seu saldo.
3. **Leia o código** Consulte GET /v1/orders/{id} a cada 3 a 5 segundos até messages trazer o SMS.
4. **Encerre o pedido** POST finish quando o código funcionou, ou cancel quando nada chegou, para receber o estorno.

## A API em resumo

| Item | Valor |
|---|---|
| URL base | https://smsnitro.com/api/v1 |
| Formato | JSON sobre HTTPS, UTF-8. Preços em string decimal (USD), datas em ISO 8601 (UTC) |
| Autenticação | Cabeçalho X-Api-Key, ou Authorization: Bearer |
| Cobrança | Preço reservado na compra, cobrado só quando o SMS chega, estornado caso contrário |
| Validade do número | Até 20 minutos por ativação |
| Limites | 500 compras por minuto, 30 pedidos de reenvio por minuto |
| Especificação | OpenAPI 3.1 em /developers/openapi.json |

## Sua primeira requisição

Confira se a chave funciona lendo o saldo. Uma resposta 200 com balance e frozen significa que você já pode comprar números. Frozen é o valor reservado pelos pedidos que ainda aguardam SMS.

**Requisição**

```bash
curl https://smsnitro.com/api/v1/balance \
  -H "X-Api-Key: $SMSNITRO_API_KEY"
```

**Resposta**

```json
{
  "balance": "12.50",
  "frozen": "0.45",
  "currency": "USD"
}
```

## FAQ

**Existe ambiente de testes (sandbox)?** Não. As chamadas usam o catálogo real, mas nada é cobrado sem SMS, então testar o fluxo completo custa apenas os códigos que você recebe de fato.

**O preço pela API é diferente do painel?** Não. A API usa o mesmo catálogo, os mesmos preços e o mesmo saldo do site, sem acréscimo.

**Onde fica a especificação OpenAPI?** O documento OpenAPI 3.1 dos endpoints públicos está em https://smsnitro.com/developers/openapi.json. Importe no Postman, no Insomnia ou num gerador de código.

**Como consigo uma chave de API?** Crie a conta, faça a primeira recarga e gere a chave em Painel > API. Cada conta tem uma chave ativa.

## Artigos

- [Autenticação](https://smsnitro.com/pt/desenvolvedores/autenticacao): Como autenticar na API da SMS Nitro: onde gerar a chave, os cabeçalhos X-Api-Key e Bearer, como trocar a chave e por que ela nunca deve ir para o front-end.
- [Referência de endpoints](https://smsnitro.com/pt/desenvolvedores/endpoints): Todos os endpoints da API REST v1 da SMS Nitro: saldo, serviços, países, pedidos, finish, cancel, resend e ban, com parâmetros, chamadas curl e respostas JSON.
- [Ciclo do pedido e cobrança](https://smsnitro.com/pt/desenvolvedores/ciclo-do-pedido): O que significa cada status de pedido na SMS Nitro, quando o saldo é cobrado ou estornado, quanto dura o número e quando concluir, cancelar ou reenviar.
- [Erros e limites de uso](https://smsnitro.com/pt/desenvolvedores/erros): Os códigos HTTP que a API da SMS Nitro retorna (400, 401, 402, 404, 409, 429, 502), o que cada um significa, os limites de uso e uma estratégia de nova tentativa.
- [Verificação por SMS em Python](https://smsnitro.com/pt/desenvolvedores/python): Receba códigos de verificação por SMS em Python com a API da SMS Nitro e requests: compre o número, espere o código, conclua ou cancele. Script completo.
- [Verificação por SMS em Node.js](https://smsnitro.com/pt/desenvolvedores/nodejs): Receba códigos de verificação por SMS no Node.js 18+ com fetch e a API da SMS Nitro: compre o número, espere o código, conclua ou cancele. Com tipos TypeScript.
- [Verificação por SMS em PHP](https://smsnitro.com/pt/desenvolvedores/php): Receba códigos de verificação por SMS em PHP 8 com cURL e a API da SMS Nitro: compre o número, espere o código, conclua ou cancele. Script completo para copiar.

Fonte: https://smsnitro.com/pt/desenvolvedores