GLS · Đề xuất API đồng bộ PWMS ↔ TMS (BD/SC)

1. Tổng quan đề xuất

PWMS (AppSheet / bảng trong GLSPWMS) là nguồn dữ liệu kho · NCC · sản phẩm · chứng từ. TMS (Quản lý xe) gọi các API dưới đây để seed lần đầu, đồng bộ định kỳ, và đẩy phiếu BD/SC kèm vật tư sang bộ phận mua hàng.

#	API	Hướng	Bảng nguồn (Excel)	Mục đích
1	Master sync	PWMS → TMS	`Supplier`, `Product_SERI`, `Object`, `Product`, `Repair_Category`, `Storage_Type`	Đồng bộ danh mục master
2	Purchase sync	PWMS → TMS	`Repair_Card` / `Repair_Transaction` (+ chứng từ liên quan theo mã phiếu)	Kéo dữ liệu mua hàng theo mã phiếu BD/SC hoặc khoảng thời gian
3	Send order	TMS → PWMS	Ghi nhận phiếu trên PWMS để MH nhập liệu đúng mã	Gửi phiếu BD/SC + vật tư dự kiến
4	Storage sync	PWMS → TMS	`Storage_Transaction`, `Storage_Card`	Giá VT · thời điểm xuất kho
5	Fuel sync	PWMS → TMS	`Fuel_Card`	Thông tin dầu nội bộ
6	Tire / battery lifecycle	TMS → PWMS	Cập nhật vòng đời / hao mòn lốp · ắc (seri, xe, vị trí, km/ngày, mức mòn, phiếu ĐG/SC)	Đẩy ngược sau ĐG hoặc phiếu SC có thay / cập nhật lốp–ắc

Bốn tình huống sync cần hỗ trợ trên mọi API đọc (1) Đồng bộ tất cả · (2) Đồng bộ chỉ định (bảng / mã phiếu / mã phiếu kho) · (3) Đồng bộ theo khoảng updated_from → updated_to (đồng bộ theo khoảng sau lần chạy đầu) · (4) Chỉ bản đang áp dụng (active_only=true / ap_dung) hoặc lấy cả ngưng dùng.

2. Quy ước chung

Base URL (đề xuất)

https://{pwms-host}/api/v1

Auth: Authorization: Bearer {token} · Content-Type: application/json

Tham số dùng chung (query / body)

Tham số	Ý nghĩa
`mode`	`ALL` \| `RANGE` \| `BY_KEY`
`updated_from` / `updated_to`	ISO-8601 · lọc `ngay_cap_nhat` / thời gian chứng từ
`active_only`	`true` = chỉ `ap_dung=true` · `false` = tất cả
`page` / `page_size`	Phân trang (mặc định 200, tối đa 1000)
`cursor`	Tuỳ chọn thay page khi dataset lớn

Gợi ý vận hành Lần đầu: mode=ALL (có thể tách theo bảng). Các lần sau: mode=RANGE với updated_from = last_synced_at (mốc đồng bộ lần trước) lần sync trước trên TMS. Phiếu MH: ưu tiên BY_KEY theo mã phiếu TMS khi người dùng bấm «Đồng bộ mua hàng».

3. API #1 — Đồng bộ master

Một endpoint nhận tên bảng (hoặc danh sách bảng) để trả về bản ghi master từ PWMS. Hỗ trợ get all, get theo khoảng ngày cập nhật, active only / tất cả.

POST/api/v1/masters/sync

Supplier Product_SERI Object Product Repair_Category Storage_Type

ALL — toàn bộ bản ghi (một hoặc nhiều bảng)
BY_KEY — chỉ định bảng + danh sách id / mã
RANGE — theo ngay_cap_nhat trong khoảng
active_only — chỉ bản đang áp dụng

Request — đồng bộ tất cả master (lần đầu)

