Nhật ký thay đổi

Trang này ghi lại các thay đổi của API và của tài liệu này. Các mục bắt đầu từ 2026-09-19: bất cứ thay đổi nào diễn ra trước khi trang này tồn tại đều không được liệt kê hồi tố, nên hãy coi một mục vắng mặt là “không được ghi lại” chứ không phải “không thay đổi”.

Cách đọc trang này

Loại	Ý nghĩa
API	Dịch vụ đã thay đổi — một endpoint, một trường, một giới hạn.
Hợp đồng	Tài liệu OpenAPI đã công bố thay đổi.
Tài liệu	Tài liệu đã thay đổi. API không đổi.
Sửa đổi	Tài liệu đã mô tả API không chính xác.

Các mục Sửa đổi được nêu riêng một cách có chủ đích. Chúng mô tả một thay đổi ở những gì bạn đọc, không phải ở những gì API làm — nên không có gì trong tích hợp của bạn bị vỡ, nhưng bất cứ thứ gì bạn xây từ phần mô tả cũ đều có thể sai.

2026-09-19 — Tái cấu trúc tài liệu, công bố hợp đồng

Tài liệu · Bổ sung

Một mục Tham chiếu: OpenAPI, Phiên bản & ngừng hỗ trợ, Trạng thái & hỗ trợ, Bảo mật và Thuật ngữ.
Tài liệu OpenAPI 3.1 nay được công bố tại https://docs.zelnum.com/openapi.yaml, một bản sao giống hệt từng byte của bản trên nền tảng, có thể nhập vào Postman, Insomnia và các trình tạo client.
Ví dụ client bằng Python, Node.js, PHP và Go cho cả hai chế độ phát hiện, bên cạnh các ví dụ cURL sẵn có. Thanh điều hướng trước đây hứa hẹn các ví dụ SDK trong khi chỉ có cURL.
Bảng phản hồi theo từng trường cho các endpoint kiểm tra thời gian thực, gửi hàng loạt, trạng thái tác vụ và kết quả.
Hai cơ chế bảo vệ build mới: build nay thất bại khi có một bảng lệch cột ở bất kỳ ngôn ngữ nào, và nó đối chiếu mọi endpoint mà tài liệu này nêu tên với tài liệu OpenAPI đã vendor theo cả hai chiều — một endpoint được ghi tài liệu mà hợp đồng không có, và một đường dẫn trong hợp đồng mà không ai ghi tài liệu, đều là lỗi.

Hợp đồng · Bổ sung

Bản thân tài liệu OpenAPI: 10 đường dẫn, 9 schema, và deprecated: true trên POST /v1/realtime/detect cũ.

Tài liệu · Sửa đổi

