# Khi đồng bộ sang ERP hỏng giữa chừng, retry an toàn là phần khó nhất

> Idempotency key, outbox và đối soát ba chiều giúp sổ sách của khách khớp đến đồng cuối cùng khi khoá sổ.

Bản gốc: https://fdetimes.net/vi/bach-khoa/tich-hop-ke-toan-kieu-ramp-dong-bo-giao-dich-sang-erp-khach/

Ngày thứ ba của kỳ khoá sổ, kế toán trưởng phía khách gửi bạn một ảnh chụp màn hình: trong ERP có hai bút toán giống hệt nhau cho cùng một khoản payout, còn khoản của ngày hôm trước thì không thấy đâu. Code của bạn không hề crash. Log ghi "timeout, retrying" rồi "success".

Đây là tình huống quen thuộc khi FDE tích hợp kế toán cho khách lớn. Với đội tài chính, một bút toán trùng không phải bug nhỏ: chỉ cần một con số lệch là họ không ký báo cáo được.

Bạn có thể dựng một demo đồng bộ ngon lành trong một tuần, nhưng để khách tin hệ thống của bạn thì nó phải đúng sau hàng nghìn lần mạng chập chờn.

Ba câu hỏi quyết định chất lượng của mọi tích hợp ERP: giao dịch có bị mất không, có bị ghi hai lần không, và khi hỏng giữa chừng thì sổ sách nằm ở trạng thái nào. Thêm câu thứ tư, câu mà khách thực sự quan tâm: làm sao chứng minh hai bên khớp nhau.

## Giao dịch bị mất trước cả khi tới ERP

Lỗi đầu tiên nằm ngay trong service của bạn. Service lưu giao dịch vào database rồi mới phát sự kiện "cần đồng bộ". Nếu tiến trình chết đúng giữa hai việc đó, bản ghi vẫn nằm đấy mà không ai báo cho worker đồng bộ biết. Microsoft gọi đây là bài toán dual-write.

Cách sửa là Transactional Outbox: ghi giao dịch và sự kiện vào một bảng outbox trong *cùng một* database transaction. Tài liệu kiến trúc của Microsoft khẳng định khi lưu đối tượng nghiệp vụ và sự kiện của nó trong cùng transaction thì hệ thống bảo đảm không mất dữ liệu.

Worker chỉ việc đọc outbox và đẩy dần sang ERP, nên tiến trình chết lúc nào cũng không còn khe hở.

## Vì sao một lần retry lại sinh bút toán thứ hai?

Quay lại ảnh chụp màn hình. Thử hình dung: worker gửi bút toán, ERP ghi sổ xong nhưng phản hồi bị rơi trên đường về. Worker thấy timeout nên gửi lại. ERP không biết đây là cùng một yêu cầu, vậy là ghi thêm một bút toán.

Stripe giải bài này bằng idempotency key. Client gắn một key vào request tạo hoặc cập nhật, nên nếu lỗi kết nối xảy ra, bạn có thể gửi lại mà không sợ tạo đối tượng thứ hai hay cập nhật hai lần.

Ở API v1, server lưu phản hồi đầu tiên ứng với key và trả lại đúng phản hồi đó cho mọi lần retry, kể cả khi phản hồi đầu là lỗi `500`.

Còn hai chi tiết nữa trong tài liệu của Stripe. Key do client tự sinh, và được xoá sau tối thiểu 24 giờ. Cùng một key mà gửi kèm tham số khác thì bị từ chối, để chặn dùng nhầm.

Từ hai chi tiết đó rút ra được hai quy tắc. Key phải sinh từ ID nghiệp vụ ổn định (chẳng hạn `erp-journal:po_123`), không được dùng `uuid4()` mỗi lần gửi, vì key ngẫu nhiên khiến lần retry trông như một yêu cầu mới.

Và vì key có hạn dùng, còn không phải ERP nào cũng có cơ chế này, bạn không thể giao trọn việc chống trùng cho phía ERP. Phải tự lưu bảng ánh xạ từ key sang ID bản ghi phía ERP, và quan trọng hơn, phải ghi dòng đó *trước* lần gửi đầu tiên chứ không phải sau khi nhận phản hồi.

## Một worker đồng bộ payout, viết cho đúng

Giả sử bạn đẩy payout hằng đêm sang NetSuite. Theo tài liệu của Oracle, khi vượt giới hạn concurrency, NetSuite REST Web Services trả HTTP 429 với mã `CONCURRENCY_LIMIT_EXCEEDED` và thông điệp "Concurrent request limit exceeded. Request blocked."

Oracle hướng dẫn gửi lại request, và logic retry nằm trong code của bạn. Đoạn dưới đây dùng một wrapper `erp` giả định, có hàm tra bút toán theo external ID:

