Hoá đơn

~6 phút đọc

Kết nối hoá đơn, đồng bộ công nợ và theo dõi ghi ngược các phân bổ đã duyệt.

Endpoint

Method	Path	Tóm tắt	Quyền	Nhóm tốc độ	Tương tác
`GET`	`/v1/integrations/hoadon-pro`	Trạng thái kết nối hoadon.pro	`invoice.read`	`read`	Scalar
`POST`	`/v1/integrations/hoadon-pro:connect`	Kết nối hoadon.pro bằng API key (D37)	`hoadon.connect`	`write`	Scalar
`POST`	`/v1/integrations/hoadon-pro:disconnect`	Ngắt kết nối hoadon.pro	`hoadon.connect`	`write`	Scalar
`POST`	`/v1/integrations/hoadon-pro:sync`	Đồng bộ thủ công hoá đơn từ hoadon.pro	`hoadon.connect`	`write`	Scalar
`GET`	`/v1/invoices`	Danh sách hoá đơn đồng bộ từ hoadon.pro	`invoice.read`	`read`	Scalar
`GET`	`/v1/invoices/search`	Tìm kiếm hoá đơn	`invoice.read`	`read`	Scalar
`GET`	`/v1/invoices/{id}`	Chi tiết hoá đơn điện tử	`invoice.read`	`read`	Scalar

Chi tiết endpoint

`GET /v1/integrations/hoadon-pro`

Trạng thái kết nối hoadon.pro

Quyền: invoice.read

Nhóm tốc độ: read
Phản hồi thành công 200: Trạng thái kết nối — object, application/json
Mã lỗi: chỉ các mã lỗi chung ở Tổng quan

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
`company_id`	query	Không	`OrgId`	Mã công ty / tổ chức (`org_…`).

curl -sS -X GET "https://api.dongtien.pro/v1/integrations/hoadon-pro" \
  -H "Authorization: Bearer $DT_API_KEY"

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/integrations/hoadon-pro");

import os

from dongtien import DongTien
from dongtien_api.api.hoa_don import get_hoadon_connection

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = get_hoadon_connection.sync(client=dt.client)

Mở trong tài liệu tương tác

`POST /v1/integrations/hoadon-pro:connect`

Kết nối hoadon.pro bằng API key (D37)

Probe capabilities (invoices.read, invoice.payment.write, webhook.manage), seal key và đăng ký webhook tự động.

Quyền: hoadon.connect

Nhóm tốc độ: write
Nội dung yêu cầu: object (application/json)
Phản hồi thành công 200: Kết nối thành công — object, application/json
Mã lỗi riêng của endpoint: conflict

