Lần lặp thứ ba: khi lỗi tích hợp của khách là lỗi của nền tảng

Thử hình dung bạn là FDE đầu tiên của một ngân hàng bán API cho developer. Sang tuần thứ ba, bạn đã gỡ cùng một lỗi cho khách thứ ba: chạy trong sandbox thì ổn, lên production thì một lệnh chuyển tiền bị tạo hai lần.

Gặp đến lần thứ ba thì bạn có hai đường. Đường thứ nhất là tiếp tục gỡ cho từng khách, việc này ai cũng làm được. Đường thứ hai là coi lần lặp thứ ba ấy là dữ liệu và sửa tận gốc để khách thứ tư không bao giờ gặp lại lỗi đó.

Bài này dạy đường thứ hai. Đây là kỹ năng tách một FDE khỏi một kỹ sư hỗ trợ giỏi, và cũng là thứ một số nhà tuyển dụng ngành tài chính đã ghi thẳng vào tin tuyển dụng.

Khi API là sản phẩm, vướng mắc của khách là việc của bạn

Column tự giới thiệu là ngân hàng có giấy phép quốc gia đầu tiên được lập ra để phục vụ developer và các đội làm sản phẩm.

API của họ được định nghĩa bằng một OpenAPI spec, nên khách có thể sinh SDK, nạp vào Postman hay Insomnia, hoặc dựng mock chạy ở máy mình.

Ngân hàng này còn có sandbox để developer viết phần mềm làm việc trực tiếp với tài khoản ngân hàng.

Chi tiết quan trọng nhất với một FDE nằm ở chỗ khác. Theo nhà sáng lập Column, vì ngân hàng có core system và nền tảng developer của riêng mình nên không cần lớp trung gian, và khách là developer tích hợp thẳng với ngân hàng. Không có vendor ở giữa để đổ lỗi, nhưng cũng không có vendor ở giữa cản đường khi bạn muốn sửa.

Vì thế, ở một ngân hàng kiểu này, chỗ nào khách bị kẹt thì nên được đọc trước hết như một tín hiệu về sản phẩm. Ba tin tuyển FDE ở mảng tài chính, của Monumint, Bretton AI và ModernFi, không nói thẳng như vậy, nhưng đều giao cho FDE việc đưa phản hồi của khách ngược về sản phẩm.

Monumint đòi FDE biến phản hồi của khách thành cải tiến sản phẩm, và muốn những bản sửa nhanh, chắp vá dần trở thành hệ thống lâu dài cho hàng nghìn khách dùng.

Bretton AI yêu cầu xây connector, công cụ cấu hình và framework nội bộ để biến giải pháp làm riêng cho một khách thành năng lực lặp lại được.

Bản sửa nên nằm ở tầng nào?

Cái khó không nằm ở việc sửa mà ở việc chọn chỗ đặt bản sửa. Hãy nghĩ theo bốn tầng, từ rẻ và nhanh đến đắt và bền:

Tầng	Khi nào dùng	Ví dụ với lỗi tạo lệnh hai lần
Gỡ tại chỗ	Lần đầu gặp, khách đang bị chặn	Sửa logic retry trong code của khách
Tài liệu	Lặp lại, nguyên nhân là hiểu sai	Thêm cảnh báo và ví dụ vào mô tả endpoint trong spec
Công cụ	Lặp lại dù tài liệu đã rõ	Thêm bước kiểm tra retry vào quy trình onboarding
Nền tảng	Nhiều khách, rủi ro cao	Đề xuất SDK tự gắn khóa chống trùng

Quy tắc dễ nhớ: lúc nào cũng gỡ ở tầng thấp nhất trước để khách chạy tiếp được, rồi để số lần lặp lại quyết định có leo lên tầng trên hay không.

Tin tuyển dụng của ModernFi cho thấy các tầng giữa là việc thật của FDE chứ không phải việc phụ. FDE ở đó phụ trách và cải thiện tài liệu API công khai, đồng thời cùng đội customer success tiếp nhận phản hồi để tối ưu công cụ onboarding tự phục vụ.

Một ví dụ đi trọn vòng

Quay lại kịch bản ở đầu bài, giờ coi nó như một bài tập giả định. Giả sử API của bạn có hỗ trợ khóa idempotency, nhưng tài liệu chỉ nhắc đến nó ở một trang ít người đọc.

Khách đầu tiên là một startup trả lương. Code của họ retry khi gặp timeout mà không gửi khóa, nên mạng chập chờn ở production là đủ sinh ra lệnh trùng. Sandbox không lộ ra lỗi này vì ở đó mạng hiếm khi timeout.

Bretton AI mô tả đúng loại việc này: những edge case chỉ lộ ra khi đã chạy production thật. Ở tuần đầu, bạn gỡ tại chỗ bằng cách sửa hàm retry của khách. Nhưng trước khi đóng ticket, bạn ghi một mục vào friction log:

- date: 2026-10-05
  customer: payroll-startup-a
  env: production
  endpoint: POST /transfers
  symptom: transfer created twice after timeout
  root_cause: retry sent without idempotency key
  tag: retry-duplicate
  workaround: fixed client retry, added key from payroll_run_id
  time_spent_hours: 3

