Gótica API · v1

Números virtuais por API para revender no seu software.

Compre um número, receba o código do SMS e entregue tudo ao seu cliente — direto do seu bot, site ou plataforma. Saldo em reais, preço por ativação, sem mensalidade.

Começar agora Ver endpoints

REST JSON e protocolo handler_api (compatível com bots prontos)
109 países e 24 serviços com códigos simples
Estorno automático quando o SMS não chega

comprar número

$ curl -X POST https://seudominio.com/api/v1/activations \
     -H "X-API-Key: gsk_live_..." \
     -d '{"service":"whatsapp","country":"br"}'

HTTP/1.1 201 Created
{
  "id": "v1.8f3a91c4…",
  "phone": "+5511987654321",
  "price": 5.96,
  "currency": "BRL",
  "status": "WAITING"
}

2formatos de integração

109países disponíveis

24serviços suportados

R$ 0de mensalidade

Como começar

Três passos. Do zero à primeira ativação em poucos minutos.

Recarregue seu saldo

Crie sua conta no painel e adicione saldo por Pix ou cartão. Cada ativação desconta desse saldo — só o que você usar.

Ir para o painel →

Gere sua chave de API

Na seção Minha chave desta página, clique em Gerar nova chave. A chave aparece uma única vez — guarde em local seguro.

gsk_live_4f2a…

Compre o primeiro número

Faça um POST em /api/v1/activations com o serviço e o país. O número e o telefone chegam na resposta.

Ver exemplo completo →

Autenticação

Toda requisição autenticada leva sua chave. Sem sessão, sem cookie.

Como enviar a chave

Envie em qualquer um destes formatos. O header é o recomendado: ele não aparece em log de navegador nem em histórico.

X-API-Key: gsk_live_4f2a9c…

Authorization: Bearer gsk_live_4f2a9c…

GET /api/v1/balance?api_key=gsk_live_4f2a9c…

Cuidados com a chave

A chave dá acesso ao seu saldo. Nunca a exponha no código do front-end, em repositório público ou em print.
Use sempre HTTPS — todas as chamadas da API exigem.
Se a chave vazar, revogue no painel e gere outra. A revogação é imediata.
Cada conta pode ter até 5 chaves ativas, para separar por projeto.

Como usar

Escolha o serviço e o país: montamos o código pronto para você copiar.

Serviço País

Preço por número —

Como ler a resposta: guarde o id retornado — é ele que você usa para consultar o status, cancelar ou concluir a ativação. Depois, consulte até receber o código em code.

Sobre o preço: é um preço por ativação, estável para cada país e serviço — ele não muda no meio do jogo. O valor exato aparece no campo price da resposta e é exatamente o que sai do seu saldo.

API REST

Endereço base: https://seudominio.com/api/v1 · Respostas e erros em JSON · Valores em BRL.

GET /api/v1/balance

Saldo disponível na conta.

{ "balance": 37.50, "currency": "BRL" }

POST /api/v1/activations

Compra um número. O valor é debitado do saldo imediatamente.

Parâmetro	Tipo	Descrição
`service`	string	Código do serviço (`whatsapp`, `telegram`…)
`country`	string	Código ISO do país (`br`, `us`…)

HTTP/1.1 201 Created
{
  "id": "v1.8f3a91c4…",
  "phone": "+5511987654321",
  "price": 5.96,
  "currency": "BRL",
  "service": "whatsapp",
  "country": "br",
  "status": "WAITING",
  "createdAt": 1793812000000,
  "expiresAt": 1793812900000,
  "balance": 26.59
}

GET /api/v1/activations

Lista suas ativações recentes (use ?limit= para mudar a quantidade).

GET /api/v1/activations/:id

Consulta uma ativação. Quando o SMS chega, o status vira RECEIVED e o campo code traz o código.

{ "id": "v1.8f3a91c4…", "phone": "+5511987654321",
  "status": "RECEIVED", "code": "483920", "price": 5.96 }

POST /api/v1/activations/:id/cancel

Cancela e devolve o valor ao saldo. Liberado a partir de 2 minutos após a compra (regra das operadoras) e recusado se o SMS já tiver chegado.

POST /api/v1/activations/:id/finish

Conclui a ativação após receber o código. Útil para liberar o número imediatamente.

GET /api/v1/prices?service=&country=

Preço de uma combinação, ou de todas quando os parâmetros são omitidos.

GET /api/v1/countries · /api/v1/services

Listas completas de países e serviços com os códigos aceitos.

Estados de uma ativação

