# API de SMS para Verificação

A **API da SMS Falcon** deixa o seu sistema comprar um número, ler o código de verificação e cancelar ou concluir o pedido usando **REST e JSON**. Os preços, o saldo e o **reembolso automático** são os mesmos do site, com **90% a 98% de entrega em todos os serviços**.

- **REST + JSON** uma chave de API por conta
- **a partir de US$ 0,01** mesmos preços do site
- **Reembolso automático** quando o código não chega

## Comece a integrar em quatro passos

1. **Crie a conta e coloque saldo.** Pix a partir de R$ 15 ou cripto. O saldo é o mesmo para o site e para a API.
2. **Gere a sua chave de API.** Depois da primeira recarga confirmada, abra a área API no painel e crie a chave. Guarde a chave em segredo.
3. **Mande a chave em toda requisição.** Coloque a chave no cabeçalho **X-Api-Key** (ou em Authorization: Bearer). A URL base é https://smsfalcon.com/api/v1.
4. **Compre um número e consulte o código.** Crie um pedido e leia esse pedido até o SMS aparecer na lista de mensagens.

## Endpoints da API

Todos os caminhos partem de **https://smsfalcon.com/api/v1**.

| Método e caminho | O que faz |
|---|---|
| GET /balance | O seu saldo em dólares e o valor reservado em pedidos abertos |
| GET /services | Todos os apps para os quais dá para comprar número, com o preço inicial de cada um |
| GET /services/{product}/countries | Os países e os preços de um app |
| POST /orders | Compra um número: envie o product e, se quiser, o country |
| GET /orders | Os seus pedidos recentes |
| GET /orders/{id} | Um pedido, com as mensagens SMS que ele recebeu |
| POST /orders/{id}/resend | Pede outro SMS no mesmo número ativo, sem custo extra |
| POST /orders/{id}/finish | Encerra o pedido depois que você usou o código |
| POST /orders/{id}/cancel | Cancela antes de o código chegar; o valor reservado volta para o saldo |
| POST /orders/{id}/ban | Devolve um número que o app recusou; reembolsado se nenhum código chegou |

## Exemplo de requisição e resposta

Compra de um número para WhatsApp do Reino Unido e leitura do código. Os valores dos campos são só exemplos.

| Etapa | O que você envia ou recebe |
|---|---|
| Requisição | POST https://smsfalcon.com/api/v1/orders com o cabeçalho X-Api-Key e o corpo {"product": "whatsapp", "country": "gb"} |
| Resposta | 201 com o pedido: id, phone, product, country, price, status, expires e a lista messages vazia |
| Consulta | GET https://smsfalcon.com/api/v1/orders/{id} a cada poucos segundos |
| O código chega | messages traz sender, text, code e received_at; depois chame finish |
| Sem código | Quando o número expira, o valor reservado volta sozinho para o seu saldo |

## Códigos de status que a API devolve

| Código | Significado | O que fazer |
|---|---|---|
| 201 | Pedido criado | Consulte o pedido até as mensagens aparecerem |
| 401 | Chave de API ausente ou inválida | Confira o cabeçalho X-Api-Key |
| 402 | Saldo insuficiente | Coloque saldo e tente de novo |
| 404 | App ou pedido desconhecido | Confira o nome do product em /services |
| 409 | Sem número para esse app e país agora | Tente outro país |
| 429 | Requisições demais (mais de 500 compras por minuto) | Diminua o ritmo e tente de novo |

## Como a cobrança funciona pela API

- **Reservado, cobrado só na entrega.** A compra reserva o preço no seu saldo. A cobrança só acontece quando um SMS chega.
- **Reembolso automático.** Sem código até o número expirar, ou cancelamento antes do código: o valor reservado volta.
- **Outro SMS sem custo.** Enquanto o número está ativo, o /resend pede um novo código nele.
- **Mesmos preços do site.** A partir de US$ 0,01; WhatsApp a partir de US$ 0,32.

## Limites e regras da API

- Uma chave de API por conta. Você pode revogar a chave e criar outra pelo painel.
- O código é lido consultando o pedido. A API não envia avisos automáticos para o seu servidor.
- Até 500 compras por minuto em cada conta.
- Os números recebem só SMS, não recebem ligações.
- Use a API nos seus próprios apps, em QA e em testes, dentro dos [termos de uso](https://smsfalcon.com/pt/termos).

## A API da SMS Falcon em uma tabela

| | |
|---|---|
| URL base | https://smsfalcon.com/api/v1 |
| Autenticação | Cabeçalho X-Api-Key, uma chave por conta |
| Cobertura | 265 apps em 156+ países |
| Entrega | 90% a 98% em todos os serviços |
| Se o código não chegar | Reembolso automático para o saldo |
| Pagamento | Pix a partir de R$ 15 ou cripto |

## Páginas relacionadas

- [Como funciona uma ativação](https://smsfalcon.com/pt/ativacao-sms) (reservada, cobrada ou devolvida)
- [Preços em CSV ou JSON](https://smsfalcon.com/pt/dados) (para as suas ferramentas)
- [Ficar com o número por mais tempo](https://smsfalcon.com/pt/aluguel-de-numero) (aluguel)

## Perguntas sobre a API de SMS

### O que é a API da SMS Falcon?

É uma API REST que deixa o seu sistema comprar números virtuais e ler os códigos de verificação por SMS que eles recebem, com os mesmos preços e reembolsos do site.

### Como consigo uma chave de API?

Coloque saldo na conta uma vez e depois crie a chave na área API do seu painel.

### Quanto custa usar a API?

Não existe taxa de API. Você paga o mesmo preço por número do site, a partir de US$ 0,01.

### Como recebo o código pela API?

Leia o pedido com GET /orders/{id} até a lista messages trazer o SMS. O código vem no campo code.

### E se nenhum código chegar?

O valor reservado volta sozinho para o seu saldo quando o número expira. Cancelar antes do código também devolve o valor.

### Posso pedir outro código no mesmo número?

Sim, com POST /orders/{id}/resend enquanto o número estiver ativo, sem custo extra.

### A API tem limite de requisições?

Tem: até 500 compras por minuto em cada conta. Se receber um 429, diminua o ritmo.

### Dá para escolher o país do número?

Sim. Envie o país como código ISO, por exemplo gb, ou deixe o campo de fora para usar o padrão.

### Os números recebem ligações?

Não. Eles recebem só mensagens de texto.

### Para que posso usar a API?

Para os seus próprios apps, QA e testes, dentro dos nossos termos. Ela não serve para driblar as checagens ou as regras de nenhum app.

### Como coloco saldo para usar a API?

Com Pix, a partir de R$ 15, ou com cripto. O saldo da conta vale para o site e para a API.

Fonte: https://smsfalcon.com/pt/api-de-sms · Atualizado em 2026-11-05