开发者 API

API 允许您通过自有网站或应用转售临时 SMS 号码。您的客户无需访问 Ativa SMS。

请创建账户，并通过控制面板个人资料菜单中的转售号码申请访问权限。须接受经销商条款；使用条款同样适用。获批后，在控制面板 → API中创建密钥。

基础 URL：https://www.ativasms.store/api/v1。请求体请发送 UTF-8 JSON，并使用 Content-Type: application/json。响应为 JSON，包含 Cache-Control: no-store。

金额为以分为单位的整数：moeda 根据账户为 BRL 或 USD；83 BRL 分即 R$ 0.83。测试模式始终使用 BRL。日期为 ISO 8601 UTC。电话号码使用国际 +国家代码格式，或在号码预留仍在进行时为 null。

示例仅供说明，遵循实际响应格式；购买示例使用虚构测试数据。请使用 API 返回的服务代码和选项；live 价格会变化。curl 示例从您的服务器上的环境变量读取 ATIVA_API_KEY。

供工具和 AI 代理使用的 OpenAPI 3.1 规范：/openapi.json。

每个端点均须发送 Authorization: Bearer <key>。生产密钥以 ativa_live_ 开头，测试密钥以 ativa_test_ 开头。不接受查询字符串或请求体中的密钥。

密钥仅在创建时显示一次。请保存在服务器上，绝不能放在客户的浏览器或应用中。每个账户最多有 5 个有效密钥，live 和 test 密钥合并计数。如密钥遗失或泄露，请在控制面板撤销并更换。如配置了 IP 限制，请求也须满足该限制。

身份验证失败返回相同的 HTTP 401 响应，不透露原因：

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

默认限制可针对各经销商调整。请在控制面板查看账户当前限制：

限制	默认值
每分钟请求数	120
每分钟购买/更换数	20
同时等待 SMS 的号码数	20
每账户 24 h 内未收到验证码的尝试数	100
每 cliente_ref 24 h 内未收到验证码的尝试数	15

请求和购买速率合并计算账户在同一模式内的所有密钥。test 和 live 计数独立，使用相同的已配置限制。未收到 SMS 的取消、更换和过期均消耗尝试次数；每个收到验证码的号码恢复 5 次尝试，以限制为上限。交付故障不计入。live 账户的开放号码和尝试次数限制也涵盖网站购买。

超出请求或购买速率时返回 HTTP 429 muitas_requisicoes 和 Retry-After: 60（秒）。其他限制返回 429 及相应代码，不含 Retry-After：请根据情况等待开放号码或尝试次数释放。

购买和更换必须使用 Idempotency-Key：1–64 个字母、数字或 . _ : -。每个预期操作使用新密钥，重试使用同一密钥。密钥以账户和模式为作用域；购买和更换共享该作用域。不要为其他客户或订单复用密钥。

重复已记录的密钥将返回 HTTP 200、相同号码及其当前状态，即使请求体发生变化；新购买返回 201。live 查询不在 24 h 后停止：只要记录仍存在，该密钥就指向该号码。测试历史保留 30 天。重置测试余额会保留历史和幂等性。

preco_maximo_centavos 为您接受的以账户币种计价的最高扣款。如当前价格超过该值，API 返回 preco_acima_do_maximo，附带 preco_centavos 和 opcoes，不进行购买。preco_centavos 从余额扣除；preco_site_centavos 为网站参考价格。购买时会再次检查价格。

GET /saldo

无参数。返回账户币种（BRL 或 USD）的余额。测试模式始终使用 BRL 和虚构资金。

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

HTTP 200

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

GET /servicos

无参数。返回全部可用服务，不含重复或已屏蔽服务。示例显示一个条目；测试模式还包括 teste_falha（Teste sem código）。无论文档使用何种语言，API 字段名和服务标签均保持葡萄牙语。

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

HTTP 200

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

GET /paises

