API Connection

Conecte seu sistema à nossa API

Use o domínio oficial e sua api_key nas chamadas.

Base URL

https://api.numerosvirtuais.com.br/stubs/handler_api

GETJSON / TextLatency Ready

Introdução

Todas as solicitações são GET com o parâmetro api_key. As respostas variam entre texto simples e JSON.

Formato

Ações simples e consistentes para reduzir o tempo de integração.

Latência

Otimizada para alto volume e respostas rápidas.

Segurança

Cada conta tem uma API key exclusiva. Rotacione quando necessário.

Primeiros passos

Com a API key ativa, faça sua primeira chamada.

API key

Copie sua chave no painel.

Saldo

Use getBalance para validar.

Número

Chame getNumber com país e serviço.

Endpoints

Ações disponíveis para compras, status e listagens.

GET

Consultar saldo

Retorna o saldo atual da conta.

ParâmetroTipoObrigatórioDescrição

actionstringSimgetBalance

api_keystringSimYour API key

getBalance

GET

https://api.numerosvirtuais.com.br/stubs/handler_api?action=getBalance&api_key=YOUR_API_KEY

Resposta esperada

ACCESS_BALANCE:123.45

GET

Listar países

Lista países disponíveis.

ParâmetroTipoObrigatórioDescrição

actionstringSimgetCountries

api_keystringSimYour API key

getCountries

GET

https://api.numerosvirtuais.com.br/stubs/handler_api?action=getCountries&api_key=YOUR_API_KEY

Resposta esperada

ACCESS_COUNTRIES:{"0":{"id":76,"name":"Brazil"}}

GET

Listar serviços

Lista serviços e seus IDs.

ParâmetroTipoObrigatórioDescrição

actionstringSimgetServices

api_keystringSimYour API key

getServices

GET

https://api.numerosvirtuais.com.br/stubs/handler_api?action=getServices&api_key=YOUR_API_KEY

Resposta esperada

ACCESS_SERVICES:{"wa":"WhatsApp","tg":"Telegram"}

GET

Consultar preços

Retorna preços por país/serviço.

ParâmetroTipoObrigatórioDescrição

actionstringSimgetPrices

api_keystringSimYour API key

countrynumberNãoCountry ID

servicestringNãoService code

getPrices

GET

https://api.numerosvirtuais.com.br/stubs/handler_api?action=getPrices&api_key=YOUR_API_KEY&country=76&service=wa

Resposta esperada

ACCESS_PRICES:{"wa":{"cost":1.42}}

GET

Solicitar número

Reserva um número disponível.

ParâmetroTipoObrigatórioDescrição

actionstringSimgetNumber

api_keystringSimYour API key

servicestringSimService code

countrynumberSimCountry ID

price_tierstringNãogeneralstandardpremium

getNumber

GET

https://api.numerosvirtuais.com.br/stubs/handler_api?action=getNumber&api_key=YOUR_API_KEY&service=wa&country=76

Resposta esperada

ACCESS_NUMBER:987654:5511999999999

GET

Ativação extra

Reativa o mesmo número, coloca em processamento e cobra o preço atual.

Usa o número do activationId, cobra o preço atual e coloca em processamento. Resposta igual ao getNumber.

ParâmetroTipoObrigatórioDescrição

actionstringSimgetExtraNumber

api_keystringSimYour API key

activationIdnumberSimActivation ID

getExtraNumber

GET

https://api.numerosvirtuais.com.br/stubs/handler_api?action=getExtraNumber&api_key=YOUR_API_KEY&activationId=987654

Resposta esperada

ACCESS_NUMBER:123456:5511999999999

GET

Status da ativação

Consulta o status da ativação.

ParâmetroTipoObrigatórioDescrição

actionstringSimgetStatus

api_keystringSimYour API key

idnumberSimActivation ID

getStatus

GET

https://api.numerosvirtuais.com.br/stubs/handler_api?action=getStatus&api_key=YOUR_API_KEY&id=987654

Resposta esperada

STATUS_WAIT_CODE

GET

Atualizar status

Atualiza o status da ativação.

ParâmetroTipoObrigatórioDescrição

actionstringSimsetStatus

api_keystringSimYour API key

idnumberSimActivation ID

statusnumberSim1 = complete3 = new SMS8 = cancel

setStatus

GET

https://api.numerosvirtuais.com.br/stubs/handler_api?action=setStatus&api_key=YOUR_API_KEY&id=987654&status=1

Resposta esperada

ACCESS_READY

Erros & status

Em caso de erro, a API responde com códigos padronizados.

StatusSignificado

STATUS_WAIT_CODEAguardando SMS.

STATUS_WAIT_RETRYAguardando novo SMS.

STATUS_WAIT_RESENDAguardando novo SMS.

STATUS_OKCódigo recebido.

STATUS_CANCELAtivação cancelada.

ACCESS_READYNúmero pronto para uso.

ACCESS_RETRY_GETAguardando novo SMS.

ACCESS_ACTIVATIONAtivação concluída.

ACCESS_CANCELAtivação cancelada.

BAD_KEYAPI key inválida

BAD_ACTIONAção inválida

BAD_SERVICEServiço inválido

NO_BALANCESaldo insuficiente

NO_NUMBERSNenhum número disponível

EXTRA_NO_NUMBERSAtivação indisponível para uso extra

NO_ACTIVATIONAtivação não encontrada

BAD_STATUSStatus inválido

EARLY_CANCEL_DENIEDCancelamento negado nos primeiros 2 minutos