Quy ước

Tiền và dung lượng là chuỗi

{
  "balance": "124.30",
  "currency": "USD"
}
{
  "purchased_gb": "25.000",
  "used_gb": "2.566",
  "left_gb": "22.434"
}

Phân tích thành decimal, không phải float. Tiền tệ - USD. Gigabyte = 10^9 byte.

Thời gian

ISO-8601 với độ lệch múi giờ rõ ràng, luôn là UTC: 2026-08-28T14:03:11+00:00.

Enum có thể mở rộng

Trạng thái đơn hàng, loại giao dịch, loại sự kiện, trạng thái gói, kind, family được bổ sung trong v1 mà không báo trước - code của bạn phải xử lý được giá trị lạ. Trong bộ lọc, giá trị lạ được hiểu là “không lọc”.

Phân trang

Tham số	Ý nghĩa
offset	số dòng cần bỏ qua; mặc định 0
limit	1..200, mặc định 50 (với GET /api/v1/packages - 200)

Cả hai được cắt về phạm vi hợp lệ thay vì bị từ chối, và được trả về trong nội dung ở dạng đã cắt. Phản hồi mang total.

GET /api/v1/orders?limit=100&offset=100
    -> { "orders": [...], "total": 317, "offset": 100, "limit": 100 }

Với các danh sách đang được ghi thêm, offset chỉ định một vị trí: khi tải toàn bộ, hãy loại trùng theo id. Thứ tự cố định - mới nhất ở trên.

Nhật ký sự kiện được đọc theo cách khác: ?after=<id>, phản hồi mang next_after.

Idempotency

Các thao tác trừ tiền yêu cầu header: POST /api/v1/packages (mua), POST /api/v1/packages/{id}/topup (nạp thêm lưu lượng) và POST /api/v1/packages/{id}/prolong (gia hạn địa chỉ).

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Chuỗi tối đa 255 ký tự, khoảng trắng ở hai đầu bị cắt bỏ.

Lần thử lại với cùng khóa và cùng nội dung trả về cùng phản hồi. Hãy tạo khóa trước khi gửi yêu cầu và dùng lại khi thử lại, kể cả khi thử lại sau khi hết thời gian chờ.

Khóa được ghi nhớ trong 24 giờ: cùng khóa đó sau một ngày sẽ bắt đầu một thao tác mới.

Lỗi:

• 422 - idempotency_key_required (thiếu header), idempotency_key_invalid (rỗng hoặc dài hơn 255), idempotency_key_reused (cùng khóa với nội dung khác)
• 409 - idempotency_in_progress (yêu cầu trước vẫn đang được xử lý - hãy thử lại sau một lúc với cùng khóa)
• 500 - operation_indeterminate (thử lại với khóa của một thao tác chưa xác định được kết quả - xem Lỗi)

Bộ nhớ đệm của danh mục địa lý

Các cấp của danh mục địa lý trả về ETag - mã băm không minh bạch của phiên bản danh mục. Gửi nó trong If-None-Match - bạn sẽ nhận 304 không có nội dung. Cùng phiên bản đó ở dạng dễ đọc nằm trong nội dung, ở trường version.

Quản lý phiên bản

Phát hành trong v1 mà không báo trước: trường mới trong phản hồi, tham số tùy chọn mới, giá trị mới của enum có thể mở rộng, endpoint mới, mã lỗi mới trên một mã trạng thái hiện có.

Chỉ trong phiên bản mới: xóa hoặc đổi tên trường, thu hẹp kiểu, trường bắt buộc mới trong yêu cầu, thay đổi mã trạng thái hoặc mã lỗi cho một trường hợp đã mô tả, thay đổi giá trị mặc định.

Ngừng hỗ trợ: header Deprecation và Sunset, ít nhất 6 tháng trước khi tắt.