Tích hợp API MISA: Cách đồng bộ đơn hàng vào kế toán

Trước hết: bạn cần tích hợp sản phẩm MISA nào?

Tích hợp API MISA là cụm tìm kiếm rộng, nhưng phạm vi kỹ thuật chỉ rõ khi biết doanh nghiệp đang dùng sản phẩm nào. AMIS Kế toán Doanh nghiệp dùng cho dữ liệu kế toán của doanh nghiệp; MISA ASP phục vụ mô hình kế toán dịch vụ; MISA meInvoice có API riêng cho hóa đơn điện tử. Không nên dùng một tài liệu API để suy diễn rằng mọi phiên bản MISA đều hỗ trợ cùng endpoint hoặc cùng nghiệp vụ.

Cổng tích hợp chính thức của MISA nêu quy trình nhà phát triển đăng ký, hai bên làm rõ nghiệp vụ, thống nhất phạm vi rồi MISA cung cấp tài liệu, môi trường và tiêu chuẩn kỹ thuật. Tài liệu tổng quan AMIS Kế toán cũng yêu cầu đăng ký để nhận app_id và callback URL trước khi lấy access_code, access_token.

Vì vậy, báo giá đáng tin cậy phải bắt đầu bằng tên sản phẩm, phiên bản, tenant hoặc dữ liệu kế toán, nghiệp vụ cần kết nối và quyền API đã được MISA xác nhận. Friday Works không phải MISA và bài viết này không tuyên bố tư cách đối tác tích hợp; mọi triển khai cụ thể phải đi qua kênh đăng ký chính thức và phạm vi được MISA chấp thuận.

• ✓AMIS Kế toán: đồng bộ danh mục và tạo yêu cầu sinh chứng từ kế toán cho doanh nghiệp.
• ✓MISA ASP: luồng riêng cho đơn vị cung cấp dịch vụ kế toán và dữ liệu nhiều khách hàng.
• ✓MISA meInvoice: luồng hóa đơn điện tử đầu vào hoặc đầu ra; không đồng nghĩa toàn bộ nghiệp vụ kế toán.

Tích hợp kế toán chỉ hoàn tất khi đơn hàng, danh mục và chứng từ đối soát được từ đầu đến cuối — không phải khi API vừa trả về thành công.

Một luồng website hoặc phần mềm bán hàng → MISA gồm những gì?

Đầu vào thường là đơn hàng, thanh toán, hoàn tiền, khách hàng, hàng hóa và kho từ website, web app, POS hoặc ERP. Đầu ra không nên là việc sao chép nguyên payload sang kế toán. Hệ thống cần chuyển sự kiện kinh doanh thành đúng danh mục, đề nghị lập chứng từ và trạng thái đối soát theo nghiệp vụ kế toán đã thống nhất.

Tài liệu AMIS Kế toán công bố khả năng lấy hoặc tạo các danh mục như đối tượng, vật tư, kho, đơn vị tính, hệ thống tài khoản, cơ cấu tổ chức và tài khoản ngân hàng; phần chứng từ gồm bán hàng, mua hàng, hóa đơn, nhập kho và trả lại hàng hóa. Trang hướng dẫn người dùng cập nhật ngày 03/08/2026 cho biết dữ liệu kết nối có thể dùng để lập chứng từ ở các phân hệ Tiền mặt, Tiền gửi, Mua hàng và Bán hàng.

Luồng nên tách thành ba lớp: hệ thống nguồn giữ trạng thái đơn hàng, connector chuẩn hóa và gửi dữ liệu, MISA tiếp nhận rồi tạo chứng từ theo quy tắc. Không để mã gọi API nằm trực tiếp ở trình duyệt hoặc trong plugin không có log và cơ chế phục hồi.

