Xác thực

Tích hợp từ hệ thống bên ngoài xác thực bằng API key, gửi trong header Authorization theo dạng Bearer. Phiên đăng nhập bằng cookie chỉ dành cho ứng dụng web của hoadon.pro, không dùng cho tích hợp.

Gửi API key

GET /v1/... HTTP/1.1
Host: api.hoadon.pro
Authorization: Bearer hd_live_xxxxxxxxxxxxxxxxxxxxxx

Với cURL:

curl "https://api.hoadon.pro/v1/..." \
  -H "Authorization: Bearer $HOADON_API_KEY"

Hình dạng của khoá

Tiền tố	Dùng cho
`hd_live_`	Dữ liệu thật.
`hd_test_`	Môi trường thử nghiệm.

Sau tiền tố là chuỗi ký tự ngẫu nhiên. Khoá chỉ hiển thị một lần khi tạo; hoadon.pro chỉ lưu giá trị băm của khoá nên không khôi phục được khoá đã mất. Nếu mất hoặc lộ khoá, hãy thu hồi và tạo khoá mới.

Quyền và phạm vi

Mỗi khoá có hai giới hạn:

Quyền (permissions): danh sách thao tác khoá được làm. Khoá dùng cùng danh mục quyền với vai trò người dùng (xem bảng dưới).
Phạm vi tổ chức: danh sách tổ chức khoá được truy cập. Khoá không giới hạn truy cập mọi tổ chức thuộc tổ chức gốc đã tạo khoá; khoá có giới hạn chỉ truy cập các tổ chức đã chọn.

Chỉ cấp quyền tối thiểu cần cho tích hợp.

Quyền	Cho phép
`invoice.read`, `invoice.write`, `invoice.delete`	Xem, ghi, xoá hoá đơn.
`invoice.export`	Xuất hoá đơn.
`invoice.accept_exception`	Chấp nhận ngoại lệ trên kết quả kiểm tra.
`mailbox.read`, `mailbox.manage`	Xem và quản lý hộp thư.
`catalog.read`, `catalog.write`	Xem và sửa danh mục nhà cung cấp, khách hàng.
`org.read`, `org.manage`	Xem và quản lý cơ cấu tổ chức.
`tax_connection.read`, `tax_connection.manage`	Xem và quản lý kết nối Cơ quan Thuế.
`customs.read`, `customs.write`	Xem và nhập tờ khai hải quan.
`report.read`, `report.export`	Xem và xuất báo cáo.
`user.manage`, `role.manage`	Quản lý người dùng và vai trò.
`billing.read`, `billing.manage`	Xem và quản lý gói, credit.
`api_key.manage`, `webhook.manage`	Quản lý API key và webhook.
`audit.read`, `settings.manage`	Xem nhật ký; quản lý cài đặt.

Danh sách quyền mà từng endpoint yêu cầu nằm trong Scalar.

Thu hồi và xoay khoá

Thu hồi khoá có hiệu lực ngay. Để xoay khoá không gián đoạn: tạo khoá mới, cập nhật hệ thống của bạn, kiểm tra chạy đúng rồi mới thu hồi khoá cũ.

Bảo vệ khoá

Không đưa khoá vào mã nguồn, ảnh chụp màn hình hay tin nhắn.
Lưu trong biến môi trường hoặc kho bí mật.
Dùng một khoá cho mỗi hệ thống để thu hồi từng cái khi cần.
Gọi API từ máy chủ của bạn, không từ trình duyệt hay ứng dụng di động của người dùng cuối.