Integration Guide

Hướng dẫn tích hợp API tạo đơn POD — giải thích chi tiết các field, rules, và ví dụ.

Overview

API tạo đơn POD hỗ trợ 2 loại đơn:

• Đơn thường — Hệ thống tính phí ship
• Đơn có label — Bạn cung cấp sẵn shipping label (TikTok, Etsy, v.v.)

Authentication

Authorization: Bearer <your_token>

Ví dụ nhanh

Đơn thường (không có label)

POST /v1/orders/pod

{
  "reference_id": "MY-ORDER-001",
  "customer": {
    "email": "customer@example.com",
    "first_name": "John",
    "last_name": "Doe",
    "phone": "+14155551234"
  },
  "shipping_address": {
    "address1": "123 Main St",
    "address2": "Apt 4B",
    "city": "Los Angeles",
    "province": "CA",
    "country_code": "US",
    "zip": "90001"
  },
  "shipping_service": "eco",
  "line_items": [
    {
      "variant_id": "3c371069-9ff6-4930-ab3a-3f130fe77afe",
      "quantity": 2,
      "sides": {
        "front_large": "https://cdn.example.com/design-front.png",
        "back": "https://cdn.example.com/design-back.png"
      },
      "printing_technique": "DTG"
    }
  ],
  "note": "Please prioritize",
  "tags": "rush,vip"
}

Đơn có label (TikTok/Etsy)

POST /v1/orders/pod

{
  "reference_id": "TIKTOK-ORDER-001",
  "customer": {
    "email": "customer@example.com",
    "first_name": "Jane",
    "last_name": "Smith"
  },
  "label_link": "https://labels.tiktok.com/your-label.pdf",
  "tracking_number": "9400111899223456789012",
  "shipping_service": "eco",
  "line_items": [
    {
      "variant_id": "3c371069-9ff6-4930-ab3a-3f130fe77afe",
      "quantity": 1,
      "sides": {
        "front_large": "https://cdn.example.com/design.png"
      },
      "printing_technique": "DTF"
    }
  ]
}

Hai loại đơn

Warning: Bạn chỉ được chọn 1 trong 2 loại. Không được truyền cả shipping_address lẫn label_link.

Loại 1: Đơn thường

Truyền shipping_address. Hệ thống sẽ tính phí ship dựa trên shipping_service và country_code.

Loại 2: Đơn có label

Truyền label_link + tracking_number. Không truyền shipping_address.

Important: label_link và tracking_number phải đi đôi — truyền 1 thiếu 1 sẽ bị reject.

Sides (vị trí in/thêu)

Mỗi line item bắt buộc có ít nhất 1 side. Truyền dạng object { "side_code": "url_ảnh" }.

Side codes hợp lệ

Note: URL phải là link ảnh hợp lệ (bắt đầu bằng http:// hoặc https://).

Printing (In ấn)

Dùng cho đơn in trên vải.

{
  "sides": { "front_large": "https://..." },
  "printing_technique": "DTG"
}

Embroidery (Thêu)

Dùng cho đơn thêu. Có 2 trường hợp:

Trường hợp 1: Có file thêu sẵn

Bạn đã có file thêu định dạng chuyên dụng (.dst, .pes, .jef...) và gửi kèm.

{
  "sides": { "front_large": "https://..." },
  "emb_file": "Available"
}

Chỉ cần truyền emb_file: "Available". Không cần các field khác.

Trường hợp 2: Không có file thêu (cần digitize)

Bạn chỉ có hình design, cần bên mình chuyển đổi sang file thêu.

{
  "sides": { "front_large": "https://..." },
  "emb_file": "No EMB file",
  "design_emb_type": "vector / cartoon artwork"
}

Khi emb_file = "No EMB file", bắt buộc truyền design_emb_type:

Photo to Embroidery

Nếu chọn "Photo to Embroidery", bắt buộc truyền thêm number_of_pets:

{
  "emb_file": "No EMB file",
  "design_emb_type": "Photo to Embroidery",
  "number_of_pets": 2
}

Warning: Không mix in và thêu trong cùng 1 line item. Chọn printing_technique HOẶC emb_file, không cả hai.

Yarn Type (Loại chỉ thêu)

Note: Field này phụ thuộc vào product variant. Không phải tất cả sản phẩm đều cần.

Cách biết variant nào cần yarn_type

Gọi API lấy products, mỗi variant có field requires_yarn_type là mảng các yarn_type hợp lệ cho variant đó:

GET /v1/stores/{store_id}/products

// Response:
{
  "variant_id": "abc-123",
  "title": "Black / M",
  "category": "hoodie",
  "requires_yarn_type": ["yarn_6_7mm", "yarn_8_10mm", "yarn_20mm"]  // ← chọn 1 giá trị trong mảng
}

• Mảng rỗng [] → KHÔNG ĐƯỢC truyền yarn_type (truyền vào sẽ bị reject).
• Mảng có phần tử → BẮT BUỘC truyền yarn_type, và giá trị phải nằm trong mảng đó.

Đừng đoán theo tên sản phẩm — luôn đọc mảng requires_yarn_type của chính variant rồi chọn 1 giá trị.

Mảng hợp lệ theo category

Ý nghĩa các giá trị

Ví dụ

{
  "variant_id": "variant-requires-yarn",
  "quantity": 1,
  "sides": { "front_large": "https://..." },
  "emb_file": "Available",
  "yarn_type": "yarn_8_10mm"
}

Add-on Service

Dịch vụ bổ sung (optional):

{
  "addon_service": "Fabric applique"
}

Warning: Không khả dụng cho sản phẩm tote và cap/hat.

Shipping Service

Dedup (Chống trùng đơn)

Hệ thống kiểm tra trùng đơn theo reference_id:

• Cùng reference_id + cùng store → bị reject 409 DUPLICATE_REFERENCE_ID
• Nếu muốn bỏ qua soft dedup (content hash), truyền "force": true

Order Flow

Tạo đơn → PENDING → QUEUED → PROCESSING → SUCCESS
                                             ↓
                                           FAILED (auto retry tối đa 3 lần)

Kiểm tra trạng thái

GET /v1/orders/pod/{order_id}

Retry đơn FAILED

POST /v1/orders/pod/{order_id}/retry

Hủy đơn

POST /v1/orders/pod/{order_id}/cancel

Chỉ hủy được đơn ở trạng thái PENDING, QUEUED, hoặc FAILED.

Errors thường gặp

Checklist trước khi gửi đơn

1. ✅ Lấy variant_id từ API Products
2. ✅ Check requires_yarn_type — nếu mảng không rỗng thì chọn 1 giá trị trong mảng làm yarn_type
3. ✅ Chọn loại đơn: shipping_address HOẶC label_link + tracking_number
4. ✅ Truyền ít nhất 1 side trong sides với URL ảnh hợp lệ
5. ✅ Chọn technique: printing_technique HOẶC emb_file (không cả hai)
6. ✅ Nếu emb_file = "No EMB file" → truyền design_emb_type
7. ✅ Nếu design_emb_type = "Photo to Embroidery" → truyền number_of_pets