API para desenvolvedores

A API permite revender números temporários para receber SMS no seu próprio site ou aplicativo. O cliente final não precisa visitar o Ativa SMS.

Crie uma conta e peça acesso em Revender números, no menu do perfil do dashboard. O aceite dos Termos de revenda é condição para o acesso; os Termos de uso também valem. Após a liberação, crie as chaves em Dashboard → API.

Base URL: https://www.ativasms.store/api/v1. Envie JSON UTF-8 com Content-Type: application/json nos corpos. As respostas são JSON e incluem Cache-Control: no-store.

Valores monetários são inteiros em centavos: moeda indica BRL ou USD conforme a conta; 83 em BRL significa R$ 0,83. No teste, a moeda é sempre BRL. Datas são ISO 8601 UTC. Telefone vem em formato internacional com +DDI, ou null enquanto a reserva está em andamento.

Os exemplos são ilustrativos, usam o formato real das rotas e, nas compras, dados fictícios do modo test. Use códigos e opções retornados pela API; os preços live variam. Os comandos curl usam uma variável de ambiente do seu servidor: ATIVA_API_KEY.

Especificação OpenAPI 3.1, para ferramentas e agentes de IA: /openapi.json.

Envie Authorization: Bearer <chave> em todas as rotas. Chaves começam com ativa_live_ (produção) ou ativa_test_ (teste). Não envie a chave em query ou corpo.

A chave aparece uma única vez ao criar. Guarde-a somente no servidor do revendedor, nunca no navegador nem no aplicativo do cliente. Há até 5 chaves ativas por conta, somando live e test. Se perder ou expor uma chave, revogue e crie outra no dashboard. Uma restrição de IP configurada também precisa ser respeitada.

Falhas de autenticação devolvem o mesmo HTTP 401, sem revelar o motivo:

{
  "erro": "nao_autorizado",
  "mensagem": "Chave de API ausente, inválida ou revogada."
}

Valores padrão, ajustáveis por revendedor; veja os limites da sua conta no dashboard:

Limite	Padrão
Pedidos por minuto	120
Compras/trocas por minuto	20
Números aguardando SMS ao mesmo tempo	20
Tentativas sem código em 24 h por conta	100
Tentativas sem código em 24 h por cliente_ref	15

Pedidos e compras somam todas as chaves da conta do mesmo modo. Teste e produção têm contagens separadas e os mesmos tetos configurados. Cancelados, trocados e expirados sem SMS consomem tentativas; cada número com código libera 5 tentativas, até o teto. Falhas de entrega não contam. Na produção, os limites de abertos/tentativas da conta também abrangem suas compras pelo site.

Ao exceder pedidos/compras por minuto, há HTTP 429 muitas_requisicoes com Retry-After: 60 (segundos). Os demais limites devolvem 429 com o código específico, sem Retry-After: aguarde liberação de números ou de tentativas, conforme o caso.

Idempotency-Key é obrigatório em compra e troca: 1–64 caracteres, letras, dígitos e . _ : -. Use uma chave nova para cada operação desejada e a mesma chave em retentativas. A chave pertence à conta e ao modo; compra e troca compartilham esse espaço. Não reutilize uma chave para outro cliente ou pedido.

Repetir uma chave já registrada retorna HTTP 200, o mesmo número e seu estado atual, mesmo que o corpo tenha mudado; compra nova retorna 201. A consulta live não limita a repetição a 24 h: enquanto o registro existir, a chave retorna aquele número. No teste, o histórico é retido por 30 dias. Reiniciar o saldo de teste preserva idempotência e histórico.

preco_maximo_centavos é o maior débito que você aceita na moeda da conta. Se o preço atual estiver acima, a API retorna preco_acima_do_maximo, com preco_centavos e opcoes, sem comprar. preco_centavos é o valor que sai do seu saldo; preco_site_centavos é o preço de referência no site. O preço é conferido novamente na compra.

GET /saldo

