NgothanhloiPOS API

Businesses

Quản lý liên kết dịch vụ HDDT với Business trong hệ thống

GET /e-invoices/businesses

Lấy danh sách liên kết dịch dụ HHDT của doanh nghiệp: - Param: provider_uuid, business_uuid, is_active, is_default. Quyền: einvoice.business.view_list

Fields

Field	Type	Description	Required
provider_uuid			NO
business_uuid			NO
account			NO
acpassword			NO
username			NO
password			NO
is_active			NO
is_default			NO
action			NO
link_service			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "_embedded": {
        "businesses": [
            {
                "uuid",
                "account",
                "username",
                "is_active": "Y|N",
                "is_default": "Y|N",
                "has_manager_sale_docs_vh":"Y|N"
                "provider_name",
                "business_name"
            },
            ...
        ]
    }
}

POST /e-invoices/businesses

Thêm liên kết mới

Fields

Field	Type	Description	Required
provider_uuid			NO
business_uuid			NO
account			NO
acpassword			NO
username			NO
password			NO
is_active			NO
is_default			NO
action			NO
link_service			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Content-Type	application/vnd.e-invoices.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
   "provider_uuid",
   "business_uuid",
   "link_service", //link api service
   "account", //tài khoản quản trị
   "acpassword", //mật khẩu tài khoản quản trị
   "username", //username đăng nhập service (chỉ áp dụng với vnpt company)
   "password", //mật khẩu user đăng nhập service (chỉ áp dụng với vnpt company)
   "is_active": "Y|N",
   "is_default": "Y|N"
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{"result": "SUCCESS|ERRPO"}
Các mã lỗi:
- DEFAULT_MUST_ACTIVE: Liên kết mặc định thì phải active
- ERROR_PROVIDER_UUID: provider_uuid không đúng
- ERROR_BUSINESS_UUID: business_uuid không đúng
- ERROR_USERNAME_PASSWORD: username, password không đúng
- ERROR: Lỗi khác

PUT /e-invoices/businesses[/:business_id]

Chỉnh sửa thông tin đăng nhập: action editUserPass, quyền einvoice.business.edit_user_pass.
Chỉnh sửa trạng thái, mặc định: action editActiveDefault, quyền einvoice.business.edit_active_default.

Fields

Field	Type	Description	Required
provider_uuid			NO
business_uuid			NO
account			NO
acpassword			NO
username			NO
password			NO
is_active			NO
is_default			NO
action			NO
link_service			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Content-Type	application/vnd.e-invoices.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
   "action": "editUserPass | editActiveDefault"
   "link_service": //Với action editUserPass
   "account", //Với action editUserPass
   "acpassword", //Với action editUserPass
   "username", //Với action editUserPass
   "password", //Với action editUserPass
   "is_active", //Với action editActiveDefault
   "is_default" //Với action editActiveDefault
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{result: "SUCCESS | ERROR"}
Các mã lỗi:
- NOT_FOUND_LINK: Không tìm thấy liên kết
- DEFAULT_MUST_ACTIVE (với action editActiveDefault)
- ERROR_USERNAME_PASSWORD: username, password không đúng (Với action editUserPass)
- ERROR

DELETE /e-invoices/businesses[/:business_id]

Xóa liên kết. Quyền einvoice.business.delete. Các lỗi xảy ra: NOT_FOUND_LINK, ERROR

Fields

Field	Type	Description	Required
provider_uuid			NO
business_uuid			NO
account			NO
acpassword			NO
username			NO
password			NO
is_active			NO
is_default			NO
action			NO
link_service			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
204: No Content
404: Not Found
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

GET /e-invoices/businesses[/:business_id]

Lấy thông tin liên kết. Quyền einvoice.business.view_detail

Fields

Field	Type	Description	Required
provider_uuid			NO
business_uuid			NO
account			NO
acpassword			NO
username			NO
password			NO
is_active			NO
is_default			NO
action			NO
link_service			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "result": "OK",
    "business": {
        "uuid",
        "link_service",
        "account",
        "acpassword",
        "username",
        "password",
        "is_active": "Y|N",
        "is_default": "Y|N",
        "provider_uuid",
        "provider_name",
        "business_uuid",
        "business_name"
    }
}
Lỗi nếu có: NOT_FOUND_LINK

DigitalCerts

GET /e-invoices/digital-certs/:eb_uuid

Lấy danh sách chứng thư số Quyền einvoice.digital_cert.view_list

Fields

Field	Description	Required
serialnumber		NO
datefrom		NO
dateto		NO
is_active		NO
is_default		NO
user_id	User_Id trong chứng thư số	NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "_embedded": {
        "digital_certs": [
            {
                "uuid",
                "serialnumber",
                "datefrom",
                "dateto",
                "user_id",
                "is_active": "Y|N",
                "is_default": "Y|N"
            }
        ]
    },
}

POST /e-invoices/digital-certs/:eb_uuid

Thêm chứng thư số. Quyền einvoice.digital_cert.add

Fields

