Phát hành hóa đơn qua API

POST /invoices với Idempotency-Key, thuế GTGT theo phần trăm, cùng việc liệt kê, storno và đánh dấu đã thanh toán.

Hóa đơn đầu tiên trong 6 bước

Gửi POST /v1/invoices với một đối tượng buyer và ít nhất một mục trong lines.
Thêm header Idempotency-Key — bắt buộc, một khóa cho mỗi thao tác logic.
Gửi vat_rate dưới dạng phần trăm (21) và unit_price là đơn giá CHƯA THUẾ.
Phản hồi 201 chứa id, number, series, tổng tiền net/vat/gross và metadata bạn đã gửi.
Lấy chứng từ bằng GET /v1/invoices/{id}/pdf hoặc XML UBL bằng GET /v1/invoices/{id}/xml.

Mọi endpoint

Phương thức	Endpoint	Scope	Idempotency-Key	Yêu cầu / phút
POST	/invoices Phát hành hóa đơn hoặc proforma	invoices:write	bắt buộc	30
GET	/invoices Liệt kê hóa đơn (phân trang bằng con trỏ)	invoices:read	—	120
POST	/invoices/preview-totals Tính tổng tiền mà không tạo bất cứ thứ gì	invoices:read	—	120
GET	/invoices/{invoice_id} Lấy một hóa đơn	invoices:read	—	120
GET	/invoices/{invoice_id}/pdf Tải PDF hóa đơn	invoices:read	—	120
POST	/invoices/{invoice_id}/storno Phát hành hóa đơn điều chỉnh hủy hóa đơn này	invoices:write	bắt buộc	30
POST	/invoices/{invoice_id}/payments Đánh dấu hóa đơn đã thanh toán	invoices:write	—	30
DELETE	/invoices/{invoice_id}/payments Đánh dấu hóa đơn chưa thanh toán	invoices:write	—	30

API 4invoices là gì

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: order-10457-invoice' \
  -d '{
    "buyer": {
      "name": "Exemplu Comert SRL",
      "tax_id": "RO12345678",
      "address": "Str. Fabricii 12",
      "city": "Cluj-Napoca",
      "county": "Cluj",
      "country": "RO",
      "email": "[email protected]"
    },
    "lines": [
      { "description": "Abonament SaaS, iulie", "quantity": 1, "unit_price": 400, "vat_rate": 21, "unit": "buc" },
      { "description": "Implementare", "quantity": 6, "unit_price": 250, "vat_rate": 21, "unit": "ora" }
    ],
    "currency": "RON",
    "document_kind": "factura",
    "due_date": "2026-08-15",
    "metadata": { "order_id": "10457" }
  }'

bash
# Phân trang bằng con trỏ: tiếp tục theo next_cursor cho đến khi has_more là false.
curl -sS "https://api.4invoices.net/v1/invoices?limit=50&status=issued&issued_from=2026-07-01" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# → {"object":"list","data":[...],"has_more":true,"next_cursor":"inv_01J..."}

curl -sS "https://api.4invoices.net/v1/invoices?limit=50&cursor=inv_01J..." \
  -H "Authorization: Bearer $ACCESS_TOKEN"

bash
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/storno \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'Idempotency-Key: storno-inv_01J7ABC-1'

# Hóa đơn điều chỉnh có số tài chính RIÊNG; số của hóa đơn gốc không bao giờ được dùng lại.

bash
# Đánh dấu đã thanh toán
curl -sS -X POST https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# Hoàn tác
curl -sS -X DELETE https://api.4invoices.net/v1/invoices/inv_01J7ABC/payments \
  -H "Authorization: Bearer $ACCESS_TOKEN"

https://api.4invoices.net/v1 · https://api.4invoices.net/v1/openapi.json

Lỗi

Trạng thái	Loại	Mã
422	invalid_request_error	issuer_profile_incomplete
422	invalid_request_error	cannot_storno_draft
422	invalid_request_error	nothing_to_storno

Lỗi thường gặp

Việc liệt kê dựa trên con trỏ: tiếp tục theo next_cursor cho đến khi has_more là false. Bộ lọc gồm status, document_kind, buyer_tax_id, issued_from, issued_to và q.
Storno là POST /v1/invoices/{id}/storno và có số tài chính riêng — số của hóa đơn gốc không bao giờ được dùng lại.
Proforma (document_kind proforma) không tiêu tốn số tài chính nào và không thể nộp lên hệ thống hóa đơn điện tử quốc gia.
metadata được trả lại khi đọc: hãy lưu mã đơn hàng của bạn vào đó để không cần bảng ánh xạ riêng.
POST /v1/invoices/preview-totals thực hiện cùng phép tính mà không có tác dụng phụ — tiện để hiển thị tổng tiền trong giỏ hàng của bạn.

Câu hỏi và trả lời cho nhà phát triển

Một hóa đơn có thể có bao nhiêu dòng?

Từ 1 đến 400. description tối đa 1024 ký tự, và quantity phải là số dương.

Điều gì xảy ra nếu tôi gửi lại cùng yêu cầu sau khi hết thời gian chờ?

Với cùng Idempotency-Key, bạn nhận được hóa đơn gốc kèm header Idempotency-Replayed: true. Không có chứng từ thứ hai nào được phát hành.

Làm thế nào để đánh dấu hóa đơn đã thanh toán?

POST /v1/invoices/{id}/payments đánh dấu đã thanh toán, còn DELETE trên cùng đường dẫn sẽ hoàn tác. Cả hai đều yêu cầu scope invoices:write.

Xem thêm