Sem parâmetros. Retorna o saldo na moeda da conta (BRL ou USD). No teste, sempre BRL e saldo fictício.

curl "https://www.ativasms.store/api/v1/saldo" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

{
  "saldo_centavos": 10000,
  "moeda": "BRL"
}

GET /servicos

Sem parâmetros. Retorna a lista completa de serviços permitidos, sem duplicatas nem serviços bloqueados. O exemplo mostra um item; no teste, a lista também inclui teste_falha (Teste sem código). Os nomes e campos da API permanecem em português nos dois idiomas do site.

curl "https://www.ativasms.store/api/v1/servicos" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

[
  {
    "codigo": "wa",
    "nome": "WhatsApp"
  }
]

GET /paises

Sem parâmetros. Retorna todos os países. Use codigo nas consultas e compras; iso é maiúsculo e ddi é o código de discagem. O exemplo mostra um item.

curl "https://www.ativasms.store/api/v1/paises" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

[
  {
    "codigo": 73,
    "iso": "BR",
    "nome": "Brasil",
    "ddi": "+55"
  }
]

GET /opcoes

Query obrigatória: servico (código da lista de serviços) e pais (código numérico da lista de países). Retorna até 6 opções, ordenadas pelo preco_centavos crescente; pode retornar []. opcao é um identificador opaco no formato op_ seguido de 12 caracteres hexadecimais: use o valor devolvido, sem interpretá-lo. preco_centavos é o débito do revendedor; preco_site_centavos é a referência do site, ambos na moeda indicada. prazo_min é o prazo; taxa_sucesso pode ser null; estoque indica disponibilidade e recomendada indica a sugestão. O exemplo usa a opção fictícia do modo test.

curl "https://www.ativasms.store/api/v1/opcoes?servico=wa&pais=73" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

[
  {
    "opcao": "op_000000000001",
    "preco_centavos": 83,
    "preco_site_centavos": 120,
    "moeda": "BRL",
    "prazo_min": 20,
    "taxa_sucesso": null,
    "estoque": 100,
    "recomendada": false
  }
]

POST /numeros

Corpo JSON obrigatório: servico (1–20 letras minúsculas, dígitos ou _; serviço permitido), pais (inteiro válido do catálogo), preco_maximo_centavos (inteiro positivo) e cliente_ref (identificador anônimo de 1–64 caracteres: letras, dígitos, . _ : -; nunca e-mail ou CPF). opcao é opcional ou null; sem ela, escolhe a mais barata. Envie Idempotency-Key. Compra nova: 201; repetição: 200 com o mesmo id e estado atual, sem novo débito. O exemplo é uma compra test.

curl -X POST "https://www.ativasms.store/api/v1/numeros" \
  -H "Authorization: Bearer $ATIVA_API_KEY" \
  -H "Idempotency-Key: compra_abc123" \
  -H "Content-Type: application/json" \
  -d '{"servico":"wa","pais":73,"opcao":"op_000000000001","preco_maximo_centavos":83,"cliente_ref":"cliente_abc123"}'

HTTP 201

{
  "id": "5f0c0000-0000-4000-8000-000000000001",
  "servico": "wa",
  "servico_nome": "WhatsApp",
  "pais": 73,
  "telefone": "+12025550123",
  "status": "aguardando_sms",
  "motivo": null,
  "preco_centavos": 83,
  "preco_site_centavos": 120,
  "moeda": "BRL",
  "criado_em": "2026-10-08T12:00:00.000Z",
  "cancelavel_em": "2026-10-08T12:02:00.000Z",
  "expira_em": "2026-10-08T12:20:00.000Z",
  "encerrado_em": null,
  "substitui_id": null,
  "cliente_ref": "cliente_abc123",
  "sms": []
}

GET /numeros/{id}