country của hàng loạt từng được ghi là bắt buộc cho mọi lần gửi. Nó bắt buộc với sản phẩm điện thoại và phải bỏ hẳn với sản phẩm email. Như đã viết, chín sản phẩm email hàng loạt không thể gửi được — mọi request đều sẽ thất bại khi validation.
Quy tắc khối lượng hàng loạt từng sai. Nó ghi “1,000 đến 2,000,000 số mỗi request”. Quy tắc thật là mức tối thiểu của chính sản phẩm được chọn — 500, 1,000 hoặc 2,000 — cho tới mức tối đa của nền tảng là 2,000,000. Con số cũ loại trừ mười một sản phẩm có mức tối thiểu là 500.
Danh mục lỗi từng liệt kê bốn mã mà API không bao giờ trả về. Trang tài liệu cũ của nền tảng nêu not_found, result_not_ready, result_expired và validation_failed; phần triển khai không phát ra mã nào trong số đó, và những phản hồi ấy hoàn toàn không mang trường code. Bảng nay liệt kê 22 mã mà API thực sự trả về, và một bảng thứ hai ghi tài liệu cho các trường hợp không có mã — kèm cảnh báo cho bất cứ ai đã chuyển nguyên bốn nhánh đó.
Các ví dụ phản hồi từng thiếu những trường mà API thực sự trả về. series, charged_amount và refunded_amount trên phản hồi thời gian thực; idempotent_replay và recovery_pending trên các lần gửi hàng loạt; và mười bộ đếm tiến độ tác vụ gồm submitted, prefiltered, deduped, stage, last_progress_at và failure_message.
Trang giới hạn tần suất từng nêu sai endpoint. Dòng realtime ghi POST /v1/realtime/check/phone; giới hạn áp dụng cho POST /v1/realtime/check/{series}, kể cả email.
Các header phản hồi từng được mô tả sai. Trang giới hạn tần suất ngụ ý rằng toàn bộ tập header xuất hiện trên mọi phản hồi. Không phải vậy: bộ đếm của realtime chỉ báo X-RateLimit-Remaining khi thành công và không bao giờ báo X-RateLimit-Limit, còn X-RateLimit-Reset chỉ xuất hiện trên 429 của nhóm chung hoặc nhóm phát hiện. Trang nay nói rõ header nào xuất hiện ở đâu.
Mô hình khóa từng được mô tả sai. Trang bảo mật khẳng định một tài khoản chỉ giữ một khóa tại một thời điểm. Một tài khoản có thể giữ nhiều khóa hoạt động, và Bảng điều khiển tạo, tạo lại và xóa chúng riêng lẻ — nên có thể xoay vòng theo giai đoạn mà không gián đoạn, và tạo lại tại chỗ là biến thể không có chồng lấn. GET /v1/api-key báo cáo khóa hoạt động mới nhất thay vì một bản kiểm kê, và last_used của nó chỉ được ghi nhiều nhất một lần mỗi năm phút.
ID và slug từng được mô tả sai. Trang thuật ngữ nói rằng một ID hay slug bị lẫn lộn sẽ bị từ chối với product_mode_not_supported. Trên các endpoint thời gian thực, product_ids được kiểm tra như một mảng số nguyên, nên một slug bị từ chối sớm hơn với 400 invalid_realtime_request; 422 product_mode_not_supported là câu trả lời của endpoint hàng loạt cho một sản phẩm thời gian thực.
Trang định dạng phản hồi mâu thuẫn với trang số dư về đơn vị tiền tệ. Một trang nói “đơn vị tiền tệ thanh toán của tài khoản”, trang kia nói USD. Cả hai nay đều nói USD, đúng như hợp đồng và endpoint số dư nói.
Một đơn vị giá được nêu mà không có nguồn. Hàng loạt từng được mô tả là “tính giá theo mỗi 10,000 lượt kiểm tra”. Danh mục không công bố giá, nên khẳng định đó đã bị gỡ bỏ thay vì giữ lại.
Hai sửa đổi mới chỉ tới được các trang viết tay. Câu về đơn vị tiền tệ và khẳng định “theo mỗi 10,000 lượt kiểm tra” đã được sửa trên các trang tiếng Anh và tiếng Trung Giản thể, nhưng bảng chuỗi dùng để tạo bảy ngôn ngữ còn lại vẫn mang chúng, nên bảy ngôn ngữ tiếp tục công bố cả hai. Chúng cũng đã được sửa trong bảng.
/examples/ là một trang khác nhau ở mỗi ngôn ngữ. Trang tiếng Anh là một trung tâm điều hướng ngắn trong khi tám ngôn ngữ kia hiển thị một hướng dẫn hàng loạt gồm năm bước. Tiếng Anh nay khớp với hướng dẫn đó, nên cả chín ngôn ngữ mang cùng một nội dung.

Tài liệu · Sửa lỗi

Các bảng tham số âm thầm mất cột mô tả ở cả bảy ngôn ngữ được tạo. Một hàm dùng chung phát ra header ba cột cho những dòng bốn ô, và GFM bỏ mọi ô vượt quá độ rộng của header — nên chẳng hạn ở tiếng Tây Ban Nha, giá trị “Bắt buộc” hiển thị dưới tiêu đề “Mô tả” còn phần mô tả thì biến mất, trên ba trang ở bảy ngôn ngữ. Hàm này nay nhận một dạng cột tường minh và làm build thất bại khi có một dòng lệch cột, còn cơ chế bảo vệ ở giai đoạn dist kiểm tra lại độc lập mọi bảng đã kết xuất ở mọi ngôn ngữ.
Các ngôn ngữ được tạo hiển thị header cột của bảng sản phẩm, ghi chú và dòng đồng bộ của nó bằng tiếng Anh, và các dấu backtick trong ghi chú tới trình duyệt dưới dạng ký tự nguyên văn. Phần chữ của component nay đến từ bảng chuỗi đã dịch, và một bản dịch thiếu sẽ làm build thất bại thay vì dùng giá trị dự phòng.

Theo dõi các thay đổi

Chưa có feed. Cho tới khi có, tín hiệu đáng tin cậy là hợp đồng:

npm run openapi:check

trong một job theo lịch — nó thoát với mã trả về báo lỗi ngay khi tài liệu đã công bố khác với bản bạn đã vendor. Xem OpenAPI để biết hai URL.