• ✓Sự kiện nguồn: order_confirmed, payment_captured, refund_completed hoặc return_received.
• ✓Dữ liệu nền: khách hàng, hàng hóa, kho, đơn vị tính, chi nhánh và tài khoản hạch toán.
• ✓Kết quả: yêu cầu sinh chứng từ, trạng thái cuối, mã chứng từ hoặc lỗi cần xử lý.

Đồng bộ danh mục trước, chứng từ sau

Lỗi phổ biến nhất không nằm ở HTTP mà ở mapping. Một mã sản phẩm trên website có thể chưa tồn tại trong AMIS, cùng tên kho nhưng khác chi nhánh, hoặc đơn vị tính hiển thị giống nhau nhưng dùng mã nội bộ khác. Nếu gửi chứng từ trước khi danh mục sẵn sàng, request có thể bị từ chối hoặc đi vào sai đối tượng.

Hãy lập data contract cho từng trường: nguồn, kiểu dữ liệu, mã định danh ngoài, mã MISA tương ứng, quy tắc tạo mới, ai phê duyệt và cách xử lý khi thiếu. Tài liệu MISA yêu cầu branch_id để xác định dữ liệu đi vào đúng cơ cấu tổ chức; org_company_code dùng phân biệt phần mềm hoặc khách hàng kết nối. Các khóa này phải được quản lý như cấu hình có version, không hard-code rải rác.

Mỗi danh mục nên có bảng mapping hai chiều và trạng thái đồng bộ. Khi kế toán đổi mã kho, gộp khách hàng hoặc khóa vật tư, connector phải phát hiện thay đổi thay vì âm thầm tạo bản ghi mới.

• ✓Khóa nguồn ổn định: customer_id, sku, warehouse_id, order_id và payment_id.
• ✓Khóa đích: mã đối tượng, vật tư, kho, đơn vị tính, branch_id và mã tài khoản MISA.
• ✓Quy tắc ngoại lệ: tạo mới, chờ kế toán duyệt, dùng giá trị mặc định có kiểm soát hoặc từ chối.

Request thành công chưa phải chứng từ thành công

Tài liệu Open API AMIS Kế toán nói rõ luồng tạo chứng từ là bất đồng bộ: hệ thống có thể ghi nhận request nhưng điều đó chưa có nghĩa dữ liệu đã đúng; chỉ khi chứng từ được tạo thành công mới có kết quả nghiệp vụ cuối. Đây là lý do không được đánh dấu đơn hàng “đã hạch toán” ngay khi endpoint trả Success=true.

Connector cần lưu một integration job với external reference ổn định, request ID, thời điểm gửi, số lần thử, trạng thái tiếp nhận, trạng thái callback và mã chứng từ cuối. Callback phải xác định đúng job; nếu callback đến lặp hoặc đến trễ, việc xử lý vẫn phải idempotent.

Nếu MISA tạm thời không phản hồi, hệ thống nguồn vẫn giữ được sự kiện và thử lại theo chính sách. Nếu dữ liệu sai, job chuyển sang needs_attention cùng lỗi rõ ràng để kế toán hoặc vận hành sửa mapping rồi replay, không tạo lại một đơn hàng giả.

• ✓accepted: MISA đã nhận yêu cầu, chưa phải kết quả kế toán cuối.
• ✓processing: đang tạo hoặc kiểm tra chứng từ.
• ✓completed/failed: trạng thái dùng để đối soát và quyết định có cần con người xử lý.

Đối soát số tiền, thuế, chiết khấu và hoàn trả

Đơn hàng thương mại thường có giá trước hoặc sau thuế, chiết khấu theo dòng hoặc toàn đơn, phí vận chuyển, phí thanh toán, điểm thưởng và nhiều lần thanh toán. Nếu chỉ so sánh tổng cuối, chứng từ vẫn có thể sai cơ cấu doanh thu, thuế hoặc công nợ.

