Tạo đơn hàng Partner

Hogotopod Partner API cung cấp bộ API giúp đối tác đẩy đơn hàng trực tiếp vào dây chuyền sản xuất tự động với độ trễ thấp và kiểm tra hợp lệ chặt chẽ.

Các phương thức tạo đơn

Hệ thống cung cấp 3 endpoint chính cho nghiệp vụ đặt hàng:

Endpoint	Method	Mục đích
`/v1/partner/order/store`	`POST`	Tạo một đơn hàng mới (tối ưu tốc độ, xử lý đồng bộ).
`/v1/partner/order/store-batch`	`POST`	Tạo danh sách nhiều đơn hàng cùng lúc (dạng mảng các đơn).
`/v1/partner/order/estimate`	`POST`	Ước tính chi phí sản xuất và vận chuyển mà không tạo đơn thật.

Cấu trúc Payload chi tiết (`PartnerOrderAddInfo`)

Dưới đây là bảng giải thích chi tiết các khối dữ liệu trong payload tạo đơn:

1. Thông tin chung

referenceCode (string, tối đa 100 ký tự): Mã đơn hàng riêng trên hệ thống của đối tác (ví dụ: mã order từ Shopify, WooCommerce, TikTok Shop). Phải là duy nhất để tránh tạo trùng đơn.
customerNote (string, tối đa 1000 ký tự): Lời nhắn hoặc chỉ dẫn sản xuất cho xưởng (ví dụ: Cắt chỉ thừa kỹ, Đóng gói bọc bóng khí).
autoDeposit (boolean): Tự động trừ tiền trong ví cọc tài khoản nếu số dư đủ. Khuyến nghị đặt true để đơn tự động chuyển vào khâu sản xuất ngay khi tạo.
shippingMethod (string): Mã phương thức vận chuyển:
- HOGOTOFAST: Tuyến bay nhanh.
- HOGOTO_EPACKET: Tuyến kinh tế.
- TIKTOK: Dành cho các đơn TikTok Shop (đối tác tự cấp label hoặc tracking).
- SHIPPING_OUTSIDE_US, SHIPPING_TIKTOK_UK, SHIP_TO_EU, NONE.
- Khi shippingMethod = SHIP_TO_EU, mỗi phần tử trong products bắt buộc có mPid (ASIN / Item Number / SKU sàn).

2. Thông tin địa chỉ (`address`) & Người nhận (`recipient`)

"address": {
  "details": "123 Main Street, Apt 4B",
  "addressText2": "Flat 2", // Bắt buộc khi gửi đi UK (mã GB), chứa tên đường/phường
  "city": "New York",
  "state": "NY",
  "country": "US",
  "zip": "10001",
  "iossCode": "IM3720000222" // Mã IOSS (nếu gửi hàng vào EU/UK)
},
"recipient": {
  "firstName": "John",
  "lastName": "Doe",
  "phone": "+1234567890",
  "email": "customer@example.com",
  "note": "Gọi trước khi giao hàng"
}

3. Thông tin nhãn vận chuyển (`shippingLabel`)

"shippingLabel": {
  "labelUrl": "https://storage.yourdomain.com/labels/label_123.pdf",
  "trackingNumber": "9400111899562537635678",
  "trackingNumberByTiktok": "9400111899562537635678",
  "contentType": "pdf",
  "needScanLabel": true
}

4. Danh sách sản phẩm (`products`)

Mỗi phần tử trong mảng products đại diện cho một sản phẩm cần sản xuất:

