Khóa API: cách dùng trên KetoanX

ketoanx.com/settings/api-keys

Chứng từ gửi qua khóa đi vào đúng bộ máy kiểm của nhập từ Excel: tài khoản phải là tài khoản chi tiết đang dùng, mã đối tượng phải có trong danh mục, ngày không được nằm trong kỳ đã khóa sổ. Chứng từ vào sổ ngay hoặc chỉ được cất, tùy bạn đặt trong nội dung gửi. Chứng từ do khóa tạo mang tên người tạo khóa là người lập.

Trong quy trình, khóa đứng sau khi công ty đã có hệ thống tài khoản và danh mục khách hàng, nhà cung cấp (mã đối tượng) và trước khi phần mềm bán hàng bắt đầu gửi. Nếu chỉ cần nạp số liệu một lần, dùng nhập từ Excel thay vì khóa API.

Hãy chuẩn bị ba thứ. Một là hệ thống tài khoản với các tài khoản chi tiết mà phần mềm kia sẽ dùng (không dùng được tài khoản tổng hợp). Hai là mã đối tượng trong khách hàng, nhà cung cấp, vì phần mềm kia gửi mã, không gửi tên. Ba là một người lập trình hoặc nhà cung cấp phần mềm bán hàng đọc được tài liệu nối API.

Quan trọng hơn cả, khóa mang quyền của người tạo nó. Hãy để chủ sở hữu hoặc một quản trị viên ổn định tạo khóa; nếu người tạo rời công ty hoặc bị hạ quyền, mọi khóa họ tạo ngừng hoạt động.

ketoanx.com/settings/api-keys

Mỗi lần gửi chỉ một chứng từ, nội dung tối đa 64 KB. Mỗi khóa gọi tối đa 120 lần mỗi phút.

Khi muốn chứng từ chỉ được cất để kế toán duyệt

Gửi posted là false. Chứng từ vào danh sách ở trạng thái chưa ghi sổ; kế toán kiểm rồi ghi sổ bằng tay. Nên dùng cho phiếu chi hoặc phiếu của phần mềm chưa tin cậy.

Khi thu hồi khóa

Bấm Thu hồi ở dòng khóa, xác nhận câu hỏi phần mềm đang dùng khóa này sẽ không gửi được chứng từ nữa. Khóa hết hiệu lực ngay, mọi lần gọi sau trả mã 401. Không khôi phục được; cần thì tạo khóa mới. Thu hồi khóa không xóa các chứng từ khóa đã tạo.

Khi nghi khóa bị lộ hoặc người quản lý khóa nghỉ việc

Thu hồi ngay, tạo khóa mới với tên mới, đổi trong phần mềm kia, rồi mở Hệ thống→, Nhật ký thao tác và tìm các dòng ghi "qua API, khóa" kèm tên và 8 ký tự đầu của khóa để xem khóa đã tạo chứng từ nào trong khoảng nghi ngờ. Chứng từ lạ thì xử lý như bên dưới.

Khi chứng từ gửi qua API sai

API chỉ tạo chứng từ, không sửa và không xóa. Chứng từ đã ghi sổ không tẩy xóa dấu vết; sửa bằng chứng từ điều chỉnh theo mở sổ, ghi sổ, khóa sổ và sửa sổ. Nếu công ty bật công tắc Chứng từ đã ghi sổ chỉ sửa bằng bút toán điều chỉnh ở cài đặt cảnh báo (bật sẵn cho công ty chưa từng chọn), chứng từ do khóa tạo cũng bị chặn sửa, xóa như chứng từ người dùng lập.

Khi phần mềm kia gửi phiếu chi tiền mặt

Hai điều phần mềm không làm hộ bạn. Thứ nhất, API không chạy các cảnh báo của form lập chứng từ như chi quá tồn quỹ hay vượt dự toán: nó chỉ kiểm tài khoản, đối tượng, ngày và khóa sổ. Thứ hai, nó cũng không cảnh báo khoản trả tiền mặt từ 5 triệu đồng. Từ 01/7/2025, hàng hóa, dịch vụ mua vào từ 5 triệu đồng (đã gồm thuế GTGT) phải có chứng từ thanh toán không dùng tiền mặt thì thuế đầu vào mới được khấu trừ; xem thanh toán không dùng tiền mặt. Nếu phần mềm bán hàng gửi phiếu chi tiền mặt cho nhà cung cấp, hãy rà bằng trang Kiểm tra sổ sách cuối kỳ.

Lỗi trả về dạng JSON có error.code và error.message. Các mã thường gặp:

Thiếu khóa API: gửi tiêu đề Authorization: Bearer <khóa> (mã 401, missing_key) nghĩa là chưa gửi khóa hoặc khóa sai dạng (không bắt đầu bằng kx_).

Khóa API không đúng (401, invalid_key) nghĩa là khóa không có trong hệ thống; kiểm tra có chép thiếu ký tự không.

Khóa API đã bị thu hồi (401, key_revoked), hoặc Khóa API hết hiệu lực vì người tạo khóa không còn là chủ sở hữu hoặc quản trị viên của công ty. Tạo khóa mới bằng người còn quyền.

Nội dung không phải JSON hợp lệ (400) và câu "Nội dung tối đa 64 KB" (413).

Lỗi invalid_body có dạng "Trường ... : ..." chỉ đúng trường sai, ví dụ thiếu lines.

Ngày không hợp lệ (dùng YYYY-MM-DD) (422, invalid_date).

"Sổ đã khóa đến ngày ..." (422, period_locked) khi ngày nằm trong kỳ đã khóa sổ kế toán. Gửi với ngày sau ngày khóa hoặc nhờ kế toán mở khóa.

"Dòng ...: tài khoản ... không có trong hệ thống tài khoản hoặc đã ngừng dùng" (unknown_account) và "... là tài khoản tổng hợp, hạch toán vào tài khoản chi tiết" (summary_account). Sửa mã tài khoản.

"... tài khoản Nợ và tài khoản Có trùng nhau" (same_account), "... số tiền phải lớn hơn 0" (invalid_amount), "... không có đối tượng mã ..." (unknown_party). Thêm đối tượng vào danh mục trước.

Câu "Vượt 120 lần gọi mỗi phút, thử lại sau" (429, rate_limited). Cho phần mềm kia gửi chậm lại.