Kế toán và chủ quy trình phải phê duyệt bảng mapping nghiệp vụ trước khi phát triển: thời điểm ghi nhận, tài khoản nợ/có, mã thuế, cách làm tròn, loại tiền, chi nhánh, kho và cách xử lý trả hàng. Kỹ sư không nên tự suy đoán tài khoản hạch toán từ tên trường trên website.

Báo cáo đối soát nên so sánh theo ngày và theo external reference: số đơn đủ điều kiện, số job accepted, số chứng từ hoàn tất, số tiền hàng, thuế, chiết khấu, phí, hoàn tiền và phần chênh lệch. Chênh lệch bằng không theo tổng chưa đủ; cần drill-down đến từng đơn và từng dòng.

• ✓Golden dataset có đơn thường, giảm giá, nhiều mức thuế, phí vận chuyển, hoàn một phần và trả toàn bộ.
• ✓Cùng quy tắc làm tròn giữa nguồn, connector và MISA.
• ✓Kế toán ký xác nhận kết quả, không giao nghiệm thu chỉ cho đội kỹ thuật.

Xác thực, token, callback và vận hành an toàn

Theo tài liệu chính thức, AMIS Kế toán dùng app_id đã đăng ký, access_code lấy từ ứng dụng và access_token có thời hạn 12 giờ; request nghiệp vụ gửi X-MISA-AccessToken. Token phải nằm ở server hoặc secret store, được xoay vòng trước khi hết hạn và không xuất hiện trong log, URL hay mã frontend.

Callback là endpoint công khai nên phải giới hạn phương thức, kích thước payload, content type và schema; ghi nhận request ID trước khi xử lý; chống replay bằng khóa idempotency; redaction dữ liệu nhạy cảm trong log. Chỉ phản hồi thành công sau khi sự kiện callback đã được lưu bền vững.

Cần theo dõi tuổi job chưa hoàn tất, tỷ lệ lỗi theo ErrorCode, số token refresh thất bại và chênh lệch đối soát. Cảnh báo phải đến người chịu trách nhiệm vận hành; dashboard đẹp nhưng không có runbook replay vẫn chưa đủ để bàn giao.

• ✓Không lưu access_code hoặc access_token trong trình duyệt, Git hay ảnh chụp tài liệu.
• ✓Phân tách cấu hình test và production; không dùng dữ liệu thật trong môi trường thử nếu chưa được phép.
• ✓Có audit trail cho thay đổi mapping, replay job và thao tác ghi đè thủ công.

Checklist lấy báo giá và nghiệm thu tích hợp MISA

Trước khi lấy báo giá, doanh nghiệp nên cung cấp tên sản phẩm MISA, trạng thái đăng ký API, hệ thống nguồn, số chi nhánh, số đơn mỗi ngày, danh mục cần đồng bộ, loại chứng từ, quy tắc kế toán và yêu cầu độ trễ. Không nên báo một giá trọn gói chỉ từ câu “kết nối website với MISA”.

Pilot nên chạy trên tài khoản hoặc môi trường thử được MISA cung cấp, dùng golden dataset đã được kế toán duyệt và đi đủ vòng từ nguồn đến chứng từ cuối. Tài liệu MISA nêu quy trình đăng ký, sandbox hoặc môi trường thi công và hỗ trợ kỹ thuật; phạm vi thực tế cần xác nhận trực tiếp theo sản phẩm và tài khoản.

Friday Works có thể khảo sát tính khả thi, thiết kế data contract, connector, callback, dashboard đối soát và runbook trong phạm vi API chính thức. Kết quả khảo sát phải nêu rõ phần nào MISA hỗ trợ, phần nào cần thay đổi quy trình và phần nào không nên tự động hóa.

• ✓Tất cả test case truy vết được từ order_id đến integration job và mã chứng từ cuối.
• ✓Retry hoặc callback lặp không tạo trùng danh mục hay chứng từ.
• ✓Số tiền, thuế, chiết khấu, phí và hoàn trả khớp theo từng đơn; lỗi có owner và SLA xử lý.