18. Tích Hợp API

◀ Mục lục

API của Inkica cho phép hệ thống của bạn tự gửi đơn sang Inkica — không cần vào dashboard tạo tay từng đơn. Phù hợp khi bạn:

• Bán trên website riêng hoặc một kênh Inkica chưa kết nối sẵn.
• Có công cụ/phần mềm riêng quản lý đơn và muốn đẩy thẳng sang xưởng.
• Muốn tự động hoá toàn bộ: đơn về → tạo đơn Inkica → theo dõi tracking.

Nếu bạn bán trên eBay, Etsy, TikTok Shop, Shopify hay Amazon, cách đơn giản hơn là kết nối shop — đơn tự về, không cần lập trình. API dành cho trường hợp còn lại.

Trang này viết cho cả bạn lẫn lập trình viên sẽ làm phần tích hợp — có thể gửi thẳng link trang này cho họ.

Tổng quan cách hoạt động

1. Tạo API token trên dashboard Inkica (làm 1 lần).
2. Tra catalog để lấy variant_id của sản phẩm muốn bán (mẫu áo, màu, size).
3. Tạo đơn — gửi địa chỉ người nhận + file in. Đơn được tạo ở trạng thái nháp, chưa trừ tiền.
4. Gửi sản xuất — Inkica trừ tiền từ ví và chuyển đơn sang xưởng.
5. Theo dõi đơn — đọc trạng thái và mã tracking khi đơn được giao cho hãng vận chuyển, hoặc đăng ký webhook để Inkica tự báo.

1. Tạo API token

1. Mở menu tài khoản (góc dưới cùng thanh bên) → API.
2. Bấm Create token, đặt tên dễ nhớ (vd “Website sync”).
3. Copy token ngay — token có dạng ink_pat_... và chỉ hiện đúng 1 lần. Đóng hộp thoại là không xem lại được, chỉ có cách tạo token mới.

🔒 Giữ token như giữ mật khẩu. Ai có token là tạo được đơn và tiêu tiền trong ví của bạn. Không dán token vào code chạy trên trình duyệt, không gửi qua chat, không commit lên GitHub. Nghi bị lộ → vào Settings → API bấm Revoke để thu hồi ngay, token đó hết hiệu lực lập tức.

Mỗi tài khoản có tối đa 10 token cùng lúc. Nên tạo mỗi hệ thống/công cụ 1 token riêng, để khi cần thu hồi 1 cái thì các cái khác vẫn chạy.

2. Gọi API

Thử nhanh token bằng cách lấy danh sách sản phẩm:

curl https://api.inkica.com/api/v1/catalog/blueprints?limit=5 \
  -H "Authorization: Bearer ink_pat_xxxxxxxxxxxx"

Nhận về danh sách sản phẩm là token đã dùng được.

3. Chọn sản phẩm (catalog)

Catalog có 2 tầng:

• Blueprint — mẫu sản phẩm gốc, vd “US Unisex Heavy Cotton Tee”.
• Variant — 1 tổ hợp màu × size cụ thể của blueprint đó, vd Black / L. Khi tạo đơn, bạn chọn theo variant_id.

Danh sách blueprint

GET /v1/catalog/blueprints?q=tee&page=1&limit=20

Lọc thêm theo category (vd clothing). Mỗi blueprint có id, name, product_type, ảnh và print_areas — các vị trí in được.

Chi tiết 1 blueprint

GET /v1/catalog/blueprints/1

{
  "id": 1,
  "name": "US Unisex Heavy Cotton Tee 2D",
  "colors": [{ "name": "Black", "hex": "#000000" }],
  "sizes": ["S", "M", "L", "XL", "2XL"],
  "included_print_area": "front",
  "print_areas": [
    { "position": "front", "fee": 4.2, "width": 38, "height": 58, "unit": "cm" },
    { "position": "back",  "fee": 4.2, "width": 38, "height": 58, "unit": "cm" },
    { "position": "sleeve_left", "fee": 3.35, "width": 4, "height": 3.5, "unit": "inch" }
  ]
}

• print_areas[].width / height / unit — kích thước vùng in, dùng để làm file in đúng tỉ lệ.
• fee — phí in của vị trí đó.

