Lọc theo nội dung CK

~6 phút đọc

Mặc định một endpoint nhận mọi sự kiện bạn đã chọn. Nếu bạn chỉ cần các khoản tiền về của một nhóm đơn hàng, hãy gắn cho endpoint một bộ lọc theo nội dung chuyển khoản: Dòng Tiền Pro chỉ giao sự kiện khi nội dung khớp mẫu. Trang này nêu cách viết mẫu, cách lọc theo mã thanh toán DTP và cách dùng mẫu mã đơn riêng của công ty.

Cách bộ lọc hoạt động

Bộ lọc là một biểu thức chính quy RE2 chạy trên nội dung chuyển khoản của sự kiện. Mỗi endpoint có một trong ba lựa chọn, đặt trong mục Bộ lọc nội dung chuyển khoản của form endpoint:

Lựa chọn	Trường API	Ý nghĩa
Không lọc	không gửi trường nào	Giao mọi sự kiện đã chọn.
Regex trực tiếp	`memo_regex`	Biểu thức nhập ngay ở endpoint, tối đa 128 ký tự.
Mẫu đã lưu	`memo_pattern_id`	Mẫu mã đơn đã lưu của công ty, dùng chung với đối soát.

Một endpoint chỉ dùng một trong hai trường memo_regex và memo_pattern_id, không dùng cả hai. Nội dung lấy từ trường memo của data.object (nếu không có thì description).

Quy tắc áp dụng cho từng sự kiện:

Bộ lọc chỉ áp dụng cho các sự kiện mang nội dung chuyển khoản: nhóm transaction.*, payment.*, collect.* và reconcile.*. Sự kiện thuộc nhóm khác luôn được giao.
Mẫu khớp ở bất kỳ vị trí nào trong nội dung, không cần khớp toàn bộ.
Giao dịch không có nội dung chuyển khoản thì không khớp mẫu nào và không được giao tới endpoint có bộ lọc.
Sự kiện không khớp không tạo lần giao nào cho endpoint đó; các endpoint khác không bị ảnh hưởng.
Nút Gửi thử (sự kiện ping) luôn giao, bất kể bộ lọc.

Nội dung được chuẩn hoá trước khi khớp

Trước khi chạy mẫu, nội dung được xử lý theo thứ tự sau:

Cắt còn 512 ký tự đầu; phần sau không được xét.
Bỏ dấu tiếng Việt và đổi đ thành D.
Đổi thành chữ hoa và gộp các khoảng trắng liên tiếp thành một.

Vì nội dung đã thành chữ hoa không dấu, hãy viết mẫu bằng chữ hoa. Nội dung chuyển khoản đơn od12345678 được xét dưới dạng CHUYEN KHOAN DON OD12345678, nên mẫu OD\d{8} khớp. Ký tự O, I, L không bị đổi thành 0, 1: OD trong mẫu là chữ O.

Viết mẫu mã đơn

Bộ lọc dùng RE2 nên chạy trong thời gian tuyến tính, không có nguy cơ làm chậm hệ thống. Đổi lại, một số cú pháp không được dùng:

Quy định	Chi tiết
Độ dài	Tối đa 128 ký tự.
Không dùng	Lookaround (`(?=`, `(?!`, `(?<=`, `(?<!`) và backreference (`\1`, `\k<tên>`).
Không được khớp chuỗi rỗng	Mẫu như `\d*` bị từ chối.
Độ phức tạp	Mẫu quá phức tạp, ví dụ lặp lồng nhau với số lần lớn, bị từ chối.

Mẫu vi phạm bị từ chối khi lưu với lỗi 422 mã memo_pattern_invalid. Dùng ô Thử mẫu regex ngay trong form endpoint để thử mẫu với một nội dung mẫu trước khi lưu: ô này cho biết có khớp hay không, đoạn được trích và thời gian chạy.

Ví dụ:

Mẫu	Khớp với nội dung	Không khớp với nội dung
`OD\d{8}`	`NGUYEN VAN A OD12345678 thanh toan`	`thanh toan tien hang`
`INV-[A-Z0-9]+`	`Thanh toan INV-2610A`	`Thanh toan hoa don 2610`
`[A-Z]{2,4}-?\d{6,10}`	`Ma don HD-0012345`	`Ma don HD-12`
`OD\d{8}\|INV-[A-Z0-9]+`	cả hai dạng mã trên	nội dung không có mã nào

Nếu lỗi xảy ra lúc chạy mẫu, Dòng Tiền Pro coi như không khớp cho endpoint đó và vẫn giao cho các endpoint khác.

Lọc theo mã thanh toán DTP

Mã DTP là mã nội dung chuẩn của Dòng Tiền Pro: DTP theo sau là 6 ký tự gồm chữ số và chữ cái trừ I, L, O, U, ví dụ DTPK7M2QX. Mã được cấp cho từng yêu cầu thanh toán và không đổi sau khi cấp. Mẫu riêng của công ty không thay được mã này: mẫu chỉ giúp đề xuất khớp đơn, không bao giờ tự xác nhận một khoản thanh toán.

Có hai cách để chỉ nhận giao dịch mang mã DTP:

Webhook: đặt memo_regex là DTP[0-9A-HJKMNP-TV-Z]{6}. Khoản chuyển không có mã DTP sẽ không được giao tới endpoint.
Kênh tích hợp (Telegram, Lark, Slack và các kênh khác): trong quy tắc của kênh, bật Chỉ giao dịch có mã thanh toán DTP. Trường API tương ứng là memo_code_only. Xem hướng dẫn tích hợp.

Mẫu DTP[0-9A-HJKMNP-TV-Z]{6} khớp đúng chuỗi như nội dung ghi, không tự sửa nhầm chữ O thành 0. Mã đã trích từ nội dung nằm sẵn ở trường memo_code của giao dịch trong data.object; nếu bạn muốn xử lý ở phía nhận, hãy kiểm trường này.

Mẫu đã lưu của công ty

Công ty có thể lưu mẫu mã đơn riêng, ví dụ OD kèm 8 chữ số của cửa hàng. Mẫu đã lưu dùng cho hai việc:

Đối soát: trích mã đơn từ nội dung để đề xuất khớp với đơn hoặc hoá đơn. Đây chỉ là đề xuất; người duyệt vẫn quyết định.
Lọc: chọn mẫu ở endpoint (Mẫu mã đơn đã lưu) thay vì nhập lại regex.

Mỗi công ty bật tối đa 5 mẫu cùng lúc. Chọn mẫu của công ty khác nhận 404. Dùng mẫu đã lưu khi nhiều endpoint hoặc kênh cùng lọc một kiểu mã; sửa mẫu một lần thì mọi nơi dùng nó đổi theo.

Kiểm tra bộ lọc

Lưu endpoint với bộ lọc, rồi bấm Gửi thử: phải nhận được sự kiện ping, vì thử luôn giao.
Dùng dtp trigger transaction.confirmed --memo "OD12345678" để tạo một giao dịch thử có nội dung khớp mẫu và một giao dịch không khớp; chỉ giao dịch khớp tới endpoint. Xem dtp trigger.
Nếu bạn không nhận được sự kiện, thử mẫu với đúng nội dung của giao dịch: nhớ rằng nội dung bị chuẩn hoá thành chữ hoa không dấu.

Chi tiết về endpoint, header và quy tắc xác nhận ở trang Webhooks; lịch thử lại ở thử lại và phát lại.