无参数。返回全部国家。在查询和购买中使用 codigo；iso 为大写，ddi 为拨号代码。示例显示一个条目。

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

必需查询参数：servico（服务列表中的代码）和 pais（数字国家代码）。按 preco_centavos 升序返回最多 6 个选项；结果可能为 []。opcao 是不应解析其含义的标识符：op_ 后跟 12 个十六进制字符。请原样传回返回值，不要解析。preco_centavos 为经销商扣款金额；preco_site_centavos 为网站参考价格，均使用所示币种。prazo_min 为期限；taxa_sucesso 可为 null；estoque 表示可用情况，recomendada 标记建议选项。本示例使用虚构的测试选项。

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

必需 JSON 字段：servico（1–20 个小写字母、数字或 _；须为允许的服务）、pais（有效的整数国家代码）、preco_maximo_centavos（正整数）和 cliente_ref（匿名标识符，1–64 个字母、数字或 . _ : -；绝不能使用电子邮箱地址或个人身份标识）。opcao 为可选，可为 null；省略时选择最便宜选项。发送 Idempotency-Key。新购买返回 201；重复请求返回 200 及相同 id 和当前状态，不再扣款。这是测试购买示例。

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}

路径：/numeros/{id}，其中 id 为号码的 UUID。仅可查看属于此账户和此模式的 API 购买；其他所有者的号码、网站购买或无效 UUID 返回 nao_encontrado。开放号码在响应前刷新，每个 live 密钥每分钟最多刷新 60 次；之后的请求返回最新可用状态（200，不额外产生同步相关的 429）。本示例显示已收到的测试验证码。

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

可选查询参数：status（文档列出的号码状态）、cliente_ref（与购买时格式相同）、pagina（1–1000，默认 1）。每页返回此账户和模式下最多 50 笔 API 购买，最新的在前。tem_mais 表示还有下一页。列出 live 号码不会强制刷新；如需刷新，请查询单个号码。

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

路径：/numeros/{id}/cancelar。可选请求体字段：motivo（desistiu、banido、ja_tem_dono、pede_outra_coisa 或 outro；默认 outro）。在未收到验证码且已过 cancelavel_em 时，关闭号码并退回余额。早于该时间：409 cedo，附带 segundos。已收到验证码的号码返回 nao_cancelavel；如果取消期间收到验证码，可能返回 codigo_recebido。返回 200 及已关闭号码。本示例在两分钟后使用 teste_falha。

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

路径：/numeros/{id}/trocar。必需请求体字段：preco_maximo_centavos（正整数）；opcao 和 motivo 为可选，格式同上。服务、国家和 cliente_ref 继承自原号码。需要 Idempotency-Key，以及具有电话号码、未收到验证码且已过取消等待期的 aguardando_sms 号码。关闭旧号码前会检查价格。旧号码变为 trocado 并退款；新购买返回 201（重复请求返回 200）。如退款后新购买失败，旧号码仍为 trocado：请查询并处理错误。本示例在两分钟后更换 teste_falha 号码。

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

路径：/numeros/{id}/concluir。无请求体。确认验证码已使用，并关闭 recebido 号码，不予退款。返回 200 及 concluido 号码；重复完成或未收到验证码即完成，返回 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

可选查询参数：pagina（1–1000，默认 1）。返回最多 50 笔账户交易，最新的在前（购买、退款、充值、调整），live 模式还包括网站交易。valor_centavos 为有符号数：扣款为负，入账为正；saldo_apos_centavos 为交易后余额。交易与号码无关时 numero_id 为 null；descricao 可为 null。账单不包含 moeda：请使用 GET /saldo 返回的币种。测试账单单独存放，始终使用 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
}

购买后，请向客户显示电话号码，并要求其在目标应用中请求验证码。购买号码不会自动请求 SMS。测试模式模拟送达。

