Nhật ký kiểm toán

Chuỗi nhật ký kiểm toán chỉ-thêm, tra cứu và xuất CSV.

Endpoint

Method	Path	Tóm tắt	Quyền	Nhóm tốc độ	Tương tác
GET	/v1/audit-events	Danh sách nhật ký kiểm toán (mới nhất trước)	audit.read	read	Scalar
GET	/v1/audit-events/{id}	Chi tiết một dòng nhật ký kiểm toán	audit.read	read	Scalar
POST	/v1/audit-events:export	Xuất nhật ký kiểm toán ra CSV	audit.export	export	Scalar

Chi tiết endpoint

GET /v1/audit-events

Danh sách nhật ký kiểm toán (mới nhất trước)

Phân trang theo con trỏ. actor lọc theo chủ thể: usr_… (người dùng), apk_… (khoá API) hoặc system. Công ty không thuộc phạm vi người gọi → 404.

Quyền: audit.read Scope: audit:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Trang nhật ký. — AuditEventList, 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_…).
actor	query	Không	string	Lọc theo chủ thể: usr_…, apk_… hoặc system.
action	query	Không	string	Lọc theo hành động, vd. apikey.revoke.
object_type	query	Không	string	—
object_id	query	Không	string	—
from	query	Không	string (date-time)	Từ thời điểm (bao gồm).
to	query	Không	string (date-time)	Đến thời điểm (không bao gồm).

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhat_ky_kiem_toan import list_audit_events

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

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

GET /v1/audit-events/{id}

Chi tiết một dòng nhật ký kiểm toán

Quyền: audit.read Scope: audit:read

• Nhóm tốc độ: read
• Phản hồi thành công 200: Dòng nhật ký. — AuditEvent, 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ó	AuditEventId	Mã dòng nhật ký kiểm toán (aud_…).

curl

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

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhat_ky_kiem_toan import get_audit_event

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

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

POST /v1/audit-events:export

Xuất nhật ký kiểm toán ra CSV

Cần xác thực lại gần đây. Tối đa 50000 dòng (nhiều hơn → 422 validation_failed: hãy thu hẹp thời gian hoặc công ty); không xuất phần diff và ghi chú. Việc xuất được ghi vào chuỗi nhật ký ở mức nhạy cảm; phản hồi có Cache-Control: no-store.

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

• Nhóm tốc độ: export
• Nội dung yêu cầu: ExportAuditEvents (application/json)
• Phản hồi thành công 200: Tệp CSV. — string, text/csv
• Mã lỗi riêng của endpoint: step_up_required, conflict

curl

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

TypeScript

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

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

const { data } = await dt.POST("/v1/audit-events:export", {
  body: {
    "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0"
  },
});

Python

import os

from dongtien import DongTien
from dongtien_api.api.nhat_ky_kiem_toan import export_audit_events
from dongtien_api.models import ExportAuditEvents

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

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

Đối tượng

AuditEventList

Trường	Kiểu	Bắt buộc	Mô tả
data	AuditEvent[]	Có	—
data[].action	string	Có	Hành động, vd. member.role_change.
data[].actor	object	Có	—
data[].company_id	string | null	Có	Công ty của dòng; null với dòng ở cấp tổ chức gốc.
data[].diff	object	Có	—
data[].id	AuditEventId	Có	—
data[].integrity	object	Có	—
data[].note	string | null	Có	—
data[].object	object	Có	—
data[].reason	string | null	Có	—
data[].result	string	Có	Giá trị: success, proposed, pending, sensitive, alert, denied.
data[].sens	boolean	Có	Hành động nhạy cảm (đã báo cho chủ sở hữu).
data[].seq	integer	Có	Số thứ tự trong chuỗi băm của tổ chức.
data[].ts	Timestamp	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.

AuditEvent

Trường	Kiểu	Bắt buộc	Mô tả
action	string	Có	Hành động, vd. member.role_change.
actor	object	Có	—
actor.id	string | null	Có	Mã định danh của chủ thể: người dùng, khoá API hoặc tên tác vụ hệ thống.
actor.role	string | null	Có	Vai trò của chủ thể tại công ty lúc thực hiện.
actor.type	string	Có	Giá trị: human, ai, mcp_client, api_key, system, staff, staff_impersonation, integration, device, oauth.
company_id	string | null	Có	Công ty của dòng; null với dòng ở cấp tổ chức gốc.
diff	object	Có	—
diff.after	any	Không	—
diff.before	any	Không	—
id	AuditEventId	Có	—
integrity	object	Có	—
integrity.chain_ok	boolean | null	Có	null khi trang trải quá nhiều mắt xích để kiểm tra ngay (dùng tác vụ kiểm tra toàn vẹn).
integrity.hash	string	Có	—
integrity.prev_hash	string	Có	—
integrity.verified_at	Timestamp	Có	—
note	string | null	Có	—
object	object	Có	—
object.id	string | null	Có	—
object.type	string	Có	—
reason	string | null	Có	—
result	string	Có	Giá trị: success, proposed, pending, sensitive, alert, denied.
sens	boolean	Có	Hành động nhạy cảm (đã báo cho chủ sở hữu).
seq	integer	Có	Số thứ tự trong chuỗi băm của tổ chức.
ts	Timestamp	Có	—

ExportAuditEvents

Trường	Kiểu	Bắt buộc	Mô tả
company_id	OrgId	Không	—
from	string (date-time)	Không	—
to	string (date-time)	Không	—