Field	Description	Required
serialnumber		NO
datefrom		NO
dateto		NO
is_active		NO
is_default		NO
user_id	User_Id trong chứng thư số	NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Content-Type	application/vnd.e-invoices.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
   "serialnumber", //Serial Chứng Thư 
   "datefrom": "YYYY-MM-DD HH:mm:ss", //Ngày có hiệu lực
   "dateto": "YYYY-MM-DD HH:mm:ss", //Ngày hết hạn
   "user_id", //User_id chứng thư số
   "is_active": "Y|N",
   "is_default": "Y|N"
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{result: "SUCCESS | ERROR"}
Các lỗi:
- DEFAULT_MUST_ACTIVE
- ERROR_EB_UUID
- ERROR_SERIALNUMBER

PUT /e-invoices/digital-certs/:eb_uuid[/:digital_cert_id]

Chỉnh sửa thông tin chứng thư số. Quyền einvoice.digital_cert.edit

Fields

Field	Description	Required
serialnumber		NO
datefrom		NO
dateto		NO
is_active		NO
is_default		NO
user_id	User_Id trong chứng thư số	NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Content-Type	application/vnd.e-invoices.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
   "serialnumber",
   "datefrom",
   "dateto",
   "user_id",
   "is_active": "Y|N",
   "is_default": "Y|N"
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{result: "SUCCESS | ERROR"}
Các mã lỗi:
- NOT_FOUND_DIGITAL_CERT
- ERROR_EB_UUID
- DEFAULT_MUST_ACTIVE
- ERROR_SERIALNUMBER

DELETE /e-invoices/digital-certs/:eb_uuid[/:digital_cert_id]

Xóa chứng thư số. Quyền einvoice.digital_cert.delete. Mã lỗi: NOT_FOUND_DIGITAL_CERT

Fields

Field	Description	Required
serialnumber		NO
datefrom		NO
dateto		NO
is_active		NO
is_default		NO
user_id	User_Id trong chứng thư số	NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
204: No Content
404: Not Found
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Providers

Quản lý NCC dịch vụ HDDT

GET /e-invoices/providers[/:provider_id]

Lấy danh sách NCC dịch vụ HDDT. Quyền: einvoice.provider.view_list

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "_embedded": {
        "providers": [
            {
                "uuid",
                "name",
            }
        ]
    }
}

SalesDocsVH

Xử lý chứng từ bán hàng hóa đơn điện tử MTT từ dịch vụ VNPT HKD

GET /e-invoices/sales-docs-vh/:eb_uuid

Lấy danh sách hóa đơn điện tử - Filter: TuNgayHoaDon (Từ ngày, YYYYMMDD), DenNgayHoaDon (Đến ngày, YYYYMMDD), KyHieu (Ký hiệu) - Sort: Tự xây dựng chức năng sort theo các cột khác (NgayHoaDon, SoHoaDon, CoChungTu, TrangThaiCQT, TrangThaiHoaDon) Quyền: einvoice.sale_doc_vh.view_list

Fields

Field	Type	Description	Required
IdHoaDon			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

//Dữ liệu trả về tất cả, không có phân trang
{
    "_embedded": {
        "sales_docs_vh": [
            {
                "Id", //Id hóa đơn
                "MauSo", //Mẫu số
                "KyHieu", //Ký hiệu
                "SoHoaDon", //Số hóa đơn
                "NgayHoaDon", //Ngày hóa đơn
                "MaKH", //Mã khách hàng
                "DonViMuaHang", //Đơn vị mua hàng
                "NguoiMuaHang", //Người mua hàng
                "TrangThaiHoaDon", //Trạng thái hóa đơn
                "TrangThaiCQT", //Trạng thái CQT
                "TongTien", //Tổng tiền
                "CoChungTu": "Y" //Có chứng từ
                "DuocTaoChungTu": "Y" //Được phép tạo chứng từ hay không
            },
            ...
        ]
    }
}
Các lỗi:
- NOT_FOUND_EB: Không tìm thấy dịch vụ HDDT doanh nghiệp
- NOT_EB_VNPT_HOUSEHOLD: dịch vụ HDDT doanh nghiệp không thuộc dạng VNPT HKD
- NOT_EB_REQUIRED_INFO: Thông tin dịch vụ HDDT doanh nghiệp chưa đầy đủ: link_service, account, acpassword
- ERROR_LOGIN_EB: //Lỗi lấy thông tin đăng nhập VNPT HKD
- ERROR: Lỗi lấy danh sách HDDT

PUT /e-invoices/sales-docs-vh/:eb_uuid[/:id]

Tạo chứng từ bán hàng Quyền: einvoice.sale_doc_vh.create_doc Link: PUT /e-invoices/sales-docs-vh/[:eb_uuid]/sale_docs

Fields

Field	Type	Description	Required
IdHoaDon			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Content-Type	application/vnd.e-invoices.v1+json application/json

Body

