API dành cho nhà phát triển

API cho phép bạn bán lại số SMS tạm thời qua trang web hoặc ứng dụng riêng. Khách hàng của bạn không cần truy cập Ativa SMS.

Tạo tài khoản và yêu cầu quyền truy cập qua Bán lại số trong menu hồ sơ của bảng điều khiển. Bắt buộc chấp nhận Điều khoản đại lý; Điều khoản sử dụng cũng áp dụng. Sau khi được phê duyệt, tạo khóa tại Bảng điều khiển → API.

URL cơ sở: https://www.ativasms.store/api/v1. Gửi JSON UTF-8 với Content-Type: application/json cho nội dung yêu cầu. Phản hồi là JSON và có Cache-Control: no-store.

Số tiền là số nguyên tính bằng xu: moeda là BRL hoặc USD tùy tài khoản; 83 xu BRL nghĩa là R$ 0.83. Chế độ thử nghiệm luôn sử dụng BRL. Ngày theo ISO 8601 UTC. Số điện thoại theo định dạng quốc tế +mã-quốc-gia, hoặc null khi việc giữ số vẫn đang diễn ra.

Các ví dụ có tính minh họa và tuân theo định dạng phản hồi thực tế; ví dụ mua sử dụng dữ liệu thử nghiệm giả lập. Sử dụng mã dịch vụ và lựa chọn do API trả về; giá live thay đổi. Ví dụ curl đọc ATIVA_API_KEY từ biến môi trường trên máy chủ của bạn.

Đặc tả OpenAPI 3.1 dành cho công cụ và tác nhân AI: /openapi.json.

Gửi Authorization: Bearer <key> trên mọi endpoint. Khóa bắt đầu bằng ativa_live_ cho môi trường thực hoặc ativa_test_ cho thử nghiệm. Không chấp nhận khóa trong chuỗi truy vấn hoặc nội dung yêu cầu.

Khóa chỉ được hiển thị một lần, khi tạo. Lưu trên máy chủ của bạn, tuyệt đối không trong trình duyệt hoặc ứng dụng khách hàng. Tài khoản có tối đa 5 khóa đang hoạt động, tính chung khóa live và test. Thu hồi và thay thế khóa bị mất hoặc lộ trong bảng điều khiển. Nếu có cấu hình hạn chế IP, yêu cầu cũng phải đáp ứng hạn chế đó.

Lỗi xác thực trả về cùng phản hồi HTTP 401 mà không tiết lộ nguyên nhân:

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

Giới hạn mặc định có thể điều chỉnh cho từng đại lý. Kiểm tra giới hạn hiện tại của tài khoản trong bảng điều khiển:

Giới hạn	Mặc định
Yêu cầu mỗi phút	120
Mua/đổi mỗi phút	20
Số đang chờ SMS cùng lúc	20
Lần thử không có mã theo tài khoản trong 24 h	100
Lần thử không có mã theo cliente_ref trong 24 h	15

Tốc độ yêu cầu và mua cộng tất cả khóa của tài khoản trong cùng chế độ. Bộ đếm test và live tách biệt, sử dụng cùng giới hạn đã cấu hình. Hủy, đổi và hết hạn mà chưa có SMS tiêu tốn lần thử; mỗi số có mã khôi phục 5 lần thử, đến giới hạn. Lỗi giao không được tính. Giới hạn tài khoản live về số đang mở và lần thử cũng bao gồm giao dịch mua trên trang web.

Vượt tốc độ yêu cầu hoặc mua trả về HTTP 429 muitas_requisicoes và Retry-After: 60 (giây). Các giới hạn khác trả về 429 với mã riêng và không có Retry-After: chờ số đang mở hoặc lần thử được giải phóng tùy trường hợp.

Idempotency-Key là bắt buộc khi mua và đổi: 1–64 chữ cái, chữ số hoặc . _ : -. Dùng khóa mới cho mỗi thao tác mong muốn và cùng khóa khi thử lại. Khóa có phạm vi theo tài khoản và chế độ; mua và đổi chia sẻ phạm vi đó. Không dùng lại khóa cho khách hàng hoặc đơn hàng khác.