```python
def sync_payout(payout_id):
    key = f"erp-journal:{payout_id}"         # từ ID nghiệp vụ, không ngẫu nhiên
    row = mapping.get(key)
    if row and row.erp_id:
        return row.erp_id                     # đã xác nhận ghi sổ: không gửi lại
    if row is None:
        mapping.save_pending(key)             # ghi "pending" TRƯỚC lần gửi đầu
    for attempt in range(6):
        found = erp.find_by_external_id(key)  # lần gửi trước có thể đã ghi sổ
        if found:
            mapping.confirm(key, found.id)
            outbox.mark_done(payout_id)
            return found.id
        try:
            resp = erp.post_journal(build_payload(payout_id),
                                    external_id=key, idempotency_key=key)
        except Timeout:                       # không biết ERP đã ghi hay chưa
            sleep(min(2 ** attempt, 60) + random())
            continue                          # vòng sau sẽ tra lại trước khi gửi
        if resp.status == 429:                # CONCURRENCY_LIMIT_EXCEEDED: lỗi tạm thời
            sleep(min(2 ** attempt, 60) + random())
            continue
        resp.raise_for_status()
        mapping.confirm(key, resp.id)         # xác nhận ánh xạ trước khi xoá khỏi outbox
        outbox.mark_done(payout_id)
        return resp.id
    alert_oncall(payout_id, key)              # hết lượt retry: chuyển cho người
```

Thử chạy kịch bản đêm đó qua đoạn code này. Trước khi gửi, worker đã ghi một dòng "pending" cho key. Lần gửi đầu timeout, nhưng ERP thật ra đã ghi sổ. Worker bắt exception `Timeout`, chờ backoff rồi sang vòng sau.

Ở vòng sau, việc đầu tiên không phải gửi lại mà là hỏi ERP xem đã có bút toán mang external ID này chưa. Có rồi, nên worker chỉ xác nhận ánh xạ và dừng. Nếu ERP hỗ trợ idempotency thì cùng một key cũng cho thêm một lớp bảo vệ, nhưng thiết kế này không phụ thuộc vào nó.

Dòng "pending" còn có tác dụng khi tiến trình chết hẳn rồi chạy lại sau ba ngày: worker thấy dòng chưa xác nhận, nên luôn tra ERP trước khi gửi. Điều kiện duy nhất là bạn phải ghi key vào một trường external ID tra cứu được trên bút toán, và nên thống nhất trường này với khách ngay từ tuần đầu.

## Hỏng ở bước thứ hai thì làm gì với bước thứ nhất?

Một payout thật thường đi qua nhiều bước trên nhiều hệ thống: tạo bản ghi doanh thu, ghi bút toán, đánh dấu đã thanh toán. Không có transaction ACID nào trải qua được cả nền tảng của bạn lẫn ERP. Mẫu Saga thay nó bằng chuỗi transaction cục bộ: bước nào hỏng thì một loạt compensating transaction hoàn tác những gì các bước trước đã làm.

Saga có khái niệm pivot transaction, tức điểm không quay lại. Các bước sau pivot phải retry được và idempotent để saga luôn tới được trạng thái cuối, kể cả khi gặp lỗi tạm thời. Với luồng ghi sổ ERP, bút toán đã ghi sổ thường chính là pivot.

Lý do cụ thể ở từng khách thì nên coi là giả định cần kiểm chứng: hỏi kế toán trưởng xem khi một bút toán sai, họ sửa thẳng hay phải ghi bút toán đảo. Nếu đó đúng là điểm không quay lại, sau nó bạn chỉ còn cách đi tiếp.

Microsoft đưa ra thứ tự ưu tiên rất thực tế: lỗi tạm thời thì retry trước, chỉ dừng và kích hoạt bù trừ khi một bước hỏng lặp đi lặp lại hoặc không thể phục hồi, và có những lỗi cần cảnh báo để con người can thiệp. Bản thân bước bù trừ cũng có thể hỏng, nên phải viết nó thành lệnh idempotent để chạy lại được.

Với kế toán, yêu cầu quan trọng nhất là audit. Microsoft yêu cầu có thể liên kết và kiểm toán cả thao tác gốc lẫn thao tác bù trừ từ đầu đến cuối. Hãy gắn cùng một correlation ID vào bút toán gốc, bút toán bù trừ và log, để kiểm toán viên lần được cả chuỗi chỉ bằng một lần tìm kiếm.

## Đối soát là cách bạn chứng minh, không phải việc làm thêm

Đồng bộ đúng rồi cũng chưa đủ, vì khách cần thấy bằng chứng. Mô hình đối soát ngân hàng của Stripe là một mẫu tốt: mỗi payout được ghép với khoản tiền về ngân hàng bằng một reference key chung, rồi gắn trạng thái Reconciled hoặc Unreconciled. Bạn mở rộng mô hình này thành ba chiều: nền tảng, ERP và sao kê ngân hàng, cùng chung một khoá.