Caminho: /numeros/{id}, com o UUID do número. Retorna apenas um número comprado pela API desta conta e deste modo; outro dono, compra pelo site ou UUID inválido resulta em nao_encontrado. Números abertos são atualizados antes da resposta, até 60 atualizações/min por chave live; acima disso, a resposta usa o último estado disponível (200, sem um novo 429 de sincronização). O exemplo mostra o código de teste recebido.

curl "https://www.ativasms.store/api/v1/numeros/5f0c0000-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

{
  "id": "5f0c0000-0000-4000-8000-000000000001",
  "servico": "wa",
  "servico_nome": "WhatsApp",
  "pais": 73,
  "telefone": "+12025550123",
  "status": "recebido",
  "motivo": null,
  "preco_centavos": 83,
  "preco_site_centavos": 120,
  "moeda": "BRL",
  "criado_em": "2026-10-08T12:00:00.000Z",
  "cancelavel_em": "2026-10-08T12:02:00.000Z",
  "expira_em": "2026-10-08T12:20:00.000Z",
  "encerrado_em": null,
  "substitui_id": null,
  "cliente_ref": "cliente_abc123",
  "sms": [
    {
      "codigo": "123456",
      "texto": "Seu código de teste: 123456",
      "recebido_em": "2026-10-08T12:00:20.000Z"
    }
  ]
}

GET /numeros

Query opcional: status (um dos estados documentados), cliente_ref (mesmo formato da compra), pagina (1–1000, padrão 1). Retorna até 50 números por página, mais recentes primeiro, somente das compras pela API desta conta e modo. tem_mais indica outra página. A lista não força a atualização de números live; consulte o número individual para isso.

curl "https://www.ativasms.store/api/v1/numeros?status=aguardando_sms&cliente_ref=cliente_abc123&pagina=1" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

{
  "numeros": [
    {
      "id": "5f0c0000-0000-4000-8000-000000000001",
      "servico": "wa",
      "servico_nome": "WhatsApp",
      "pais": 73,
      "telefone": "+12025550123",
      "status": "aguardando_sms",
      "motivo": null,
      "preco_centavos": 83,
      "preco_site_centavos": 120,
      "moeda": "BRL",
      "criado_em": "2026-10-08T12:00:00.000Z",
      "cancelavel_em": "2026-10-08T12:02:00.000Z",
      "expira_em": "2026-10-08T12:20:00.000Z",
      "encerrado_em": null,
      "substitui_id": null,
      "cliente_ref": "cliente_abc123",
      "sms": []
    }
  ],
  "pagina": 1,
  "tem_mais": false
}

POST /numeros/{id}/cancelar

Caminho: /numeros/{id}/cancelar. Corpo: motivo opcional (desistiu, banido, ja_tem_dono, pede_outra_coisa ou outro; padrão outro). Sem código e após cancelavel_em, encerra e estorna ao saldo. Antes do mínimo: 409 cedo com segundos. Se já está recebido, responde nao_cancelavel; codigo_recebido pode ocorrer se o código chegar durante o cancelamento. Resposta 200 com o número encerrado. O exemplo usa teste_falha, após dois minutos.

curl -X POST "https://www.ativasms.store/api/v1/numeros/5f0c0000-0000-4000-8000-000000000001/cancelar" \
  -H "Authorization: Bearer $ATIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"motivo":"desistiu"}'

HTTP 200

{
  "id": "5f0c0000-0000-4000-8000-000000000001",
  "servico": "teste_falha",
  "servico_nome": "Teste sem código",
  "pais": 73,
  "telefone": "+12025550123",
  "status": "cancelado",
  "motivo": "desistiu",
  "preco_centavos": 83,
  "preco_site_centavos": 120,
  "moeda": "BRL",
  "criado_em": "2026-10-08T12:00:00.000Z",
  "cancelavel_em": "2026-10-08T12:02:00.000Z",
  "expira_em": "2026-10-08T12:20:00.000Z",
  "encerrado_em": "2026-10-08T12:02:01.000Z",
  "substitui_id": null,
  "cliente_ref": "cliente_abc123",
  "sms": []
}

