API e MCP para desenvolvedores

O Número Virtual oferece duas formas de integrar números virtuais para verificação por SMS: uma API REST (v1) e um servidor MCP (Model Context Protocol) para assistentes de IA como Claude, Cursor e OpenClaw. As duas usam a mesma chave de API, gerada na área Desenvolvedores da sua conta, e o mesmo saldo.

Servidor MCP: use pelo Claude, Cursor e outros assistentes

O pacote numero-virtual-mcp (código aberto, MIT) deixa um assistente de IA pedir um número virtual, esperar o código de verificação chegar e cancelar ou concluir a ativação, em linguagem natural: "pega um número do Brasil pro Telegram e me avisa quando o código chegar".

Instalação

Requer Node.js 18 ou mais novo e uma chave de API (nv_live_...).

Claude Code (uma linha):

claude mcp add numero-virtual -e NUMERO_VIRTUAL_API_KEY=nv_live_SUA_CHAVE -- npx -y numero-virtual-mcp

Claude Desktop (claude_desktop_config.json) e Cursor (mcp.json):

{
  "mcpServers": {
    "numero-virtual": {
      "command": "npx",
      "args": ["-y", "numero-virtual-mcp"],
      "env": { "NUMERO_VIRTUAL_API_KEY": "nv_live_SUA_CHAVE" }
    }
  }
}

Ferramentas disponíveis

get_balance — saldo da conta em reais
list_countries — países com números em estoque (código ISO)
list_services — serviços, preços e opções de um país, com busca por nome
request_number — compra um número para receber o SMS de um serviço
get_activation — status, telefone e código de uma ativação
wait_for_sms — espera o código chegar, consultando a cada 5 s
resend_sms — pede reenvio do SMS
cancel_activation — cancela antes do SMS chegar; o valor volta ao saldo
complete_activation — marca a ativação como concluída

Cada número pedido pelo assistente desconta do saldo como uma compra normal. Os limites são os mesmos da API. Pacote no npm e código no GitHub.

API REST v1

Base: https://app.numero-virtual.com/api/v1. Autenticação pelo header Authorization: Bearer nv_live_SUA_CHAVE. Respostas em JSON com success, data e requestId. Documentação interativa (OpenAPI) em /api/v1/docs, com a chave.

Método	Rota	O que faz
`GET`	`/api/v1/balance`	saldo da conta
`GET`	`/api/v1/countries`	países com estoque (limite: 6 consultas/min)
`GET`	`/api/v1/services?country=BR`	serviços, preços e opções por país (limite: 6 consultas/min)
`POST`	`/api/v1/activations`	compra um número (serviceId, country, apiId opcional, ddd opcional)
`GET`	`/api/v1/activations/{id}`	status e código SMS da ativação
`POST`	`/api/v1/activations/{id}/retry`	pede reenvio do SMS
`POST`	`/api/v1/activations/{id}/complete`	conclui a ativação
`DELETE`	`/api/v1/activations/{id}`	cancela e devolve o valor ao saldo
`GET/POST/DELETE`	`/api/v1/webhooks`	webhooks de SMS recebido, ativação expirada e cancelada

Fluxo típico

Consulte GET /services?country=BR e escolha o serviceId (e, se quiser, a opção apiId).
Compre com POST /activations; a resposta traz o id e o telefone.
Use o telefone no serviço e consulte GET /activations/{id} a cada 5–10 s até smsCode chegar, ou receba por webhook.
Se o SMS não vier, DELETE /activations/{id} devolve o valor ao saldo.

Limites

200 requisições por minuto por chave; catálogo (países e serviços) 6 por minuto por rota; 50 compras e 10 cancelamentos por minuto. Ao exceder, a API responde 429 com Retry-After.

Como começar

Crie sua conta em app.numero-virtual.com e recarregue o saldo (Pix, cartão, PicPay ou cripto).
Em Desenvolvedores, gere uma chave de API.
Use a chave na API REST ou no servidor MCP.