Thuộc tính	Kiểu	Mô tả
`productCode`	`string`	Mã phôi sản phẩm (ví dụ: `P001`, `P004`, `SW01`). Phôi phải đang cho phép bán (`allowSale != false`); nếu tắt trên CMS sẽ trả lỗi not available for sale.
`productType`	`string`	Kỹ thuật sản xuất: `EMBROIDERY` (Thêu), `PRINT_2D` (In 2D), `PRINT_3D` (In 3D), `PRINT_UV` (In UV), `PRINT_3D_EMBROIDERY` (In 3D rồi chuyển qua thêu). Phải khớp category của mã phôi (xem bảng bên dưới). Có thể bỏ trống — hệ thống lấy `defaultProductType` trên master product (hoặc suy từ category).
`quantity`	`integer`	Số lượng sản phẩm (tối thiểu `1`).
`size`	`string`	Kích cỡ sản phẩm: `S`, `M`, `L`, `XL`, `2XL`, `3XL`, v.v.
`colorCode`	`string`	Mã màu áo phôi (ví dụ: `BLACK`, `WHITE`, `SAND`, `NAVY`, `AS_DESIGN`).
`positionCode`	`string`	Vị trí chính (ví dụ: `CENTER`, `LEFT_CHEST`).
`mPid`	`string` (tối đa 70)	Marketplace product ID: ASIN / Item Number / SKU trên sàn. Bắt buộc khi `shippingMethod = SHIP_TO_EU`; dùng làm `declaration_info[].mpid` khi tạo đơn vận chuyển.
`designAttachments`	`array`	Danh sách file thiết kế & cấu hình màu thêu (xem chi tiết tại Cẩm nang thêu & đắp vải).
`feeCodes`	`array`	Danh sách mã phụ phí cấp sản phẩm (xem bảng bên dưới). Tùy chọn — một số mã được hệ thống tự gắn theo `designAttachments`.

Map `category.code` (master product) → `productType`

Khi tạo đơn, productType phải khớp danh mục của mã phôi trên hệ thống:

Category code	Tên danh mục	`productType` / `defaultProductType`
`SHIRT`	SẢN PHẨM THÊU	`EMBROIDERY`
`DM002`	SẢN PHẨM IN 2D (DTF)	`PRINT_2D`
`DM003`	SẢN PHẨM IN 3D	`PRINT_3D` hoặc `PRINT_3D_EMBROIDERY` (cấu hình trên CMS theo từng phôi)
`DM004`	SẢN PHẨM IN UV	`PRINT_UV`

Master product có field defaultProductType — portal khách ẩn chọn loại SP và dùng giá trị này. Hybrid In 3D + Thêu: set defaultProductType = PRINT_3D_EMBROIDERY trên CMS (phôi DM003 hoặc SHIRT). Luồng SX hybrid: Thiết kế in → In 3D → Phôi 3D → Thiết kế thêu (embroideryDesignStatus) → Thêu → QC thêu → Đóng gói thêu. Hybrid dùng hai file thiết kế tách biệt trên designAttachments[]: designUrl = file in 3D, designEmbUrl = file thêu. Thêu/in thuần vẫn chỉ dùng designUrl. Thiếu designEmbUrl → tự gắn DESIGN_FILE_EMB. Phí 2_SIDE_PRINTED (In 2 mặt) chỉ hiện khi master product có allowTwoSidePrint != false (mặc định cho phép). Tắt checkbox Cho phép in 2 mặt trên CMS nếu SP chỉ in 1 mặt. Sản phẩm có allowSale = false (tắt Cho phép bán trên CMS) vẫn xem được trên catalog nhưng không tạo được đơn qua Partner API / portal khách hàng.

Danh sách mã `feeCodes` hợp lệ (phí sản phẩm)

Nguồn: catalog phí (ord_fees) với showMode != 0 và có flag FEE_PRODUCT (hiển thị / chọn trên sản phẩm tương ứng màn hình tạo đơn form-order). Bạn có thể tra cứu danh sách phụ phí có thể chọn qua endpoint GET /v1/partner/product-fees (hỗ trợ lọc theo productType) hoặc trường productFees trong GET /v1/partner/embroidery-catalogs. Các phí không thể chọn (như EMBROIDERY_STITCH_OVERAGE hay EMBROIDERY_3D) được ẩn đi hoàn toàn. Không gửi mã vận chuyển trong feeCodes — dùng field shippingMethod.

