VNCX Developer API

Upsert theo externalRef + source

Body: { "source": "<tên hệ thống>", "items": [ ... ] }. Mỗi phần tử bắt buộc có externalRef — mã tham chiếu của chính hệ thống nguồn, không phải id nội bộ của VNCX. Hệ thống khớp theo bộ ba (tổ chức, source, externalRef): đã có bản ghi khớp thì cập nhật, chưa có thì tạo mới — bạn không cần biết trước id nội bộ, và có thể gọi lại nhiều lần với cùng dữ liệu nguồn mà không tạo bản ghi trùng.

Với lô: mỗi phần tử cần productId hoặc productExternalRef (tham chiếu sản phẩm bằng externalRef của cùng source thay vì id nội bộ).

curl -X POST https://app.vncx.io/api/v1/products/bulk \
  -H "X-API-Key: vncx_sk_..." \
  -H "Idempotency-Key: sap-sync-2026-07-13-01" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "sap-erp",
    "items": [
      { "externalRef": "<externalRef-1>", "sku": "SKU-001", "name": "Sản phẩm A", "category": "food" },
      { "externalRef": "<externalRef-2>", "sku": "SKU-002", "name": "Sản phẩm B", "category": "food" }
    ]
  }'

Partial success — luôn 200, trừ lỗi toàn request

Một phần tử lỗi (externalRef trùng lặp trong cùng request, thiếu sản phẩm tham chiếu, lô ngoài vùng, ...) không làm hỏng cả request — response vẫn 200, chỉ riêng phần tử đó mang status: "failed". Chỉ khi cả request sai (body sai dạng, thiếu source, hoặc items vượt quá 500 phần tử) mới nhận 400 validation_error — không phần tử nào được xử lý.

{
  "data": {
    "results": [
      { "index": 0, "externalRef": "<externalRef-1>", "status": "created", "id": "prod_..." },
      { "index": 1, "externalRef": "<externalRef-2>", "status": "failed",
        "error": { "code": "validation_error", "message": "..." } }
    ],
    "summary": { "created": 1, "updated": 0, "failed": 1 }
  },
  "request_id": "..."
}

• results[i].status là một trong "created", "updated", "failed"; index là vị trí trong items bạn gửi lên, để đối chiếu ngược.
• summary gộp số lượng theo trạng thái — { created, updated, failed }.
• Trùng externalRef trong cùng request: phần tử đầu tiên được xử lý, các phần tử trùng sau đó nhận failed / validation_error.
• Một lần gọi bulk chỉ tốn MỘT đơn vị rate-limit (600 request/phút của key), bất kể items có bao nhiêu phần tử.

Idempotency-Key cho bulk: chỉ để retry y hệt

Cả hai endpoint bulk đều nhận Idempotency-Key (xem mục Idempotency bên dưới để biết cơ chế đầy đủ), nhưng key ở đây áp dụng cho cả request, không phải từng phần tử. Gửi lại đúng key + đúng body chỉ phát lại nguyên data.results đã lưu từ lần gọi trước — kể cả các phần tử "failed", hệ thống không tự thử lại chúng.

Muốn sửa/thử lại riêng các phần tử lỗi: gửi một request bulk mới (chỉ chứa các phần tử cần thử lại) kèm một Idempotency-Key mới — đừng tái sử dụng key cũ, vì key cũ chỉ phát lại kết quả cũ nguyên trạng.

Giới hạn vùng: sản phẩm KHÔNG, lô CÓ

products/bulk không giới hạn theo vùng — sản phẩm là tài nguyên cấp tổ chức, không gắn khu vực sản xuất. batches/bulk thì có: mỗi phần tử lô phải có productionAreaId nằm trong vùng được cấp cho key — lô ngoài vùng chỉ khiến riêng phần tử đó nhận status: "failed" với error.code: "forbidden", các phần tử khác trong cùng request không bị ảnh hưởng.

Xác thực chữ ký