curl -sS -X POST "https://api.dongtien.pro/v1/integrations/hoadon-pro:connect" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "api_key": "hd_live_9f2c4a7e1b3d5f60",
  "mst_map": [
    {
      "mst": "0312345678",
      "hoadon_org_id": "hdorg_0001",
      "hoadon_org_name": "Công ty TNHH Thương mại Sao Việt"
    }
  ],
  "backfill_days": 90
}'

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/integrations/hoadon-pro:connect", {
  body: {
    "api_key": "hd_live_9f2c4a7e1b3d5f60",
    "mst_map": [
      {
        "mst": "0312345678",
        "hoadon_org_id": "hdorg_0001",
        "hoadon_org_name": "Công ty TNHH Thương mại Sao Việt"
      }
    ],
    "backfill_days": 90
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.hoa_don import connect_hoadon

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = connect_hoadon.sync(
        client=dt.client,
        body={
            "api_key": "hd_live_9f2c4a7e1b3d5f60",
            "mst_map": [
                {
                    "mst": "0312345678",
                    "hoadon_org_id": "hdorg_0001",
                    "hoadon_org_name": "Công ty TNHH Thương mại Sao Việt",
                },
            ],
            "backfill_days": 90,
        },
    )

Mở trong tài liệu tương tác

`POST /v1/integrations/hoadon-pro:disconnect`

Ngắt kết nối hoadon.pro

Quyền: hoadon.connect

Nhóm tốc độ: write
Nội dung yêu cầu: object (application/json)
Phản hồi thành công 200: Đã ngắt kết nối — object, application/json
Mã lỗi riêng của endpoint: conflict

curl -sS -X POST "https://api.dongtien.pro/v1/integrations/hoadon-pro:disconnect" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0"
}'

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/integrations/hoadon-pro:disconnect", {
  body: {
    "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0"
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.hoa_don import disconnect_hoadon

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = disconnect_hoadon.sync(
        client=dt.client,
        body={
            "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        },
    )

Mở trong tài liệu tương tác

`POST /v1/integrations/hoadon-pro:sync`

Đồng bộ thủ công hoá đơn từ hoadon.pro

Quyền: hoadon.connect

Nhóm tốc độ: write
Nội dung yêu cầu: object (application/json)
Phản hồi thành công 200: Kết quả đồng bộ — object, application/json
Mã lỗi riêng của endpoint: conflict

curl -sS -X POST "https://api.dongtien.pro/v1/integrations/hoadon-pro:sync" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0"
}'

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.POST("/v1/integrations/hoadon-pro:sync", {
  body: {
    "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0"
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.hoa_don import sync_hoadon

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = sync_hoadon.sync(
        client=dt.client,
        body={
            "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        },
    )

Mở trong tài liệu tương tác

`GET /v1/invoices`

Danh sách hoá đơn đồng bộ từ hoadon.pro

Quyền: invoice.read

Nhóm tốc độ: read
Phản hồi thành công 200: Danh sách hoá đơn — InvoiceRefList, application/json
Mã lỗi riêng của endpoint: invalid_cursor

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
`limit`	query	Không	`integer`	Số phần tử mỗi trang (1–100, mặc định 20).
`cursor`	query	Không	`Cursor`	Con trỏ phân trang mờ (`cur_…`) lấy từ `next_cursor`; không tự tạo hay sửa.
`company_id`	query	Không	`OrgId`	Mã công ty / tổ chức (`org_…`).
`direction`	query	Không	`string`	—
`payment_status`	query	Không	`string`	—
`buyer_tax_code`	query	Không	`string`	—
`seller_tax_code`	query	Không	`string`	—

curl -sS -X GET "https://api.dongtien.pro/v1/invoices" \
  -H "Authorization: Bearer $DT_API_KEY"

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/invoices");

import os

from dongtien import DongTien
from dongtien_api.api.hoa_don import list_invoices

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = list_invoices.sync(client=dt.client)

Mở trong tài liệu tương tác

`GET /v1/invoices/search`

Tìm kiếm hoá đơn

Quyền: invoice.read

Nhóm tốc độ: read
Phản hồi thành công 200: Kết quả tìm kiếm — object, application/json
Mã lỗi: chỉ các mã lỗi chung ở Tổng quan

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
`company_id`	query	Không	`OrgId`	Mã công ty / tổ chức (`org_…`).
`q`	query	Có	`string`	—
`direction`	query	Không	`string`	—

curl -sS -X GET "https://api.dongtien.pro/v1/invoices/search?q=$Q" \
  -H "Authorization: Bearer $DT_API_KEY"

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/invoices/search", {
  params: {
    query: { "q": "<q>" },
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.hoa_don import search_invoices

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = search_invoices.sync(client=dt.client, q="<q>")

Công cụ search_invoices, scope invoices:read.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "search_invoices",
    "arguments": {}
  }
}

Mở trong tài liệu tương tác

`GET /v1/invoices/{id}`

Chi tiết hoá đơn điện tử

Quyền: invoice.read

Nhóm tốc độ: read
Phản hồi thành công 200: Chi tiết hoá đơn — object, application/json
Mã lỗi riêng của endpoint: resource_not_found

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
`id`	path	Có	`InvoiceRefId`	Mã tham chiếu hoá đơn (`inv_…`).

curl -sS -X GET "https://api.dongtien.pro/v1/invoices/$ID" \
  -H "Authorization: Bearer $DT_API_KEY"

import { createClient } from "@dongtien/sdk";

const dt = createClient({ apiKey: process.env.DT_API_KEY! });

const { data } = await dt.GET("/v1/invoices/{id}", {
  params: {
    path: { "id": "inv_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.hoa_don import get_invoice

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = get_invoice.sync(id="inv_0f5k2m9q4h7t3n8r6v1w0x5yz0", client=dt.client)

Mở trong tài liệu tương tác

Đối tượng

`InvoiceRefList`

Trường	Kiểu	Bắt buộc	Mô tả
`data`	`object[]`	Có	—
`data[].buyer_name`	`string \| null`	Không	—
`data[].buyer_tax_code`	`string \| null`	Không	—
`data[].currency`	`Currency`	Không	Giá trị: `VND`.
`data[].direction`	`string`	Có	Giá trị: `in`, `out`.
`data[].dtp_allocated`	`Vnd`	Không	—
`data[].due_date`	`Timestamp \| null`	Không	—
`data[].external_paid`	`Vnd`	Không	—
`data[].hoadon_id`	`string \| null`	Không	—
`data[].id`	`InvoiceRefId`	Có	—
`data[].issue_date`	`Timestamp`	Có	—
`data[].lookup_code`	`string \| null`	Không	—
`data[].number`	`string`	Có	—
`data[].org_id`	`OrgId`	Có	—
`data[].outstanding_amount`	`Vnd`	Có	—
`data[].payment_status`	`string`	Có	Giá trị: `unpaid`, `partially_paid`, `paid`, `overpaid`.
`data[].seller_name`	`string`	Có	—
`data[].seller_tax_code`	`string`	Có	—
`data[].series`	`string`	Có	—
`data[].template_code`	`string`	Có	—
`data[].total_amount`	`Vnd`	Có	—
`has_more`	`boolean`	Có	—
`next_cursor`	`string \| null`	Có	Con trỏ trang kế; `null` khi hết dữ liệu.
`object`	`string`	Có	Giá trị: `list`.