Đến tuần thứ ba có thêm hai mục cùng tag. Một đoạn script ngắn đủ để biến cảm giác “hình như lỗi này hay gặp” thành con số:

import collections, yaml

entries = yaml.safe_load(open("friction_log.yaml"))
by_tag = collections.Counter(e["tag"] for e in entries)
for tag, n in by_tag.most_common():
    hours = sum(e["time_spent_hours"] for e in entries if e["tag"] == tag)
    flag = "ESCALATE" if n >= 3 else ""
    print(f"{tag:20} {n}x  {hours}h  {flag}")

Có ba lần lặp, bạn leo lên tầng tài liệu. Vì API được định nghĩa bằng OpenAPI spec, bạn nên đặt cảnh báo và ví dụ ngay vào mô tả của endpoint trong spec chứ đừng viết thêm một trang wiki. Làm vậy thì SDK sinh ra, collection trong Postman và mock chạy ở máy khách đều mang theo cảnh báo, đúng chỗ developer đang nhìn.

Tiếp theo là tầng công cụ: thêm vào checklist onboarding một bước “giả lập timeout trong sandbox và kiểm tra không tạo lệnh trùng”.

Còn tầng nền tảng, bạn viết một trang đề xuất cho đội product gồm ba khách bị ảnh hưởng, số giờ đã tốn, cách đang gỡ tạm và phương án SDK tự gắn khóa.

Bretton AI gọi việc này là biến cách khách dùng sản phẩm thành insight cho đội kỹ thuật và product.

Tự làm từ ngày mai

Bắt đầu bằng việc ghi friction log ngay từ ticket đầu tiên, dù lúc đó bạn chưa thấy mẫu hình nào. Thiếu dữ liệu từ sớm thì đến lần thứ ba bạn chỉ có trí nhớ. Mỗi mục cần có endpoint, môi trường, nguyên nhân gốc, cách gỡ tạm và số giờ, vì đội product sẽ hỏi đúng những thứ đó.

Sau đó, đặt cho mình một ngưỡng rõ ràng, chẳng hạn ba lần lặp, rồi xem lại log mỗi tuần thay vì chờ cảm hứng. Khi chạm ngưỡng, chọn tầng thấp nhất giải quyết được nguyên nhân gốc.

Khách hiểu sai thì sửa tài liệu, khách hiểu đúng mà vẫn làm sai thì cần công cụ. Còn nếu cả hai đều đã làm mà lỗi vẫn quay lại thì đó là việc của nền tảng.

Bước hay bị bỏ qua nhất là quay lại báo cho những khách từng gặp lỗi rằng bản sửa đã có. Việc này khép vòng phản hồi và cho bạn thêm lý do để khách kể tiếp chỗ họ bị kẹt.

Những cái bẫy hay gặp

Cái bẫy phổ biến nhất là kẹt mãi ở tầng gỡ tại chỗ. Khách hài lòng và bạn thấy mình có ích, nhưng sau sáu tháng bạn chỉ còn là một tư vấn viên đi theo từng khách, còn nền tảng vẫn y như cũ.

Bẫy ngược lại là đòi sửa nền tảng ngay từ lần gặp đầu tiên, khi trong tay chưa có bằng chứng nào cho thấy lỗi ấy lặp lại.

Một bẫy khác là mang giai thoại đến cuộc họp với product. Câu “khách hay kêu chỗ này” thua hẳn câu “ba khách, chín giờ kỹ thuật, cùng một endpoint”. Cũng đừng coi sandbox chạy được nghĩa là xong: lỗi khó nhất ở ngân hàng thường chỉ lộ ra ở production, nên checklist onboarding cần có bước giả lập điều kiện xấu.

Biến kỹ năng này thành lợi thế khi đi xin việc

Khi đọc tin tuyển FDE, nhất là ở công ty fintech hay bán hạ tầng cho ngân hàng, hãy tìm các cụm như “turning customer feedback into product improvements”, “repeatable” hay “own API documentation”.

Có những cụm đó nghĩa là công ty mong bạn làm việc trên cả bốn tầng chứ không chỉ gỡ lỗi. Riêng Monumint còn yêu cầu nối vào các hệ thống khách đang chạy như Salesforce, nCino, Fiserv hay Jack Henry, nên ai có kinh nghiệm tích hợp thật sẽ có lợi thế.

Trong CV, hãy viết theo trọn vòng thay vì liệt kê nhiệm vụ. Một dòng kiểu “Phát hiện lỗi retry gặp ở ba khách qua friction log, sửa spec và checklist onboarding, đề xuất thay đổi SDK được đưa vào roadmap” cho người tuyển thấy bạn biết nhìn từ một khách ra cả nền tảng.

Nếu chưa làm FDE, bạn có thể tập vòng này với bất kỳ API công khai nào: tích hợp thử, ghi lại chỗ mình bị kẹt rồi gửi đề xuất sửa tài liệu.

Khách thứ tư sẽ không bao giờ biết mình đã tránh được lỗi gì. Một FDE làm tốt việc này thì để lại dấu vết trên nền tảng nhiều hơn trong hộp thư hỗ trợ.