API dành cho nhà phát triển

Customix Integrations API cho phép bạn đưa các đơn hàng cá nhân hoá vào hệ thống của riêng mình — gồm file in do Customix tạo và mọi nội dung khách hàng đã nhập khi cá nhân hoá, như tên, chữ tuỳ chỉnh, màu sắc và bố cục đã chọn. Hãy dùng API này khi một công cụ sản xuất, bảng tính hoặc nền tảng tự động hoá như Make cần thông tin đơn hàng của bạn mà không phải ai đó sao chép thủ công.

Để lấy API key, vào Cài đặt ở thanh bên trái, mở tab Tích hợp, rồi bấm Tạo key trong thẻ API key. Xem Cách lấy API key của Customix để biết chi tiết.

🔑 Xác thực

Mọi yêu cầu đều cần API key của bạn trong header:

Authorization: Bearer <your_api_key>

🌐 Base URL

https://app.customix.io/api/integrations/v1

📘 Endpoint

1. Lấy danh sách đơn hàng

Endpoint:

GET /orders

Mô tả: Lấy các đơn hàng cá nhân hoá của bạn, mặc định đơn mới nhất xếp trước.

Tham số:

Header:

Ví dụ yêu cầu:

GET https://app.customix.io/api/integrations/v1/orders?shop=abcdef&limit=2

Phản hồi:

{
  "data": [
    {
      "shop": "abcdef.myshopify.com",
      "order_id": 123456789,
      "order_number": "#1001",
      "currency": "USD",
      "customer": "John Doe",
      "email": "[email protected]",
      "ip": "123.123.123.123",
      "total_price": 123.45,
      "financial_status": "paid",
      "fulfillment_status": "fulfilled",
      "ordered_at": "2025-01-21 01:01:01",
      "customizations": [
        {
          "id": "01jjavmg7t7vqj5z6qvxwie14b",
          "public_customization_id": "01jjavmg7t7vqj5z6qvxwpc9kd",
          "campaign_id": "01jphjdfmtxhaio94h0wd0kv0c",
          "shopify_line_item_id": 11106133639222,
          "shopify_product_id": 11179841648222,
          "shopify_variant_id": 11191300929074,
          "platform": "shopify",
          "line_item_quantity": 1,
          "files": [
            {
              "id": "01jb3092vabc7m8qw4cdqv09we",
              "name": "default",
              "path": "https://d6opbaohxg209.cloudfront.net/temp/extracted_67d7d664c7awe/Accessory/Laptop.png"
            }
          ],
          "values": [
            { "key": "100001", "label": "Name", "type": "text-field", "value": "Emma" },
            { "key": "layout_100003", "label": "Layout", "type": "layout-swatch", "value": "Portrait" },
            { "key": "100004", "label": "Color", "type": "color-picker", "value": "#1a2b3c" }
          ]
        }
      ]
    }
  ]
}

Phản hồi lỗi:

2. Lấy một đơn hàng cụ thể

Endpoint:

GET /orders/{id}

Mô tả: Lấy một đơn hàng, kèm file in và các giá trị cá nhân hoá của nó.

Tham số:

Header:

Ví dụ yêu cầu:

GET https://app.customix.io/api/integrations/v1/orders/123456789?shop=abcdef

Phản hồi: một đơn hàng duy nhất trong data, với các trường giống như một mục trong danh sách ở trên:

{
  "data": {
    "shop": "abcdef.myshopify.com",
    "order_id": 123456789,
    "order_number": "#1001",
    "customizations": [
      {
        "id": "01jjavmg7t7vqj5z6qvxwie14b",
        "public_customization_id": "01jjavmg7t7vqj5z6qvxwpc9kd",
        "line_item_quantity": 1,
        "files": [
          { "id": "01jb3092vabc7m8qw4cdqv09we", "name": "default", "path": "https://d6opbaohxg209.cloudfront.net/temp/extracted_67d7d664c7awe/Accessory/Laptop.png" }
        ],
        "values": [
          { "key": "100001", "label": "Name", "type": "text-field", "value": "Emma" }
        ]
      }
    ]
  }
}

