Đồng bộ hoá đơn về ERP

Mô hình phổ biến nhất là đưa hoá đơn đầu vào đã được hoadon.pro kiểm tra vào ERP hoặc phần mềm kế toán để hạch toán. Trang này mô tả luồng tổng thể; đường dẫn endpoint và trường dữ liệu cụ thể lấy từ Scalar.

Luồng tổng thể

flowchart LR
  A[Kéo toàn bộ lần đầu] --> B[Lưu vào ERP]
  C[Webhook invoice.created và invoice.updated] --> B
  D[Đối chiếu định kỳ] --> B
  B --> E[Hạch toán]

Ba nguồn cập nhật cho cùng một kho dữ liệu trong ERP:

1. Kéo toàn bộ lần đầu những hoá đơn đã có trong kỳ cần đưa vào.
2. Webhook cập nhật tức thời khi có hoá đơn mới hoặc thay đổi.
3. Đối chiếu định kỳ bắt những sự kiện bị lỡ (bên nhận từng ngừng hoạt động quá thời hạn thử lại).

Bước 1: Kéo toàn bộ lần đầu

Lặp qua danh sách hoá đơn theo phân trang con trỏ với limit=200, lọc theo org_id của từng công ty cần đồng bộ. Với mỗi hoá đơn, lưu vào ERP theo mã hoá đơn của hoadon.pro làm khoá ngoại để cập nhật lại, không tạo trùng.

const invoices = await listAll('/v1/invoices', { org_id: ORG_ID });
for (const invoice of invoices) {
  await upsertIntoErp(invoice); // khoá theo invoice.id
}

Bước 2: Nhận hoá đơn mới qua webhook

Đăng ký webhook cho invoice.created, invoice.updated và invoice.checked. Với mỗi sự kiện:

1. Xác thực chữ ký.
2. Bỏ qua nếu id sự kiện đã xử lý.
3. Đọc lại hoá đơn qua API theo mã trong data để lấy trạng thái mới nhất.
4. Cập nhật vào ERP, rồi trả 2xx.

Bước 3: Đối chiếu định kỳ

Mỗi đêm, kéo lại các hoá đơn thay đổi gần đây và so với ERP. Cách này bù cho webhook bị lỡ và giúp phát hiện sai lệch.

Lưu ý

• Chỉ đưa vào hạch toán hoá đơn có kết quả kiểm tra bạn chấp nhận; hoá đơn cảnh báo hoặc không hợp lệ cần kế toán quyết định (Khái niệm).
• Tiền là chuỗi thập phân: đọc bằng kiểu decimal của ERP (Tổng quan API).
• Dùng Idempotency-Key cho mọi lệnh ghi ngược về hoadon.pro (Idempotency).
• Tôn trọng giới hạn tốc độ khi kéo lại dữ liệu lớn.