SDK

~2 phút đọc

Dòng Tiền Pro phát hành hai SDK chính thức: @dongtien/sdk cho TypeScript và dongtien cho Python. Cả hai được sinh từ cùng đặc tả OpenAPI công khai, nên kiểu dữ liệu và route luôn khớp với API; phần viết tay chỉ thêm những gì một tích hợp chạy thật cần: xác thực, phiên bản, idempotency, thử lại, lỗi có cấu trúc và phân trang.

Gói	Ngôn ngữ	Kho gói
`@dongtien/sdk`	TypeScript (Node 20 trở lên, trình duyệt, Cloudflare Workers, Deno, Bun)	npm
`dongtien`	Python 3.11 trở lên	PyPI

Với ngôn ngữ khác, tự sinh client từ đặc tả OpenAPI theo hướng dẫn ở Tự sinh client.

Mọi client đều làm giống nhau

Hành vi dưới đây có trong cả hai SDK.

Chủ đề	Hành vi
Xác thực	`Authorization: Bearer <khoá>`; khoá không bao giờ vào log hay thông điệp lỗi. Xem Xác thực.
Phiên bản	Tuỳ chọn `version` đặt header `DongTien-Version`; bỏ trống thì dùng phiên bản ghim ở khoá. Xem Phiên bản.
Idempotency	Route khai báo idempotent được gắn `Idempotency-Key` (UUIDv7) sinh một lần cho mỗi lời gọi và giữ nguyên qua mọi lần thử lại; khoá bạn truyền vào được ưu tiên. Xem Idempotency.
Thử lại	Tối đa 3 lần, lùi theo cấp số nhân có độ trễ ngẫu nhiên (gốc 500 ms, trần 8 giây). 429 luôn được thử lại theo `Retry-After`; nếu lớn hơn 60 giây thì báo lỗi thay vì ngủ chờ. 5xx và lỗi mạng chỉ thử lại với GET, HEAD, OPTIONS, PUT, DELETE hoặc yêu cầu có `Idempotency-Key`. Lỗi 4xx khác 429 không bao giờ thử lại.
Lỗi	Phản hồi không thành công là `ApiError` mang `code`, `request_id`, `errors[]`. Không có phản hồi nào là lỗi kết nối riêng. Xem Lỗi.
Phân trang	Danh sách là `{ object: "list", data, next_cursor, has_more }`; `paginate` đi hết mọi trang. Xem Phân trang.

Nếu tự viết client, hãy cài đặt đúng sáu hành vi này.

Xác minh webhook

SDK hiện chưa có hàm xác minh webhook riêng. Dùng thư viện standardwebhooks hoặc đoạn mã không phụ thuộc thư viện ở trang Chữ ký và xác minh.

TypeScript@dongtien/sdk: createClient, paginate, ApiError.

Pythondongtien: DongTien, AsyncDongTien, paginate.

Tự sinh clientSinh client từ openapi.json cho ngôn ngữ khác.