Status	含义
aguardando_sms	等待中；电话号码为 null 可能表示仍在预留。
recebido	至少收到一条 SMS；不可取消或更换。
concluido	收到验证码后关闭，由人工操作或期限届满触发。
cancelado	未收到验证码即取消，已退款。
trocado	原号码在更换过程中关闭并退款。
expirado	期限届满未收到验证码；自动退款。
falhou	购买/交付失败；资金已退回。

号码对象包含 servico_nome、motivo、moeda、preco_site_centavos（可为 null）、encerrado_em、substitui_id（更换时原号码的 id）及 sms。取消、过期和关闭日期可为 null。每条 SMS 包含 codigo 和 texto（两者均可为 null）以及 recebido_em。

请遵守 cancelavel_em：某些选项允许立即取消，其他选项需等待 2 分钟。cedo 错误给出剩余等待时间：

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

在期限内未收到 SMS，资金会自动退回余额。live 号码关闭前，可能为延迟 SMS 提供 5 分钟宽限期。请遵循 expira_em 和返回状态。验证码到达后完成号码会关闭且不退款；已收到验证码的号码不可取消或更换。更换过程中，如新号码购买失败，旧号码可能保持 trocado 且已退款的状态。

错误包含 erro 和 mensagem（葡萄牙语）。请处理代码，不要匹配消息文本。附加字段可能包含 campos、segundos、preco_centavos 和 opcoes。

代码	HTTP	发生情形
nao_autorizado	401	密钥缺失、无效或已撤销、IP 不允许或访问权限已暂停；相同的通用响应不透露原因。
parametro_invalido	400	字段、查询或请求体无效；可能包含 campos，列出需要更正的字段。
servico_bloqueado	400	请求了已屏蔽服务。
idempotencia_obrigatoria	400	购买或更换时 Idempotency-Key 缺失或格式错误。
saldo_insuficiente	402	购买所需资金不足。
cliente_bloqueado	403	此账户的 cliente_ref 已被封锁。
nao_encontrado	404	UUID 无效，或号码对此账户和模式不可用。
sem_numeros	409	该服务和国家无可用号码；不扣款。
opcao_indisponivel	409	所选选项已不可用；包含当前 opcoes。
preco_acima_do_maximo	409	当前价格超过最高限价；包含 preco_centavos 和 opcoes，不扣款。
preco_subiu	409	购买过程中价格变化；金额已退回。
cedo	409	取消或更换过早；包含以 segundos 表示的等待时间。
codigo_recebido	409	已收到的验证码阻止更换，或验证码在取消期间到达。
nao_cancelavel	409	当前状态不允许取消，包括已为 recebido 的号码。
nao_trocavel	409	无电话号码、号码已关闭或状态不兼容更换。
nao_concluivel	409	号码不是 recebido 状态，包括第二次完成请求。
muitas_requisicoes	429	超出请求或购买速率；Retry-After: 60。
limite_abertas	429	等待 SMS 的号码过多；无 Retry-After。
limite_tentativas	429	账户在 24 h 内未收到验证码的尝试次数耗尽；无 Retry-After。
limite_tentativas_cliente	429	此 cliente_ref 在 24 h 内未收到验证码的尝试次数耗尽；无 Retry-After。
erro_fornecedor	502	号码交付失败；金额已退回。
sem_confirmacao	502	购买未确认；请使用相同 Idempotency-Key 重试。如 10 分钟内未交付号码，将退款。
erro_interno	500	意外故障；请使用相同幂等密钥重试购买和更换。

在控制面板 → API配置公开 HTTPS URL。内部地址、URL 凭据和片段均被拒绝；不会跟随重定向。密钥仅在创建或轮换时显示一次：请保存在服务器上。仅更改 URL 会保留密钥；移除 webhook 会删除配置。每次交付尝试均使用当前 URL 和密钥。

事件通过 JSON POST 请求发送：