POST /numeros/{id}/trocar

Caminho: /numeros/{id}/trocar. Corpo: preco_maximo_centavos obrigatório (inteiro positivo); opcao e motivo opcionais, nos formatos acima. Serviço, país e cliente_ref são herdados do número original. Exige Idempotency-Key e um número aguardando_sms com telefone e sem código, após o mínimo de cancelamento. Confere o preço antes de encerrar o antigo. O antigo fica trocado e estornado; o novo é comprado com 201 (repetição: 200). Se a compra nova falhar depois do estorno, o antigo permanece trocado: consulte-o e trate o erro. O exemplo troca teste_falha após dois minutos.

curl -X POST "https://www.ativasms.store/api/v1/numeros/5f0c0000-0000-4000-8000-000000000001/trocar" \
  -H "Authorization: Bearer $ATIVA_API_KEY" \
  -H "Idempotency-Key: troca_abc123" \
  -H "Content-Type: application/json" \
  -d '{"preco_maximo_centavos":83,"motivo":"banido"}'

HTTP 201

{
  "id": "5f0c0000-0000-4000-8000-000000000002",
  "servico": "teste_falha",
  "servico_nome": "Teste sem código",
  "pais": 73,
  "telefone": "+12025550124",
  "status": "aguardando_sms",
  "motivo": null,
  "preco_centavos": 83,
  "preco_site_centavos": 120,
  "moeda": "BRL",
  "criado_em": "2026-10-08T12:02:01.000Z",
  "cancelavel_em": "2026-10-08T12:04:01.000Z",
  "expira_em": "2026-10-08T12:22:01.000Z",
  "encerrado_em": null,
  "substitui_id": "5f0c0000-0000-4000-8000-000000000001",
  "cliente_ref": "cliente_abc123",
  "sms": []
}

POST /numeros/{id}/concluir

Caminho: /numeros/{id}/concluir. Sem corpo. Confirma que o código foi usado e encerra um número recebido, sem estorno. Retorna 200 com o número concluido; concluir novamente ou concluir sem código devolve 409 nao_concluivel.

curl -X POST "https://www.ativasms.store/api/v1/numeros/5f0c0000-0000-4000-8000-000000000001/concluir" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

{
  "id": "5f0c0000-0000-4000-8000-000000000001",
  "servico": "wa",
  "servico_nome": "WhatsApp",
  "pais": 73,
  "telefone": "+12025550123",
  "status": "concluido",
  "motivo": null,
  "preco_centavos": 83,
  "preco_site_centavos": 120,
  "moeda": "BRL",
  "criado_em": "2026-10-08T12:00:00.000Z",
  "cancelavel_em": "2026-10-08T12:02:00.000Z",
  "expira_em": "2026-10-08T12:20:00.000Z",
  "encerrado_em": "2026-10-08T12:01:00.000Z",
  "substitui_id": null,
  "cliente_ref": "cliente_abc123",
  "sms": [
    {
      "codigo": "123456",
      "texto": "Seu código de teste: 123456",
      "recebido_em": "2026-10-08T12:00:20.000Z"
    }
  ]
}

GET /extrato

Query opcional: pagina (1–1000, padrão 1). Retorna até 50 movimentações da conta, mais recentes primeiro (compra, estorno, recarga, ajuste), incluindo operações pelo site no modo live. valor_centavos é assinado: negativo para débito, positivo para crédito; saldo_apos_centavos é o saldo após a movimentação. numero_id é null quando não está ligado a um número; descricao pode ser null. O extrato não inclui moeda: use a moeda de GET /saldo. No teste, o extrato é separado, sempre em BRL.

curl "https://www.ativasms.store/api/v1/extrato?pagina=1" \
  -H "Authorization: Bearer $ATIVA_API_KEY"

HTTP 200