Mã (`code`)	Mô tả	Loại SP áp dụng	Ghi chú
`GLITTER_COLOR`	Chọn màu kim tuyến	`EMBROIDERY`, `PRINT_3D_EMBROIDERY`	Tự gắn khi `designAttachments[].glitterColors` có giá trị.
`YARN_COLOR`	Chọn màu len	`EMBROIDERY`, `PRINT_3D_EMBROIDERY`	Tự gắn khi `designAttachments[].yarnColors` có giá trị.
`CHOOSE_PATTERN_FABRIC`	Chọn mẫu vải	`EMBROIDERY`, `PRINT_3D_EMBROIDERY`	Tự gắn khi `designAttachments[].fabricPatterns` có giá trị.
`DESIGN_FILE_EMB`	Phí thiết kế file thêu	`EMBROIDERY`, `PRINT_3D_EMBROIDERY`	Tự gắn khi `EMBROIDERY` thiếu `designUrl`, hoặc `PRINT_3D_EMBROIDERY` thiếu `designEmbUrl`. Khi đó mỗi `designAttachment` bắt buộc có `mockupUrl` + `note` — thiếu thì đơn kẹt `NEW`, `autoDeposit` không đặt cọc được.
`3D_FOAM_EMBROIDERY`	Thêu đắp mút 3D	`EMBROIDERY`, `PRINT_3D_EMBROIDERY`	Gửi thủ công trong `feeCodes` khi cần thêu lót 3D.
`SLEEVE_BOW_EMBROIDERY`	Thêu nơ / tay áo	`EMBROIDERY`, `PRINT_3D_EMBROIDERY`	Gửi thủ công trong `feeCodes` khi thêu tay áo (kèm `sleeveNumber`).
`DESIGN`	Phí xử lý thiết kế	`PRINT_2D`, `PRINT_3D`, `PRINT_3D_EMBROIDERY`	Gửi trong `feeCodes` khi tạo đơn in 2D / 3D.
`2_SIDE_PRINTED`	In 2 mặt	`PRINT_UV`	Chỉ khi `productType = PRINT_UV` và master product `allowTwoSidePrint != false`.

Phụ phí vượt mũi thêu (EMBROIDERY_STITCH_OVERAGE) được hệ thống tự tính khi tổng mũi thêu > 50,000 mũi, không thể chọn thủ công nên ẩn đi khỏi API tra cứu product-fees.

Các phí vận chuyển trong catalog (TRANSPORT_FEE, HOGOTOFAST, HOGOTO_EPACKET, SHIPPING_OUTSIDE_US, SHIPPING_TIKTOK_US, SHIPPING_TIKTOK_UK, SHIP_TO_EU, NON_SHIPPING, SCAN_LABEL, …) không đưa vào feeCodes; hệ thống áp theo shippingMethod / cấu hình đơn.

Ví dụ tạo đơn hoàn chỉnh

Đơn thêu đắp vải & kim tuyến
Đơn in ấn All-Over-Print (3D)
Tạo nhiều đơn hàng loạt (Batch)

curl --location 'https://seller.hogotopod.com/api/v1/partner/order/store' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant: fulfillment' \
  --header 'Content-Type: application/json' \
  --data '{
  "referenceCode": "ORD_EMB_9921",
  "autoDeposit": true,
  "shippingMethod": "HOGOTOFAST",
  "address": {
    "details": "742 Evergreen Terrace",
    "addressText2": "",
    "city": "Springfield",
    "state": "OR",
    "country": "US",
    "zip": "97477"
  },
  "recipient": {
    "firstName": "Homer",
    "lastName": "Simpson",
    "phone": "+15415551234",
    "email": "homer@example.com"
  },
  "products": [
    {
      "productCode": "SW01",
      "productType": "EMBROIDERY",
      "quantity": 1,
      "size": "L",
      "colorCode": "SAND",
      "feeCodes": ["GLITTER_COLOR", "CHOOSE_PATTERN_FABRIC"],
      "designAttachments": [
        {
          "positionCode": "CENTER",
          "designUrl": "https://example.com/designs/mama_flower.png",
          "mockupUrl": "https://example.com/mockups/sweater_sand.jpg",
          "threadColors": "WHITE",
          "glitterColors": "GOLD,SILVER",
          "yarnColors": "RED,WHITE",
          "fabricPatterns": "MAMA,FLORAL_01"
        }
      ]
    }
  ]
}'

curl --location 'https://seller.hogotopod.com/api/v1/partner/order/store' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant: fulfillment' \
  --header 'Content-Type: application/json' \
  --data '{
  "referenceCode": "ORD_PRINT_3D_102",
  "autoDeposit": true,
  "shippingMethod": "HOGOTO_EPACKET",
  "address": {
    "details": "100 Broadway",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "zip": "10005"
  },
  "recipient": {
    "firstName": "Alice",
    "lastName": "Smith",
    "phone": "+12125559876",
    "email": "alice@example.com"
  },
  "products": [
    {
      "productCode": "TS3D_01",
      "productType": "PRINT_3D",
      "quantity": 2,
      "size": "XL",
      "colorCode": "AS_DESIGN",
      "designAttachments": [
        {
          "positionCode": "ALL_OVER_PRINT",
          "designUrl": "https://example.com/designs/aop_pattern.jpg",
          "mockupUrl": "https://example.com/mockups/tshirt_front.jpg"
        }
      ]
    }
  ]
}'