{
  "mode": "ALL",
  "tables": [
    "Supplier",
    "Product_SERI",
    "Object",
    "Product",
    "Repair_Category",
    "Storage_Type"
  ],
  "active_only": false,
  "page": 1,
  "page_size": 500
}

Request — chỉ một bảng + đang áp dụng

{
  "mode": "ALL",
  "tables": ["Product"],
  "active_only": true,
  "page": 1,
  "page_size": 200
}

Request — theo khoảng ngày cập nhật (RANGE)

{
  "mode": "RANGE",
  "tables": ["Supplier", "Product", "Storage_Type"],
  "updated_from": "2026-09-01T00:00:00+07:00",
  "updated_to": "2026-10-01T23:59:59+07:00",
  "active_only": false,
  "page": 1,
  "page_size": 200
}

Request — chỉ định khóa (BY_KEY)

{
  "mode": "BY_KEY",
  "tables": ["Object"],
  "keys": {
    "Object": ["50E-65517", "51C-29273"]
  },
  "active_only": false
}

Response sample

{
  "request_id": "mst-20261001-001",
  "mode": "RANGE",
  "last_synced_at": "2026-10-01T23:59:59+07:00",
  "tables": {
    "Supplier": {
      "total": 2,
      "page": 1,
      "page_size": 200,
      "has_more": false,
      "rows": [
        {
          "ma_khach": "GLS:HCM",
          "loai_hinh": "Tổ Chức",
          "ten_ngan": "GLS HCM",
          "ten_doanh_nghiep": "GLS HỒ CHÍ MINH",
          "ap_dung": true,
          "ngay_tao": "2025-08-03T00:00:00+07:00",
          "ngay_cap_nhat": "2025-08-03T00:00:00+07:00"
        }
      ]
    },
    "Product": {
      "total": 1,
      "page": 1,
      "page_size": 200,
      "has_more": false,
      "rows": [
        {
          "id": "VTU-342-1000002",
          "nhom": "Vật tư",
          "he_thong": "Ắc Quy",
          "ten_vat_tu": "Ắc Bi Nhê",
          "dvt": "Cái",
          "ap_dung": true,
          "ngay_cap_nhat": "2026-09-15T10:20:00+07:00"
        }
      ]
    },
    "Repair_Category": { "total": 0, "rows": [] },
    "Storage_Type": { "total": 0, "rows": [] },
    "Product_SERI": { "total": 0, "rows": [] },
    "Object": { "total": 0, "rows": [] }
  }
}

Ghi chú cột nguồn Các field response bám cột sheet Excel (vd. Supplier: ma_khach, ap_dung, ngay_cap_nhat; Product: id, he_thong, ten_vat_tu; Object: ma_phuong_tien, bien_so…). Endpoint phụ (tuỳ chọn): GET /api/v1/masters/{table} với cùng query params.

4. API #2 — Đồng bộ dữ liệu mua hàng

Kéo dữ liệu mua hàng / sửa chữa đã nhập trên PWMS về TMS. Ưu tiên truyền mã phiếu BD/SC từ TMS; sau lần sync đầu có thể lấy phần mới theo khoảng ngày giờ.

POST/api/v1/purchase/sync

Repair_Card Repair_Transaction Storage_Card (liên quan)

Request — theo mã phiếu TMS (khi cần)

{
  "mode": "BY_KEY",
  "order_codes": ["RO-2026-1002", "RO-2026-3388"],
  "include": ["header", "lines", "issue_docs"],
  "active_only": false
}

Request — theo khoảng thời gian (sau lần đầu)

{
  "mode": "RANGE",
  "updated_from": "2026-09-28T00:00:00+07:00",
  "updated_to": "2026-10-01T18:00:00+07:00",
  "include": ["header", "lines"],
  "page": 1,
  "page_size": 100
}

Request — lấy toàn bộ (lần đồng bộ đầu)

{
  "mode": "ALL",
  "include": ["header", "lines"],
  "page": 1,
  "page_size": 200
}