{
  "movimentacoes": [
    {
      "id": 42,
      "tipo": "compra",
      "valor_centavos": -83,
      "saldo_apos_centavos": 9917,
      "descricao": "Número WhatsApp",
      "numero_id": "5f0c0000-0000-4000-8000-000000000001",
      "criado_em": "2026-10-08T12:00:00.000Z"
    }
  ],
  "pagina": 1,
  "tem_mais": false
}

Depois da compra, mostre o telefone ao cliente e peça que ele solicite o código no aplicativo de destino. Comprar um número não solicita o SMS automaticamente. O modo de teste simula essa chegada.

Status	Significado
aguardando_sms	Aguardando; telefone null pode indicar reserva em andamento.
recebido	Pelo menos um SMS chegou; não cancela nem troca.
concluido	Encerrado após receber código, manualmente ou pelo prazo.
cancelado	Cancelado sem código, com estorno.
trocado	Número anterior encerrado e estornado durante uma troca.
expirado	Prazo acabou sem código; estorno automático.
falhou	Compra/entrega falhou; valor devolvido.

O objeto do número inclui servico_nome, motivo, moeda, preco_site_centavos (pode ser null), encerrado_em, substitui_id (id anterior na troca) e sms. Datas de cancelamento, expiração e encerramento podem ser null; cada SMS contém codigo e texto (podem ser null) e recebido_em.

Respeite cancelavel_em: algumas opções permitem cancelar imediatamente, outras após 2 min. O erro cedo informa a espera:

{
  "erro": "cedo",
  "mensagem": "Este número ainda não pode ser cancelado. Tente de novo após `segundos`.",
  "segundos": 45
}

Sem SMS no prazo, o estorno é automático ao saldo; em produção, pode haver tolerância de 5 min para SMS atrasados antes do encerramento. Use expira_em e o estado retornado. Com código, concluir encerra sem estorno; número já recebido não cancela, e a troca também é recusada. Na troca, uma falha na nova compra pode deixar o anterior trocado e estornado.

Erros têm erro e mensagem (em português); trate o código, não o texto. Campos extras podem incluir campos, segundos, preco_centavos e opcoes.

Código	HTTP	Quando ocorre
nao_autorizado	401	Chave ausente, inválida, revogada, IP não permitido ou acesso suspenso; resposta genérica, sem revelar a causa.
parametro_invalido	400	Campo, query ou corpo inválido; pode incluir campos com os nomes a corrigir.
servico_bloqueado	400	Serviço bloqueado solicitado.
idempotencia_obrigatoria	400	Idempotency-Key ausente ou fora do formato permitido, na compra ou troca.
saldo_insuficiente	402	Saldo insuficiente para a compra.
cliente_bloqueado	403	cliente_ref bloqueado para esta conta.
nao_encontrado	404	UUID inválido ou número indisponível para esta conta e modo.
sem_numeros	409	Nenhuma opção disponível para o serviço e país; nenhum débito.
opcao_indisponivel	409	A opção escolhida saiu da lista; inclui opcoes atuais.
preco_acima_do_maximo	409	Preço atual acima do máximo; inclui preco_centavos e opcoes, sem débito.
preco_subiu	409	Preço mudou durante a compra; valor devolvido ao saldo.
cedo	409	Ainda não pode cancelar/trocar; inclui segundos de espera.
codigo_recebido	409	Código recebido impede a troca, ou chegou durante o cancelamento.
nao_cancelavel	409	Estado não permite cancelar, inclusive um número já recebido.
nao_trocavel	409	Número sem telefone, encerrado ou em estado incompatível com troca.
nao_concluivel	409	Número não está recebido, inclusive uma segunda conclusão.
muitas_requisicoes	429	Teto de pedidos ou compras por minuto; Retry-After: 60.
limite_abertas	429	Teto de números aguardando SMS atingido; sem Retry-After.
limite_tentativas	429	Tentativas sem código da conta esgotadas em 24 h; sem Retry-After.
limite_tentativas_cliente	429	Tentativas sem código deste cliente_ref esgotadas em 24 h; sem Retry-After.
erro_fornecedor	502	Falha na entrega do número; valor devolvido ao saldo.
sem_confirmacao	502	Compra sem confirmação; consulte repetindo a mesma Idempotency-Key. Sem número em 10 min, há estorno.
erro_interno	500	Falha inesperada; tente novamente com idempotência nas compras/trocas.