WAITING

Número reservado, aguardando o SMS.

RECEIVED

SMS entregue. O campo code tem o código.

CANCELLED

Ativação encerrada. O valor volta ao saldo.

O SMS costuma chegar em segundos. Se nada chegar em 15 minutos, a ativação expira sozinha e o valor é devolvido ao saldo automaticamente — sem você precisar chamar nada.

Compatível com bots

Mesmo formato handler_api.php usado pelos bots de ativação: respostas em texto puro, pronto para plug-and-play.

https://seudominio.com/api/v1/handler_api.php?api_key=SUA_CHAVE&action=getBalance

action	Parâmetros	Resposta
`getBalance`	—	`ACCESS_BALANCE:37.50`
`getNumber`	`service`, `country`	`ACCESS_NUMBER:ID:TELEFONE`
`getStatus`	`id`	`STATUS_WAIT_CODE` · `STATUS_OK:CODIGO` · `STATUS_CANCEL`
`setStatus`	`id`, `status=6`	`ACCESS_ACTIVATION` (concluir)
`setStatus`	`id`, `status=8`	`ACCESS_CANCEL` (cancelar + estornar)
`getPrices`	`service` e/ou `country`	JSON com os preços
`getCountries`	—	JSON de países
`getServicesList`	—	JSON de serviços
`getNumbersStatus`	—	Disponibilidade por serviço

Códigos de país e serviço

Use sempre estes códigos. Digite para filtrar.

Serviços

Países

Erros e limites

Erros sempre chegam como {"error":{"code":…,"message":…}}.

Códigos de erro

Código	HTTP	Significado
`BAD_KEY`	401	Chave ausente, inválida ou revogada
`NO_BALANCE`	402	Saldo insuficiente
`BAD_SERVICE` / `BAD_COUNTRY`	400	Código inexistente
`NO_NUMBERS`	409	Sem estoque no momento
`PRICE_CHANGED`	409	O preço do número mudou agora — nada foi cobrado, tente de novo
`NOT_FOUND`	404	Ativação inexistente ou de outra conta
`NOT_ACTIVE`	409	Ativação já finalizada
`TOO_EARLY`	429	Cancelamento antes de 2 minutos
`CANCEL_REFUSED`	409	Cancelamento recusado (SMS pode ter sido entregue)
`TOO_MANY_REQUESTS`	429	Limite de requisições ou de compras simultâneas
`DAILY_LIMIT`	429	Teto diário de ativações atingido
`TEMPORARILY_UNAVAILABLE`	503	Serviço temporariamente indisponível
`ERROR`	500	Erro interno — tente novamente

Limites por chave

Requisições: até 60 por minuto.
Compras simultâneas: até 3 em andamento.
Ativações por dia: sem teto.
Chaves por conta: 5 ativas.

Boas práticas

Consulte o status a cada 2 a 5 segundos. O SMS chega sozinho e o estorno também.
Trate 429 com espera progressiva (backoff) antes de repetir.
Guarde o id da ativação no seu banco antes de consultar.
Publique o preço ao seu cliente com sua própria margem — a API não aparece para ele.

Minha chave de API

Gere, acompanhe e revogue suas chaves. A chave é mostrada uma única vez.

Dúvidas frequentes

Preciso pagar mensalidade ou taxa de cadastro?

Não. Você paga apenas pelo número que comprar — o valor sai do seu saldo na hora da ativação.

E se o SMS não chegar?

Você não paga por ativação frustrada: se o SMS não chegar em 15 minutos, a ativação expira e o valor volta ao seu saldo automaticamente. Também pode cancelar antes, a partir de 2 minutos.

Posso definir meu próprio preço para o meu cliente?

Sim. A API trabalha nos bastidores do seu software: seu cliente vê só o seu site, o seu preço e a sua marca.

Em quais linguagens posso usar?

Em qualquer uma. A API REST fala JSON sobre HTTPS e o formato handler_api é texto puro — Node.js, PHP, Python, JavaScript, Go, C#… qualquer linguagem que faça requisições HTTP serve.

Quais formas de pagamento existem para recarregar o saldo?

Pix (aprovação em segundos) e cartão de crédito.

Minha chave pode ser usada por outra pessoa?

Quem tiver a chave usa seu saldo. Guarde-a em segredo e, se suspeitar de vazamento, revogue na hora e gere outra — a revogação vale imediatamente.

Pronto para vender números no seu software?

Recarregue o saldo, gere sua chave e faça a primeira ativação hoje.

Criar minha conta