Integration Catalog — Catalog connector tích hợp GoTrace ​

1. Mục đích — Tại sao Integration là yếu tố sống còn ​

GoTrace định vị là Nền tảng dữ liệu chuỗi cung ứng — không phải một hệ thống ERP/WMS thay thế. Doanh nghiệp đã đầu tư vào MISA, FAST, BRAVO, SAP, Oracle qua nhiều năm; mọi chiến lược triển khai GoTrace phải tôn trọng và liên thông với hệ thống đang vận hành. Vì vậy:

• Không buộc DN bỏ ERP cũ. GoTrace là Lớp Liên kết + Truy xuất + Chia sẻ, đặt trên nền tảng dữ liệu vận hành sẵn có.
• Đa chiều: GoTrace vừa là consumer (đọc Master Data + transaction từ ERP/WMS/MES), vừa là producer (đẩy QR/cert/recall ra portal đối tác B2B + cơ quan quản lý).
• Open API + Connector chuẩn: hơn 12 connector sẵn cho thị trường Việt Nam và quốc tế, plus REST API generic + Excel template cho DN không có ERP.

Tài liệu này là catalog chính thức các kênh tích hợp, cung cấp cho:

• Sales Engineer: trả lời câu hỏi "GoTrace có integrate với MISA/SAP của tôi được không?"
• Solution Architect: thiết kế tích hợp khi triển khai cho khách hàng tier Control / Intelligence / Ecosystem.
• Partner Engineering: đối tác ERP/WMS/MES vendor có template kỹ thuật để xây connector.
• RFP Response Team: bằng chứng năng lực tích hợp khi đấu thầu.

2. Cách tiếp cận tích hợp — 3 mode ​

GoTrace hỗ trợ 3 mode tích hợp song song, lựa chọn theo độ "trưởng thành dữ liệu" của DN.

2.1. Mode A — Real-time API (REST/JSON) ​

Cơ chế: GoTrace gọi API của hệ thống đối tác (hoặc đối tác push API tới GoTrace) với chuẩn REST/JSON, OAuth 2.0 / API Key, retry + idempotency.

Phù hợp:

• DN đã có ERP/WMS/MES với REST API hiện đại (SAP S/4HANA, Oracle Fusion, MISA AMIS).
• Cần đồng bộ near-real-time (≤ 5 phút lag) cho quản lý vận hành.

Quy trình:

1. Đối tác cấp client_id + client_secret cho GoTrace.
2. GoTrace lưu credential (encrypted at-rest, AES-256-GCM).
3. GoTrace queue job (BullMQ) đồng bộ Master Data theo lịch + transaction theo event.
4. Idempotency key trên mọi POST để tránh double-write khi retry.

2.2. Mode B — Batch sync (Excel / CSV / FTP) ​

Cơ chế: DN export Excel/CSV theo template chuẩn của GoTrace, upload qua portal hoặc đặt vào folder FTP/SFTP. Cron job của GoTrace pull file theo lịch (15 phút / 1 giờ / 1 ngày).

Phù hợp:

• DN dùng phần mềm offline / không có API (FAST cũ, MISA SME ngoài cloud, ERP tự phát triển).
• Onboarding ban đầu — bulk import Master Data trước khi cấu hình API.
• Báo cáo định kỳ (vd. lô hàng tuần) — không cần real-time.

Quy trình:

1. GoTrace cung cấp template Excel chuẩn (có data validation, dropdown, công thức check).
2. DN export từ ERP / nhập tay → upload qua portal.
3. GoTrace validate (Lớp 4 Data Quality) → import → trả report sai sót.

2.3. Mode C — Event-driven (Webhook / Message Queue) ​

Cơ chế: Đối tác gửi event tới GoTrace qua webhook HTTPS (POST), hoặc qua message queue (Kafka, RabbitMQ, Azure Service Bus) với GoTrace là consumer.

Phù hợp:

• Khách Enterprise / Ecosystem đã có data fabric / event bus nội bộ.
• Cần đồng bộ tức thì cho recall, IoT alert.
• Tập đoàn có nhiều subsidiary cần consolidate event lên 1 platform chung.

Quy trình:

1. Đối tác đăng ký webhook URL của GoTrace trong hệ thống của họ.
2. Mỗi event chuỗi cung ứng → POST lên /api/v1/webhooks/inbound/{partner_id}.
3. GoTrace verify signature (HMAC-SHA256), enqueue, ACK 200.
4. Async worker xử lý, ghi vào graph.

3. 12 Connector chuẩn — Spec chi tiết ​

3.1. MISA AMIS (ERP nội địa) ​

Endpoint mapping:

• MISA_GET_PRODUCTS → SCDC.product_master
• MISA_GET_INVENTORIES → TXNG.warehouse_movement
• MISA_POST_BATCH (write back) → MISA tạo lô SX khi GoTrace MO.COMPLETED

3.2. FAST ERP ​

3.3. BRAVO ERP ​

3.4. SAP (S/4HANA, ECC) ​

IDOC types hỗ trợ:

• MATMAS05 (Material Master) → SCDC.product_master
• BATCH_MASTER → TXNG.batch_master
• WMMBXY01 (Goods Movement) → TXNG.warehouse_movement
• LOIPRO01 (Production Order) → TXNG.manufacturing_order

3.5. Oracle EBS / Fusion ​

