Xác thực

Mọi request tới /api/open/v1 phải mang khoá API trong header Authorization:

curl "https://danix.vn/api/open/v1/shop" \
  -H "Authorization: Bearer dnx_live_…"

Khoá thiếu, sai định dạng, đã thu hồi hoặc đã hết hạn nhận 401 với code là invalid-api-key. Một khoá API không dùng được làm phiên đăng nhập của người dùng: đường dành cho phiên nhận 401 "chưa đăng nhập", riêng đăng xuất và đăng ký thông báo đẩy nhận 400 api-key-not-accepted để nói rõ lý do.

Khoá API

Dạng dnx_live_ kèm 38 ký tự chữ và số, 6 ký tự cuối là mã kiểm. Có thể dò khoá bị lộ bằng biểu thức \bdnx_live_[0-9A-Za-z]{38}\b.
Mỗi khoá thuộc về một shop qua một "ứng dụng kết nối". Khoá của shop X không bao giờ đọc hay ghi được dữ liệu của shop Y, kể cả khi bạn gửi đúng mã của một bản ghi thuộc shop Y: lớp chặn nằm ở cơ sở dữ liệu, không chỉ ở API.
DANIX chỉ lưu giá trị băm của khoá. Khoá nguyên văn hiện đúng một lần, lúc tạo hoặc lúc xoay. Mất khoá thì xoay khoá để lấy khoá mới.
Khoá chỉ đi trong header Authorization. Không đặt khoá trong địa chỉ URL, trong tham số query hay trong mã chạy ở trình duyệt; API cũng không mở CORS.

Quyền

Khi tạo ứng dụng kết nối, bạn chọn tập quyền. Khoá chỉ gọi được những đường mà tập quyền ấy cho phép, và đường nào cần quyền gì được ghi ở mục Quyền cần có của từng endpoint trong phần tham chiếu. Thiếu quyền nhận 403 với code là insufficient-permission.

Vài trường của thân yêu cầu cần thêm quyền riêng, ghi ở mục Quyền thêm theo trường của endpoint: tạo hay sửa đơn với unitPrice khác giá niêm yết của mẫu mã, hay giảm giá (của dòng hoặc cả đơn) khác 0, cần pos.orders.price.override (và shop không bật khoá sửa giá trong cài đặt bán hàng); tạo đơn kèm payments cần pos.orders.payment.record; đổi trạng thái để huỷ một đơn đã gửi hàng (từ shipped, delivered, paid, returning, partially_returned hay returned sang cancelled — hàng khách đang giữ được nhập lại kho) cần pos.orders.delete; tạo sản phẩm có variants[].attributes mang tên thuộc tính hay giá trị CHƯA có trong shop (hệ thống tạo chúng) cần pos.products.update. Khoá thiếu quyền ấy vẫn tạo được đơn theo giá niêm yết, không giảm giá, chưa thu tiền, vẫn huỷ được đơn chưa gửi hàng, và vẫn tạo được sản phẩm dùng thuộc tính đã có.

Giới hạn khi cấp quyền:

Ứng dụng không được có nhiều quyền hơn chính người đang tạo hay sửa nó, và điều này được kiểm lại mỗi lần người ấy xoay khoá, sửa quyền hay sửa trang.
Không cấp được các quyền quản trị shop (pos.admin.*) và quyền của chính ứng dụng Tự động hoá (automation.*).
Một shop có tối đa 10 ứng dụng kết nối.

Trang chat được chọn

Với các endpoint chat, ứng dụng kết nối mang kèm danh sách trang Facebook hoặc Zalo mà người tạo chọn. Khoá chỉ thấy và chỉ gửi tin được trên các trang ấy; một trang ngoài danh sách trả 404 not-found như thể nó không tồn tại. Người tạo chỉ chọn được trang mà chính họ thấy.

Xoay khoá

Xoay khoá cấp một khoá mới và cho khoá cũ sống thêm một thời gian chồng (mặc định 24 giờ, chọn từ 0 đến 72 giờ) để bạn thay khoá ở các hệ thống mà không phải ngừng chạy. Tối đa hai khoá cùng sống. Hết thời gian chồng, khoá cũ nhận 401.

Cấp thêm một khoá mà không xoay (ví dụ cho hệ thống thứ hai) thì khoá đang có giữ nguyên, không bị đặt hạn. Ứng dụng đã có đủ hai khoá sống thì không cấp thêm được: thu hồi một khoá trước.

Cách xoay không gián đoạn: tạo khoá mới, cập nhật nơi giữ bí mật của hệ thống, triển khai, theo dõi tới khi không còn request nào dùng khoá cũ, rồi để khoá cũ hết hạn hoặc thu hồi nó.

Thu hồi

Thu hồi khoá có hiệu lực ngay: request kế tiếp dùng khoá ấy nhận 401, không có độ trễ bộ đệm. Màn hình Kết nối có nút thu hồi cho từng khoá; tạo, xoay và thu hồi đều được ghi vào nhật ký của shop, đứng tên người thao tác.

Khi người tạo ứng dụng rời shop, bị khoá tài khoản hay đổi mật khẩu, khoá không tự bị thu hồi: màn hình Kết nối gắn nhãn "Người tạo đã rời shop" hoặc "Tài khoản người tạo đã bị khoá" kèm nút xoay và thu hồi để quản trị viên quyết định.

Khi shop không dùng được API

Tình huống	Kết quả
Shop bị đình chỉ	Mọi request bị từ chối với 403 `shop-suspended`.
Gói của shop hết hạn (chỉ đọc)	Request đọc (`GET`) vẫn chạy; request ghi nhận 402 `subscription-expired`. Gia hạn gói là hết lỗi.
Gói của shop không có tính năng Tự động hoá	403 `automation-not-active`.

Danh sách đầy đủ các mã ở trang Lỗi.

Giữ khoá an toàn

Lưu khoá ở kho bí mật của hệ thống (biến môi trường của máy chủ, trình quản lý bí mật), không commit vào mã nguồn.
Không in khoá ra log. Khi log request, che header Authorization.
Cấp cho mỗi hệ thống một ứng dụng kết nối riêng với đúng quyền cần dùng, để thu hồi một nơi không kéo theo nơi khác.
Nghi ngờ lộ khoá thì thu hồi ngay rồi tạo khoá mới.