🔒 Đóng gói 100% kín đáo · che tên sản phẩm 🚚 Freeship đơn từ 500.000đ 📞 0900 000 000
🛒0

Tài liệu API đối tác

API cho phép CTV và đại lý của Kín Đáo Shop lấy danh sách sản phẩm, tạo đơn hàng và nhận thông báo trạng thái đơn tự động. Đăng ký tài khoản tại trang đối tác, sau khi được duyệt lấy API key ở mục Datafeed & API.

1. Tổng quan

Base URLhttps://setia-edenias.com/api/v1
Xác thựcHeader Authorization: Bearer pk_xxx (hoặc X-API-Key: pk_xxx)
Định dạngJSON, UTF-8. Giá tính bằng VNĐ (số nguyên). Thời gian theo ISO 8601 (UTC).
Giới hạn120 request / phút / key. Vượt quá trả về 429.
QuyềnCTV: đọc sản phẩm, danh mục, đơn của mình. Đại lý: thêm quyền tạo / hủy đơn.

Mã lỗi

{ "error": { "type": "validation_error", "message": "customer.phone phải gồm 10 số, bắt đầu bằng 0." } }
401 unauthorizedSai hoặc thiếu API key
403 forbiddenTài khoản chưa duyệt / bị khóa / không đủ quyền
404 not_foundKhông tìm thấy
409 conflictKhông thể thực hiện ở trạng thái hiện tại
422 validation_errorDữ liệu gửi lên không hợp lệ
429 rate_limitedQuá giới hạn request

2. Tài khoản

GET /me

Thông tin đối tác, tỷ lệ hoa hồng / chiết khấu và số dư.

curl https://setia-edenias.com/api/v1/me -H "Authorization: Bearer pk_xxx"

3. Sản phẩm

GET /categories

GET /products

Tham sốMô tả
categoryslug hoặc id danh mục
qtừ khóa (gõ không dấu được)
updated_sincechỉ lấy sản phẩm cập nhật sau thời điểm này – dùng để đồng bộ định kỳ
in_stock=1chỉ lấy hàng còn
page, per_pagephân trang (tối đa 200 / trang)
{
  "data": [{
    "id": 6, "sku": "SP006", "name": "Gel bôi trơn gốc nước 50ml",
    "category": "Gel bôi trơn", "brand": "Durex",
    "price": 120000, "sale_price": 99000, "final_price": 99000,
    "wholesale_price": 69300,      // chỉ với Đại lý
    "commission": 19800,           // chỉ với CTV
    "in_stock": true, "stock": 20,
    "short_desc": "...", "description_html": "<p>...</p>",
    "image": "https://setia-edenias.com/uploads/...jpg", "gallery": [],
    "url": "https://setia-edenias.com/san-pham/...", "ref_url": "https://setia-edenias.com/san-pham/...?ref=MA_CUA_BAN",
    "updated_at": "2026-10-01T08:00:00+00:00"
  }],
  "meta": { "page": 1, "per_page": 50, "total": 120, "total_pages": 3 }
}

GET /products/{id hoặc sku}

4. Đơn hàng

GET /orders

Đơn của bạn (cả đơn từ link giới thiệu và đơn tạo qua API). Lọc status: new (Mới), confirmed (Đã xác nhận), shipping (Đang giao), done (Hoàn thành), cancelled (Đã hủy). Đơn từ link giới thiệu chỉ hiện tên khách đã che để bảo mật.

GET /orders/{code hoặc partner_order_id}

POST /orders (Đại lý)

Tạo đơn giao tới khách của bạn. Shop đóng gói kín đáo, giao hàng và thu hộ cod_amount.

curl -X POST https://setia-edenias.com/api/v1/orders \
  -H "Authorization: Bearer pk_xxx" -H "Content-Type: application/json" \
  -d '{
    "partner_order_id": "WEB-10025",
    "customer": { "name": "Nguyễn Văn A", "phone": "0912345678", "address": "12 Lê Lợi, P. Bến Nghé, Q.1, TP.HCM" },
    "items": [ { "sku": "SP006", "qty": 2 }, { "product_id": 9, "qty": 1 } ],
    "cod_amount": 450000,
    "note": "Giao giờ hành chính"
  }'
TrườngMô tả
partner_order_idMã đơn bên bạn (khuyên dùng). Gửi lại cùng mã sẽ trả về đơn cũ, không tạo trùng.
customer *name, phone (10 số), address
items *Mảng {sku hoặc product_id, qty}. Tối đa 50 dòng.
cod_amountSố tiền shop thu hộ của khách. 0 nếu khách đã thanh toán cho bạn.

Đối soát: commission = cod_amount − wholesale_total − shipping. Số dương: shop trả lại bạn. Số âm: bạn thanh toán cho shop. Được ghi nhận khi đơn Hoàn thành.

Trả về 201 kèm đơn hàng (code, status, wholesale_total, shipping, commission...).

POST /orders/{code}/cancel (Đại lý)

Chỉ hủy được khi đơn còn ở trạng thái new.

5. Webhook

POST /webhook

{ "url": "https://web-cua-ban.com/shop-webhook" }

Mỗi khi đơn của bạn đổi trạng thái, shop gửi:

POST https://web-cua-ban.com/shop-webhook
Content-Type: application/json
X-Event: order.status_changed
X-Signature: sha256=<HMAC-SHA256(body, api_key)>

{ "event": "order.status_changed", "sent_at": "...", "data": { "code": "DH261001ABCD", "status": "shipping", ... } }

Sự kiện: order.created (đơn mới từ link giới thiệu), order.status_changed, ping (gửi thử). Trả về HTTP 2xx trong 5 giây.

Kiểm tra chữ ký (PHP):

$body = file_get_contents('php://input');
$ok = hash_equals('sha256=' . hash_hmac('sha256', $body, 'pk_xxx'), $_SERVER['HTTP_X_SIGNATURE'] ?? '');

6. Datafeed (không cần lập trình)

Lấy toàn bộ sản phẩm một lần, cập nhật mỗi 10 phút:

https://setia-edenias.com/feed.json?key=pk_xxx
https://setia-edenias.com/feed.csv?key=pk_xxx

Google Sheet: =IMPORTDATA("https://setia-edenias.com/feed.csv?key=pk_xxx")

7. Link giới thiệu

Thêm ?ref=MA_CUA_BAN vào cuối bất kỳ link nào của shop. Khách đặt hàng trong 30 ngày kể từ lần bấm cuối sẽ được tính hoa hồng cho bạn.

Zalo Gọi