Danh sách variant (kèm giá)

GET /v1/catalog/blueprints/1/variants?page=1&limit=100

{
  "data": [
    { "id": 20139, "sku": "IUSG5000-S-ASH", "color": "ASH", "size": "S", "is_available": true, "price": 7.58 }
  ],
  "page": 1, "limit": 100, "total": 821
}

Cách tính giá: price của variant đã bao gồm in 1 vị trí (vị trí included_print_area, thường là mặt trước). In thêm vị trí khác thì cộng thêm phí in của vị trí đó. Ví dụ trên: in mặt trước = $7.58; in cả trước + sau = $7.58 + $4.20 = $11.78.

Giá chính xác của từng dòng luôn có trong unit_price khi bạn tạo đơn — lấy số đó làm chuẩn.

Chỉ dùng variant có is_available: true. Blueprint lớn có hàng trăm variant — tăng limit (tối đa 1000) hoặc lật page để lấy hết.

4. Ước tính phí ship (không bắt buộc)

Muốn báo phí ship cho khách trước khi đặt:

POST /v1/orders/shipping

{
  "line_items": [{ "variant_id": 20139, "quantity": 2 }],
  "address_to": { "country": "US", "region": "CA", "zip": "90001" },
  "shipping_method": "standard"
}

Trả về { "shipping": 7.39, "currency": "USD", "is_estimate": true }. Đơn gửi tới Mỹ bắt buộc có zip.

Nếu bạn tự gửi label thì gửi thêm "shipping_mode": "self" — shipping trả về là phí xử lý cố định (thay cho phí ship), is_estimate: false.

5. Tạo đơn

POST /v1/orders

{
  "external_id": "WEB-10023",
  "shipping_method": "standard",
  "address_to": {
    "first_name": "John",
    "last_name": "Smith",
    "email": "john@example.com",
    "phone": "+1 555 123 4567",
    "country": "US",
    "region": "CA",
    "address1": "123 Main St",
    "address2": "Apt 4",
    "city": "Los Angeles",
    "zip": "90001"
  },
  "line_items": [
    {
      "variant_id": 20139,
      "quantity": 2,
      "print_areas": {
        "front": "https://your-cdn.com/designs/front.png",
        "back": "https://your-cdn.com/designs/back.png"
      },
      "mockups": {
        "front": "https://your-cdn.com/mockups/front.jpg"
      }
    }
  ]
}

