Nhà phát triển

API cho nhà phát triển

Kết nối cửa hàng Dikafy với những hệ thống khác bạn đang chạy — ERP, đơn vị vận chuyển, kho, bảng tính, hay một script bạn tự viết.

Mở tài liệu API Tải mô tả OpenAPI

Bắt đầu trong ba bước

01
Tạo khoá
Trong dashboard, vào Cài đặt → API keys và tạo một khoá. Khoá chỉ hiện ra đúng một lần lúc tạo — Dikafy chỉ lưu bản băm, nên mất khoá thì tạo khoá mới chứ không lấy lại được.
02
Chỉ cấp đúng thứ cần
Cấp cho khoá toàn quyền theo vai trò của nó, hoặc giới hạn đúng những tài nguyên nó thật sự dùng. Một tích hợp kho thường chỉ cần đơn hàng và giao hàng.
03
Gọi API
Gửi khoá dưới dạng bearer token. Khoá tự xác định cửa hàng của nó, nên không cần truyền store id và cũng không có cách nào chạm tới cửa hàng khác.

Request đầu tiên

curl https://YOUR-STORE.dikafy.com/api/v1/store/products \
  -H "Authorization: Bearer dk_sk_YOUR_KEY"

{
  "status": true,
  "products": [
    { "id": 42, "title": "Makeup bag", "handle": "makeup-bag", "status": "active" }
  ],
  "total": 1
}

Mọi phản hồi đều cùng một khuôn: một trường status, và nhiều nhất một payload có tên. Danh sách phân trang có thêm total.

Scope và vai trò

Mỗi request đi qua hai cổng và phải qua được cả hai. Scope quyết định khoá được chạm vào tài nguyên nào và có được ghi hay không; vai trò là quyền của khoá trong cửa hàng, không bao giờ cao hơn người tạo ra nó. Tài liệu ghi rõ cả hai trên từng endpoint.

Những việc khoá không bao giờ làm được

Một số endpoint bị từ chối với mọi khoá, bất kể scope hay vai trò: mời hoặc gỡ nhân sự, đóng cửa hàng, đổi cổng thanh toán hoặc thẻ thanh toán, và quản lý API key. Đó là những việc quyết định ai được tác động lên cửa hàng, và hai trong số đó sẽ vẫn còn hiệu lực sau khi bạn thu hồi chính khoá đã dùng.

Webhook

Thay vì hỏi liên tục, hãy đăng ký nhận sự kiện. Dikafy gửi tới endpoint của bạn kèm chữ ký HMAC-SHA256 trong header X-DK-Signature, và thử lại có giãn cách khi endpoint của bạn lỗi.

Các sự kiện có sẵn

order.paid: A payment is captured and the order exists.
order.refunded: A refund succeeds, in full or in part.
order.fulfilled: A shipment is created against an order.
order.cancelled: An order is cancelled.
upsell.accepted: A shopper accepts a post-purchase offer.
checkout.abandoned: A checkout is flagged as abandoned.
cart.abandoned: A cart is flagged as abandoned.
checkout.recovered: An abandoned checkout converts.

Giới hạn tần suất

Giới hạn tính theo từng khoá, mỗi phút. Mọi phản hồi đều kèm giới hạn và phần còn lại; lỗi 429 cho biết cần đợi bao lâu. Hãy đọc header thay vì đoán — giới hạn được cấu hình theo từng hệ thống.

Khi có lỗi

Lỗi cũng cùng khuôn đó, với status false và một message viết cho người đọc. Mã trạng thái cho biết đó là loại vấn đề gì.

400: Request không đọc được, hoặc có giá trị không hợp lệ.
401: Không có khoá, hoặc khoá không tồn tại / đã thu hồi / đã hết hạn.
403: Khoá thiếu scope hoặc vai trò — hoặc endpoint đó đóng với mọi khoá.
404: Không có bản ghi này trong cửa hàng.
409: Request xung đột với dữ liệu đang có.
429: Quá nhiều request. Đợi theo Retry-After.