Lặp lại khóa đã ghi nhận trả về HTTP 200 với cùng số và trạng thái hiện tại, ngay cả khi nội dung đã thay đổi; mua mới trả về 201. Tra cứu live không dừng sau 24 h: khóa tham chiếu tới số đó chừng nào bản ghi còn tồn tại. Lịch sử thử nghiệm được giữ 30 ngày. Đặt lại số dư thử nghiệm bảo toàn lịch sử và tính lũy đẳng.

preco_maximo_centavos là khoản thu cao nhất bạn chấp nhận theo loại tiền tài khoản. Nếu giá hiện tại vượt mức đó, API trả về preco_acima_do_maximo cùng preco_centavos và opcoes, không mua. preco_centavos được trừ từ số dư; preco_site_centavos là giá tham chiếu trên trang web. Giá được kiểm tra lại tại thời điểm mua.

GET /saldo

Không có tham số. Trả về số dư theo loại tiền của tài khoản (BRL hoặc USD). Chế độ thử nghiệm luôn dùng BRL và tiền giả lập.

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

HTTP 200

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

GET /servicos

Không có tham số. Trả về tất cả dịch vụ có sẵn, không trùng lặp hoặc có dịch vụ bị chặn. Ví dụ hiển thị một mục; chế độ thử nghiệm còn bao gồm teste_falha (Teste sem código). Tên trường API và nhãn dịch vụ vẫn bằng tiếng Bồ Đào Nha bất kể ngôn ngữ tài liệu.

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

HTTP 200

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

GET /paises

Không có tham số. Trả về tất cả quốc gia. Sử dụng codigo trong truy vấn và giao dịch mua; iso viết hoa và ddi là mã quay số. Ví dụ hiển thị một mục.

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

Tham số truy vấn bắt buộc: servico (mã từ danh sách dịch vụ) và pais (mã quốc gia dạng số). Trả về tối đa 6 lựa chọn theo thứ tự preco_centavos tăng dần; kết quả có thể là []. opcao là định danh không mang ý nghĩa để diễn giải: op_ theo sau bởi 12 ký tự thập lục phân. Gửi lại giá trị được trả về mà không diễn giải. preco_centavos là khoản thu của đại lý; preco_site_centavos là giá tham chiếu trên trang web, cả hai theo loại tiền đã nêu. prazo_min là thời hạn; taxa_sucesso có thể là null; estoque cho biết khả năng cung cấp và recomendada đánh dấu lựa chọn được đề xuất. Ví dụ này sử dụng lựa chọn thử nghiệm giả lập.

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

Trường JSON bắt buộc: servico (1–20 chữ cái thường, chữ số hoặc _; dịch vụ được phép), pais (mã quốc gia số nguyên hợp lệ), preco_maximo_centavos (số nguyên dương) và cliente_ref (định danh ẩn danh gồm 1–64 chữ cái, chữ số hoặc . _ : -; tuyệt đối không dùng địa chỉ email hoặc định danh cá nhân). opcao là tùy chọn và có thể là null; bỏ qua sẽ chọn lựa chọn rẻ nhất. Gửi Idempotency-Key. Giao dịch mua mới trả về 201; lặp lại trả về 200 với cùng id và trạng thái hiện tại, không thu thêm tiền. Đây là ví dụ mua thử nghiệm.

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}

Đường dẫn: /numeros/{id}, trong đó id là UUID của số. Chỉ hiển thị giao dịch mua qua API thuộc tài khoản và chế độ này; số của chủ khác, giao dịch mua trên trang web hoặc UUID không hợp lệ trả về nao_encontrado. Số đang mở được cập nhật trước khi phản hồi, tối đa 60 lần cập nhật/phút cho mỗi khóa live; yêu cầu tiếp theo trả về trạng thái mới nhất có sẵn (200, không thêm lỗi đồng bộ hóa 429). Ví dụ này hiển thị mã thử nghiệm đã nhận.

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

Tham số truy vấn tùy chọn: status (trạng thái số được mô tả trong tài liệu), cliente_ref (cùng định dạng khi mua), pagina (1–1000, mặc định 1). Trả về tối đa 50 giao dịch mua qua API mỗi trang cho tài khoản và chế độ này, mới nhất trước. tem_mais cho biết có trang tiếp theo. Liệt kê số live không bắt buộc cập nhật; truy vấn từng số để cập nhật.

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

