Bắt đầu nhanh (Quickstart) - Hogotopod Partner API

Trang này hướng dẫn bạn từng bước từ chuẩn bị cấu hình xác thực đến việc gửi thành công đơn hàng thêu/in đầu tiên tới hệ thống sản xuất của Hogotopod.

Chuẩn bị

Trước khi thực hiện lệnh gọi API, hãy đảm bảo bạn đã:

Đăng ký tài khoản tại Seller Portal.
Tạo một API Key (xem hướng dẫn tại Xác thực & API Key).
Chuẩn bị URL ảnh thiết kế (designUrl) và mockup (mockupUrl) công khai để xưởng in/thêu có thể tải về.

Các bước thực hiện

Bước 1: Kiểm tra kết nối & tra cứu danh mục thêu

Trước khi tạo đơn hàng có sản phẩm thêu, bạn nên gọi API danh mục để lấy danh sách mã màu kim tuyến, len, mẫu vải hợp lệ:

curl --location 'https://seller.hogotopod.com/api/v1/partner/embroidery-catalogs' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant: fulfillment' \
  --header 'Content-Type: application/json'

Phản hồi sẽ trả về các mảng danh mục: threadColors, glitterColors, yarnColors, fabricPatterns, positions.

Bước 2: Gửi yêu cầu tạo đơn hàng (POST /v1/partner/order/store)

Gửi lệnh cURL dưới đây để tạo đơn hàng thêu áo với mã tham chiếu ORDER_001. Hãy thay YOUR_API_KEY bằng key thực tế của bạn:

curl --location 'https://seller.hogotopod.com/api/v1/partner/order/store' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --header 'X-Tenant: fulfillment' \
  --data '{
  "referenceCode": "ORDER_001",
  "customerNote": "Vui lòng kiểm tra kỹ đường chỉ thêu",
  "autoDeposit": true,
  "shippingMethod": "TIKTOK",
  "address": {
    "details": "123 Main Street",
    "addressText2": "",
    "city": "New York",
    "state": "NY",
    "country": "US",
    "zip": "10001"
  },
  "recipient": {
    "firstName": "John",
    "lastName": "Doe",
    "email": "customer@example.com",
    "phone": "+1234567890",
    "note": null
  },
  "shippingLabel": {
    "labelUrl": "USPS",
    "trackingNumber": "1234567890",
    "trackingNumberByTiktok": "1234567890",
    "providerCode": null,
    "contentType": null,
    "type": null,
    "needScanLabel": true
  },
  "products": [
    {
      "productCode": "P001",
      "productType": "EMBROIDERY",
      "quantity": 1,
      "size": "M",
      "colorCode": "AS_DESIGN",
      "positionCode": null,
      "feeCodes": ["GLITTER_COLOR"],
      "designAttachments": [
        {
          "positionCode": "ALL_OVER_PRINT",
          "designUrl": "https://example.com/design.jpg",
          "mockupUrl": "https://example.com/mockup.jpg",
          "threadColors": "WHITE",
          "glitterColors": "GOLD",
          "yarnColors": null,
          "fabricPatterns": null,
          "note": null
        }
      ]
    }
  ]
}'

Bước 3: Kiểm tra phản hồi đơn hàng

Nếu đơn hàng hợp lệ, hệ thống sẽ trả về mã đơn hàng code (ví dụ: ORD-20260914-XXXX) cùng thông tin tổng tiền và trạng thái:

{
  "error": false,
  "code": "200",
  "message": "Thành công",
  "result": {
    "id": "66f4xxxxxxxxxxxx",
    "code": "ORD-20260914-0012",
    "referenceCode": "ORDER_001",
    "status": "NEW",
    "customerDisplayStatus": "DEPOSITED",
    "totalQuantity": 1,
    "amountProduct": 18.5,
    "amountTransport": 5.2,
    "totalFee": 23.7
  }
}

Bước 4: Tra cứu chi tiết & tiến độ sản xuất

Sử dụng mã code vừa nhận được để tra cứu thông tin chi tiết bất cứ lúc nào:

curl --location 'https://seller.hogotopod.com/api/v1/partner/order/detail?orderCode=ORD-20260914-0012' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Tenant: fulfillment'

Tiếp theo là gì?

Chi tiết tạo đơn hàng

Khám phá tạo đơn hàng loạt, ước tính chi phí và cấu hình nâng cao.

Cẩm nang thêu & đắp vải

Hướng dẫn toàn diện về phối màu chỉ thêu, thêu kim tuyến và đắp vải.

​Chuẩn bị

​Các bước thực hiện

​Tiếp theo là gì?

Chi tiết tạo đơn hàng

Cẩm nang thêu & đắp vải

Chuẩn bị

Các bước thực hiện

Tiếp theo là gì?