Configure uma URL HTTPS pública em Dashboard → API. Não são aceitos endereços internos, credenciais ou fragmentos na URL, nem redirecionamentos. O segredo aparece uma vez ao criar ou regerar; guarde-o no servidor. Alterar apenas a URL mantém o segredo; remover apaga a configuração. Cada tentativa usa a URL e o segredo atuais.

Eventos enviados por POST JSON:

• numero.codigo_recebido: um aviso por SMS novo; dados.sms é um objeto com codigo, texto e recebido_em, e não a lista de SMS. Pode haver mais de um aviso por número, inclusive SMS atrasado após encerramento.
• numero.encerrado: concluido, cancelado, trocado, expirado ou falhou; inclui motivo (pode ser null), encerrado_em e estornado_centavos (zero se não houve estorno), na moeda indicada.
• teste.ping: teste de entrega solicitado no dashboard, sem número nem cobrança.

O envelope tem id (UUID do aviso, diferente de dados.id), evento, criado_em e dados. Eventos de números incluem id, cliente_ref, servico, pais, telefone (ou null), status e moeda em dados. Eventos de números de teste incluem modo: "test" no envelope; eventos live e o ping do dashboard não incluem esse campo. Exemplos:

{
  "id": "a7100000-0000-4000-8000-000000000001",
  "evento": "numero.codigo_recebido",
  "criado_em": "2026-10-08T12:00:20.000Z",
  "modo": "test",
  "dados": {
    "id": "5f0c0000-0000-4000-8000-000000000001",
    "cliente_ref": "cliente_abc123",
    "servico": "wa",
    "pais": 73,
    "telefone": "+12025550123",
    "status": "recebido",
    "moeda": "BRL",
    "sms": {
      "codigo": "123456",
      "texto": "Seu código de teste: 123456",
      "recebido_em": "2026-10-08T12:00:20.000Z"
    }
  }
}

{
  "id": "a7100000-0000-4000-8000-000000000002",
  "evento": "numero.encerrado",
  "criado_em": "2026-10-08T12:20:00.000Z",
  "modo": "test",
  "dados": {
    "id": "5f0c0000-0000-4000-8000-000000000001",
    "cliente_ref": "cliente_abc123",
    "servico": "teste_falha",
    "pais": 73,
    "telefone": "+12025550123",
    "status": "expirado",
    "moeda": "BRL",
    "motivo": "prazo",
    "encerrado_em": "2026-10-08T12:20:00.000Z",
    "estornado_centavos": 83
  }
}

{
  "id": "a7100000-0000-4000-8000-000000000003",
  "evento": "teste.ping",
  "criado_em": "2026-10-08T12:00:00.000Z",
  "dados": {
    "mensagem": "Teste de webhook do Ativa SMS"
  }
}

Cabeçalhos:

• X-Ativa-Evento: nome do evento.
• X-Ativa-Timestamp: timestamp Unix em segundos, atualizado a cada tentativa.
• X-Ativa-Assinatura: HMAC-SHA256 em hexadecimal minúsculo, calculado sobre os bytes UTF-8 de timestamp + "." + corpo, usando o segredo como texto, sem decodificá-lo de hexadecimal.

Confira o corpo bruto, antes de interpretar o JSON; serializar de novo pode mudar a assinatura. Recuse timestamps cuja diferença do horário atual exceda 5 minutos, para o passado ou futuro. Compare com crypto.timingSafeEqual, conferindo o tamanho primeiro. Exemplo Node.js, com Request/Headers e um Buffer do corpo original:

import { createHmac, timingSafeEqual } from "node:crypto";

