Como usar a API de verificação por SMS com o Claude Code: guia de configuração

O Claude Code integra a verificação por SMS ao seu projeto: dê a ele a skill da API do SMS Activate App e mantenha sua chave de API em uma variável de ambiente.

O Claude Code pode integrar a verificação por SMS ao seu projeto: dê a ele a skill da API do SMS Activate App, mantenha sua chave de API em uma variável de ambiente e revise cada etapa que gasta dinheiro.

Com este guia, você faz essa configuração em cerca de dez minutos. Funciona do mesmo jeito com Codex, Cursor ou qualquer agente de código que leia arquivos e execute comandos.

O que o agente pode fazer com a API

Com uma chave, um agente de código pode fazer tudo o que o seu próprio código faz:

  • Buscar números disponíveis em um país e ver o seu preço.
  • Comprar um número privado por 28 dias, com um Idempotency-Key para que uma nova tentativa nunca cobre duas vezes.
  • Ler os SMS que chegam nele e também as chamadas: desde novembro de 2026, uma chamada curta vem com o texto dela e o código lido em voz alta nela.
  • Liberar um número ou desativar a renovação dele.
  • Configurar um webhook para que os códigos cheguem ao seu servidor sem polling.

Tarefas típicas para delegar: um teste de ponta a ponta do seu fluxo de cadastro, uma função auxiliar que espera um código no CI ou um receptor de webhook com verificação de assinatura.

Passo 1: crie uma chave e mantenha-a fora do código

  • Crie uma conta na página de cadastro e adicione saldo.
  • Crie uma chave de API pessoal na aba de chaves de API da sua conta ou no bot do Telegram.
  • Coloque a chave no seu shell ou no armazenamento de segredos do projeto, nunca em um arquivo que o agente possa commitar:

A chave gasta o seu saldo. O Claude Code lê a variável quando executa um comando e não precisa ver o valor no chat. Se a chave aparecer em um arquivo, em um commit ou em um log, revogue-a na conta e crie uma nova.

Passo 2: dê a skill ao Claude Code

O site publica um arquivo de skill pronto para agentes de código em /api-skill.md. Ele traz a URL base, as rotas, os limites e os erros que você deve tratar. Salve-o como uma skill do projeto:

O Claude Code carrega uma skill quando a tarefa corresponde à descrição dela, por exemplo “aguardar o código SMS no meu teste de cadastro”. Faça o commit do arquivo da skill se a sua equipe for usá-lo também: ele não contém nenhuma chave.

Seu agente não tem suporte a skills? Abra a documentação da API e clique no botão que copia o prompt do agente. Ele traz as mesmas regras em um único bloco de texto que você pode colar em qualquer chat.

Passo 3: defina as regras da casa

Adicione algumas linhas ao CLAUDE.md do seu projeto, para que toda sessão as siga:

A segunda regra é a mais importante. Uma compra é definitiva e não reembolsável depois que o número é emitido, então uma pessoa deve ver cada uma antes que aconteça. O Claude Code pede permissão antes de executar um comando: mantenha esse pedido ativo para os comandos que chamam a rota de compra.

Passo 4: dê uma tarefa a ele

Peça o resultado, não as chamadas à API. Por exemplo:

Adicione uma fixture do pytest que alugue um número dos EUA pela API do SMS Activate App, espere até cinco minutos por um SMS nesse número e retorne o código. Reutilize entre as execuções um único número que se renova, em vez de comprar um novo a cada vez.

Um bom resultado tem este aspecto:

  • Ele busca com GET /v1/public/numbers/search?country=US e mostra a você o número e o preço antes de comprar.
  • Ele compra com POST /v1/public/numbers e um Idempotency-Key.
  • Ele faz polling de GET /v1/public/numbers/{id}/sms a cada 5 a 15 segundos, com um timeout, ou configura um webhook.
  • Ele trata insufficientbalance, numberunavailable e rate_limited como respostas, não como erros que interrompem a execução.

Se ele inventar uma rota que não está na skill, indique o arquivo OpenAPI e peça que verifique.

Passo 5: revise antes de fazer o merge

Antes de fazer o merge do que o agente escreveu, confira quatro pontos:

  • Nenhuma chave no diff, na saída dos testes ou nos logs do CI.
  • Toda compra envia um Idempotency-Key, e uma nova tentativa o reutiliza.
  • Cada espera tem um timeout e uma mensagem de falha clara que nomeia o número.
  • O teste não compra um número novo a cada execução quando um único número renovável resolveria.

Custos que você precisa conhecer

Cada número é alugado por 28 dias pelo preço que a busca mostra e renova a partir do saldo enquanto a renovação automática estiver ativada. Desde novembro de 2026, as chamadas recebidas (por minuto) e os SMS em um número também são cobrados do saldo, a um preço por país que a API retorna como usagePricing. Consulte os preços para ver os valores atuais antes de deixar um agente executar uma suíte de testes de forma agendada.

Quando não usar

A API recebe SMS e chamadas, mas não os envia. Use-a em seus próprios apps, contas e testes. A plataforma com a qual você verifica, e não nós, decide se aceita um número. Por isso, teste um número com o serviço de destino antes de construir um pipeline sobre ele: como verificar um número antes de alugá-lo.

Próximos passos