Tổ chức

Gốc tổ chức và công ty (MST), mẫu công ty mới, bàn giao, xoá công ty có hai người duyệt, đồng bộ hồ sơ từ nguồn MST.

Endpoint

Method	Path	Tóm tắt	Quyền	Nhóm tốc độ	Tương tác
GET	/v1/access-grants	Danh sách quyền truy cập chéo	tenant.manage	read	Scalar
POST	/v1/access-grants	Đề xuất quyền truy cập chéo	tenant.manage	write	Scalar
POST	/v1/access-grants/{id}:activate	Kích hoạt quyền truy cập chéo	tenant.manage	write	Scalar
POST	/v1/access-grants/{id}:revoke	Thu hồi quyền truy cập chéo	tenant.manage	write	Scalar
GET	/v1/org-templates	Danh sách mẫu công ty	tenant.manage	read	Scalar
POST	/v1/org-templates	Tạo mẫu công ty	tenant.manage	write	Scalar
GET	/v1/orgs	Danh sách công ty	org.read	read	Scalar
POST	/v1/orgs	Thêm công ty theo mã số thuế	company.create	write	Scalar
GET	/v1/orgs/{id}	Chi tiết công ty	org.read	read	Scalar
PATCH	/v1/orgs/{id}	Sửa hồ sơ công ty	org.write	write	Scalar
POST	/v1/orgs/{id}:delete-cancel	Huỷ yêu cầu xoá công ty	company.delete_request	write	Scalar
POST	/v1/orgs/{id}:delete-confirm	Xác nhận xoá công ty	company.delete_confirm	write	Scalar
POST	/v1/orgs/{id}:delete-request	Yêu cầu xoá công ty	company.delete_request	write	Scalar
POST	/v1/orgs/{id}:resync-mst	Đồng bộ lại hồ sơ từ mã số thuế	org.write	write	Scalar
POST	/v1/orgs/{id}:transfer-ownership	Bàn giao công ty cho khách hàng	company.transfer_ownership	write	Scalar

Chi tiết endpoint

GET /v1/access-grants

Danh sách quyền truy cập chéo

Cả hai phía: quyền đã cấp (given, người gọi là bên cấp) và quyền được nhận (received, người gọi là bên nhận), mới nhất trước. direction và status thu hẹp kết quả.

Quyền: tenant.manage

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách quyền truy cập. — AccessGrantList, 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.
status	query	Không	AccessGrantStatus	pending: chờ bên kia kích hoạt; active: đang hiệu lực (trừ khi expires_at đã qua); revoked: đã thu hồi, không khôi phục.
direction	query	Không	AccessGrantDirection	given: người gọi là bên cấp (dữ liệu của họ được chia sẻ); received: người gọi là bên nhận (văn phòng kế toán).

curl

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

TypeScript

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

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

const { data } = await dt.GET("/v1/access-grants");

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import list_access_grants

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

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

POST /v1/access-grants

Đề xuất quyền truy cập chéo

Cần xác thực lại gần đây. Bên cấp hoặc bên nhận đều đề xuất được; quyền ở trạng thái pending tới khi bên còn lại kích hoạt. Người gọi không thuộc phía nào, hoặc bên cấp không tồn tại: 404. Đã có quyền chưa thu hồi cho cùng cặp (bên cấp, bên nhận): 409 conflict. expires_at đã qua hoặc vai trò owner: 422.

Quyền: tenant.manage Cần xác thực lại gần đây

• Nhóm tốc độ: write
• Nội dung yêu cầu: ProposeAccessGrant (application/json, bắt buộc)
• Phản hồi thành công 201: Đã đề xuất. — AccessGrant, application/json
• Mã lỗi riêng của endpoint: step_up_required, conflict

curl