{
    IdHoaDon //Chuỗi string json không rỗng danh sách IdHoaDon (number)
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{result:"SUCCESS|ERROR"}
Các mã lỗi:
- NOT_FOUND_EB: Không tìm thấy EB
- NOT_EB_VNPT_HOUSEHOLD: EB Không phải dịch vụ VNPT HKD
- NOT_EB_REQUIRED_INFO: Thông tin EB chưa đầy đủ
- ERROR_LOGIN_EB: Lỗi lấy thông tin đăng nhập VNPT HKD
- ERROR_CREATE: Lỗi tạo chứng từ - Có kèm danh sách idHoaDon lỗi gồm 3 mục con là HAS_DOC, NOT_CUSTOMER_CODE, ERROR_OTHER

Serials

Quản lý ký hiệu hóa đơn

GET /e-invoices/serials/:eb_uuid

Lấy danh sách ký hiệu. Quyền einvoice.serial.view_list

Fields

Field	Type	Description	Required
mauso			NO
kyhieu			NO
ngaybatdausudung			NO
is_active			NO
is_default			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{
    "_embedded": {
        "serials": [
            {
                "uuid",
                "mauso",
                "kyhieu"",
                "ngaybatdausudung",
                "is_active",
                "is_default",
            },
            ...
        ]
    }
}

POST /e-invoices/serials/:eb_uuid

Thêm ký hiệu. Quyền einvoice.serial.add

Fields

Field	Type	Description	Required
mauso			NO
kyhieu			NO
ngaybatdausudung			NO
is_active			NO
is_default			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Content-Type	application/vnd.e-invoices.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
   "mauso", //Mẫu số
   "kyhieu", //Ký hiệu
   "ngaybatdausudung": "YYYY-MM-DD",
   "is_active": "Y|N",
   "is_default": "Y|N"
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
201: Created
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{result: "SUCCESS | ERROR"}
Các mã lỗi:
- DEFAULT_MUST_ACTIVE
- ERROR_EB_UUID: eb_uuid không đúng
- ERROR_KYHIEU: Kí hiệu hoặc mẫu số truyền vào không đúng, không khớp
- ERROR1, ERROR2, ERROR3, ERROR4, ERROR5: Lỗi khác

PUT /e-invoices/serials/:eb_uuid[/:serial_id]

Chỉnh sửa thông tin ký hiệu Quyền einvoice.serial.edit

Fields

Field	Type	Description	Required
mauso			NO
kyhieu			NO
ngaybatdausudung			NO
is_active			NO
is_default			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Content-Type	application/vnd.e-invoices.v1+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Body

{
   "mauso",
   "kyhieu",
   "ngaybatdausudung": "YYYY-MM-DD",
   "is_active": "Y|N",
   "is_default": "Y|N"
}

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
200: OK
404: Not Found
400: Client Error
422: Unprocessable Entity
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Body

{result: "SUCCESS | ERROR"}
Các mã lỗi:
- NOT_FOUND_SERIAL: serial_uuid không đúng
- ERROR_EB_UUID: eb_uuid không đúng
- DEFAULT_MUST_ACTIVE
- ERROR_KYHIEU: kyhieu hoặc mẫu số không đúng, không khớp
- ERROR1, ERRO2, ERROR3, ERROR4, ERROR5: lỗi khác

DELETE /e-invoices/serials/:eb_uuid[/:serial_id]

Xóa ký hiệu. Quyền einvoice.serial.delete

Fields

Field	Type	Description	Required
mauso			NO
kyhieu			NO
ngaybatdausudung			NO
is_active			NO
is_default			NO

Request

Headers

Header	Value
Accept	application/vnd.e-invoices.v1+json application/hal+json application/json
Authorization	HTTP Basic, HTTP Digest, or OAuth2 Bearer token (check API provider for details)

Response

Status Codes

406: Not Acceptable
415: Unsupported Media Type
204: No Content
404: Not Found
401: Unauthorized
403: Forbidden

Headers

Header	Value
Content-Type	application/vnd.e-invoices.v1+json application/hal+json application/json
Allow	Comma-separated list of all HTTP methods allowed

Documentation

EInvoices (v1)

Businesses

GET /e-invoices/businesses

Fields

Request

Headers

Response

Status Codes

Headers

Body

POST /e-invoices/businesses

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

PUT /e-invoices/businesses[/:business_id]

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

DELETE /e-invoices/businesses[/:business_id]

Fields

Request

Headers

Response

Status Codes

Headers

GET /e-invoices/businesses[/:business_id]

Fields

Request

Headers

Response

Status Codes

Headers

Body

DigitalCerts

GET /e-invoices/digital-certs/:eb_uuid

Fields

Request

Headers

Response

Status Codes

Headers

Body

POST /e-invoices/digital-certs/:eb_uuid

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

PUT /e-invoices/digital-certs/:eb_uuid[/:digital_cert_id]

Fields

Request

Headers

Body

Response

Status Codes

Headers

Body

DELETE /e-invoices/digital-certs/:eb_uuid[/:digital_cert_id]

Fields

Request

Headers

Response

Status Codes

Headers

Providers

GET /e-invoices/providers[/:provider_id]