Response sample

{
  "request_id": "pur-20261001-014",
  "mode": "BY_KEY",
  "orders": [
    {
      "order_code": "RO-2026-1002",
      "header": {
        "ma_phieu": "RO-2026-1002",
        "ngay": "2026-01-13",
        "supplier": "HYUNDAI PHÚ LÂM",
        "phuong_tien": "51C-29273",
        "ma_base": "BASE-2026-1002",
        "chot_phieu": true,
        "ngay_cap_nhat": "2026-01-14T09:30:00+07:00"
      },
      "lines": [
        {
          "id": "rtx-99101",
          "phieu_sc": "RO-2026-1002",
          "dich_vu": "Thay cảm biến",
          "he_thong": "Hệ Thống Điện",
          "hang_muc_tac_nghiep": "Thay cảm biến + dây nguồn",
          "don_gia": 300000,
          "vat": 0.08,
          "thanh_tien": 324000,
          "so_luong": 1,
          "product_id": "VTU-ELC-001",
          "issued_at": "2026-01-13T15:40:00+07:00",
          "purchase_doc_code": "XK-1002-01",
          "fulfillment": "ISSUE"
        }
      ]
    }
  ],
  "meta": { "matched": 1, "missing_codes": [] }
}

Khuyến nghị TMS Nút «Đồng bộ mua hàng» trên chi tiết phiếu gọi BY_KEY với đúng order_codes=[phiếu.code]. Job nền đêm gọi RANGE để bắt phiếu MH nhập muộn mà KTV chưa bấm sync.

5. API #3 — Gửi phiếu BD/SC (+ vật tư) sang PWMS

TMS đẩy phiếu đã duyệt (và vật tư dự kiến nếu có) sang PWMS để bộ phận mua hàng nhập liệu đúng mã phiếu.

POST/api/v1/orders/send

Gọi lại an toàn theo order_code · gửi lại = cập nhật bản nháp phía PWMS nếu chưa chốt.

Request sample

{
  "order": {
    "order_code": "RO-2026-3388",
    "type": "PERIODIC",
    "vehicle_plate": "50E-65517",
    "pwms_object_id": "50E-65517",
    "date": "2026-09-30",
    "km": 121090,
    "garage": "Xưởng Hải Phòng",
    "system": "Dầu Nhớt",
    "content": "Thay dầu nhớt động cơ (thay thế)",
    "source": "KTV tạo",
    "approval_status": "APPROVED",
    "work_items": [
      {
        "system": "Dầu Nhớt",
        "service": "Bảo dưỡng",
        "content": "Thay dầu nhớt động cơ (thay thế)",
        "standard_hours": 1.0,
        "hours": 1.0,
        "performer": "Nguyễn Văn Kỹ thuật"
      }
    ],
    "materials": [
      {
        "source": "PWMS",
        "fulfillment": "ISSUE",
        "product_id": "VTU-342-1000002",
        "code": "VTU-342-1000002",
        "name": "Ắc Bi Nhê",
        "qty": 1,
        "uom": "Cái",
        "ref_price": 1850000,
        "note": "Giá tham chiếu lúc lập phiếu"
      },
      {
        "source": "TECHNICIAN",
        "fulfillment": "TECHNICIAN",
        "code": null,
        "name": "Gia công ron (ghi tay)",
        "qty": 1,
        "uom": "Lần",
        "ref_price": 0
      }
    ]
  },
  "options": {
    "create_or_update": true,
    "notify_purchase_team": true
  }
}

Response sample

{
  "request_id": "snd-20261001-003",
  "status": "ACCEPTED",
  "order_code": "RO-2026-3388",
  "pwms_ticket_id": "RC-RO-2026-3388",
  "received_at": "2026-09-30T08:21:00+07:00",
  "material_lines_accepted": 2,
  "message": "Phiếu đã sẵn sàng để mua hàng nhập liệu theo mã RO-2026-3388"
}