curl --location 'https://seller.hogotopod.com/api/v1/partner/order/store-batch' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant: fulfillment' \
  --header 'Content-Type: application/json' \
  --data '[
    {
      "referenceCode": "BATCH_ORD_01",
      "autoDeposit": true,
      "shippingMethod": "HOGOTOFAST",
      "address": { "details": "123 Main St", "city": "Dallas", "state": "TX", "country": "US", "zip": "75001" },
      "recipient": { "firstName": "Bob", "lastName": "Lee", "phone": "+19725551122" },
      "products": [{ "productCode": "P001", "productType": "PRINT_2D", "quantity": 1, "size": "M", "colorCode": "BLACK" }]
    },
    {
      "referenceCode": "BATCH_ORD_02",
      "autoDeposit": true,
      "shippingMethod": "HOGOTOFAST",
      "address": { "details": "456 Elm St", "city": "Miami", "state": "FL", "country": "US", "zip": "33101" },
      "recipient": { "firstName": "Carol", "lastName": "Danvers", "phone": "+13055553344" },
      "products": [{ "productCode": "P001", "productType": "PRINT_2D", "quantity": 1, "size": "L", "colorCode": "WHITE" }]
    }
  ]'

Ước tính giá đơn hàng trước khi đặt (`/order/estimate`)

Nếu hệ thống của bạn cần hiển thị trước tổng tiền (giá gốc sản phẩm + các loại phụ phí + cước vận chuyển) cho khách hàng hoặc nhân viên duyệt:

Gửi payload giống hệt POST /v1/partner/order/store tới endpoint:
POST https://seller.hogotopod.com/api/v1/partner/order/estimate
Kết quả trả về sẽ tính toán chi tiết:
- amountProduct: Tiền sản xuất gốc.
- amountTransport: Phí vận chuyển ước tính.
- totalFee: Tổng phụ phí (kim tuyến, vải đắp, thêu tay áo, v.v.).
- amount: Tổng số tiền thanh toán cuối cùng.
Đơn hàng ước tính sẽ không được lưu vào danh sách đơn và không trừ tiền tài khoản.

Bắt đầu

Hướng dẫn tích hợp

Các phương thức tạo đơn

Cấu trúc Payload chi tiết (`PartnerOrderAddInfo`)

1. Thông tin chung

2. Thông tin địa chỉ (`address`) & Người nhận (`recipient`)

3. Thông tin nhãn vận chuyển (`shippingLabel`)

4. Danh sách sản phẩm (`products`)

Map `category.code` (master product) → `productType`

Danh sách mã `feeCodes` hợp lệ (phí sản phẩm)

Ví dụ tạo đơn hoàn chỉnh

Ước tính giá đơn hàng trước khi đặt (`/order/estimate`)

​Các phương thức tạo đơn

​Cấu trúc Payload chi tiết (PartnerOrderAddInfo)

​1. Thông tin chung

​2. Thông tin địa chỉ (address) & Người nhận (recipient)

​3. Thông tin nhãn vận chuyển (shippingLabel)

​4. Danh sách sản phẩm (products)

​Map category.code (master product) → productType

​Danh sách mã feeCodes hợp lệ (phí sản phẩm)

​Ví dụ tạo đơn hoàn chỉnh

​Ước tính giá đơn hàng trước khi đặt (/order/estimate)

Các phương thức tạo đơn

Cấu trúc Payload chi tiết (`PartnerOrderAddInfo`)

1. Thông tin chung

2. Thông tin địa chỉ (`address`) & Người nhận (`recipient`)

3. Thông tin nhãn vận chuyển (`shippingLabel`)

4. Danh sách sản phẩm (`products`)

Map `category.code` (master product) → `productType`

Danh sách mã `feeCodes` hợp lệ (phí sản phẩm)

Ví dụ tạo đơn hoàn chỉnh

Ước tính giá đơn hàng trước khi đặt (`/order/estimate`)