Yêu cầu với file in: URL phải là link công khai (https://...), tải được trực tiếp không cần đăng nhập, và giữ nguyên link đó cho tới khi đơn giao xong — xưởng tải file từ link này lúc sản xuất. File PNG nền trong suốt, đủ độ phân giải theo kích thước vùng in ở bước 3.

Kết quả trả về là đơn ở trạng thái draft:

{
  "id": "4821",
  "external_id": "WEB-10023",
  "status": "draft",
  "line_items": [
    { "id": "9150", "variant_id": 20139, "sku": "IUSG5000-S-ASH", "quantity": 2, "unit_price": 11.78, "print_areas": { "front": "...", "back": "..." } }
  ],
  "subtotal": 23.56,
  "shipping": 0,
  "total": 23.56,
  "currency": "USD",
  "shipment": null
}

Đơn nháp chưa trừ tiền và chưa sản xuất. Phí ship lúc này luôn là 0 — được tính khi gửi sản xuất. Đơn tạo qua API cũng hiện trong mục Orders trên dashboard, cùng chỗ với các đơn khác.

Tự gửi label vận chuyển (self-ship)

Đã có sẵn label (tự mua, hoặc do sàn cấp)? Gửi kèm label trong đơn — xưởng in và dán label của bạn lên kiện, Inkica không mua label và không thu phí ship, chỉ thu 1 khoản phí xử lý cố định nhỏ (xem đúng số tiền bằng POST /v1/orders/shipping hoặc dry_run).

{
  "external_id": "WEB-10024",
  "shipping_mode": "self",
  "shipping_label": {
    "label_url": "https://your-cdn.com/labels/WEB-10024.pdf",
    "tracking_number": "9400111899223197428490",
    "carrier": "USPS"
  },
  "address_to": { "...": "..." },
  "line_items": [ { "...": "..." } ]
}

• shipping_mode: "self" và shipping_label phải đi cùng nhau — thiếu 1 trong 2 → lỗi 400.
• Label phải gửi tới đúng địa chỉ address_to của đơn. Inkica không đọc nội dung label: label sai địa chỉ, hết hạn hay đã dùng thì kiện đi sai, và bạn chịu trách nhiệm.
• label_url phải tải trực tiếp được (không cần đăng nhập) và giữ nguyên link cho tới khi đơn giao xong, giống file in.
• Chỉ dùng với giao tiêu chuẩn — kèm priority/express → lỗi 400 (tốc độ giao do label của bạn quyết định).
• 1 label chỉ dán được lên 1 kiện, nên mọi sản phẩm trong đơn phải do cùng 1 xưởng làm; và không phải xưởng nào cũng nhận label ngoài. Đơn không đáp ứng được thì lệnh gửi sản xuất báo lỗi 400 — kiểm tra trước bằng dry_run. Khi đó tách thành nhiều đơn, hoặc bỏ shipping_mode/shipping_label để Inkica mua label.
• Đổi ý khi đơn còn nháp: gửi lại đúng external_id không kèm shipping_label → đơn chuyển về chế độ Inkica mua label, label cũ bị bỏ.
• Kết quả trả về có "shipping_mode": "self", và shipment hiện ngay label + tracking của bạn. Nếu dùng webhook, sự kiện order:shipment:created của đơn này đến ngay khi tạo/gửi đơn, không đợi xưởng giao hàng.

6. Gửi sản xuất

POST /v1/orders/4821/send_to_production

Inkica tính phí ship, trừ tổng tiền từ ví và chuyển đơn sang xưởng. Ví không đủ tiền → API báo lỗi, đơn vẫn giữ nguyên ở trạng thái nháp, nạp thêm tiền rồi gửi lại.

Chạy thử trước khi gửi thật (dry_run)

Đang làm tích hợp và chưa muốn tốn tiền thật? Gửi kèm "dry_run": true:

POST /v1/orders/4821/send_to_production

{ "dry_run": true }

Inkica chạy đủ mọi bước kiểm tra như khi gửi thật — địa chỉ, file in, còn hàng không, có xưởng in được vị trí đó không, phí ship — rồi trả về số tiền sẽ trừ, nhưng không trừ tiền, không sản xuất gì, đơn vẫn là nháp:

{
  "dry_run": true,
  "orders": [
    { "external_id": "WEB-10023", "subtotal": 23.56, "shipping": 7.39, "total": 30.95 }
  ],
  "total": 30.95,
  "currency": "USD",
  "wallet_balance": 26.66,
  "sufficient_balance": false
}

• total là đúng số tiền sẽ bị trừ nếu gửi thật ngay lúc đó.
• sufficient_balance: false → ví chưa đủ, gửi thật sẽ bị từ chối — nạp thêm trước.
• Đơn có vấn đề (hết hàng, vị trí in không làm được…) → nhận đúng lỗi 400 mà lần gửi thật sẽ gặp.

Chạy thử bao nhiêu lần cũng được. Khi đã ổn, gửi lại không có dry_run (hoặc "dry_run": false) để gửi sản xuất thật.

Chạy thử không đi qua các bước sau khi gửi (đơn chuyển in_production → shipped, có tracking). Để kiểm tra phần đọc trạng thái/tracking, dùng 1 đơn thật nhỏ — huỷ ngay nếu cần, tiền được hoàn vào ví.

⚠️ Sau bước này đơn có id mới. Đơn nháp được thay bằng đơn chính thức, nên id cũ (4821) không còn dùng được nữa. Hãy lưu lại orders[].id trong kết quả trả về để theo dõi về sau:

{
  "orders": [
    { "id": "4822", "external_id": "WEB-10023", "status": "in_production", "shipping": 7.39, "total": 30.95 }
  ]
}

Thường orders chỉ có 1 đơn. Nếu các sản phẩm trong đơn phải làm ở nhiều xưởng khác nhau, đơn sẽ được tách thành nhiều đơn — external_id khi đó có thêm đuôi -F1, -F2…

Lỡ mất kết quả trả về (vd mạng rớt giữa chừng)? Đừng gửi lại — tìm đơn theo external_id:

GET /v1/orders?external_id=WEB-10023

Kết quả gồm cả các phần -F1, -F2 nếu đơn đã bị tách.

7. Theo dõi đơn

GET /v1/orders/4822
GET /v1/orders?status=shipped&page=1&limit=50

Khi đơn được giao cho hãng vận chuyển, trường shipment có thông tin tracking để bạn gửi cho khách:

"shipment": {
  "carrier": "usps",
  "tracking_number": "9400111899223456789012",
  "tracking_url": "https://tools.usps.com/go/TrackConfirmAction?tLabels=9400111899223456789012",
  "label_url": "https://cdn.inkica.com/labels/4822.pdf",
  "status": "in_transit",
  "delivered_at": null
}

label_url là file label (PDF) dán trên kiện hàng — là null khi xưởng tự mua label và chỉ gửi lại mã tracking. tracking_url cũng có thể null; khi đó tra theo tracking_number trên trang của carrier.

Đơn tự gửi label thì shipment chính là label và mã tracking bạn đã gửi, có ngay từ lúc tạo đơn.

Muốn Inkica tự báo mỗi khi đơn đổi trạng thái hoặc có tracking, thay vì hệ thống của bạn phải hỏi lại liên tục? Dùng webhook. Nếu không dùng webhook, gợi ý kiểm tra các đơn đang pending/in_production khoảng 1 giờ/lần.

8. Huỷ đơn

POST /v1/orders/4822/cancel

Chỉ huỷ được khi xưởng chưa bắt đầu sản xuất. Đơn đã trả tiền được hoàn lại vào ví. Huỷ đơn nháp thì không có gì để hoàn vì chưa trừ tiền. Quá thời điểm huỷ được, API trả lỗi — liên hệ support nếu vẫn cần xử lý.

9. Webhook — nhận thông báo tự động

Đăng ký 1 địa chỉ (URL) trên server của bạn — Inkica sẽ tự gửi (POST) sang đó mỗi khi có thay đổi, không cần hỏi lại liên tục.

Đăng ký

Cách nhanh nhất: mở menu tài khoản → API → phần Webhooks → Add webhook, nhập URL và chọn sự kiện. Ở đây bạn cũng thấy trạng thái từng webhook (đang chạy / bị tắt và lý do), lần gửi gần nhất thành công hay lỗi, nút Send test và nút xoá.

Hoặc đăng ký bằng API:

POST /v1/webhooks

{
  "url": "https://your-server.com/inkica/webhooks",
  "events": ["order:updated", "order:shipment:created"]
}

Bỏ trống events = nhận tất cả. Kết quả trả về có secret dạng whsec_... — chỉ hiện 1 lần, lưu lại để kiểm tra chữ ký (bên dưới).

• url phải là https:// công khai — không nhận địa chỉ nội bộ (localhost, IP mạng LAN…).
• Tối đa 5 webhook mỗi tài khoản, mỗi URL chỉ đăng ký 1 lần. Xem danh sách: GET /v1/webhooks · Xoá: DELETE /v1/webhooks/{id}.
• Gửi thử ngay: POST /v1/webhooks/{id}/test — Inkica gửi 1 sự kiện ping và trả về kết quả (delivered, status_code, error).

Nội dung Inkica gửi sang

{
  "id": "dlv_1042",
  "event": "order:updated",
  "created_at": "2026-10-17T08:06:10.000Z",
  "data": {
    "previous_status": "in_production",
    "order": { "id": "4822", "external_id": "WEB-10023", "status": "shipped", "shipment": { "tracking_number": "9400111899223456789012", "...": "..." }, "...": "..." }
  }
}

data.order có đúng cấu trúc như GET /v1/orders/{id} — dùng lại được code xử lý đơn sẵn có.

Server của bạn cần trả về mã 2xx trong vòng 10 giây. Nên lưu lại rồi trả 200 ngay, xử lý sau.

Kiểm tra chữ ký (bắt buộc nên làm)

Để chắc request đúng là từ Inkica (không phải ai đó giả mạo), mỗi request có các header:

Tính lại chữ ký trên nội dung gốc (chưa parse JSON) rồi so sánh:

// Node.js (Express) — dùng express.raw() để giữ nguyên nội dung gốc
const crypto = require('crypto');
app.post('/inkica/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const ts = req.get('X-Inkica-Timestamp');
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.INKICA_WEBHOOK_SECRET)
    .update(`${ts}.${req.body}`).digest('hex');
  const got = req.get('X-Inkica-Signature') || '';
  const valid = got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected));
  if (!valid || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return res.sendStatus(401);
  const event = JSON.parse(req.body);
  // ... lưu event, xử lý sau
  res.sendStatus(200);
});