6. API #4 — Đồng bộ Storage (giá & giờ xuất kho)

Lấy dữ liệu từ Storage_Transaction và Storage_Card phục vụ kiểm tra giá vật tư và thời điểm xuất kho.

POST/api/v1/storage/sync

Storage_Transaction Storage_Card

Request — theo khoảng (sau lần đồng bộ đầu)

{
  "mode": "RANGE",
  "entities": ["Storage_Transaction", "Storage_Card"],
  "updated_from": "2026-09-20T00:00:00+07:00",
  "updated_to": "2026-10-01T23:59:59+07:00",
  "filters": {
    "loai": ["XUAT", "XUAT_SUA_NGOAI"],
    "product_ids": []
  },
  "page": 1,
  "page_size": 500
}

Request — theo mã phiếu / mã lô chỉ định

{
  "mode": "BY_KEY",
  "entities": ["Storage_Card", "Storage_Transaction"],
  "keys": {
    "ma_phieu": ["XK-1002-01", "XK-3388-02"],
    "ma_lo": []
  }
}

Request — get all (lần đầu)

{
  "mode": "ALL",
  "entities": ["Storage_Transaction", "Storage_Card"],
  "page": 1,
  "page_size": 500
}

Response sample

{
  "request_id": "stg-20261001-008",
  "mode": "RANGE",
  "last_synced_at": "2026-10-01T23:59:59+07:00",
  "Storage_Card": {
    "total": 1,
    "rows": [
      {
        "ma_phieu": "XK-1002-01",
        "loai": "XUAT",
        "ngay_chung_tu": "2026-01-13",
        "thoi_gian": "2026-01-13T15:40:00+07:00",
        "thao_tac": "Xuất kho",
        "kho_id": "Kho VT HCM",
        "phuong_tien": "51C-29273",
        "nha_cung_cap": "Công ty TNHH Phụ tùng GLS"
      }
    ]
  },
  "Storage_Transaction": {
    "total": 1,
    "rows": [
      {
        "id": "stx-77881",
        "ma_phieu": "XK-1002-01",
        "ma_lo": "LO-2026-0113-01",
        "product_id": "VTU-ELC-001",
        "supplier_id": "NCC-PT-01",
        "don_gia": 300000,
        "vat": 0.08,
        "thanh_tien": 324000,
        "so_luong": 1,
        "ngay": "2026-01-13T15:40:00+07:00",
        "kho_id": "Kho VT HCM"
      }
    ]
  }
}

Dùng trên TMS Tra cứu giá xuất thực / thoi_gian xuất để điền mốc «có đủ vật tư» và snapshot cụm mua hàng.

7. API #5 — Lấy thông tin dầu nội bộ (Fuel_Card)

Query / đồng bộ phiếu cấp dầu nội bộ từ bảng Fuel_Card.

POST/api/v1/fuel/sync

Tuỳ chọn GET: GET /api/v1/fuel/cards?mode=RANGE&updated_from=…

Request — theo khoảng thời gian

{
  "mode": "RANGE",
  "updated_from": "2026-09-01T00:00:00+07:00",
  "updated_to": "2026-10-01T23:59:59+07:00",
  "filters": {
    "phuong_tien": [],
    "kho_id": [],
    "phan_loai": ["NOI_BO"]
  },
  "page": 1,
  "page_size": 200
}

Request — theo mã phiếu / biển số

{
  "mode": "BY_KEY",
  "keys": {
    "ma_phieu": ["FC-2026-0912-01"],
    "phuong_tien": ["50E-65517"]
  }
}

Response sample

