Danh tính

~12 phút đọc

Người gọi là ai, đang làm việc ở tổ chức nào, tra cứu MST, tiến độ làm quen và phiên đăng nhập.

Endpoint

Method	Path	Tóm tắt	Quyền	Nhóm tốc độ	Tương tác
`GET`	`/v1/lookup/mst/{mst}`	Tra cứu doanh nghiệp theo mã số thuế	`org.read`	`read`	Scalar
`GET`	`/v1/me`	Người gọi, các công ty và chế độ chạy	`Mọi khoá hợp lệ`	`read`	Scalar
`POST`	`/v1/me/root:switch`	Chuyển gốc tổ chức của phiên	`Mọi khoá hợp lệ`	`write`	Scalar
`GET`	`/v1/me/roots`	Các gốc tổ chức của người dùng	`Mọi khoá hợp lệ`	`read`	Scalar
`GET`	`/v1/onboarding`	Tiến độ làm quen đã lưu	`Mọi khoá hợp lệ`	`read`	Scalar
`PUT`	`/v1/onboarding`	Lưu tiến độ làm quen	`Mọi khoá hợp lệ`	`write`	Scalar
`GET`	`/v1/sessions`	Các phiên đăng nhập của tôi	`Mọi khoá hợp lệ`	`read`	Scalar
`DELETE`	`/v1/sessions/{id}`	Đăng xuất một phiên	`Mọi khoá hợp lệ`	`write`	Scalar
`POST`	`/v1/sessions:revoke-others`	Đăng xuất mọi nơi trừ phiên này	`Mọi khoá hợp lệ`	`write`	Scalar

Chi tiết endpoint

`GET /v1/lookup/mst/{mst}`

Tra cứu doanh nghiệp theo mã số thuế

Dữ liệu được lưu đệm 24 giờ; khi nguồn tra cứu lỗi trả bản đã lưu với stale: true, không có bản lưu thì 503. MST không tồn tại trả 404, sai định dạng trả 422. Chỉ cho người dùng đăng nhập (kể cả người chưa có tổ chức, ở bước làm quen).

Quyền: org.read

Nhóm tốc độ: read
Phản hồi thành công 200: Doanh nghiệp. — MstLookup, 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ả
`mst`	path	Có	`string`	Mã số thuế 10 số, có thể kèm `-NNN`.

curl -sS -X GET "https://api.dongtien.pro/v1/lookup/mst/$MST" \
  -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/lookup/mst/{mst}", {
  params: {
    path: { "mst": "<mst>" },
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.danh_tinh import lookup_mst

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

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

`GET /v1/me`

Người gọi, các công ty và chế độ chạy

Mọi thông tin xác thực hợp lệ đều gọi được. companies chỉ liệt kê những công ty thông tin xác thực này truy cập được; mode là sandbox với khoá dt_test_.

Quyền: Mọi khoá hợp lệ

Nhóm tốc độ: read
Phản hồi thành công 200: Người gọi. — Me, application/json
Mã lỗi: chỉ các mã lỗi chung ở Tổng quan

curl -sS -X GET "https://api.dongtien.pro/v1/me" \
  -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/me");

import os

from dongtien import DongTien
from dongtien_api.api.danh_tinh import get_me

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

Xem người gọi và công ty.

dtp whoami --json

Công cụ whoami, không cần scope.

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

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

`POST /v1/me/root:switch`

Chuyển gốc tổ chức của phiên

Đổi gốc tổ chức mà phiên đăng nhập này làm việc; các phiên khác không đổi và hiệu lực từ yêu cầu kế tiếp. Gốc người dùng không thuộc về trả 404 resource_not_found (không phân biệt với gốc không tồn tại). Có ghi nhật ký kiểm toán session.root_switch tại gốc đích. Chỉ cho người dùng đăng nhập.

Quyền: Mọi khoá hợp lệ

Nhóm tốc độ: write
Nội dung yêu cầu: SwitchRoot (application/json, bắt buộc)
Phản hồi thành công 200: Gốc phiên đang làm việc sau khi đổi. — MeRoot, application/json
Mã lỗi riêng của endpoint: conflict

curl -sS -X POST "https://api.dongtien.pro/v1/me/root:switch" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "root_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0"
}'

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

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