Đường dẫn: /numeros/{id}/cancelar. Trường nội dung tùy chọn: motivo (desistiu, banido, ja_tem_dono, pede_outra_coisa hoặc outro; mặc định outro). Khi chưa có mã và đã qua cancelavel_em, đóng số và hoàn lại số dư. Trước thời điểm đó: 409 cedo kèm segundos. Số đã nhận mã trả về nao_cancelavel; codigo_recebido có thể xảy ra nếu mã đến trong lúc hủy. Trả về 200 kèm số đã đóng. Ví dụ này dùng teste_falha sau hai phút.

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

Đường dẫn: /numeros/{id}/trocar. Trường nội dung bắt buộc: preco_maximo_centavos (số nguyên dương); opcao và motivo là tùy chọn, theo định dạng trên. Dịch vụ, quốc gia và cliente_ref được kế thừa từ số gốc. Yêu cầu Idempotency-Key và số aguardando_sms có điện thoại, chưa có mã và đã hết thời gian chờ hủy. Giá được kiểm tra trước khi đóng số cũ. Số cũ chuyển thành trocado và được hoàn tiền; giao dịch mua mới trả về 201 (lặp lại trả về 200). Nếu giao dịch mua mới thất bại sau hoàn tiền, số cũ vẫn là trocado: hãy truy vấn và xử lý lỗi. Ví dụ này đổi số teste_falha sau hai phút.

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

Đường dẫn: /numeros/{id}/concluir. Không có nội dung. Xác nhận mã đã được dùng và đóng số recebido mà không hoàn tiền. Trả về 200 kèm số concluido; hoàn tất lại hoặc hoàn tất khi chưa có mã trả về 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

Tham số truy vấn tùy chọn: pagina (1–1000, mặc định 1). Trả về tối đa 50 giao dịch tài khoản, mới nhất trước (mua, hoàn tiền, nạp tiền, điều chỉnh), bao gồm giao dịch trên trang web ở chế độ live. valor_centavos có dấu: âm cho ghi nợ, dương cho ghi có; saldo_apos_centavos là số dư sau đó. numero_id là null khi giao dịch không liên quan đến số; descricao có thể là null. Sao kê không có moeda: sử dụng loại tiền từ GET /saldo. Sao kê thử nghiệm tách biệt và luôn dùng 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
}

Sau khi mua, hiển thị số điện thoại cho khách hàng và yêu cầu họ xin mã trong ứng dụng đích. Mua số không tự động yêu cầu SMS. Chế độ thử nghiệm mô phỏng việc giao.

Status	Ý nghĩa
aguardando_sms	Đang chờ; điện thoại null có thể nghĩa là việc giữ số vẫn đang diễn ra.
recebido	Ít nhất một SMS đã đến; không thể hủy hoặc đổi.
concluido	Đã đóng sau khi nhận mã, bằng tay hoặc khi hết thời hạn.
cancelado	Đã hủy khi chưa có mã và hoàn tiền.
trocado	Số trước đã đóng và hoàn tiền trong khi đổi.
expirado	Hết thời hạn mà chưa có mã; hoàn tiền tự động.
falhou	Mua/giao thất bại; tiền được trả lại.

Đối tượng số bao gồm servico_nome, motivo, moeda, preco_site_centavos (có thể là null), encerrado_em, substitui_id (id của số trước khi đổi) và sms. Ngày hủy, hết hạn và đóng có thể là null. Mỗi SMS bao gồm codigo và texto (mỗi trường có thể là null) và recebido_em.

Tuân thủ cancelavel_em: một số lựa chọn cho phép hủy ngay; lựa chọn khác yêu cầu 2 phút. Lỗi cedo chỉ định thời gian chờ còn lại:

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

Không có SMS trước thời hạn, tiền tự động quay lại số dư. Số live có thể có thời gian gia hạn 5 phút cho SMS đến muộn trước khi đóng. Theo dõi expira_em và trạng thái trả về. Hoàn tất số sau khi mã đến sẽ đóng số mà không hoàn tiền; số đã nhận không thể hủy hoặc đổi. Trong khi đổi, nếu mua số mới thất bại, số cũ có thể vẫn là trocado và được hoàn tiền.

Lỗi bao gồm erro và mensagem (bằng tiếng Bồ Đào Nha). Xử lý theo mã thay vì so khớp thông báo. Trường bổ sung có thể bao gồm campos, segundos, preco_centavos và opcoes.

