Tài liệu tham khảo IIAPI

Tài liệu tham khảo API đầy đủ cho tích hợp hóa đơn điện tử IIAPI.

URL Cơ sở

Production: https://api.your-domain.com/api/iiapi
Development: http://localhost:3000/api/iiapi

Điểm cuối Hóa đơn

Tạo Hóa đơn GTGT (VAT Invoice)

POST /vat-invoices
Content-Type: application/json

{
  "seller": {
    "taxCode": "0123456789",
    "name": "Công ty Của Bạn",
    "address": "123 Đường phố"
  },
  "buyer": {
    "taxCode": "9876543210",
    "name": "Công ty Khách hàng",
    "address": "456 Đại lộ"
  },
  "invoiceDate": "2024-01-15",
  "currencyCode": "VND",
  "items": [
    {
      "itemName": "Sản phẩm",
      "quantity": 10,
      "unitPrice": 100000,
      "amount": 1000000,
      "vatRate": 10,
      "vatAmount": 100000
    }
  ],
  "totalAmount": 1000000,
  "totalVatAmount": 100000,
  "totalPayment": 1100000
}

Tạo Hóa đơn POS

POST /pos-sale-invoices
Content-Type: application/json

{
  "invoiceDate": "2024-01-15",
  "items": [
    {
      "itemName": "Cà phê",
      "quantity": 2,
      "unitPrice": 50000,
      "amount": 100000
    }
  ],
  "totalAmount": 100000,
  "totalPayment": 100000,
  "paymentMethod": "CASH"
}

Quản lý Hóa đơn

InvoiceManagementService cung cấp bốn thao tác. Tham số truy vấn clientName tùy chọn chọn client đã đăng ký; khi bỏ trống, client mặc định được dùng.

Hủy Hóa đơn

POST /invoices/cancel?clientName=vnpay-client
Content-Type: application/json

{ ...body yêu cầu hủy hóa đơn }

Lấy Chi tiết Hóa đơn

POST /invoices/detail?clientName=vnpay-client
Content-Type: application/json

{ ...body yêu cầu chi tiết hóa đơn }

Lấy Thông tin Mã số thuế

GET /tax-code/{taxCode}?clientName=vnpay-client

Lấy PDF Hóa đơn

Trả về PDF hóa đơn dưới dạng base64.

POST /invoices/pdf?clientName=vnpay-client
Content-Type: application/json

{ ...body yêu cầu PDF hóa đơn }

Trạng thái Hóa đơn

Trạng thái	Mô tả
DRAFT	Đã tạo, chưa gửi
PENDING	Đã gửi đến T-VAN
SIGNED	Đã ký số
SENT	Đã gửi đến CQT
ACCEPTED	CQT chấp nhận
REJECTED	CQT từ chối
CANCELLED	Đã hủy

Mã lỗi

BANA không tự định nghĩa danh mục lỗi hóa đơn điện tử - lỗi được trả về từ response của provider VNPAY viiAPI (HTTP status + payload lỗi). Kiểm tra response provider và log service.

Liên quan

• Các loại Hóa đơn
• Webhooks
• Tuân thủ