Bẫy lớn nhất là lẫn chênh lệch thời gian với lỗi thật. Ví dụ mẫu của Stripe ghi rằng ngân hàng thường không ghi có payout vào Chủ nhật, nên ô số tiền của Chủ nhật 4 tháng 2 trong ví dụ để trống.

Nếu báo cáo của bạn đánh dấu mọi dòng như vậy là lỗi, đội tài chính sẽ chìm trong cảnh báo giả và thôi tin báo cáo.

| Nhóm | Dấu hiệu | Việc cần làm |
|---|---|---|
| Khớp | Đủ ba chiều, cùng số tiền | Không làm gì |
| Chênh lệch thời gian | Có ở nền tảng và ERP, ngân hàng chưa ghi có | Chờ, kiểm tra lại sau chu kỳ thanh toán |
| Lệch thật | Thiếu một chiều quá thời hạn, hoặc lệch số tiền | Mở ticket, truy theo correlation ID |

**Điểm mấu chốt:** Đồng bộ đúng chưa đủ: khách cần một báo cáo đối soát chứng minh từng đồng đều khớp.

## Tự làm từ đầu, theo thứ tự nào?

Ở khách mới, việc đầu tiên là ngồi với kế toán trưởng và hỏi bước nào là điểm không quay lại, và khi sai thì họ sửa bằng cách nào. Câu trả lời cho bạn biết pivot nằm ở đâu và bước bù trừ phải trông ra sao.

Tiếp theo, dựng outbox trong database của bạn, định nghĩa key cho từng bước dựa trên ID nghiệp vụ, chọn trường external ID trên ERP để lưu key, rồi viết worker có retry kèm backoff cho lỗi tạm thời.

Chỉ sau đó mới tới bù trừ và cảnh báo. Đối soát nên chạy từ tuần đầu tiên, không đợi đến cuối kỳ: báo cáo ba nhóm ở trên là cách nhanh nhất để phát hiện lỗi thiết kế trước khi khách tự phát hiện.

## Những lỗi khiến đội tài chính mất niềm tin

Lỗi hay gặp nhất là sinh key ngẫu nhiên mỗi lần gửi, khiến idempotency mất tác dụng. Gần với nó là chỉ ghi ánh xạ sau khi nhận phản hồi thành công, nên đúng lúc timeout thì bảng trống trơn. Lỗi tiếp theo là coi mọi phản hồi 429 hay timeout là thất bại rồi chạy bù trừ ngay, trong khi đáng lẽ phải retry trước.

Còn hai lỗi nữa. Bước bù trừ viết không idempotent, nên khi chạy lại thì bù trừ hai lần. Và ở khâu giao tiếp: báo "lệch" cho mọi khoản chưa về ngân hàng. Khách sẽ nhớ một báo cáo đầy cảnh báo giả lâu hơn mười đêm đồng bộ trơn tru.

## Kể kỹ năng này trong CV thế nào?

Một dòng "tích hợp NetSuite" trong CV gần như không nói lên điều gì. Hãy mô tả bạn thiết kế đồng bộ idempotent, xử lý lỗi từng phần và đối soát ba chiều thế nào, kèm số kỳ khoá sổ mà khách không phải sửa tay dòng nào.

Trong phỏng vấn, kịch bản "ERP ghi xong nhưng phản hồi bị rơi" là một câu chuyện ngắn cho thấy bạn nghĩ đến lỗi trước khi nó xảy ra.

Lần tới có ai nói "cứ retry là được", hãy hỏi lại họ: retry với key nào, và trước khi gửi lại thì đã hỏi ERP chưa?

**Thử ngay tuần này:**

- Mở code đồng bộ hiện tại, tìm mọi chỗ sinh key bằng uuid4() hoặc timestamp và thay bằng key ghép từ ID nghiệp vụ cộng tên bước.
- Viết một test giả lập ERP ghi nhận thành công nhưng trả timeout, rồi kiểm tra lần retry có tạo bản ghi thứ hai không.
- Lấy 7 ngày payout gần nhất, xếp mỗi dòng vào một trong ba nhóm: khớp, chênh lệch thời gian, lệch thật.

## Nguồn

- [Idempotent requests | Stripe API Reference](https://docs.stripe.com/api/idempotent_requests)

- [Error Handling in REST Web Services (Oracle NetSuite Help)](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_156570709583.html)

- [Saga Design Pattern - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/saga)

- [Compensating Transaction Pattern - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/compensating-transaction)

- [Implement the Transactional Outbox Pattern by Using Azure Cosmos DB - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/databases/guide/transactional-out-box-cosmos)

- [Bank reconciliation | Stripe Documentation](https://docs.stripe.com/reconciliation/bank-reconciliation)