curl -sS -X POST "https://api.dongtien.pro/v1/access-grants" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "grantor_org_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "grantee_root_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "role_key": "admin",
  "expires_at": "2026-10-19T01:30:15Z"
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/access-grants", {
  body: {
    "grantor_org_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "grantee_root_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "role_key": "admin",
    "expires_at": "2026-10-19T01:30:15Z"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import propose_access_grant
from dongtien_api.models import ProposeAccessGrant

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = propose_access_grant.sync(
        client=dt.client,
        body=ProposeAccessGrant.from_dict({
            "grantor_org_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "grantee_root_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "role_key": "admin",
            "expires_at": "2026-10-19T01:30:15Z",
        }),
    )

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

POST /v1/access-grants/{id}:activate

Kích hoạt quyền truy cập chéo

Do bên KHÔNG đề xuất thực hiện, cần xác thực lại gần đây. Bên đề xuất tự kích hoạt: 403. Quyền không còn pending (đã kích hoạt, đã thu hồi) hoặc đã quá expires_at: 409 conflict. Không phải một bên của quyền: 404.

Quyền: tenant.manage Cần xác thực lại gần đây

• Nhóm tốc độ: write
• Phản hồi thành công 200: Quyền đang hiệu lực. — AccessGrant, application/json
• Mã lỗi riêng của endpoint: step_up_required, resource_not_found, conflict

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	AccessGrantId	Mã quyền truy cập chéo (grt_…).

curl

curl -sS -X POST "https://api.dongtien.pro/v1/access-grants/$ID:activate" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

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

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

const { data } = await dt.POST("/v1/access-grants/{id}:activate", {
  params: {
    path: { "id": "grt_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import activate_access_grant

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

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

POST /v1/access-grants/{id}:revoke

Thu hồi quyền truy cập chéo

Cả hai bên đều thu hồi được, bất cứ lúc nào, cần xác thực lại gần đây; có hiệu lực ở yêu cầu kế tiếp và không khôi phục (muốn cấp lại, đề xuất quyền mới). Đã thu hồi rồi: 409 conflict. Không phải một bên của quyền: 404.

Quyền: tenant.manage Cần xác thực lại gần đây

• Nhóm tốc độ: write
• Phản hồi thành công 200: Quyền đã thu hồi. — AccessGrant, application/json
• Mã lỗi riêng của endpoint: step_up_required, resource_not_found, conflict

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	AccessGrantId	Mã quyền truy cập chéo (grt_…).

curl

curl -sS -X POST "https://api.dongtien.pro/v1/access-grants/$ID:revoke" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

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

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

const { data } = await dt.POST("/v1/access-grants/{id}:revoke", {
  params: {
    path: { "id": "grt_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import revoke_access_grant

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

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

GET /v1/org-templates

Danh sách mẫu công ty

Mẫu thuộc về nút gốc, nên chỉ người giữ nút gốc (phạm vi all) quản lý được. Không phân trang.

Quyền: tenant.manage

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách mẫu. — OrgTemplateList, application/json
• Mã lỗi: chỉ các mã lỗi chung ở Tổng quan

curl

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

TypeScript

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

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

const { data } = await dt.GET("/v1/org-templates");

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import list_org_templates

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

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

POST /v1/org-templates

Tạo mẫu công ty

Quyền: tenant.manage

• Nhóm tốc độ: write
• Nội dung yêu cầu: CreateOrgTemplate (application/json, bắt buộc)
• Phản hồi thành công 201: Đã tạo. — OrgTemplate, application/json
• Mã lỗi riêng của endpoint: conflict

curl

curl -sS -X POST "https://api.dongtien.pro/v1/org-templates" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "Công ty dịch vụ",
  "coa_profile": "TT133",
  "default_role": "accountant",
  "require_2fa_days": 7,
  "is_default": false
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/org-templates", {
  body: {
    "name": "Công ty dịch vụ",
    "coa_profile": "TT133",
    "default_role": "accountant",
    "require_2fa_days": 7,
    "is_default": false
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import create_org_template
from dongtien_api.models import CreateOrgTemplate

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = create_org_template.sync(
        client=dt.client,
        body=CreateOrgTemplate.from_dict({
            "name": "Công ty dịch vụ",
            "coa_profile": "TT133",
            "default_role": "accountant",
            "require_2fa_days": 7,
            "is_default": False,
        }),
    )

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

GET /v1/orgs

Danh sách công ty

Các công ty (và nút gốc) trong phạm vi của thông tin xác thực. Không phân trang: luôn trả đủ, has_more luôn false.

Quyền: org.read Scope: mcp:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Danh sách tổ chức. — OrgList, application/json
• Mã lỗi: chỉ các mã lỗi chung ở Tổng quan

curl

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

TypeScript

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

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

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import list_orgs

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

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

POST /v1/orgs

Thêm công ty theo mã số thuế

Tra cứu mã số thuế để điền tên pháp lý, địa chỉ, người đại diện. Người dùng chưa có tổ chức: hệ thống tạo luôn nút gốc và gán họ làm chủ sở hữu. Nguồn MST lỗi không chặn việc tạo (cần gửi name).

Quyền: company.create

• Nhóm tốc độ: write
• Nội dung yêu cầu: CreateOrg (application/json, bắt buộc)
• Phản hồi thành công 201: Đã tạo. — CreateOrgResult, application/json
• Mã lỗi riêng của endpoint: conflict

curl

curl -sS -X POST "https://api.dongtien.pro/v1/orgs" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "parent_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "mst": "0100109106",
  "alert_email": "ketoan@congty.vn"
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/orgs", {
  body: {
    "parent_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "mst": "0100109106",
    "alert_email": "ketoan@congty.vn"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import create_org
from dongtien_api.models import CreateOrg

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = create_org.sync(
        client=dt.client,
        body=CreateOrg.from_dict({
            "parent_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "mst": "0100109106",
            "alert_email": "ketoan@congty.vn",
        }),
    )

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

GET /v1/orgs/{id}

Chi tiết công ty

Quyền: org.read Scope: mcp:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Tổ chức. — Org, 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ó	OrgId	Mã công ty / tổ chức (org_…).

curl

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

TypeScript

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

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

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import get_org

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

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

PATCH /v1/orgs/{id}

Sửa hồ sơ công ty

Đổi hệ thống tài khoản hoặc múi giờ được ghi nhật ký riêng (org.coa_change).

Quyền: org.write

• Nhóm tốc độ: write
• Nội dung yêu cầu: UpdateOrg (application/json, bắt buộc)
• Phản hồi thành công 200: Tổ chức sau cập nhật. — Org, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict

Tham số

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

curl

curl -sS -X PATCH "https://api.dongtien.pro/v1/orgs/$ID" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "alert_email": "ketoan@congty.vn",
  "coa_profile": "TT133"
}'

TypeScript

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

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

const { data } = await dt.PATCH("/v1/orgs/{id}", {
  params: {
    path: { "id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "alert_email": "ketoan@congty.vn",
    "coa_profile": "TT133"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import update_org
from dongtien_api.models import UpdateOrg

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = update_org.sync(
        id="org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=UpdateOrg.from_dict({
            "alert_email": "ketoan@congty.vn",
            "coa_profile": "TT133",
        }),
    )

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

POST /v1/orgs/{id}:delete-cancel

Huỷ yêu cầu xoá công ty

Chỉ người đã gửi yêu cầu được rút lại, khi yêu cầu còn chờ xác nhận. Không có yêu cầu đang chờ trả 404; yêu cầu vừa được xử lý xong trả 409 conflict. Phản hồi có state: withdrawn.

Quyền: company.delete_request

• Nhóm tốc độ: write
• Nội dung yêu cầu: CancelOrgDeletion (application/json)
• Phản hồi thành công 200: Yêu cầu đã rút lại. — OrgApproval, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict

Tham số

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

curl

curl -sS -X POST "https://api.dongtien.pro/v1/orgs/$ID:delete-cancel" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Gửi nhầm công ty."
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/orgs/{id}:delete-cancel", {
  params: {
    path: { "id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "reason": "Gửi nhầm công ty."
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import cancel_org_deletion
from dongtien_api.models import CancelOrgDeletion

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = cancel_org_deletion.sync(
        id="org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=CancelOrgDeletion.from_dict({
            "reason": "Gửi nhầm công ty.",
        }),
    )

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

POST /v1/orgs/{id}:delete-confirm

Xác nhận xoá công ty

Người xác nhận phải khác người yêu cầu. Công ty bị đóng băng 30 ngày (dữ liệu giữ nguyên) rồi mới xoá hẳn.

Quyền: company.delete_confirm

• Nhóm tốc độ: write
• Phản hồi thành công 200: Công ty đã đóng băng. — OrgApproval, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict

Tham số

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

curl

curl -sS -X POST "https://api.dongtien.pro/v1/orgs/$ID:delete-confirm" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

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

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

const { data } = await dt.POST("/v1/orgs/{id}:delete-confirm", {
  params: {
    path: { "id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import confirm_org_deletion

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

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

POST /v1/orgs/{id}:delete-request

Yêu cầu xoá công ty

Cần người thứ hai xác nhận (:delete-confirm). Chỉ công ty đang active; đã có yêu cầu đang chờ trả 409 conflict.

Quyền: company.delete_request

• Nhóm tốc độ: write
• Nội dung yêu cầu: DeleteOrgRequest (application/json)
• Phản hồi thành công 200: Yêu cầu đang chờ. — OrgApproval, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict

Tham số

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

curl

curl -sS -X POST "https://api.dongtien.pro/v1/orgs/$ID:delete-request" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Công ty đã giải thể."
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/orgs/{id}:delete-request", {
  params: {
    path: { "id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "reason": "Công ty đã giải thể."
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import request_org_deletion
from dongtien_api.models import DeleteOrgRequest

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = request_org_deletion.sync(
        id="org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=DeleteOrgRequest.from_dict({
            "reason": "Công ty đã giải thể.",
        }),
    )

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

POST /v1/orgs/{id}:resync-mst

Đồng bộ lại hồ sơ từ mã số thuế

Làm mới tên pháp lý, địa chỉ, người đại diện và tình trạng thuế của một công ty từ nguồn MST (tối đa một lần tra mới mỗi giờ cho mỗi mã). Nguồn lỗi hoặc không biết mã: giữ nguyên dữ liệu, mst_source.status cho biết lý do. Tên gọi trong hệ thống và tên hiển thị VietQR không bị đổi. Chỉ áp dụng cho công ty (không phải nút gốc).

Quyền: org.write Idempotency-Key: tuỳ chọn

• Nhóm tốc độ: write
• Phản hồi thành công 200: Kết quả đồng bộ. — ResyncOrgResult, application/json
• Mã lỗi riêng của endpoint: resource_not_found, conflict, idempotency_in_flight, idempotency_key_reused

Tham số

Tên	Vị trí	Bắt buộc	Kiểu	Mô tả
id	path	Có	OrgId	Mã công ty / tổ chức (org_…).
idempotency-key	header	Không	string	Khoá chống gửi trùng (≤ 255 ký tự, nên là UUID). Giữ 24 giờ; gửi lại cùng khoá + cùng nội dung trả lại kết quả cũ.

curl

curl -sS -X POST "https://api.dongtien.pro/v1/orgs/$ID:resync-mst" \
  -H "Authorization: Bearer $DT_API_KEY"

TypeScript

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

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

const { data } = await dt.POST("/v1/orgs/{id}:resync-mst", {
  params: {
    path: { "id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import resync_org_mst

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

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

POST /v1/orgs/{id}:transfer-ownership

Bàn giao công ty cho khách hàng

Chỉ chủ sở hữu, cần xác thực lại gần đây. Khách nhận lời mời làm chủ sở hữu và trở thành thành viên khi chấp nhận; phản hồi không tiết lộ email đã có tài khoản hay chưa.

Quyền: company.transfer_ownership Cần xác thực lại gần đây

• Nhóm tốc độ: write
• Nội dung yêu cầu: TransferOrg (application/json, bắt buộc)
• Phản hồi thành công 200: Tổ chức sau bàn giao. — Org, application/json
• Mã lỗi riêng của endpoint: step_up_required, resource_not_found, conflict

Tham số

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

curl

curl -sS -X POST "https://api.dongtien.pro/v1/orgs/$ID:transfer-ownership" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "customer_email": "chu@khach.example",
  "billing_payer": "customer",
  "isolation": "hard"
}'

TypeScript

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

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

const { data } = await dt.POST("/v1/orgs/{id}:transfer-ownership", {
  params: {
    path: { "id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0" },
  },
  body: {
    "customer_email": "chu@khach.example",
    "billing_payer": "customer",
    "isolation": "hard"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.to_chuc import transfer_org_ownership
from dongtien_api.models import TransferOrg

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = transfer_org_ownership.sync(
        id="org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
        client=dt.client,
        body=TransferOrg.from_dict({
            "customer_email": "chu@khach.example",
            "billing_payer": "customer",
            "isolation": "hard",
        }),
    )

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

Đối tượng

AccessGrantList

Trường	Kiểu	Bắt buộc	Mô tả
data	AccessGrant[]	Có	—
data[].created_at	Timestamp	Có	—
data[].decided_at	string | null	Có	Lần kích hoạt hoặc thu hồi gần nhất.
data[].direction	AccessGrantDirection	Có	Giá trị: given, received.
data[].expires_at	string | null	Có	Hết hiệu lực vào lúc này; null = không hết hạn.
data[].grantee_root_id	string	Có	Bên nhận: nút gốc của văn phòng kế toán.
data[].grantor_org_id	string	Có	Bên cấp: một công ty, hoặc nút gốc của khách (cấp cho mọi công ty của nút gốc đó).
data[].id	AccessGrantId	Có	—
data[].object	string	Có	Giá trị: access_grant.
data[].requested_by	string	Có	Bên đề xuất; bên còn lại là bên kích hoạt. Giá trị: grantor, grantee.
data[].revoked_at	Timestamp | null	Có	—
data[].role_key	string	Có	Vai trò bên nhận có tại công ty được cấp.
data[].status	AccessGrantStatus	Có	Giá trị: pending, active, revoked.
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.

ProposeAccessGrant

Trường	Kiểu	Bắt buộc	Mô tả
expires_at	string	Không	Thời điểm hết hạn, phải ở tương lai; bỏ trống = không hết hạn.
grantee_root_id	string	Có	Nút gốc của văn phòng kế toán nhận quyền.
grantor_org_id	string	Có	Công ty (hoặc nút gốc) của khách được cấp quyền. Bên cấp đề xuất: người gọi phải có phạm vi trùm nó; bên nhận đề xuất: người gọi thuộc grantee_root_id.
role_key	AccessGrantRole	Có	Giá trị: admin, accountant_chief, accountant, developer, viewer, auditor.

AccessGrant

Trường	Kiểu	Bắt buộc	Mô tả
created_at	Timestamp	Có	—
decided_at	string | null	Có	Lần kích hoạt hoặc thu hồi gần nhất.
direction	AccessGrantDirection	Có	Giá trị: given, received.
expires_at	string | null	Có	Hết hiệu lực vào lúc này; null = không hết hạn.
grantee_root_id	string	Có	Bên nhận: nút gốc của văn phòng kế toán.
grantor_org_id	string	Có	Bên cấp: một công ty, hoặc nút gốc của khách (cấp cho mọi công ty của nút gốc đó).
id	AccessGrantId	Có	—
object	string	Có	Giá trị: access_grant.
requested_by	string	Có	Bên đề xuất; bên còn lại là bên kích hoạt. Giá trị: grantor, grantee.
revoked_at	Timestamp | null	Có	—
role_key	string	Có	Vai trò bên nhận có tại công ty được cấp.
status	AccessGrantStatus	Có	Giá trị: pending, active, revoked.

OrgTemplateList

Trường	Kiểu	Bắt buộc	Mô tả
data	OrgTemplate[]	Có	—
data[].coa_profile	string	Có	Hệ thống tài khoản mà công ty mới bắt đầu với: TT133 hoặc TT99.
data[].created_at	Timestamp	Có	—
data[].default_role	string	Có	Vai trò mặc định khi mời kế toán vào công ty tạo từ mẫu.
data[].id	string (uuid)	Có	UUID: mẫu công ty chưa có tiền tố mã công khai.
data[].is_default	boolean	Có	—
data[].name	string	Có	—
data[].require_2fa_days	integer	Có	Số ngày ân hạn trước khi bắt buộc xác thực hai lớp.
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.

CreateOrgTemplate

Trường	Kiểu	Bắt buộc	Mô tả
coa_profile	string	Không	Giá trị: TT133, TT99.
default_role	string	Không	Giá trị: owner, admin, accountant_chief, accountant, developer, viewer, auditor.
is_default	boolean	Không	—
name	string	Có	—
require_2fa_days	integer	Không	—

OrgTemplate

Trường	Kiểu	Bắt buộc	Mô tả
coa_profile	string	Có	Hệ thống tài khoản mà công ty mới bắt đầu với: TT133 hoặc TT99.
created_at	Timestamp	Có	—
default_role	string	Có	Vai trò mặc định khi mời kế toán vào công ty tạo từ mẫu.
id	string (uuid)	Có	UUID: mẫu công ty chưa có tiền tố mã công khai.
is_default	boolean	Có	—
name	string	Có	—
require_2fa_days	integer	Có	Số ngày ân hạn trước khi bắt buộc xác thực hai lớp.

OrgList

Trường	Kiểu	Bắt buộc	Mô tả
data	Org[]	Có	—
data[].address	string | null	Có	—
data[].alert_email	string (email) | null	Có	Email nhận cảnh báo kênh / tiền vào của công ty. Để trống: gửi tới các chủ sở hữu.
data[].billing_payer	string	Có	Bên trả phí: văn phòng kế toán hoặc khách hàng. Giá trị: firm, customer.
data[].coa_profile	string	Có	Hệ thống tài khoản kế toán: Thông tư 133 hoặc 99. Giá trị: TT133, TT99.
data[].created_at	Timestamp	Có	—
data[].delete_after	string | null	Có	Thời điểm công ty bị đóng băng sẽ được xoá hẳn.
data[].display_name	string | null	Có	Tên hiển thị trên mã VietQR: chữ in hoa không dấu, tối đa 25 ký tự.
data[].entity_type	string | null	Có	—
data[].fiscal_year_start	string	Có	Ngày bắt đầu năm tài chính MM-DD.
data[].id	OrgId	Có	—
data[].is_accounting_firm	boolean	Có	—
data[].isolation	string	Có	hard: dữ liệu tách hẳn, văn phòng chỉ vào được khi được chỉ định rõ. Giá trị: hard, consolidate.
data[].kind	string	Có	root (văn phòng kế toán / doanh nghiệp) hoặc company (một mã số thuế).
data[].legal_name	string | null	Có	Tên pháp lý theo nguồn MST.
data[].legal_rep	string | null	Có	Người đại diện pháp luật.
data[].mst	string | null	Có	Mã số thuế (10 hoặc 13 số, không có dấu gạch).
data[].mst_synced_at	string | null	Có	Lần cuối đồng bộ hồ sơ pháp lý từ nguồn MST; null nếu chưa từng.
data[].name	string	Có	Tên gọi trong hệ thống.
data[].parent_id	string | null	Có	Tổ chức gốc chứa công ty; null với root.
data[].role	string | null	Có	Vai trò của người gọi tại nút này (người dùng và OAuth); null với khoá API.
data[].root_id	OrgId	Có	—
data[].status	string	Có	active, suspended, frozen (đang chờ xoá) hoặc deleted.
data[].tax_status	string	Có	Tình trạng thuế theo nguồn MST: active, suspended, closed hoặc unknown.
data[].timezone	string	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.

CreateOrg

Trường	Kiểu	Bắt buộc	Mô tả
alert_email	string (email)	Không	Email nhận cảnh báo kênh / tiền vào của công ty. Để trống: gửi tới các chủ sở hữu.
display_name	string	Không	Tên hiển thị trên VietQR; mặc định suy ra từ tên pháp lý.
is_accounting_firm	boolean	Không	Áp dụng khi lời gọi này tạo nút gốc (lần đầu sử dụng).
mst	string	Có	Mã số thuế, 10 số hoặc 10 số + -NNN.
name	string	Không	Chỉ bắt buộc khi nguồn MST không trả được tên pháp lý.
parent_id	string	Không	Nút gốc để thêm công ty vào; mặc định là nút gốc của người gọi. Người dùng mới chưa có tổ chức: bỏ trống, hệ thống tạo nút gốc.
template_id	string (uuid)	Không	Mã mẫu từ GET /v1/org-templates; mặc định là mẫu mặc định của nút gốc.

CreateOrgResult

Trường	Kiểu	Bắt buộc	Mô tả
company	Org	Có	—
company.address	string | null	Có	—
company.alert_email	string (email) | null	Có	Email nhận cảnh báo kênh / tiền vào của công ty. Để trống: gửi tới các chủ sở hữu.
company.billing_payer	string	Có	Bên trả phí: văn phòng kế toán hoặc khách hàng. Giá trị: firm, customer.
company.coa_profile	string	Có	Hệ thống tài khoản kế toán: Thông tư 133 hoặc 99. Giá trị: TT133, TT99.
company.created_at	Timestamp	Có	—
company.delete_after	string | null	Có	Thời điểm công ty bị đóng băng sẽ được xoá hẳn.
company.display_name	string | null	Có	Tên hiển thị trên mã VietQR: chữ in hoa không dấu, tối đa 25 ký tự.
company.entity_type	string | null	Có	—
company.fiscal_year_start	string	Có	Ngày bắt đầu năm tài chính MM-DD.
company.id	OrgId	Có	—
company.is_accounting_firm	boolean	Có	—
company.isolation	string	Có	hard: dữ liệu tách hẳn, văn phòng chỉ vào được khi được chỉ định rõ. Giá trị: hard, consolidate.
company.kind	string	Có	root (văn phòng kế toán / doanh nghiệp) hoặc company (một mã số thuế).
company.legal_name	string | null	Có	Tên pháp lý theo nguồn MST.
company.legal_rep	string | null	Có	Người đại diện pháp luật.
company.mst	string | null	Có	Mã số thuế (10 hoặc 13 số, không có dấu gạch).
company.mst_synced_at	string | null	Có	Lần cuối đồng bộ hồ sơ pháp lý từ nguồn MST; null nếu chưa từng.
company.name	string	Có	Tên gọi trong hệ thống.
company.parent_id	string | null	Có	Tổ chức gốc chứa công ty; null với root.
company.role	string | null	Có	Vai trò của người gọi tại nút này (người dùng và OAuth); null với khoá API.
company.root_id	OrgId	Có	—
company.status	string	Có	active, suspended, frozen (đang chờ xoá) hoặc deleted.
company.tax_status	string	Có	Tình trạng thuế theo nguồn MST: active, suspended, closed hoặc unknown.
company.timezone	string	Có	—
mst_source	MstSource	Có	—
mst_source.checksum_ok	boolean	Có	Chữ số kiểm tra của mã số thuế hợp lệ (chỉ là cảnh báo).
mst_source.stale	boolean	Có	true: dữ liệu là bản đã lưu lần trước vì nguồn đang lỗi.
mst_source.status	string	Có	found: có dữ liệu; unavailable: nguồn MST không trả lời; not_found: nguồn không biết mã số thuế này. Giá trị: found, unavailable, not_found.
root	object | null	Có	Nút gốc vừa được tạo (lần đầu sử dụng); null nếu đã có.
root.address	string | null	Có	—
root.alert_email	string (email) | null	Có	Email nhận cảnh báo kênh / tiền vào của công ty. Để trống: gửi tới các chủ sở hữu.
root.billing_payer	string	Có	Bên trả phí: văn phòng kế toán hoặc khách hàng. Giá trị: firm, customer.
root.coa_profile	string	Có	Hệ thống tài khoản kế toán: Thông tư 133 hoặc 99. Giá trị: TT133, TT99.
root.created_at	Timestamp	Có	—
root.delete_after	string | null	Có	Thời điểm công ty bị đóng băng sẽ được xoá hẳn.
root.display_name	string | null	Có	Tên hiển thị trên mã VietQR: chữ in hoa không dấu, tối đa 25 ký tự.
root.entity_type	string | null	Có	—
root.fiscal_year_start	string	Có	Ngày bắt đầu năm tài chính MM-DD.
root.id	OrgId	Có	—
root.is_accounting_firm	boolean	Có	—
root.isolation	string	Có	hard: dữ liệu tách hẳn, văn phòng chỉ vào được khi được chỉ định rõ. Giá trị: hard, consolidate.
root.kind	string	Có	root (văn phòng kế toán / doanh nghiệp) hoặc company (một mã số thuế).
root.legal_name	string | null	Có	Tên pháp lý theo nguồn MST.
root.legal_rep	string | null	Có	Người đại diện pháp luật.
root.mst	string | null	Có	Mã số thuế (10 hoặc 13 số, không có dấu gạch).
root.mst_synced_at	string | null	Có	Lần cuối đồng bộ hồ sơ pháp lý từ nguồn MST; null nếu chưa từng.
root.name	string	Có	Tên gọi trong hệ thống.
root.parent_id	string | null	Có	Tổ chức gốc chứa công ty; null với root.
root.role	string | null	Có	Vai trò của người gọi tại nút này (người dùng và OAuth); null với khoá API.
root.root_id	OrgId	Có	—
root.status	string	Có	active, suspended, frozen (đang chờ xoá) hoặc deleted.
root.tax_status	string	Có	Tình trạng thuế theo nguồn MST: active, suspended, closed hoặc unknown.
root.timezone	string	Có	—
warnings	string[]	Có	Cảnh báo không chặn: mst_checksum_failed, mst_lookup_unavailable, mst_not_found_at_source, tax_status_not_active.

Org

Trường	Kiểu	Bắt buộc	Mô tả
address	string | null	Có	—
alert_email	string (email) | null	Có	Email nhận cảnh báo kênh / tiền vào của công ty. Để trống: gửi tới các chủ sở hữu.
billing_payer	string	Có	Bên trả phí: văn phòng kế toán hoặc khách hàng. Giá trị: firm, customer.
coa_profile	string	Có	Hệ thống tài khoản kế toán: Thông tư 133 hoặc 99. Giá trị: TT133, TT99.
created_at	Timestamp	Có	—
delete_after	string | null	Có	Thời điểm công ty bị đóng băng sẽ được xoá hẳn.
display_name	string | null	Có	Tên hiển thị trên mã VietQR: chữ in hoa không dấu, tối đa 25 ký tự.
entity_type	string | null	Có	—
fiscal_year_start	string	Có	Ngày bắt đầu năm tài chính MM-DD.
id	OrgId	Có	—
is_accounting_firm	boolean	Có	—
isolation	string	Có	hard: dữ liệu tách hẳn, văn phòng chỉ vào được khi được chỉ định rõ. Giá trị: hard, consolidate.
kind	string	Có	root (văn phòng kế toán / doanh nghiệp) hoặc company (một mã số thuế).
legal_name	string | null	Có	Tên pháp lý theo nguồn MST.
legal_rep	string | null	Có	Người đại diện pháp luật.
mst	string | null	Có	Mã số thuế (10 hoặc 13 số, không có dấu gạch).
mst_synced_at	string | null	Có	Lần cuối đồng bộ hồ sơ pháp lý từ nguồn MST; null nếu chưa từng.
name	string	Có	Tên gọi trong hệ thống.
parent_id	string | null	Có	Tổ chức gốc chứa công ty; null với root.
role	string | null	Có	Vai trò của người gọi tại nút này (người dùng và OAuth); null với khoá API.
root_id	OrgId	Có	—
status	string	Có	active, suspended, frozen (đang chờ xoá) hoặc deleted.
tax_status	string	Có	Tình trạng thuế theo nguồn MST: active, suspended, closed hoặc unknown.
timezone	string	Có	—

UpdateOrg

Trường	Kiểu	Bắt buộc	Mô tả
address	string | null	Không	—
alert_email	string (email) | null	Không	null xoá email cảnh báo.
coa_profile	string	Không	Giá trị: TT133, TT99.
display_name	string	Không	—
fiscal_year_start	string	Không	—
is_accounting_firm	boolean	Không	—
legal_rep	string | null	Không	—
name	string	Không	—
timezone	string	Không	—

CancelOrgDeletion

Trường	Kiểu	Bắt buộc	Mô tả
reason	string	Không	Lý do huỷ yêu cầu.

Đối tượng khác của nhóm này (xem tài liệu tương tác): OrgApproval, DeleteOrgRequest, ResyncOrgResult, TransferOrg