18. API 集成

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

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

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" }
  ]
}

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
}

POST /v1/orders/shipping

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

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"
      }
    }
  ]
}

{
  "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
}

{
  "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": [ { "...": "..." } ]
}

POST /v1/orders/4821/send_to_production

POST /v1/orders/4821/send_to_production

{ "dry_run": true }

{
  "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
}

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

GET /v1/orders?external_id=WEB-10023

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

"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
}

POST /v1/orders/4822/cancel

POST /v1/webhooks

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

{
  "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", "...": "..." }, "...": "..." }
  }
}

// Node.js (Express) — 使用 express.raw() 以保留原始内容
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);
  // ... 保存 event，稍后处理
  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()  # 原始内容（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);

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