{
  "request_id": "fuel-20261001-002",
  "mode": "BY_KEY",
  "total": 1,
  "rows": [
    {
      "ma_phieu": "FC-2026-0912-01",
      "phan_loai": "NOI_BO",
      "phuong_tien": "50E-65517",
      "ngay_gio_cap": "2026-09-12T07:15:00+07:00",
      "kho_id": "Kho dầu nội bộ",
      "loai_dau_cap": "Diesel",
      "ma_lo_cap": "LO-FUEL-0912",
      "nha_cung_cap": "Kho nội bộ GLS",
      "don_gia_cap": 21000,
      "vat": 0.08,
      "so_luong_cap": 120,
      "thanh_tien": 2520000,
      "tong_tien": 2721600
    }
  ]
}

8. API #6 — Cập nhật vòng đời / hao mòn vỏ lốp & ắc quy (TMS → PWMS)

Sau khi kỹ thuật viên ghi nhận thay thế, đổi vị trí, hoặc cập nhật độ mòn trên phiếu đánh giá / phiếu BD-SC, TMS gọi API này để mua hàng cập nhật sổ seri. TMS chỉ giữ bản đã đồng bộ để hiển thị — không phải sổ nguồn.

POST/api/v1/tire-battery/lifecycle

Nút trên UI: «Đồng bộ vòng đời → mua hàng» (sau ĐG / hoàn thành phiếu có lốp–ắc).

Request sample

{
  "request_id": "tb-life-20261002-001",
  "source": "TMS",
  "trigger": "REPAIR_ORDER_COMPLETED",
  "order_code": "RO-2026-1042",
  "assessment_id": null,
  "vehicle_plate": "50E-65517",
  "events": [
    {
      "item_type": "TIRE",
      "serial": "LOP-SR-998821",
      "product_code": "VTU-LOP-29580",
      "action": "REPLACE",
      "position": "TRUOC_TRAI",
      "odometer_km": 412500,
      "wear_percent": 85,
      "installed_at": "2026-10-02T09:30:00+07:00",
      "removed_serial": "LOP-SR-771102",
      "note": "Thay theo đánh giá tuần · mòn vượt ngưỡng"
    },
    {
      "item_type": "BATTERY",
      "serial": "AQ-SR-120045",
      "product_code": "VTU-AQ-12V",
      "action": "INSPECT",
      "position": "CABIN",
      "odometer_km": 412500,
      "wear_percent": 40,
      "installed_at": null,
      "removed_serial": null,
      "note": "Kiểm tra định kỳ — chưa thay"
    }
  ]
}

Response sample

{
  "request_id": "tb-life-20261002-001",
  "accepted": true,
  "pwms_ref": "LIFE-UPD-77821",
  "updated": 2,
  "errors": []
}

Khi nào gọi (1) Hoàn thành phiếu BD/SC có dòng lốp/ắc thay hoặc cập nhật · (2) Nộp phiếu đánh giá có hạng mục thay/kiểm tra lốp–ắc kèm seri · (3) User bấm «Đồng bộ vòng đời → mua hàng» khi trạng thái chờ đẩy. Master sync (API #1) / Storage (API #4) vẫn dùng để kéo danh mục + seri về TMS trước khi chọn.

9. Luồng gọi đề xuất

Không mô tả ánh xạ — chỉ thứ tự query / đồng bộ và gửi phiếu.

Lần đồng bộ đầu Master ALL → Storage ALL (tuỳ chọn) → Fuel ALL (tuỳ chọn) → lưu mốc đồng bộ last_synced_at trên TMS.

Hàng ngày / khi cần Master RANGE · Storage RANGE · Fuel RANGE · Send order khi duyệt · Purchase BY_KEY khi KTV đồng bộ MH.

Tình huống	mode	Tham số chính
Đồng bộ tất cả	`ALL`	`tables` / `entities` · `page`
Đồng bộ chỉ định	`BY_KEY`	`keys` · `order_codes` · `tables`
Đồng bộ khoảng thời gian	`RANGE`	`updated_from` · `updated_to`
Chỉ đang áp dụng	mọi mode	`active_only=true`
Lấy cả ngưng dùng	mọi mode	`active_only=false`