const { data } = await dt.POST("/v1/me/root:switch", {
  body: {
    "root_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0"
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.danh_tinh import switch_root
from dongtien_api.models import SwitchRoot

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

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

`GET /v1/me/roots`

Các gốc tổ chức của người dùng

Mọi gốc tổ chức mà người dùng đang đăng nhập thuộc về (lâu nhất trước), kèm gốc phiên đang làm việc (active). Chỉ cho người dùng đăng nhập, không dùng với khoá API hay OAuth. Không phân trang.

Quyền: Mọi khoá hợp lệ

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

curl -sS -X GET "https://api.dongtien.pro/v1/me/roots" \
  -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/me/roots");

import os

from dongtien import DongTien
from dongtien_api.api.danh_tinh import list_me_roots

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

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

`GET /v1/onboarding`

Tiến độ làm quen đã lưu

Quyền: Mọi khoá hợp lệ

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

curl -sS -X GET "https://api.dongtien.pro/v1/onboarding" \
  -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/onboarding");

import os

from dongtien import DongTien
from dongtien_api.api.danh_tinh import get_onboarding_draft

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

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

`PUT /v1/onboarding`

Lưu tiến độ làm quen

Chỉ cho người dùng đăng nhập, chỉ ghi được bản nháp của chính mình.

Quyền: Mọi khoá hợp lệ

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

curl -sS -X PUT "https://api.dongtien.pro/v1/onboarding" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "step": "b2",
  "data": {
    "mst": "0100109106",
    "display_name": "CONG TY ABC"
  }
}'

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

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

const { data } = await dt.PUT("/v1/onboarding", {
  body: {
    "step": "b2",
    "data": {
      "mst": "0100109106",
      "display_name": "CONG TY ABC"
    }
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.danh_tinh import save_onboarding_draft
from dongtien_api.models import SaveOnboardingDraft

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = save_onboarding_draft.sync(
        client=dt.client,
        body=SaveOnboardingDraft.from_dict({
            "step": "b2",
            "data": {
                "mst": "0100109106",
                "display_name": "CONG TY ABC",
            },
        }),
    )

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

`GET /v1/sessions`

Các phiên đăng nhập của tôi

Hoạt động gần nhất trước. Chỉ cho người dùng đăng nhập. Không phân trang.

Quyền: Mọi khoá hợp lệ

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

curl -sS -X GET "https://api.dongtien.pro/v1/sessions" \
  -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/sessions");

import os

from dongtien import DongTien
from dongtien_api.api.danh_tinh import list_sessions

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

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

`DELETE /v1/sessions/{id}`

Đăng xuất một phiên

Xoá phiên ngay: yêu cầu kế tiếp của phiên đó bị từ chối. Phiên của người khác hoặc không tồn tại đều trả 404.

Quyền: Mọi khoá hợp lệ

Nhóm tốc độ: write
Phản hồi thành công 204: Đã đăng xuất. — không có nội dung
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ó	`string`	—

curl -sS -X DELETE "https://api.dongtien.pro/v1/sessions/$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.DELETE("/v1/sessions/{id}", {
  params: {
    path: { "id": "<id>" },
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.danh_tinh import revoke_session

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

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

`POST /v1/sessions:revoke-others`

Đăng xuất mọi nơi trừ phiên này

Quyền: Mọi khoá hợp lệ

Nhóm tốc độ: write
Phản hồi thành công 200: Số phiên đã kết thúc. — RevokeOtherSessionsResult, application/json
Mã lỗi riêng của endpoint: conflict

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

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

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

const { data } = await dt.POST("/v1/sessions:revoke-others");

import os

from dongtien import DongTien
from dongtien_api.api.danh_tinh import revoke_other_sessions

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

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

Đối tượng

`MstLookup`

Trường	Kiểu	Bắt buộc	Mô tả
`checksum_ok`	`boolean`	Có	Chữ số kiểm tra chỉ mang tính tham khảo: MST sai checksum vẫn được tra cứu.
`company`	`object`	Có	—
`company.active`	`boolean`	Có	—
`company.address`	`string \| null`	Có	—
`company.legal_name`	`string`	Có	—
`company.legal_rep`	`string \| null`	Có	—
`company.short_name`	`string \| null`	Có	—
`company.status_code`	`string \| null`	Có	—
`company.status_label`	`string \| null`	Có	—
`company.tax_code`	`string`	Có	—
`fetched_at`	`string`	Có	Thời điểm lấy bản sao này.
`mst`	`string`	Có	Mã số thuế dạng chuẩn.
`source`	`string`	Có	Nguồn: bộ nhớ đệm, nguồn MST hoặc bản đã lưu. Giá trị: `kv`, `api`, `store`.
`stale`	`boolean`	Có	`true` khi nguồn đang lỗi và đây là bản đã lưu.
`stale_reason`	`string`	Không	—

`Me`

Trường	Kiểu	Bắt buộc	Mô tả
`active_root_id`	`string \| null`	Có	Gốc tổ chức phiên đang làm việc (đổi bằng `POST /v1/me/root:switch`); `null` khi chưa có tổ chức.
`companies`	`MeCompany[]`	Có	—
`companies[].id`	`OrgId`	Có	—
`companies[].kind`	`string`	Có	Giá trị: `root`, `company`.
`companies[].mst`	`string \| null`	Có	—
`companies[].name`	`string`	Có	—
`companies[].role`	`string \| null`	Có	Vai trò của người gọi tại công ty này (người dùng, OAuth); `null` với khoá API (khoá dùng phạm vi, không dùng vai trò).
`flags`	`map<string, boolean>`	Có	Cờ tính năng đang bật cho người gọi (tên → `true`/`false`). Chỉ để giao diện ẩn/hiện; máy chủ vẫn kiểm quyền ở mỗi yêu cầu.
`impersonation`	`object`	Không	Chỉ có khi người gọi là nhân viên hỗ trợ đang xem hộ khách hàng.
`impersonation.ends_at`	`string`	Có	Thời điểm phiên hỗ trợ kết thúc (RFC 3339, UTC).
`impersonation.scope`	`string`	Có	Phiên hỗ trợ luôn chỉ-đọc. Giá trị: `read_only`.
`impersonation.ticket`	`string`	Có	Phiếu hỗ trợ đã mở phiên (`SUP-nnnn`).
`mode`	`string`	Có	Giá trị: `live`, `sandbox`.
`mst`	`string \| null`	Có	—
`org`	`object \| null`	Có	—
`org.id`	`OrgId`	Có	—
`org.mst`	`string \| null`	Có	—
`org.name`	`string`	Có	—
`principal`	`MePrincipal`	Có	—
`principal.client_id`	`string \| null`	Có	—
`principal.id`	`string`	Có	`usr_…` của người dùng hoặc `apk_…` của khoá API (mã cấp quyền với OAuth).
`principal.key_env`	`string \| null`	Có	Giá trị: `live`, `test`.
`principal.session_id`	`string \| null`	Có	—
`principal.type`	`string`	Có	Giá trị: `user`, `api_key`, `oauth`, `impersonation`.
`principal.user_id`	`string \| null`	Có	Người đứng sau thông tin xác thực (người tạo khoá, người cấp quyền OAuth).
`scopes`	`string[]`	Có	—

`SwitchRoot`

Trường	Kiểu	Bắt buộc	Mô tả
`root_id`	`string`	Có	Gốc tổ chức muốn chuyển sang.

`MeRoot`

Trường	Kiểu	Bắt buộc	Mô tả
`active`	`boolean`	Có	Đây là gốc phiên hiện tại đang làm việc.
`first_joined_at`	`Timestamp`	Có	—
`has_root_node`	`boolean`	Có	Có thành viên ở chính nút gốc (`false`: khách hàng chỉ sở hữu một công ty).
`id`	`string`	Có	Mã gốc tổ chức.
`is_accounting_firm`	`boolean`	Có	Gốc là hãng kế toán (quản lý nhiều khách hàng).
`name`	`string`	Có	—
`role_key`	`string`	Có	Vai trò tốt nhất của người dùng tại gốc này.

`MeRootList`

Trường	Kiểu	Bắt buộc	Mô tả
`data`	`MeRoot[]`	Có	—
`data[].active`	`boolean`	Có	Đây là gốc phiên hiện tại đang làm việc.
`data[].first_joined_at`	`Timestamp`	Có	—
`data[].has_root_node`	`boolean`	Có	Có thành viên ở chính nút gốc (`false`: khách hàng chỉ sở hữu một công ty).
`data[].id`	`string`	Có	Mã gốc tổ chức.
`data[].is_accounting_firm`	`boolean`	Có	Gốc là hãng kế toán (quản lý nhiều khách hàng).
`data[].name`	`string`	Có	—
`data[].role_key`	`string`	Có	Vai trò tốt nhất của người dùng tại gốc này.
`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`.

`OnboardingDraft`

Trường	Kiểu	Bắt buộc	Mô tả
`data`	`map<string, any>`	Có	—
`step`	`string`	Có	Giá trị: `b1`, `b2`, `done`.
`updated_at`	`Timestamp \| null`	Có	—

`SaveOnboardingDraft`

Trường	Kiểu	Bắt buộc	Mô tả
`data`	`map<string, any>`	Có	Không đặt mật khẩu hay token ở đây; tối đa 64 KB.
`step`	`string`	Có	Giá trị: `b1`, `b2`, `done`.

`SessionList`

Trường	Kiểu	Bắt buộc	Mô tả
`data`	`Session[]`	Có	—
`data[].created_at`	`Timestamp`	Có	—
`data[].current`	`boolean`	Có	Phiên đang gửi yêu cầu này.
`data[].id`	`string`	Có	—
`data[].ip`	`string \| null`	Có	—
`data[].last_seen_at`	`Timestamp`	Có	—
`data[].mfa_at`	`string \| null`	Có	Lần qua bước xác thực hai yếu tố của phiên.
`data[].step_up_at`	`string \| null`	Có	Lần xác thực lại gần nhất (step-up).
`data[].user_agent`	`string \| null`	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`.

`RevokeOtherSessionsResult`

Trường	Kiểu	Bắt buộc	Mô tả
`revoked`	`integer`	Có	—