Cẩm nang Thêu & Đắp vải

Kỹ thuật thêu vi tính (Computerized Embroidery) và đắp vải (Appliqué) tại Hogotopod đòi hỏi độ chính xác cao về màu sắc chỉ và chất liệu vải. Để đảm bảo sản phẩm xuất xưởng đúng như thiết kế của bạn, hệ thống cung cấp các endpoint danh mục chuẩn hóa để đồng bộ trực tiếp với xưởng thêu.

Endpoint tổng hợp khuyến nghị

Thay vì phải gọi nhiều API đơn lẻ, bạn chỉ cần gọi một endpoint duy nhất:

GET https://seller.hogotopod.com/api/v1/partner/embroidery-catalogs

Endpoint này dùng chung nguồn dữ liệu với màn hình tạo đơn trên Seller Portal (form-order), đảm bảo 100% đồng nhất giữa giao diện web và API.

Cấu trúc kết quả trả về (`PartnerEmbroideryCatalogDto`)

{
  "threadColors": [ ... ],      // Danh sách mã màu chỉ thêu chuẩn hóa (group EMBROIDERY_THREAD_COLOR)
  "glitterColors": [ ... ],     // Danh sách màu kim tuyến hợp lệ (group GLITTER_COLOR)
  "yarnColors": [ ... ],        // Danh sách màu len / chỉ thêu xù (group YARN_COLOR)
  "fabricPatterns": [ ... ],    // Danh sách mẫu hoa văn vải đắp
  "fabricCategories": [ ... ],  // Nhóm phân loại mẫu vải (để lọc UI)
  "positions": [ ... ],         // Các vị trí thêu được hỗ trợ
  "productFees": [ ... ]        // Danh sách phụ phí có thể chọn cấp sản phẩm áp dụng cho thêu
}

Bảng tra cứu chi tiết từng danh mục

Thuộc tính khi tạo đơn	Endpoint tra cứu riêng	Kiểu dữ liệu	Ghi chú & Giá trị mẫu
`threadColors`	`GET /v1/partner/catalogs/group/EMBROIDERY_THREAD_COLOR`	`string` (chuỗi mã)	Mã màu chỉ thêu vi tính chuẩn hóa (lấy thuộc tính `code`), ví dụ: `WHITE`. Bắt buộc gửi đúng 1 mã màu duy nhất có sẵn trong danh mục.
`glitterColors`	`GET /v1/partner/catalogs/group/GLITTER_COLOR`	`string` (chuỗi mã)	Mã màu kim tuyến (lấy thuộc tính `code`), ví dụ: `GOLD`, `SILVER`, `RED`.
`yarnColors`	`GET /v1/partner/catalogs/group/YARN_COLOR`	`string` (chuỗi mã)	Mã màu len/chỉ thêu xù (lấy thuộc tính `code`), ví dụ: `WHITE`, `BLACK`, `PINK`.
`fabricPatterns`	`GET /v1/partner/fabrics`	`string` (chuỗi mã)	Mã hoa văn vải đắp (lấy thuộc tính `code` của fabric), ví dụ: `MAMA`, `A1`, `FLORAL_01`.
`positionCode`	`GET /v1/partner/catalogs/group/PRODUCT_POSITIONS`	`string` (chuỗi mã)	Vị trí in/thêu: `CENTER`, `LEFT_CHEST`, `RIGHT_CHEST`, `SLEEVE_LEFT`, `SLEEVE_RIGHT`.
`feeCodes`	`GET /v1/partner/product-fees`	`array<string>`	Danh sách phụ phí có thể chọn cấp sản phẩm. Hỗ trợ lọc `?productType=EMBROIDERY` hoặc theo loại sản phẩm khác. Các phí không thể chọn được ẩn đi.

Field outline / endpoint GET /v1/partner/outlines đã ngừng. Không gửi outline khi tạo đơn; thêu đắp vải chỉ cần fabricPatterns.

Cấu hình màu chỉ thêu (`threadColors`)

Hệ thống quản lý màu chỉ thêu vi tính theo bảng mã chỉ chuẩn hóa để xưởng thêu chuẩn bị chỉ chính xác cho từng vị trí thiết kế:

Không còn sử dụng enum: Hệ thống đã loại bỏ hoàn toàn các giá trị enum giả định như SAME_AS_MOCKUP (giống mockup) hay SAME_AS_DESIGN (giống file thiết kế) trên cả Backend API lẫn Giao diện Seller/Customer Portal. Bạn chỉ chọn các mã màu chỉ có sẵn trong danh mục (EMBROIDERY_THREAD_COLOR) được cấp bởi hệ thống.

Quy tắc gửi màu chỉ thêu:

Lấy danh sách mã màu hợp lệ: Gọi GET /v1/partner/embroidery-catalogs lấy mảng threadColors, hoặc gọi GET /v1/partner/catalogs/group/EMBROIDERY_THREAD_COLOR. Mỗi phần tử có code (mã màu), name (tên màu hiển thị) và hình ảnh mẫu chỉ.
Chỉ gửi đúng 1 mã màu: Mỗi vị trí thêu bắt buộc chọn đúng 1 màu chỉ duy nhất, gửi trực tiếp mã màu, ví dụ: "threadColors": "WHITE". Hệ thống sẽ từ chối nếu gửi nhiều màu ngăn cách bởi dấu phẩy.
Phân biệt các chất liệu thêu:
- threadColors: Chỉ thêu vi tính tiêu chuẩn (thêu phẳng, chi tiết nét) — chỉ chọn 1 màu duy nhất.
- yarnColors: Chỉ len / sợi thêu xù (thường dùng cho áo bóng chày, áo hoodie vintage). Gắn kèm phụ phí YARN_COLOR.
- glitterColors: Chỉ kim tuyến lấp lánh (Gold, Silver, kim tuyến màu). Gắn kèm phụ phí GLITTER_COLOR.
- fabricPatterns: Mẫu vải thêu đắp (Appliqué). Gắn kèm phụ phí CHOOSE_PATTERN_FABRIC.