(Được rút gọn ở đây — phản hồi thực tế bao gồm mọi trường có trong ví dụ danh sách.)

Phản hồi lỗi:

3. Lấy phần tuỳ chỉnh của một đơn hàng cụ thể

Endpoint:

GET /orders/{order_id}/customizations/{public_customization_id}

Mô tả: Lấy một phần tuỳ chỉnh của một đơn hàng.

Tham số:

Header:

Ví dụ yêu cầu:

GET https://app.customix.io/api/integrations/v1/orders/123456789/customizations/01jjavmg7t7vqj5z6qvxwpc9kd?shop=abcdef

Phản hồi: riêng phần tuỳ chỉnh, không nằm trong data:

{
  "id": "01jjavmg7t7vqj5z6qvxwie14b",
  "public_customization_id": "01jjavmg7t7vqj5z6qvxwpc9kd",
  "campaign_id": "01jphjdfmtxhaio94h0wd0kv0c",
  "shopify_line_item_id": 11106133639222,
  "shopify_product_id": 11179841648222,
  "shopify_variant_id": 11191300929074,
  "platform": "shopify",
  "line_item_quantity": 1,
  "files": [
    {
      "id": "01jb3092vabc7m8qw4cdqv09we",
      "name": "default",
      "path": "https://d6opbaohxg209.cloudfront.net/temp/extracted_67d7d664c7awe/Accessory/Laptop.png"
    }
  ],
  "values": [
    { "key": "100001", "label": "Name", "type": "text-field", "value": "Emma" },
    { "key": "layout_100003", "label": "Layout", "type": "layout-swatch", "value": "Portrait" }
  ]
}

Phản hồi lỗi:

🖊️ Giá trị tuỳ chỉnh

Mỗi phần tuỳ chỉnh đều có values — mỗi mục tương ứng với một trường cá nhân hoá được lưu cùng đơn hàng, chính là những thông tin bạn thấy dưới dạng thuộc tính sản phẩm trên đơn hàng trong Shopify. Mỗi mục gồm:

• key: định danh của trường trong mẫu của bạn. Giá trị này giữ nguyên giữa các đơn hàng đối với cùng một trường của cùng một mẫu, vì vậy hãy dùng nó để ánh xạ các trường trong tích hợp của bạn.
• label: tên tuỳ chọn mà khách hàng của bạn đã thấy, ví dụ "Name". Có thể để trống ở các đơn hàng cũ hơn.
• type: loại tuỳ chọn, ví dụ text-field, color-picker, font-swatch, image-swatch, layout-swatch, date-picker hoặc file-upload.
• value: những gì khách hàng của bạn đã chọn hoặc nhập, luôn ở dạng văn bản.

Cách đọc value với từng loại tuỳ chọn:

• Chữ: chính xác những gì khách hàng của bạn đã gõ.
• Bộ chọn màu: mã màu mà khách hàng của bạn đã chọn.
• Ô mẫu font, ảnh, màu và viền: giá trị của ô mẫu mà khách hàng của bạn đã chọn.
• Ô mẫu bố cục: tên của bố cục mà khách hàng của bạn đã chọn, đúng như tên của nó tại thời điểm họ đặt hàng.
• Bộ chọn ngày và giờ: ngày hoặc giờ mà khách hàng của bạn đã chọn.
• File và vector tải lên: link đến file mà khách hàng của bạn đã tải lên.
• Bảng màu và font đám mây từ: các màu hoặc font mà khách hàng của bạn đã chọn, phân tách bằng dấu phẩy.
• Các tuỳ chọn không có dạng văn bản, như kiểu bản đồ, vị trí hoặc bài hát Spotify, sẽ trả về giá trị rỗng — hãy dùng file in cho những tuỳ chọn này.

⚠️ Mã lỗi thường gặp

📌 Ghi chú

• Mọi phản hồi đều ở dạng JSON.
• Giới hạn tần suất: 2 requests/second.
• Liên hệ [email protected] nếu có thắc mắc.

Cập nhật ngày: 14/09/2026