Mã	HTTP	Khi xảy ra
nao_autorizado	401	Thiếu khóa, khóa không hợp lệ hoặc đã thu hồi, IP không được phép hoặc quyền truy cập bị đình chỉ; cùng một phản hồi chung che giấu nguyên nhân.
parametro_invalido	400	Trường, truy vấn hoặc nội dung không hợp lệ; có thể kèm campos liệt kê trường cần sửa.
servico_bloqueado	400	Đã yêu cầu dịch vụ bị chặn.
idempotencia_obrigatoria	400	Thiếu hoặc sai định dạng Idempotency-Key khi mua hoặc đổi.
saldo_insuficiente	402	Không đủ tiền để mua.
cliente_bloqueado	403	cliente_ref bị chặn cho tài khoản này.
nao_encontrado	404	UUID không hợp lệ hoặc số không khả dụng cho tài khoản và chế độ này.
sem_numeros	409	Không có số cho dịch vụ và quốc gia đó; không thu tiền.
opcao_indisponivel	409	Lựa chọn đã chọn không còn khả dụng; kèm opcoes hiện tại.
preco_acima_do_maximo	409	Giá hiện tại vượt mức tối đa; kèm preco_centavos và opcoes, không thu tiền.
preco_subiu	409	Giá thay đổi trong khi mua; tiền đã được hoàn.
cedo	409	Quá sớm để hủy hoặc đổi; kèm thời gian chờ trong segundos.
codigo_recebido	409	Mã đã nhận ngăn việc đổi, hoặc mã đến trong lúc hủy.
nao_cancelavel	409	Trạng thái không cho phép hủy, bao gồm số đã recebido.
nao_trocavel	409	Không có điện thoại, số đã đóng hoặc trạng thái không tương thích với việc đổi.
nao_concluivel	409	Số không ở trạng thái recebido, bao gồm yêu cầu hoàn tất lần thứ hai.
muitas_requisicoes	429	Vượt tốc độ yêu cầu hoặc mua; Retry-After: 60.
limite_abertas	429	Quá nhiều số đang chờ SMS; không có Retry-After.
limite_tentativas	429	Đã hết lần thử không có mã của tài khoản trong 24 h; không có Retry-After.
limite_tentativas_cliente	429	Đã hết lần thử không có mã cho cliente_ref này trong 24 h; không có Retry-After.
erro_fornecedor	502	Giao số thất bại; tiền đã được hoàn.
sem_confirmacao	502	Giao dịch mua chưa xác nhận; thử lại với cùng Idempotency-Key. Nếu không giao số trong 10 phút, tiền được hoàn.
erro_interno	500	Lỗi không mong đợi; thử lại giao dịch mua và đổi với cùng khóa idempotency.

Cấu hình URL HTTPS công khai trong Bảng điều khiển → API. Địa chỉ nội bộ, thông tin xác thực và fragment trong URL bị từ chối; không đi theo chuyển hướng. Bí mật chỉ hiển thị một lần khi tạo hoặc thay mới: lưu trên máy chủ của bạn. Chỉ đổi URL sẽ giữ nguyên bí mật; xóa webhook sẽ xóa cấu hình. Mỗi lần thử giao dùng URL và bí mật hiện tại.

Sự kiện được gửi dưới dạng yêu cầu POST JSON:

• numero.codigo_recebido: một thông báo cho mỗi SMS mới; dados.sms là đối tượng có codigo, texto và recebido_em, không phải mảng SMS. Một số có thể nhận nhiều thông báo, bao gồm SMS đến muộn sau khi đóng.
• numero.encerrado: concluido, cancelado, trocado, expirado hoặc falhou; bao gồm motivo (có thể là null), encerrado_em và estornado_centavos (bằng không nếu không hoàn tiền), theo loại tiền đã nêu.
• teste.ping: thử giao được yêu cầu trong bảng điều khiển, không có số hoặc khoản thu.

Phong bì chứa id (UUID của thông báo, khác dados.id), evento, criado_em và dados. Sự kiện số bao gồm id, cliente_ref, servico, pais, telefone (hoặc null), status và moeda trong dados. Sự kiện của số thử nghiệm thêm modo: "test" vào phong bì; sự kiện live và ping bảng điều khiển không có trường này. Ví dụ:

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

Header:

