OpenAPI

Mọi endpoint trong tài liệu này cũng được công bố dưới dạng tài liệu OpenAPI 3.1 đọc được bằng máy, để bạn có thể điều khiển công cụ từ hợp đồng thay vì tự chép tay các bảng.

Bản sao	URL	Ghi chú
Tài liệu	https://docs.zelnum.com/openapi.yaml	Ổn định, trên tên miền này. Là bản chính thức cho người đọc trang này.
Nền tảng	https://app.zelnum.com/docs/openapi.yaml	Thượng nguồn. Bản trong tài liệu là bản sao giống hệt từng byte.

Cả hai tệp là cùng một tài liệu. Bản sao tồn tại để đặc tả nằm trên máy chủ bạn đang đọc, ở một đường dẫn mà công cụ có thể tìm thấy.

Tài liệu chứa những gì

Phần	Số lượng	Nội dung
Servers	1	https://api.zelnum.com/api/v1
Paths	10	Chín endpoint được ghi tài liệu cộng với bí danh realtime cũ
Tags	3	Common, Realtime, Bulk — cùng cách phân chia mà thanh điều hướng dùng
Schemas	9	Body của request và response, gồm cả cấu trúc bao ngoài của lỗi
Lược đồ bảo mật	2	X-API-Key và Authorization: Bearer

Các chi tiết ở cấp thao tác nằm trong chính tài liệu: header bắt buộc, minItems/maxItems trên mảng, enum cho series, mode, status và billing_status, và cờ deprecated: true trên POST /v1/realtime/detect.

Nhập vào công cụ API

Postman — Import → File → openapi.yaml. Postman tạo một collection với biến môi trường cho URL cơ sở; hãy đặt khóa của bạn làm header X-API-Key ở cấp collection để mọi request kế thừa nó.

Insomnia — Create → Import From → File, rồi thêm X-API-Key làm header của collection.

Bruno / HTTPie / trình tạo curl — tất cả đều dùng trực tiếp OpenAPI 3.1:

curl -fsSL https://docs.zelnum.com/openapi.yaml -o zelnum.yaml

Tạo client có kiểu dữ liệu

Không có SDK chính thức — API chỉ là JSON thuần qua HTTPS, và một client được tạo thường vẫn phù hợp hơn client viết tay, vì nó tuân theo quy ước của ngôn ngữ bạn dùng.

# Pick your generator: python, typescript-fetch, php, go, java, csharp, ruby, …
npx @openapitools/openapi-generator-cli generate \
  -i https://docs.zelnum.com/openapi.yaml \
  -g python \
  -o ./zelnum-client

Client được tạo đọc URL cơ sở và lược đồ bảo mật từ tài liệu, nên thứ duy nhất bạn cung cấp lúc chạy là khóa API.

Realtime yêu cầu một header mà trình tạo không thể tự nghĩ ra

Idempotency-Key là header bắt buộc trên các endpoint thời gian thực, và một client được tạo sẽ đưa nó ra như một tham số phương thức mà bạn phải đặt. Nó phải duy nhất cho mỗi lần gửi — xem Idempotency & thử lại.

Giữ bản sao trung thực

Bản sao đi theo thượng nguồn; nó không bao giờ được sửa ở đây. Vì sự lệch pha giữa một hợp đồng đã công bố và tài liệu của nó chính là lỗi mà trang này tồn tại để ngăn chặn, bản sao được đối chiếu với thượng nguồn thay vì được tin tưởng:

npm run openapi:check   # fetch upstream and fail if the bytes differ
npm run openapi:sync    # re-vendor, printing which operations changed

openapi:check cần truy cập mạng và cố ý không thuộc quá trình build site — một lần triển khai không được thất bại chỉ vì máy chủ nền tảng gặp trục trặc nhất thời. Điều mà build thực sự bắt buộc là nửa ngoại tuyến của bất biến: mọi endpoint mà tài liệu này mô tả đều phải tồn tại trong tài liệu đã vendor, nên một trang không thể ghi tài liệu cho một thao tác mà hợp đồng không có.

Tiếp theo

• Phiên bản & ngừng hỗ trợ — cờ deprecated trên endpoint cũ có ý nghĩa gì với bạn
• Định dạng phản hồi — cấu trúc bao ngoài mà mọi endpoint chia sẻ