REST API cho thương hiệu.

Xác thực

Mỗi thương hiệu có một khoá API, do quản trị viên của kho cấp. Gửi khoá trong header Authorization: Bearer <khoá>. Khoá chỉ hiện một lần lúc tạo, được lưu dưới dạng băm, và thu hồi có hiệu lực ngay. Mỗi khoá được gọi tối đa 120 yêu cầu mỗi phút.

Mọi lỗi trả về dạng { "error": { "code", "message", "details" } } với thông báo tiếng Việt. Một thương hiệu chỉ thấy dữ liệu của chính mình.

POST /api/v1/orders

Tạo đơn. Gửi lại cùng externalRef sẽ nhận lại đơn cũ (200) thay vì tạo trùng.

Yêu cầu mẫu:

curl -X POST $BASE/api/v1/orders \
  -H "Authorization: Bearer $BAYHUB_KEY" -H "Content-Type: application/json" \
  -d '{
    "externalRef": "SP-240001",
    "channel": "SHOPEE",
    "carrierCode": "GHN",
    "customerName": "Trần Thu Hà",
    "phone": "0987654321",
    "address": "45 Nguyễn Huệ, Phường 1",
    "province": "TP. Hồ Chí Minh",
    "codAmount": 189000,
    "lines": [{ "skuCode": "LUNA-KDA-30ML", "qty": 1 }]
  }'

Phản hồi mẫu:

201 { "id": "...", "externalRef": "SP-240001", "status": "ALLOCATED", "warehouse": "BD1", "slaDueAt": "2026-10-12T10:00:00.000Z" }

GET /api/v1/orders/{externalRef}

Trạng thái đơn, mã vận đơn, kết quả giao của hãng (delivery), số lượng đã phân bổ/lấy/gói và nhật ký xử lý.

Yêu cầu mẫu:

curl $BASE/api/v1/orders/SP-240001 -H "Authorization: Bearer $BAYHUB_KEY"

Phản hồi mẫu:

200 { "status": "SHIPPED", "trackingNumber": "GHN4821930571",
      "delivery": { "status": "DELIVERED", "deliveredAt": "2026-10-13T04:12:00.000Z", "failedAt": null, "attempts": 1 },
      "lines": [...], "events": [...] }

POST /api/v1/orders/{externalRef}/cancel

Huỷ đơn chưa đóng gói. Hàng đã lấy được trả về kệ.

Yêu cầu mẫu:

curl -X POST $BASE/api/v1/orders/SP-240001/cancel -H "Authorization: Bearer $BAYHUB_KEY" -d '{"reason":"Khách huỷ trên sàn"}'

Phản hồi mẫu:

200 { "externalRef": "SP-240001", "status": "CANCELLED" }

GET /api/v1/inventory?sku=

Tồn có thể bán theo kho cho các SKU của thương hiệu (bỏ sku để lấy tất cả).

Yêu cầu mẫu:

curl "$BASE/api/v1/inventory?sku=LUNA-KDA-30ML" -H "Authorization: Bearer $BAYHUB_KEY"

Phản hồi mẫu:

200 { "items": [{ "sku": "LUNA-KDA-30ML", "warehouses": [{ "warehouse": "BD1", "onHand": 420, "available": 398 }] }] }

POST /api/v1/inbounds

Báo trước một lô hàng sắp gửi tới kho (ASN).

Yêu cầu mẫu:

curl -X POST $BASE/api/v1/inbounds -H "Authorization: Bearer $BAYHUB_KEY" -H "Content-Type: application/json" \
  -d '{ "supplier": "Nhà máy Luna", "expectedAt": "2026-10-14T09:00:00+07:00", "lines": [{ "skuCode": "LUNA-KDA-30ML", "expectedQty": 300 }] }'

Phản hồi mẫu:

201 { "code": "ASN261014-0042", "status": "EXPECTED" }

GET /api/v1/returns?status=

Hàng hoàn của thương hiệu, mới nhất trước: kiện giao không thành công đang hoàn về và hàng khách trả. Lọc theo EXPECTED, RECEIVED, CLOSED, CANCELLED.

Yêu cầu mẫu:

curl "$BASE/api/v1/returns?status=CLOSED" -H "Authorization: Bearer $BAYHUB_KEY"

Phản hồi mẫu:

200 { "items": [{ "code": "RGHN4821930571", "orderRef": "SP-240001", "kind": "FAILED_DELIVERY", "status": "CLOSED",
      "reason": "Không liên lạc được người nhận", "lines": [{ "sku": "LUNA-KDA-30ML", "qty": 1, "resellable": 1, "damaged": 0 }] }] }

POST /api/v1/returns

Mở yêu cầu trả hàng cho đơn đã giao thành công (trong 14 ngày). Bỏ lines để trả toàn bộ phần còn trả được.

Yêu cầu mẫu:

curl -X POST $BASE/api/v1/returns -H "Authorization: Bearer $BAYHUB_KEY" -H "Content-Type: application/json" \
  -d '{ "externalRef": "SP-240001", "reason": "Không vừa", "lines": [{ "skuCode": "LUNA-KDA-30ML", "qty": 1 }] }'

Phản hồi mẫu:

201 { "code": "RCGHN4821930571", "kind": "CUSTOMER", "status": "EXPECTED", "expectedAt": "2026-10-16T03:00:00.000Z" }

Mã lỗi