• X-Ativa-Evento: tên sự kiện.
• X-Ativa-Timestamp: dấu thời gian Unix theo giây, được làm mới mỗi lần thử.
• X-Ativa-Assinatura: HMAC-SHA256 dạng thập lục phân chữ thường trên các byte UTF-8 của timestamp + "." + body, dùng bí mật dưới dạng văn bản, không giải mã từ thập lục phân.

Xác minh nội dung thô trước khi phân tích JSON; tuần tự hóa lại có thể thay đổi chữ ký. Từ chối dấu thời gian lệch quá 5 phút so với giờ hiện tại, theo cả hai chiều. So sánh bằng crypto.timingSafeEqual sau khi kiểm tra độ dài. Ví dụ Node.js này sử dụng Request/Headers và Buffer chứa nội dung gốc:

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

Sau khi xác minh, loại trùng theo id thông báo trong lưu trữ bền vững và ghi nhận việc nhận trước khi xử lý bất đồng bộ. Trả về 2xx nhanh chóng, kể cả bản trùng đã chấp nhận. Thời gian chờ giao là 5 s. Không bảo đảm chỉ giao đúng một lần: mất phản hồi có thể gây lặp lại.

Tối đa 8 lần thử tổng cộng. Sau lần thất bại 1–7, thời gian chờ là 1, 2, 4, 8, 16, 32 và 64 phút, tính từ khi lần thử kết thúc; việc giao được kiểm tra mỗi phút. Chỉ HTTP 2xx xác nhận giao; 3xx, lỗi khác và hết thời gian chờ gây thử lại. Sau thất bại thứ tám không tự động gửi lại. id và nội dung không đổi giữa các lần thử; dấu thời gian và chữ ký được làm mới. Truy vấn GET /numeros/{id} nếu thiếu thông báo.

Tạo khóa ativa_test_ trong bảng điều khiển và dùng cùng endpoint, URL cơ sở. Không thu tiền thật. Số dư giả lập ban đầu là R$ 100.00 (10000 xu BRL), bất kể loại tiền thật của tài khoản. Lựa chọn là op_000000000001: giá giả lập R$ 0.83, giá tham chiếu trang web R$ 1.20, thời hạn 20 phút và hủy sau 2 phút.

Điện thoại là số giả lập trong dải +1 202 555-01xx, trả về không có khoảng trắng, như +12025550123; quốc gia bạn chọn vẫn nằm trong pais. Mã 123456 có sẵn sau 20 s; truy vấn số sau thời điểm đó cập nhật trạng thái, còn webhook có thể đến vào phút tiếp theo.

Dùng servico=teste_falha để không nhận mã và thử hủy, đổi (sau 2 phút) hoặc hết hạn (sau 20 phút), với hoàn tiền giả lập. Dịch vụ khác nhận mã trước khi hết thời gian chờ hủy. Số thử nghiệm có mã chuyển thành concluido khi hết hạn.

Đặt lại số dư về R$ 100.00 trong bảng điều khiển: số đang mở chưa có mã được hủy; số có mã được hoàn tất. Đặt lại bảo toàn lịch sử, lần thử, tính lũy đẳng và khóa; không đặt lại giới hạn mỗi phút. Dùng Idempotency-Key mới cho lần mua tiếp theo. Lịch sử thử nghiệm được dọn sau 30 ngày.

Khóa live và test không trộn lẫn: số, số dư, sao kê, bộ đếm sử dụng và tính lũy đẳng tách biệt. Giới hạn đã cấu hình và chặn cliente_ref áp dụng ở cả hai chế độ. Ping bảng điều khiển chỉ thử việc giao; mua số với khóa thử nghiệm để kiểm tra modo: "test".

• Dùng lại Idempotency-Key sau lỗi mạng; kiểm tra kết quả trước khi chọn khóa mới.
• Truy vấn GET /numeros/{id} nếu thiếu webhook và tuân thủ giới hạn sử dụng.
• Xử lý preco_acima_do_maximo: hiển thị giá cập nhật và lấy quyết định của khách hàng trước khi mua tiếp.
• Giữ kín giá mua vào của bạn (preco_centavos); bảo vệ cả khóa và bí mật webhook.
• Chỉ gửi cliente_ref ẩn danh; giữ liên kết với khách hàng trong hệ thống riêng.

Đọc Điều khoản đại lý. Liên hệ: contato@ativasms.store.