Quy tắc định dạng khi gửi đơn hàng

1. Chọn nhiều màu / nhiều mẫu vải

Đối với các dịch vụ phụ trợ như kim tuyến, len hoặc vải đắp, nếu thiết kế sử dụng đồng thời nhiều loại, hãy nối các mã bằng dấu phẩy (không chứa dấu cách thừa). Riêng threadColors chỉ gửi đúng 1 mã duy nhất:

{
  "threadColors": "WHITE",
  "glitterColors": "GOLD,SILVER",
  "yarnColors": "RED,WHITE,BLUE",
  "fabricPatterns": "MAMA,A1,F1"
}

2. Cấu hình mảng `feeCodes` tương ứng

Khi thiết kế có sử dụng các tùy chọn đặc biệt, bạn có thể khai báo các mã phụ phí tương ứng vào mảng feeCodes của sản phẩm (tra cứu từ GET /v1/partner/product-fees hoặc productFees trong GET /v1/partner/embroidery-catalogs):

GLITTER_COLOR: Nếu có chọn màu kim tuyến (glitterColors). Hệ thống tự động gắn khi có dữ liệu.
YARN_COLOR: Nếu có chọn màu len (yarnColors). Hệ thống tự động gắn khi có dữ liệu.
CHOOSE_PATTERN_FABRIC: Nếu có chọn mẫu vải đắp (fabricPatterns). Hệ thống tự động gắn khi có dữ liệu.
DESIGN_FILE_EMB: Phí thiết kế file thêu (tự động gắn khi EMBROIDERY thiếu designUrl, hoặc PRINT_3D_EMBROIDERY thiếu designEmbUrl).
3D_FOAM_EMBROIDERY: Thêu lót 3D (đối tác gửi thủ công trong feeCodes khi cần).
SLEEVE_BOW_EMBROIDERY: Thêu nơ / tay áo (gửi kèm sleeveNumber).

Phụ phí vượt mũi thêu (EMBROIDERY_STITCH_OVERAGE) là phụ phí hệ thống tự động tính khi tổng số mũi thêu > 50,000 mũi, người dùng không thể chọn thủ công nên được ẩn đi hoàn toàn khỏi danh sách productFees.

Cấu trúc chuẩn của một `designAttachment`

{
  "positionCode": "CENTER",
  "designUrl": "https://your-domain.com/designs/embroidery_front.png",
  "mockupUrl": "https://your-domain.com/mockups/hoodie_sand_front.jpg",
  "dstFileUrl": "https://your-domain.com/files/design_pattern.dst",
  "threadColors": "WHITE",
  "glitterColors": "GOLD",
  "yarnColors": "WHITE",
  "fabricPatterns": "MAMA",
  "note": "Ưu tiên viền chỉ trắng sắc nét"
}

Với productType = PRINT_3D_EMBROIDERY, gửi thêm designEmbUrl (file thêu). designUrl là file thiết kế in 3D:

{
  "positionCode": "CENTER",
  "designUrl": "https://your-domain.com/designs/print_3d_front.png",
  "designEmbUrl": "https://your-domain.com/designs/embroidery_front.png",
  "mockupUrl": "https://your-domain.com/mockups/hoodie_sand_front.jpg",
  "threadColors": "WHITE"
}

Nếu bạn đã có sẵn file số hóa mẫu thêu định dạng .dst (Tajima), bạn có thể truyền đường dẫn vào trường dstFileUrl. Xưởng có thể nạp thẳng vào máy thêu mà không cần qua khâu vẽ lại số hóa (digitizing).

Bắt đầu

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

Endpoint tổng hợp khuyến nghị

Cấu trúc kết quả trả về (`PartnerEmbroideryCatalogDto`)

Bảng tra cứu chi tiết từng danh mục

Cấu hình màu chỉ thêu (`threadColors`)

Quy tắc gửi màu chỉ thêu:

Quy tắc định dạng khi gửi đơn hàng

1. Chọn nhiều màu / nhiều mẫu vải

2. Cấu hình mảng `feeCodes` tương ứng

Cấu trúc chuẩn của một `designAttachment`

​Endpoint tổng hợp khuyến nghị

​Cấu trúc kết quả trả về (PartnerEmbroideryCatalogDto)

​Bảng tra cứu chi tiết từng danh mục

​Cấu hình màu chỉ thêu (threadColors)

​Quy tắc gửi màu chỉ thêu:

​Quy tắc định dạng khi gửi đơn hàng

​1. Chọn nhiều màu / nhiều mẫu vải

​2. Cấu hình mảng feeCodes tương ứng

​Cấu trúc chuẩn của một designAttachment

Endpoint tổng hợp khuyến nghị

Cấu trúc kết quả trả về (`PartnerEmbroideryCatalogDto`)

Bảng tra cứu chi tiết từng danh mục

Cấu hình màu chỉ thêu (`threadColors`)

Quy tắc gửi màu chỉ thêu:

Quy tắc định dạng khi gửi đơn hàng

1. Chọn nhiều màu / nhiều mẫu vải

2. Cấu hình mảng `feeCodes` tương ứng

Cấu trúc chuẩn của một `designAttachment`