3.6. WMS — Warehouse Management ​

3.7. MES — Manufacturing Execution ​

3.8. TMS — Transport Management ​

3.9. LIMS — Lab Information Management ​

3.10. IoT — Cảm biến chuỗi lạnh + môi trường ​

3.11. GS1 / EPCIS ​

Chi tiết mapping field EPCIS ↔ GoTrace: xem GS1_TT02_MAPPING.md §3.

3.12. Government Reporting (TT 02/2024) ​

4. Custom Integration — Khi không có connector sẵn ​

4.1. REST API Generic — DN tự build ​

DN chưa có ERP hoặc dùng phần mềm không có trong catalog có thể tự xây connector qua REST API generic của GoTrace:

• Endpoint: POST /api/v1/integrations/{enterprise_id}/inbound
• Auth: API Key (cấp tại portal DN)
• Schema: Open API 3.0 spec — xem /api/v1/integrations/openapi.json
• SDK sẵn có: Node.js, Python, Java, .NET (đăng tải GitHub gotrace/sdk)

4.2. Excel Template — Cho DN nhỏ chưa có ERP ​

GoTrace cung cấp template Excel chuẩn (16 sheet):

Mỗi sheet có data validation (dropdown enum, regex check format), template download tại /portal/templates/excel/v2.xlsx.

4.3. Zalo Mini-app ​

Cho NCC nhỏ, công nhân, tiểu thương không quen máy tính:

• Tính năng: nhập liệu nhật ký SX bằng giọng nói, quét QR, ảnh chụp phiếu giao hàng OCR.
• Tích hợp: Zalo Mini-app gọi /api/v1/zalo/... (zalo-be service riêng tại port 3002).
• Auth: Zalo OAuth + ủy quyền DN (DCTK pattern QLNN-F35/F36).
• Offline-first: localStorage cache; sync khi online.

5. Webhook Spec — Outbound từ GoTrace ​

GoTrace push event ra hệ thống đối tác qua webhook khi xảy ra sự kiện chuỗi cung ứng quan trọng.

5.1. Event types ​

5.2. Payload format ​

{
  "event_id": "evt_01HX9G2K8...",
  "event_type": "batch.released",
  "occurred_at": "2026-05-09T10:23:45.123Z",
  "enterprise_id": "ent_01HX9G...",
  "data": {
    "batch_id": "fg_01HX9G3...",
    "batch_code": "FG-2026-0501-001",
    "gtin": "8930012345678",
    "released_quantity": 985,
    "mfg_date": "2026-05-01",
    "expiry_date": "2027-05-01",
    "certifications": [
      { "cert_id": "...", "type": "VietGAP", "valid_until": "2027-04-30" }
    ]
  },
  "signature": "sha256=hex_hmac..."
}

5.3. Retry policy ​

Sau 7 lần fail → đẩy vào DLQ, gửi email cho admin DN. Đối tác phải acknowledge bằng HTTP 200/204 trong 5 giây.

5.4. Signature verification ​

• Header: X-GoTrace-Signature: sha256=<hex>
• Tính: HMAC-SHA256(body, webhook_secret) với webhook_secret cấp khi đăng ký webhook.
• Đối tác bắt buộc verify chữ ký trước khi xử lý — bảo vệ chống replay/MITM.

6. Partner Enablement Program ​

6.1. Tier 1 — Certified Partner ​

• Yêu cầu: connector đã pass full integration test (≥ 200 test case), Beta production tối thiểu 3 khách hàng, MOU 2-way với GoTrace.
• Quyền lợi: logo trên trang đối tác chính thức, joint marketing, tích hợp sâu (SSO + OAuth shared), discount giấy phép.
• Ví dụ: MISA, FAST (đang xây), một số WMS/TMS nội địa lớn.

6.2. Tier 2 — Compatible Partner ​

• Yêu cầu: connector đã pass smoke test (≥ 50 test case), được listed trong catalog.
• Quyền lợi: hiển thị trong catalog gotrace.vn/partners, hỗ trợ kỹ thuật cấp 1.
• Ví dụ: BRAVO, một số TMS/LIMS.

6.3. Tier 3 — Custom Integration ​

• Yêu cầu: tích hợp one-off cho 1 khách hàng cụ thể.
• Quyền lợi: GoTrace cử Solution Architect hỗ trợ thiết kế.
• Cost: tính phí riêng theo dự án (≈ 30-150tr tuỳ độ phức tạp).

7. Onboarding Checklist — Đối tác mới ​

Tổng: 6-8 tuần cho 1 connector mới từ kickoff đến Production stable.

8. SLA và Support Model ​

8.1. SLA theo Pricing Tier ​

8.2. Support tiers ​

• Tier 1 — Self-service: portal docs, KB, OpenAPI explorer, status page.
• Tier 2 — Business hours support: ticket system, email, Zalo group (gói Foundation/Control).
• Tier 3 — Dedicated CSM: account manager, monthly review (gói Intelligence/Ecosystem).
• Tier 4 — On-call SRE: 24/7 hotline + Slack shared channel (gói Ecosystem).

8.3. Status page ​

• URL: https://status.gotrace.vn
• Hiển thị availability per connector real-time, scheduled maintenance, incident history 90 ngày.
• Webhook subscribe để DN nhận thông báo qua email/Zalo.

9. Tham chiếu ​

10. Lịch sử phiên bản ​