# Python (Flask)
import hmac, hashlib, time
from flask import request, abort
 
@app.post("/inkica/webhooks")
def inkica_webhook():
    ts = request.headers.get("X-Inkica-Timestamp", "")
    body = request.get_data()  # nội dung gốc (bytes)
    expected = "sha256=" + hmac.new(SECRET.encode(), f"{ts}.".encode() + body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, request.headers.get("X-Inkica-Signature", "")) or abs(time.time() - int(ts or 0)) > 300:
        abort(401)
    event = request.get_json()
    return "", 200

// PHP
$body = file_get_contents('php://input');
$ts = $_SERVER['HTTP_X_INKICA_TIMESTAMP'] ?? '';
$expected = 'sha256=' . hash_hmac('sha256', $ts . '.' . $body, $secret);
if (!hash_equals($expected, $_SERVER['HTTP_X_INKICA_SIGNATURE'] ?? '') || abs(time() - (int)$ts) > 300) {
  http_response_code(401); exit;
}
$event = json_decode($body, true);
http_response_code(200);

Kiểm tra thêm X-Inkica-Timestamp không quá 5 phút để chặn ai đó gửi lại request cũ.

Gửi lại khi lỗi

• Server của bạn không trả 2xx (lỗi, quá 10 giây, không truy cập được) → Inkica tự gửi lại sau 1, 5, 15, 60 phút, rồi 3, 6, 12 giờ — tổng cộng 8 lần trong khoảng 1 ngày.
• Cùng 1 sự kiện có thể tới nhiều hơn 1 lần, và các sự kiện có thể tới không đúng thứ tự — dùng id để bỏ qua bản trùng, và luôn tin data.order.status mới nhất (hoặc gọi GET /v1/orders/{id}) thay vì giả định thứ tự.
• Lỗi liên tục quá lâu (20 lần gửi hỏng hẳn liên tiếp) → webhook tự tắt (active: false). Sửa server xong, bấm Send test ở trang API (menu tài khoản) (hoặc gọi POST /v1/webhooks/{id}/test) — ping thành công sẽ bật lại. Các thay đổi xảy ra trong lúc webhook tắt sẽ không được gửi bù — sau khi bật lại, gọi GET /v1/orders để cập nhật trạng thái các đơn đang theo dõi.
• Đơn bạn tạo qua dashboard hay đơn từ sàn (eBay, Etsy…) cũng được báo — lọc theo external_id nếu chỉ quan tâm đơn tạo qua API.

Lỗi thường gặp

Khi có lỗi, API trả về mã HTTP kèm lời giải thích trong message:

{ "statusCode": 400, "error": "Bad Request", "message": "line_items[0].print_areas: this blueprint has no \"hood\" print position" }

Giới hạn

• 600 lượt gọi / phút.
• Tối đa 50 dòng sản phẩm mỗi đơn, 10 token mỗi tài khoản.
• Chỉ tạo được đơn từ catalog Inkica (theo variant_id); sản phẩm đã tạo trong mục Products chưa dùng trực tiếp qua API được.
• Tối đa 5 webhook mỗi tài khoản.
• Chưa có môi trường thử nghiệm riêng — dùng dry_run để kiểm tra đơn mà không tốn tiền.

◀ Thông báo · Mục lục · Tiếp theo: Giới thiệu seller ▶