Dùng SePay CLI trong script

Gọi SePay CLI từ script và CI an toàn: đọc kết quả JSON, rồi dựa vào exit code để chỉ chạy lại lỗi tạm thời mà không tạo bản ghi trùng.

||

Khi script hoặc CI gọi SePay CLI, không có ai đọc bảng hay trả lời câu hỏi xác nhận. Script đọc dữ liệu trên stdout, bắt lỗi qua exit code và chỉ chạy lại với lỗi có thể thử lại.

Đọc output và exit code

KênhNội dung
stdoutDữ liệu. --json hoặc -o yaml để có JSON hoặc YAML; mặc định là bảng
stderrLỗi, cảnh báo và dòng env:. Với --json, lỗi là JSON, kể cả lỗi sai flag (định dạng lỗi)
Exit code0 thành công; giá trị khác 0 theo bảng exit code

stdout chỉ chứa dữ liệu nên pipe thẳng vào jq được. Khối JSON lỗi in trên nhiều dòng, nên script đọc cả khối rồi mới lấy trường:

Bash
1
2
3
4
5
out=$(sepay transaction list --json 2>err.json)
code=$?
if [ "$code" -ne 0 ]; then
error_code=$(sed -n '/^{/,/^}/p' err.json | jq -r .error_code)
fi

Job CI bị hủy (SIGINT, SIGTERM), hoặc lệnh bị dừng bằng Ctrl+C hay Esc ở một câu hỏi, thì CLI thoát với exit code 130, error_code là interrupted. Ghi phiên bản CLI vào log bằng sepay --version --json (trường version, commit, date, go_version, os, arch).

sepay auth status --active --json trả trạng thái phiên; trường session tương ứng cột SESSION của auth status.

Chế độ không tương tác

Khi không có terminal, lệnh cần xác nhận dừng với exit code 2 và chưa gửi request. Trên sandbox, --yes trả lời "có" (Xác nhận); trên production xem mục dưới. Đối số và flag bắt buộc phải được truyền đủ, vì lệnh không hỏi chọn hay nhập khi không có terminal (thiếu thì dừng với exit code 2; xem Chọn tương tác khi bỏ trống).

Lệnh sửa dữ liệu trên production

Script do bạn tự viết chạy được lệnh sửa dữ liệu production khi lệnh có đủ ba thứ: --env production ngay trên lệnh (default_env không tính), id của tài nguyên lệnh sửa, và --yes:

$ sepay webhook update 5f0e2a7b-xxxx-xxxx-xxxx-fa163e2f7c98 --url https://example.com/new-hook --env production --yes --json

Lệnh không có id, như webhook create, paycode create, paycode update --enable hay sepay api -X POST tạo mới, chỉ chạy trên terminal: trong script, chúng dừng với exit code 2 dù có --yes. Bảng id của từng lệnh ở Lệnh sửa dữ liệu trên production.

Không để AI agent tự thêm --yes vào script chạy trên production. Agent viết script thì để trống --yes; bạn đọc lại lệnh rồi tự thêm.

Chính sách thử lại

Lỗi có thể thử lại là exit code 1 với error_code được đánh dấu "Có" ở cột thử lại trong bảng error code: rate_limited, network_error, idempotency_conflict (chạy lại với cùng key), *_provision_failed, *_token_failed. error thì tùy: đọc message trước. server_error là lỗi phía SePay (HTTP 5xx), in SePay is temporarily unavailable (HTTP 503); retry in a moment hoặc SePay had an internal error (HTTP 500); ...: chờ một lúc rồi thử lại, lệnh tạo dữ liệu thì giữ nguyên --idempotency-key; lỗi lặp lại thì gửi SePay request_id trong khối lỗi JSON. Các lỗi còn lại cho cùng kết quả khi chạy lại, kể cả idempotency_key_reuse (key đã dùng cho một request khác): đổi sang key mới thay vì chạy lại.

Với nhóm lệnh transaction, bank-account, va, webhook, paycode, apikey, sandbox và sepay api, CLI đã tự thử lại tối đa 3 lần khi mất kết nối hoặc gặp HTTP 429 trước khi trả lỗi cho script. Nhóm pg, bankhub và einvoice chỉ tự thử lại lệnh đọc khi gặp HTTP 429. CLI không tự thử lại lỗi HTTP 5xx. Lệnh tạo dữ liệu không gửi idempotency key thì CLI không tự thử lại.

Idempotency

Lệnh tạo dữ liệu bị ngắt giữa chừng không cho biết server đã tạo hay chưa. --idempotency-key <key> gửi kèm header X-Idempotency-Key: cùng key thì server trả kết quả của lần đầu thay vì tạo bản ghi mới. Không có flag, CLI tự tạo một key mới cho mỗi lần chạy.

Chỉ các lệnh sau gửi key: webhook create, webhook replay, bank-account create, va issue, va revoke, apikey create, paycode create, sandbox init và sepay api khi ghi dữ liệu. Lệnh pg, bankhub, einvoice và paycode update không gửi key và bỏ qua flag này.

Bash
1
2
3
KEY=$(uuidgen)
sepay webhook create --url https://api.congty.vn/webhooks/sepay --bank-mode all --event-type in \
--idempotency-key "$KEY"
Key mới ở mỗi lần chạy lại tạo bản ghi trùng

Tạo KEY một lần trước vòng lặp và dùng lại ở mọi lần thử. Không dùng vòng này cho lệnh không gửi key, ví dụ einvoice invoice create: mỗi lần chạy lại có thể tạo thêm một hóa đơn.

Vòng thử lại tối đa 4 lần, chờ lâu dần, chỉ chạy lại khi error_code có thể thử lại:

Bash
1
2
3
4
5
6
7
8
9
10
KEY=$(uuidgen)
for delay in 2 4 8 16; do
sepay webhook create --url https://api.congty.vn/webhooks/sepay --bank-mode all --event-type in \
--idempotency-key "$KEY" --json 2>err.json && exit 0
case "$(sed -n '/^{/,/^}/p' err.json | jq -r .error_code)" in
rate_limited|network_error|idempotency_conflict|server_error|*_provision_failed|*_token_failed) sleep "$delay" ;;
*) cat err.json >&2; exit 1 ;;
esac
done
cat err.json >&2; exit 1