• numero.codigo_recebido：每条新 SMS 一次通知；dados.sms 是包含 codigo、texto 和 recebido_em 的对象，并非 SMS 数组。一个号码可能收到多次通知，包括关闭后延迟到达的 SMS。
• numero.encerrado：concluido、cancelado、trocado、expirado 或 falhou；包含 motivo（可为 null）、encerrado_em 和 estornado_centavos（无退款时为零），以所示币种计价。
• teste.ping：在控制面板请求的交付测试，无号码或扣款。

封装包含 id（通知的 UUID，与 dados.id 不同）、evento、criado_em 和 dados。号码事件在 dados 中包含 id、cliente_ref、servico、pais、telefone（或 null）、status 和 moeda。测试号码事件在封装中添加 modo: "test"；live 事件和控制面板 ping 不含该字段。示例：

{
  "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"
  }
}

HTTP 标头：

• X-Ativa-Evento：事件名称。
• X-Ativa-Timestamp：以秒为单位的 Unix 时间戳，每次尝试刷新。
• X-Ativa-Assinatura：对 timestamp + "." + body 的 UTF-8 字节计算的小写十六进制 HMAC-SHA256，密钥作为文本使用，不进行十六进制解码。

解析 JSON 前，请验证原始请求体；重新序列化可能改变签名。拒绝与当前时间相差超过 5 分钟的时间戳，无论提前还是滞后。先检查长度，再使用 crypto.timingSafeEqual 比较。此 Node.js 示例使用 Request/Headers 和包含原始请求体的 Buffer：

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"));
}

验证后，在持久存储中按通知 id 去重，并在异步处理前记录接收情况。请迅速返回 2xx，已接受的重复通知也应如此。交付超时为 5 s。不保证恰好交付一次：响应丢失可能造成重复。

总共最多 8 次尝试。第 1–7 次失败后，等待时间依次为 1、2、4、8、16、32 和 64 分钟，从尝试结束时算起；每分钟检查交付。仅 HTTP 2xx 确认交付；3xx、其他错误和超时均触发重试。第八次失败后不再自动重发。各次尝试的 id 和请求体保持不变；时间戳和签名会刷新。如缺少通知，请查询 GET /numeros/{id}。

在控制面板创建 ativa_test_ 密钥，使用相同端点和基础 URL。不扣除真实资金。初始虚构余额为 R$ 100.00（10000 BRL 分），与真实账户币种无关。选项为 op_000000000001：虚构价格 R$ 0.83，网站参考价 R$ 1.20，有效期 20 分钟，2 分钟后可取消。

电话号码为 +1 202 555-01xx 范围内的虚构号码，返回时不含空格，例如 +12025550123；所选国家仍保存在 pais 中。验证码 123456 在 20 s 后可用；之后查询号码会更新状态，webhook 可能在下一分钟到达。

使用 servico=teste_falha 可不接收验证码，以测试取消、更换（2 分钟后）或过期（20 分钟后），并获得虚构退款。其他服务会在取消等待期结束前收到验证码。带有验证码的测试号码过期时变为 concluido。

在控制面板将余额重置为 R$ 100.00：无验证码的开放号码被取消；有验证码的号码被完成。重置保留历史、尝试次数、幂等性和密钥；不会重置每分钟限制。下次购买请使用新的 Idempotency-Key。测试历史在 30 天后清理。

live 和 test 密钥不混用：号码、余额、账单、使用计数和幂等性各自独立。已配置限制和 cliente_ref 封锁在两种模式下均适用。控制面板 ping 仅测试交付；如需测试 modo: "test"，请使用测试密钥购买号码。

• 网络故障后复用 Idempotency-Key；选择新密钥前先检查结果。
• 如缺少 webhook，请查询 GET /numeros/{id}，并遵守使用限制。
• 处理 preco_acima_do_maximo：显示更新价格，并在再次购买前取得客户决定。
• 对您的采购价（preco_centavos）保密；同时保护密钥和 webhook 密钥。
• 仅发送匿名 cliente_ref；在您自己的系统中保存与客户的关联。

请阅读经销商条款。联系：contato@ativasms.store。