Thời gian thực

~4 phút đọc

Vé một lần và luồng sự kiện (WebSocket/SSE) cho giao diện: giao dịch mới, nâng cấp, gộp, cách ly.

Endpoint

Method	Path	Tóm tắt	Quyền	Nhóm tốc độ	Tương tác
`POST`	`/v1/realtime/tickets`	Cấp vé thời gian thực	`tx.read`	`read`	Scalar
`GET`	`/v1/realtime/ws`	Mở WebSocket thời gian thực	`tx.read`	`read`	Scalar
`GET`	`/v1/transactions/stream`	Luồng giao dịch thời gian thực (SSE)	`tx.read`	`read`	Scalar

Chi tiết endpoint

`POST /v1/realtime/tickets`

Cấp vé thời gian thực

Vé chỉ mở được một kết nối trong 60 giây và mang đúng phạm vi công/tài khoản của người gọi (khoá API giới hạn tài khoản vẫn bị giới hạn). Yêu cầu kênh ngoài phạm vi trả 404.

Quyền: tx.read Scope: transactions:read

Nhóm tốc độ: read
Nội dung yêu cầu: RealtimeTicketRequest (application/json)
Phản hồi thành công 201: Vé. — RealtimeTicket, application/json
Mã lỗi riêng của endpoint: conflict

curl -sS -X POST "https://api.dongtien.pro/v1/realtime/tickets" \
  -H "Authorization: Bearer $DT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
  "topics": [
    "org:org_0f5k2m9q4h7t3n8r6v1w0x5yzd"
  ],
  "purpose": "app"
}'

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

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

const { data } = await dt.POST("/v1/realtime/tickets", {
  body: {
    "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
    "topics": [
      "org:org_0f5k2m9q4h7t3n8r6v1w0x5yzd"
    ],
    "purpose": "app"
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.thoi_gian_thuc import create_realtime_ticket
from dongtien_api.models import RealtimeTicketRequest

with DongTien(api_key=os.environ["DT_API_KEY"]) as dt:
    result = create_realtime_ticket.sync(
        client=dt.client,
        body=RealtimeTicketRequest.from_dict({
            "company_id": "org_0f5k2m9q4h7t3n8r6v1w0x5yz0",
            "topics": [
                "org:org_0f5k2m9q4h7t3n8r6v1w0x5yzd",
            ],
            "purpose": "app",
        }),
    )

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

`GET /v1/realtime/ws`

Mở WebSocket thời gian thực

Nâng cấp lên WebSocket (101). Vé bắt buộc (?ticket=), dùng một lần. Máy chủ gửi khung JSON RealtimeEvent; ping/pong tự động. Từ chối trước khi nâng cấp: 401 vé sai/hết hạn/đã dùng, 403 kênh ngoài vé, 429 quá 5 kết nối.

Quyền: tx.read

Nhóm tốc độ: read
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ả
`ticket`	query	Có	`string`	Vé một lần từ `POST /v1/realtime/tickets` (bắt buộc; hiệu lực 60 giây).
`last_event_id`	query	Không	`string`	Tương đương header `Last-Event-ID`.
`topics`	query	Không	`string`	Danh sách kênh phân cách bằng dấu phẩy (tập con của vé).

curl -sS -X GET "https://api.dongtien.pro/v1/realtime/ws?ticket=$TICKET" \
  -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/realtime/ws", {
  params: {
    query: { "ticket": "<ticket>" },
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.thoi_gian_thuc import open_realtime_socket

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

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

`GET /v1/transactions/stream`

Luồng giao dịch thời gian thực (SSE)

Server-Sent Events: id: là số thứ tự tăng dần theo tổ chức, event: là loại (tx.created, tx.upgraded, tx.merged, tx.quarantined, …), data: là RealtimeEvent. Gửi Last-Event-ID để nhận bù tối đa 5 phút; quá hạn nhận khung event: resync và nên gọi /v1/transactions/sync. Xác thực chỉ bằng vé một lần ?ticket= (lấy từ POST /v1/realtime/tickets); cookie/Bearer không được chấp nhận ở máy chủ này.

Quyền: tx.read Scope: transactions:read

Nhóm tốc độ: read
Phản hồi thành công 200: Luồng text/event-stream. — string, text/event-stream
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ả
`ticket`	query	Có	`string`	Vé một lần từ `POST /v1/realtime/tickets` (bắt buộc; hiệu lực 60 giây).
`last_event_id`	query	Không	`string`	Tương đương header `Last-Event-ID`.
`topics`	query	Không	`string`	Danh sách kênh phân cách bằng dấu phẩy (tập con của vé).

curl -sS -X GET "https://api.dongtien.pro/v1/transactions/stream?ticket=$TICKET" \
  -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/transactions/stream", {
  params: {
    query: { "ticket": "<ticket>" },
  },
});

import os

from dongtien import DongTien
from dongtien_api.api.thoi_gian_thuc import stream_transactions

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

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

Đối tượng

`RealtimeTicketRequest`

Trường	Kiểu	Bắt buộc	Mô tả
`company_id`	`string`	Không	Chỉ nghe một công ty; bỏ trống = mọi công ty người gọi xem được.
`live`	`boolean`	Không	Chỉ với `cli_listen`: nghe sự kiện thật (cần scope `webhooks:write`, ghi nhật ký `cli.listen_live`); mặc định chỉ sự kiện sandbox.
`purpose`	`string`	Không	`cli_listen`: vé của `dtp listen` (luồng sự kiện webhook của tổ chức gốc); chỉ khoá API hoặc OAuth, `topics` bị bỏ qua. Giá trị: `app`, `cli_listen`.
`topics`	`RealtimeTopic[]`	Không	Kênh muốn nghe. Mặc định `org:<company>` cho từng công ty trong phạm vi; `user:<mình>` được phép.

`RealtimeTicket`

Trường	Kiểu	Bắt buộc	Mô tả
`expires_at`	`Timestamp`	Có	—
`object`	`string`	Có	Giá trị: `realtime_ticket`.
`sse_url`	`string`	Có	Đường dẫn SSE đã gắn vé.
`ticket`	`string`	Có	—
`topics`	`RealtimeTopic[]`	Có	—
`ws_url`	`string`	Có	Đường dẫn WebSocket đã gắn vé.