Danh sách API

Các endpoint của Open API v1 kèm URL đầy đủ, header bắt buộc, phạm vi khóa và cách kiểm tra khóa bằng GET /me.

Open API v1 có mười endpoint. URL đầy đủ của một request là địa chỉ gốc ghép với đường dẫn của endpoint.

Các endpoint

Phương thức	Đường dẫn	Phạm vi (scope)	Chức năng
`GET`	`/me`	không	Xem khóa này là ai, được dùng cửa hàng nào
`POST`	`/invoices`	`invoices.write`	Tạo hóa đơn bán
`GET`	`/invoices/{id}`	`invoices.read`	Tra cứu theo `id` NexERP
`GET`	`/invoices?external_id=`	`invoices.read`	Tra cứu theo mã giao dịch của bạn
`GET`	`/invoices/{id}/link`	`invoices.read`	Link xem hóa đơn
`POST`	`/invoices/{id}/replace`	`invoices.write`	Hóa đơn thay thế
`POST`	`/pump-logs`	`invoices.write`	Gửi giao dịch bơm
`POST`	`/pump-logs/batch`	`invoices.write`	Gửi một lô tối đa 100 giao dịch bơm
`GET`	`/pump-logs?id_log=`	`invoices.read`	Tra cứu giao dịch bơm
`GET`	`/time`	không	Giờ máy chủ, để đồng bộ giờ thiết bị trụ bơm

URL đầy đủ trên DEMO:

GET  https://api-demo.nexerp.vn/api/open/v1/me
POST https://api-demo.nexerp.vn/api/open/v1/invoices
GET  https://api-demo.nexerp.vn/api/open/v1/invoices/{id}
GET  https://api-demo.nexerp.vn/api/open/v1/invoices?external_id={external_id}
GET  https://api-demo.nexerp.vn/api/open/v1/invoices/{id}/link
POST https://api-demo.nexerp.vn/api/open/v1/invoices/{id}/replace
POST https://api-demo.nexerp.vn/api/open/v1/pump-logs
POST https://api-demo.nexerp.vn/api/open/v1/pump-logs/batch
GET  https://api-demo.nexerp.vn/api/open/v1/pump-logs?id_log={id_log}
GET  https://api-demo.nexerp.vn/api/open/v1/time

Trên môi trường thật, thay https://api-demo.nexerp.vn/api/open/v1 bằng địa chỉ gốc NexERP cấp cùng khóa. Phần đường dẫn giữ nguyên.

Header gửi lên

Header	Bắt buộc	Giá trị
`X-Api-Key`	có, mọi request	Khóa API, ví dụ `nexk_demo_…`. Không dùng `Authorization: Bearer`
`Content-Type`	có, với `POST`	`application/json`. Thân là JSON UTF-8

Trường lạ không có trong tài liệu bị từ chối với mã 422.

Header trả về

Header	Khi nào	Ý nghĩa
`X-RateLimit-Limit`	mọi phản hồi	Số request tối đa mỗi phút
`X-RateLimit-Remaining`	mọi phản hồi	Số request còn lại trong phút
`Retry-After`	phản hồi 429	Số giây phải chờ trước khi gửi lại

Kiểm tra khóa với GET /me

Gọi GET /me đầu tiên khi cấu hình. Endpoint này chạy là khóa và địa chỉ gốc đều đúng.

GET https://api-demo.nexerp.vn/api/open/v1/me

curl -s "$BASE/me" -H "X-Api-Key: $KEY"

{
  "app_code": "pump-x",
  "app_name": "Phần mềm trụ bơm X",
  "tenant_id": "6f1c2b9e-1d1a-4c9b-9a0e-2f4b8c7d5e31",
  "tenant_name": "Công ty Xăng dầu Vân Trúc",
  "scopes": ["invoices.read", "invoices.write"],
  "stores": ["CN5", "CN6"],
  "journal_mode": "none",
  "environment_prefix": "nexk_demo"
}

Trường	Kiểu	Ý nghĩa
`app_code`	chuỗi	Mã ứng dụng của bạn trên NexERP
`app_name`	chuỗi	Tên ứng dụng của bạn
`tenant_id`	chuỗi UUID	Mã doanh nghiệp mà khóa này thuộc về
`tenant_name`	chuỗi	Tên doanh nghiệp
`scopes`	mảng chuỗi	Các phạm vi khóa được dùng
`stores`	mảng chuỗi	Các mã cửa hàng khóa này được gửi trong `store_code`. NexERP có thể mở thêm cửa hàng mà không đổi khóa
`journal_mode`	chuỗi	`none`: NexERP không ghi sổ theo từng hóa đơn. `per_invoice`: mỗi hóa đơn ghi sổ ngay
`environment_prefix`	chuỗi	Tiền tố khóa của môi trường đang gọi: `nexk_demo` hoặc `nexk_live`

Lưu ý

Thiếu phạm vi cho một endpoint thì nhận 403 auth.scope_missing. Xin thêm phạm vi với doanh nghiệp.
Mã lỗi đầy đủ ở bài Mã lỗi.