Header X-VNC-Signature có dạng t=<unix-seconds>,v1=<hex hmac-sha256>, với v1 = hex(HMAC_SHA256(secret, `${t}.${rawBody}`)) tính trên raw body (không phải object đã parse rồi serialize lại). So sánh bằng timing-safe compare, và từ chối nếu |now - t| > 300s (chống replay — 300s là dung sai cố định, không cấu hình được).

// Node.js (Express) — verify chữ ký webhook VNC
const crypto = require("crypto");

// QUAN TRỌNG: HMAC tính trên RAW body. Đừng dùng express.json() rồi
// JSON.stringify() lại — thứ tự key / khoảng trắng khác đi là chữ ký sai.
app.post("/vnc-webhook", express.raw({ type: "application/json" }), async (req, res) => {
  const raw = req.body.toString("utf8");
  if (!verifyVncSignature(raw, req.get("X-VNC-Signature"), process.env.VNC_WEBHOOK_SECRET)) {
    return res.sendStatus(401);
  }

  const event = JSON.parse(raw);
  // Giao at-least-once: cùng một event có thể tới nhiều lần.
  // Dedupe theo event.id (== header X-VNC-Delivery), KHÔNG theo nội dung.
  if (await alreadyProcessed(event.id)) return res.sendStatus(200);

  switch (event.type) {
    case "warranty.activated":
      // event.data = { warrantyId, warrantyCode, productId, ... } — không có
      // tên/điện thoại người mua. Cần liên hệ thì gọi GET /warranties/{id}.
      break;
    case "batch.status_changed":
      // event.data mang CẢ BA trục: previousLifecycle/lifecycle,
      // previousQuality/quality, previousRecallStatus/recallStatus.
      // Một đợt thu hồi (recall) chỉ đổi quality/recallStatus, KHÔNG đổi
      // lifecycle — diff cả 3 cặp để biết trục nào vừa đổi.
      break;
  }

  // Trả 2xx NGAY (VNC timeout sau 10s). Việc nặng thì đẩy sang hàng đợi.
  res.sendStatus(200);
});

// Mirror của verifySignatureHeader() trong
// packages/shared/lib/webhooks/signature.ts — cùng logic, cùng hằng số.
function verifyVncSignature(rawBody, header, secret, toleranceSec = 300) {
  if (!header) return false;

  const parts = {};
  for (const kv of header.split(",")) {
    const i = kv.indexOf("=");
    if (i > 0) parts[kv.slice(0, i).trim()] = kv.slice(i + 1).trim();
  }

  const t = Number(parts.t);
  if (!Number.isFinite(t)) return false;
  // Chống replay: t nằm TRONG phần được ký, nên kẻ tấn công bắt được request
  // không thể phát lại với t mới (v1 sẽ sai) hay với t cũ (bị từ chối ở đây
  // vì đã quá hạn).
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false;

  const provided = parts.v1 || "";
  if (!/^[0-9a-f]{64}$/i.test(provided)) return false;

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${t}.${rawBody}`, "utf8")
    .digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(provided, "hex");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Ngữ nghĩa giao

• At-least-once — một event có thể tới nhiều lần; dedupe theo header X-VNC-Delivery.
• Không đảm bảo thứ tự giữa các event.
• Retry: backoff mũ bắt đầu 2s (nhân đôi, giới hạn 1h), tối đa 10 lần gửi; mỗi lần gửi timeout sau 10s. Trả bất kỳ mã 2xx nào để xác nhận đã nhận — mã khác hoặc timeout sẽ được thử lại.
• Tự động tắt (auto-disable): 5 lượt giao liên tiếp cạn hết số lần thử sẽ khiến endpoint tự tắt — bật lại trong Cài đặt → Webhooks. Bật lại không phát lại các event đã bỏ lỡ trong lúc tắt.
• Endpoint phải là URL https:// công khai. VNC không đi theo redirect — endpoint trả 3xx sẽ bị tính là giao thất bại.
• Webhook là tín hiệu, không phải nguồn sự thật: một sự cố hiếm có thể làm rơi một event. Với dữ liệu quan trọng, hãy đối soát định kỳ bằng REST API thay vì chỉ dựa vào webhook.