export function verificarWebhook(headers, corpoBruto, segredo) {
  const timestamp = headers.get("x-ativa-timestamp") ?? "";
  const assinatura = headers.get("x-ativa-assinatura") ?? "";
  if (!/^\d{1,12}$/.test(timestamp)) return false;
  const agora = Math.floor(Date.now() / 1000);
  if (Math.abs(agora - Number(timestamp)) > 300) return false;
  if (!/^[0-9a-f]{64}$/.test(assinatura)) return false;
  const esperada = createHmac("sha256", segredo)
    .update(timestamp + ".", "utf8")
    .update(corpoBruto)
    .digest();
  const recebida = Buffer.from(assinatura, "hex");
  return recebida.length === esperada.length
    && timingSafeEqual(recebida, esperada);
}

export async function lerAviso(request, segredo) {
  const corpoBruto = Buffer.from(await request.arrayBuffer());
  if (!verificarWebhook(request.headers, corpoBruto, segredo)) {
    throw new Error("assinatura_invalida");
  }
  return JSON.parse(corpoBruto.toString("utf8"));
}

Após verificar, deduplique pelo id do aviso em armazenamento persistente e registre o recebimento para processar depois. Responda 2xx rapidamente; duplicatas já aceitas também devem receber 2xx. O timeout de entrega é 5 s. Não há garantia de entrega exatamente uma vez: perder a resposta pode causar repetição.

Até 8 tentativas totais. Após falhas 1–7, as esperas são 1, 2, 4, 8, 16, 32 e 64 min, contadas da finalização da tentativa; a entrega é verificada a cada minuto. Só HTTP 2xx confirma entrega; 3xx, outros erros e timeout provocam retentativa. Após a oitava falha, não há reenvio automático. O id e o corpo permanecem iguais entre tentativas; apenas o timestamp e a assinatura são renovados. Se faltar um aviso, consulte GET /numeros/{id}.

Crie uma chave ativa_test_ no dashboard e use as mesmas rotas e URL. Nada real é cobrado. O saldo fictício inicial é R$ 100,00 (10000 centavos, BRL), independente da moeda real da conta. A opção é op_000000000001: preço fictício R$ 0,83, referência do site R$ 1,20, prazo 20 min e cancelamento após 2 min.

Os telefones são fictícios da faixa +1 202 555-01xx, retornados sem espaços, como +12025550123; o país escolhido continua em pais. O código 123456 fica disponível após 20 s; consultar o número após esse instante atualiza o estado, e o aviso automático pode chegar no minuto seguinte.

Use servico=teste_falha para nunca receber código e testar cancelar, trocar (após 2 min) ou expirar (após 20 min), com estorno fictício. Sem esse serviço, o código chega antes do cancelamento mínimo. Número test com código vira concluido ao expirar.

No dashboard, reinicie o saldo em R$ 100,00: números abertos sem código são cancelados; com código, concluídos. O reinício preserva histórico, tentativas, idempotência e chaves; não reinicia os limites por minuto. Use nova Idempotency-Key na compra seguinte. Histórico test é limpo após 30 dias.

Chaves live e test não se misturam: números, saldo, extrato, contagens de uso e idempotência são separados. Os limites configurados e os bloqueios por cliente_ref valem nos dois modos. O ping do dashboard só testa a entrega; para exercitar modo: "test", compre um número com chave de teste.

• Reutilize Idempotency-Key em retentativas de rede; não crie outra chave antes de conferir o resultado.
• Se o webhook falhar, consulte GET /numeros/{id} e respeite os limites.
• Trate preco_acima_do_maximo: mostre o preço atualizado e obtenha a decisão do cliente antes de comprar novamente.
• Não exponha ao cliente o seu preço de custo de aquisição (preco_centavos); proteja também as chaves e o segredo.
• Envie apenas cliente_ref anônimo; mantenha a relação com seu cliente no seu sistema.

Consulte os Termos de revenda. Contato: contato@ativasms.store.