API hóa đơn điện tử Pay2S giúp phần mềm của doanh nghiệp chuyển dữ liệu đã kiểm tra sang quy trình hóa đơn qua kết nối được cấu hình. Trước khi viết request, đội phát triển cần thống nhất ai xác nhận điều kiện của đơn, ai kiểm tra dữ liệu và hệ thống nào lưu kết quả cuối cùng.
Bài viết này dành cho người phụ trách website, POS hoặc phần mềm riêng. Nếu chưa chốt phạm vi sản phẩm, xem giải pháp hóa đơn điện tử tự động Pay2S. Hóa Đơn Tự Động là kênh đại lý hỗ trợ tư vấn triển khai; đặc tả kỹ thuật phải đối chiếu tài liệu API chính thức tại thời điểm tích hợp.
Chọn đúng luồng trước khi tích hợp
Đừng ghép việc xác nhận thanh toán và việc lập hóa đơn thành một trạng thái duy nhất. Phần mềm cần biết khoản thu đã được xác minh hay chưa, thông tin hóa đơn đã đủ chưa và yêu cầu đang ở bước nào. Điều này giúp nhân viên trả lời khách đúng trạng thái thay vì coi mọi phản hồi thành công là đã phát hành.
API hóa đơn hoạt động qua kết nối đã cấu hình và không tự xác minh một đơn bên ngoài đã thanh toán. Vì vậy, thiết kế backend phải xác định điều kiện gửi yêu cầu; không lấy thông báo từ trình duyệt làm bằng chứng duy nhất để bắt đầu xử lý.
Chuẩn bị cho một dự án có thể bàn giao
- Dữ liệu: nơi cung cấp người mua, hàng hóa và mã đơn; người xác nhận các trường còn thiếu.
- Kết nối: pháp nhân, mẫu và môi trường được phép sử dụng.
- Trạng thái: cách phần mềm hiển thị việc đang chờ, đã hoàn tất hoặc cần kiểm tra.
- Nhật ký: mã tham chiếu và ngữ cảnh đủ để hỗ trợ, nhưng đã che dữ liệu nhạy cảm.
- Vận hành: người tiếp nhận khi lỗi vượt phạm vi xử lý tự động.
Khóa bí mật cần nằm ở backend. Không đặt khóa trong JavaScript công khai, ảnh chụp màn hình hoặc nội dung gửi hỗ trợ. Tách cấu hình thử nghiệm khỏi vận hành thật và ghi rõ người có quyền thay đổi.
Các nhóm thao tác cần phân biệt
| Nhóm thao tác | Mục đích | Cần lưu ý |
|---|---|---|
| Tạo nháp | Chuẩn bị hồ sơ để kiểm tra | Không thông báo khách đã có hóa đơn chỉ vì nháp đã được tạo |
| Gửi nháp, phát hành | Tiếp tục quy trình theo quyền và môi trường | Xác nhận điều kiện chuyển bước và kết quả thực tế |
| Tra cứu, đồng bộ | Làm rõ trạng thái đang xử lý | Tra cứu trước khi tạo lại khi kết quả chưa rõ |
| Lấy tệp | Phục vụ hiển thị hoặc gửi kết quả | Phân biệt lỗi gửi thông báo với lỗi hóa đơn |
Các tên thao tác, trường dữ liệu, cách ký và mã lỗi cụ thể nằm trong tài liệu Pay2S. Đừng chuyển nguyên request của API thanh toán sang API hóa đơn vì cùng gắn với một đơn hàng.
Xử lý gửi lại và kết quả chưa rõ
Một thiết kế tốt phải trả lời được câu hỏi: nếu phần mềm mất phản hồi sau khi gửi, làm sao biết yêu cầu trước đã được xử lý? Hãy lưu mã tham chiếu cùng trạng thái đang biết, rồi tra kết quả trước khi mở một yêu cầu khác. Không để nhân viên chỉ có lựa chọn bấm gửi lại liên tục.
Ở bước tạo nháp, Pay2S có cơ chế nhận diện theo external_ref. Đội phát triển nên thử lại cùng dữ liệu, thử mã đã dùng với dữ liệu khác và thử mất phản hồi. Với bước phát hành, ưu tiên tra cứu hoặc đồng bộ khi kết quả chưa rõ. Đọc quy tắc hiện hành trước khi xây dựng chính sách thử lại.
Bộ kiểm thử tối thiểu trước bàn giao
- Đơn đủ dữ liệu đi qua đúng bước được phê duyệt.
- Thông tin người mua thiếu được chuyển cho đúng người bổ sung.
- Yêu cầu gửi lại không phát sinh hồ sơ trùng ngoài dự kiến.
- Kết quả chậm hoặc chưa rõ có đường tra cứu và đối soát.
- Lỗi thông báo khách được xử lý riêng, không tạo lại hóa đơn.
- Đội vận hành đọc được nhật ký và giải thích được trạng thái cho khách.
Lưu kết quả quan sát cho từng tình huống, không chỉ đánh dấu đạt. Sau mỗi lần đổi mẫu hoặc dữ liệu đầu vào, chạy lại nhóm kiểm thử có liên quan. Đây là khuyến nghị nghiệm thu giúp doanh nghiệp kiểm soát phần mềm của mình.
Trao đổi phạm vi tích hợp với đại lý
Chuẩn bị tên phần mềm, cách nhận đơn, nhà cung cấp hóa đơn đang dùng và quy trình mong muốn. Chỉ gửi dữ liệu minh họa đã che thông tin; không gửi khóa hoặc hồ sơ khách hàng thật qua yêu cầu tư vấn.
Nhận tư vấn tích hợp API hóa đơn Pay2S · Chuẩn bị kết nối nhà cung cấp · Xem bảng giá.
