TL;DR: LarkBase có thể giữ dữ liệu đơn hàng và trạng thái xử lý; n8n nhận webhook, kiểm tra dữ liệu rồi gọi MatBao Invoice API để tạo hóa đơn nháp hoặc phát hành. Nên bắt đầu bằng chế độ nháp, có bước duyệt và idempotency key trước khi cho phép ký/phát hành tự động.
Cập nhật kiểm chứng 29/07/2026: Nghị định 70/2025/NĐ-CP có hiệu lực từ ngày 01/06/2025 và sửa đổi Nghị định 123/2020/NĐ-CP về hóa đơn, chứng từ. Nghĩa vụ cụ thể phụ thuộc loại hình, doanh thu và hoạt động kinh doanh. Hãy đối chiếu văn bản Chính phủ và xác nhận với kế toán hoặc tư vấn thuế trước khi áp dụng cho doanh nghiệp.
Video demo: từ LarkBase đến hóa đơn MatBao
Video cho thấy ba thao tác chính:
| Thời gian | Nội dung |
|---|---|
| 00:00 | Kiểm tra thông tin đơn hàng |
| 00:30 | Tạo hóa đơn, phát hành và ký |
| 00:40 | Xem trước và chia sẻ PDF |
| 01:12 | Tạo hóa đơn nháp để duyệt sau |
Demo chứng minh luồng thao tác, không phải cam kết rằng mọi hệ thống có thể tích hợp mà không cần khảo sát API, quyền truy cập và quy trình duyệt hóa đơn.
Khi nào nên dùng kiến trúc này?
Mô hình phù hợp khi doanh nghiệp:
- đã quản lý khách hàng hoặc đơn hàng trong LarkBase;
- muốn giảm thao tác nhập lại dữ liệu sang phần mềm hóa đơn;
- cần lưu trạng thái, số hóa đơn hoặc link PDF về đúng record;
- có người chịu trách nhiệm kiểm tra dữ liệu trước khi phát hành;
- có quyền sử dụng API của nhà cung cấp hóa đơn.
Nếu nguồn đơn hàng nằm ở Pancake, Sapo, KiotViet hoặc hệ thống riêng, nguyên tắc vẫn tương tự nhưng webhook và mapping field phải được kiểm tra riêng. Tham khảo thêm mô hình Pancake POS kết hợp LarkBase.
Kiến trúc tích hợp đề xuất
LarkBase
-> Webhook / nút thao tác
-> n8n kiểm tra và chuẩn hóa dữ liệu
-> MatBao Invoice API
-> Tạo nháp hoặc ký/phát hành
-> Nhận kết quả
-> Cập nhật trạng thái + link PDF về LarkBase
MatBao công bố hỗ trợ tích hợp API với phần mềm kế toán, bán hàng và ERP. Tài liệu API và quyền sử dụng thực tế cần được xác nhận theo tài khoản/gói dịch vụ trước khi triển khai.
Dữ liệu cần chuẩn hóa trước khi gọi API
| Nhóm dữ liệu | Ví dụ | Kiểm tra bắt buộc |
|---|---|---|
| Người mua | Tên, MST, địa chỉ, email | Trường bắt buộc theo loại khách |
| Hàng hóa | Mã, tên, đơn vị tính | Không để trống hoặc map sai sản phẩm |
| Giá trị | Số lượng, đơn giá, thuế suất | Quy tắc làm tròn nhất quán |
| Hóa đơn | Mẫu số, ký hiệu, ngày lập | Đúng cấu hình tài khoản MatBao |
| Điều phối | Record ID, order ID | Dùng làm khóa chống tạo trùng |
Không gửi toàn bộ record LarkBase nếu API chỉ cần một số trường. Giới hạn payload giúp giảm rủi ro lộ dữ liệu và làm workflow dễ kiểm tra hơn.
Quy trình triển khai an toàn
Bước 1: Chốt nguồn dữ liệu và trạng thái
Xác định field nào là nguồn sự thật cho khách hàng, hàng hóa, thuế suất và tổng tiền. Tạo các trạng thái rõ ràng như:
Chờ kiểm tra -> Sẵn sàng tạo nháp -> Đã tạo nháp -> Đã phát hành -> Lỗi
Bước 2: Tạo webhook có kiểm soát
Chỉ trigger khi record đủ dữ liệu và đúng trạng thái. Webhook nên dùng secret, giới hạn nguồn gọi và không chứa token MatBao trong URL.
Bước 3: Validate và map field trong n8n
Workflow cần dừng trước khi gọi API nếu thiếu MST, mẫu số, ký hiệu hoặc dòng hàng. Lưu lỗi dễ hiểu về LarkBase để người vận hành biết phải sửa field nào.
Bước 4: Tạo hóa đơn nháp trước
Trong giai đoạn pilot, ưu tiên tạo nháp để kế toán kiểm tra. Chỉ bật ký/phát hành tự động khi mapping, thuế suất và quy tắc làm tròn đã được nghiệm thu.
Bước 5: Chống tạo hóa đơn trùng
Dùng order ID hoặc record ID làm idempotency key ở workflow. Trước mỗi lần retry, kiểm tra xem record đã có mã hóa đơn hoặc kết quả thành công hay chưa.
Bước 6: Ghi kết quả về LarkBase
Nên lưu tối thiểu:
- trạng thái xử lý;
- mã/số hóa đơn;
- thời điểm phát hành;
- link tra cứu hoặc PDF;
- thông báo lỗi đã được làm sạch.
Không ghi access token, chữ ký số hoặc payload nhạy cảm vào field mà nhiều người có thể xem.
Những lỗi thường gặp
Tạo trùng khi workflow retry
Nguyên nhân thường là webhook gửi lại hoặc node HTTP retry sau timeout. Khắc phục bằng khóa idempotency và bước kiểm tra trạng thái trước khi gọi API lần nữa.
Tổng tiền không khớp
Kiểm tra cách làm tròn ở từng dòng hàng, thuế suất, chiết khấu và tổng cuối. Không để n8n và phần mềm hóa đơn dùng hai quy tắc tính khác nhau.
Tạo được nháp nhưng không phát hành
Kiểm tra mẫu số, ký hiệu, quyền API, trạng thái chữ ký số và thông tin người mua. Không tự động retry thao tác ký liên tục khi chưa biết lỗi từ nhà cung cấp.
Gửi PDF nhưng không cập nhật record
Tách bước tạo hóa đơn và bước gửi thông báo. Nếu email/Zalo lỗi, hóa đơn đã phát hành vẫn phải được ghi nhận để không tạo lại.
Checklist trước khi go-live
- Đã xác nhận nghĩa vụ hóa đơn với kế toán/tư vấn thuế.
- Đã có quyền API và môi trường kiểm thử phù hợp.
- Mapping field được kế toán nghiệm thu.
- Pilot bằng hóa đơn nháp trước khi bật ký/phát hành.
- Có idempotency key và quy tắc retry.
- Token nằm trong credential store, không nằm trong LarkBase.
- Có log lỗi nhưng không lưu thông tin nhạy cảm dư thừa.
- Có người chịu trách nhiệm xử lý trạng thái lỗi.
- Có phương án thao tác thủ công nếu workflow tạm dừng.
Chi phí cần tính như thế nào?
Không nên cố định bảng giá nhà cung cấp trong một bài hướng dẫn vì gói và ưu đãi có thể thay đổi. Hãy kiểm tra bảng giá MatBao Invoice hiện hành và tính đủ:
- gói hóa đơn;
- chữ ký số;
- quyền hoặc chi phí tích hợp API nếu có;
- hạ tầng n8n;
- công triển khai, kiểm thử và hỗ trợ vận hành.
Kết luận
Giá trị chính của tích hợp không nằm ở việc gọi được một API, mà ở khả năng kiểm soát dữ liệu, phê duyệt, chống trùng và truy vết lỗi. Hãy pilot bằng hóa đơn nháp, đo tỷ lệ lỗi rồi mới mở rộng phạm vi tự động hóa.
Nếu cần khảo sát luồng LarkBase, n8n và MatBao theo dữ liệu thực tế, xem dịch vụ tư vấn và triển khai automation của Diginno.
Đọc thêm:
Bài viết hữu ích?
Chia sẻ để nhiều người biết đến!
>_ LLM-Friendly Copy
Copy as Markdown to use with ChatGPT, Claude, or other AI tools
