# Subiz API Connect your systems to Subiz customers, conversations, messages, and webhooks. API 4.0 · 4.1 Use the Subiz API to sync customer records with your CRM, send messages, coordinate agents, and receive updates on your server. In Subiz, **users** are customers and **agents** are staff. A **conversation** connects participants with their messages and event history. ## Start here 1. Read [the core concepts below](#how-the-entities-fit-together) to understand the objects and IDs you will use. 2. Follow [Authentication](/developers/get-started/authentication) to create an access token for your account. 3. [Test the token with `/4.1/me`](/developers/get-started/authentication#test-your-access-token), then choose a task below. Keep the token on your server. Requests use the issuing agent's permissions. Replace example IDs and values with those from the account you are integrating. ## Choose a task | I want to… | Start with | | --- | --- | | Sync customer records | [Create a customer](/developers/api-reference/users/create) or [update customer details](/developers/api-reference/users/update). | | Reply in an existing conversation | [Send to a conversation](/developers/api-reference/messages/send), using its conversation ID. | | Send through a customer's channel | [Send to a customer](/developers/api-reference/messages/send-to-user), using the customer ID and channel destination. | | Coordinate staff | [Invite an agent](/developers/api-reference/conversations/invite-agent) to participate, or [assign an agent](/developers/api-reference/conversations/assign-agent) responsibility for the conversation. | | React to customer or message changes | [Set up a webhook receiver](/developers/webhooks/receiving) and read the [event payload examples](/developers/webhooks/payloads). | For rich content, see [Message formats](/developers/messages/formats) for text, blocks, and links, and [Attachments](/developers/messages/attachments) for images, video, audio, and files. ## How the entities fit together When Alex contacts your business, Alex is a **user**. Sam, the staff member replying, is an **agent**. Their exchange takes place in a **conversation**. Each message is carried by an **event**. | Object | Represents | | --- | --- | | Account | The business account your integration connects to. | | User | A customer record, including attributes and a channel identity. | | Agent | A staff member serving customers. | | Conversation | An interaction with participants, an assignee, and event history. | | Event | Something that happened, such as a message or an assignment. | | Message | Text, rich blocks, or attachments inside an event. | The examples show selected fields from Subiz's shared object schemas. They use synthetic values and consistent IDs; they are not complete API responses or create-request bodies. Each endpoint defines which fields it accepts or returns. Empty or optional fields may be omitted. **Keep IDs separate.** A customer ID, conversation ID, and external profile ID identify different things. Store the account ID with resource IDs when integrating multiple businesses. ## Account An `Account` represents a business in Subiz. Its own identifier is `id`; other objects refer to it as `account_id`. `owner_id` identifies the owning agent. ```json { "id": "account_example", "name": "Example Store", "owner_id": "agent_example", "state": "activated" } ``` Use an access token for the intended account. See [Authentication](/developers/get-started/authentication). ## Agent An `Agent` is a staff member in an account. Use its `id` when inviting an agent or setting a conversation's `assignee`. ```json { "id": "agent_example", "account_id": "account_example", "fullname": "Sam Example", "email": "sam@example.com", "state": "active" } ``` `fullname` is a direct field on an agent. Customer names use an attribute instead. ## Users and channel identities A `User` is a customer. This customer has a Facebook identity: `channel_source` identifies the page, while `profile_id` identifies the profile on that page. ```json { "id": "user_example", "account_id": "account_example", "channel": "facebook", "channel_source": "page_example", "profile_id": "profile_example", "attributes": [ { "key": "fullname", "text": "Alex Example" } ] } ``` Keep the Subiz `id` separate from `profile_id`. Use [Find or create by channel identity](/developers/api-reference/users/identity) to resolve the channel, source, and profile to a Subiz user. ### Attribute Each item in `user.attributes` is an `Attribute`. Locate it by `key`, not array position. This attribute stores the customer's name: ```json { "key": "fullname", "text": "Alex Example" } ``` Read the value field appropriate to the attribute: `text`, `number`, `boolean`, or `datetime`. A `datetime` value is a date-time string. Do not assume every attribute uses `text`. ### Touchpoint A `Touchpoint` describes a conversation's channel context or a message destination. For this Facebook example, `source` is the page and `id` is the customer's profile on that page: ```json { "channel": "facebook", "source": "page_example", "id": "profile_example" } ``` These correspond to the user's `channel`, `channel_source`, and `profile_id` above. The meaning of a touchpoint's `id` depends on the channel; it can also identify a comment or another destination. Use the connected integration's values, not a Subiz user ID in place of the destination. ## Conversations, members, and ownership A `Conversation` has its own ID, members, channel context, and event history. A customer can participate in more than one conversation. Here, Sam is both a member and the responsible agent: ```json { "id": "conversation_example", "account_id": "account_example", "state": "active", "assignee": "agent_example", "members": [ { "id": "user_example", "type": "user", "membership": "active" }, { "id": "agent_example", "type": "agent", "conversation_id": "conversation_example", "membership": "active" } ], "touchpoint": { "channel": "facebook", "source": "page_example", "id": "profile_example" } } ``` `assignee` identifies the responsible agent. It can be empty or omitted when the conversation is unassigned. `members` describes participation; it is not the same as ownership. ### Conversation member A `ConversationMember` identifies a participant by `type` and `id`. `membership` records their participation state. ```json { "id": "agent_example", "type": "agent", "conversation_id": "conversation_example", "membership": "active" } ``` [Invite an agent](/developers/api-reference/conversations/invite-agent) adds an existing agent as a participant. [Assign an agent](/developers/api-reference/conversations/assign-agent) changes responsibility. Explicit assignment does not add the agent to `members`. ## Messages and events ### Message A `Message` holds content. This plain-text message belongs to the conversation above: ```json { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hello Alex" } ``` This is the message object, not the full send-request body. [Send to a conversation](/developers/api-reference/messages/send) wraps it in `data.message` and takes the conversation ID from the URL. [Send to a customer](/developers/api-reference/messages/send-to-user) uses a different request shape and requires channel destination context. ### Event data `Data` holds the object relevant to an event. For `message_sent`, it contains `message`: ```json { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hello Alex" } } ``` Other event types can carry `user` or `conversation` instead. Check the event's `type` before accessing nested fields. ### Actor The optional `By` object identifies who caused an event. It appears as `event.by`: ```json { "id": "agent_example", "type": "agent" } ``` `type` can identify a user, agent, or bot. The actor is not necessarily the conversation's assignee. Some events omit `by` or provide device context without an actor ID. ### Event An `Event` combines its identity, type, time, actor, and data. Here is the complete example envelope around the message above: ```json { "id": "event_example_1", "account_id": "account_example", "created": 1794614400000, "type": "message_sent", "by": { "id": "agent_example", "type": "agent" }, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hello Alex" } } } ``` `created` is the time recorded in Subiz, in Unix milliseconds. `event_time`, when provided, records the original occurrence time. Event `id` identifies the event; do not substitute a nested message or conversation ID. [Conversation history](/developers/api-reference/conversations/history) contains events, not only messages. A `message_sent` event or a successful send response does not by itself confirm delivery to an external channel. ## Rich messages with blocks For the full guide to plaintext, links, and text styling, see [Message formats](/developers/messages/formats). ### Block A `Block` is a node in a rich-content tree. `type` selects the node, `content` holds children, and a text node uses `text`. Text nodes can include `bold`, `italic`, or `underline`. ```json { "type": "paragraph", "content": [ { "type": "text", "text": "Hello " }, { "type": "text", "text": "Alex", "bold": true } ] } ``` This content reads “Hello **Alex**”. A block is a JSON object, not an HTML string. ### Rich message Place the block in `message.block` and set `format` to `block`: ```json { "conversation_id": "conversation_example", "format": "block", "block": { "type": "paragraph", "content": [ { "type": "text", "text": "Hello " }, { "type": "text", "text": "Alex", "bold": true } ] } } ``` Subiz can derive plain text while retaining the block tree. Store the tree if you need formatting. The model also supports images, links, lists, and tables; rendering depends on the destination channel. ### Attachment See [Attachments](/developers/messages/attachments) for image, video, audio, file, and interactive examples. Each item in `message.attachments` is an `Attachment`. This file example uses a placeholder URL; `size` is measured in bytes: ```json { "type": "file", "mimetype": "application/pdf", "url": "https://example.com/guide.pdf", "name": "guide.pdf", "size": 2048 } ``` Put attachment objects in the `attachments` array, not in `block.content`. A message can contain attachments even when its `text` is empty. ## Webhooks connect your system API calls request actions; webhooks notify your integration of events. A webhook delivery wraps events in an `events` array. The same event example would appear as: ```json { "events": [ { "id": "event_example_1", "account_id": "account_example", "created": 1794614400000, "type": "message_sent", "by": { "id": "agent_example", "type": "agent" }, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hello Alex" } } } ] } ``` A delivery can contain several events. Verify its signature, then process every event by `type` and deduplicate by `(account_id, id)`. See [Receive webhook events](/developers/webhooks/receiving) for setup and [Event payload examples](/developers/webhooks/payloads) for other event types. The delivery envelope is not the Webhook configuration object. ## API requests and versions Send requests to `https://api.subiz.com.vn`. Each endpoint page shows the full URL, HTTP method, headers, and JSON body when required. These docs cover API **4.0** and **4.1**. Use the version in each endpoint's URL exactly as shown; different operations can use different versions. See the [Changelog](/developers/changelog) for documentation updates and API change announcements. ## Before going live - Read [Usage limits](/developers/get-started/usage-limits) for token, account, and agent message allowances. Queue requests and honor `Retry-After` when throttled. - Follow [Errors](/developers/get-started/errors) to handle failures. After a message-send timeout, check the outcome before retrying to avoid duplicates. - When receiving webhooks, [verify signatures and handle duplicate events](/developers/webhooks/receiving). ## Use with your tools Read [this page as Markdown](/developers/index.md). For AI tools, use the [documentation index](/developers/llms.txt) or [full documentation](/developers/llms-full.txt). --- # Subiz API Kết nối hệ thống của bạn với khách hàng, hội thoại, tin nhắn và webhook của Subiz. API 4.0 · 4.1 Dùng Subiz API để đồng bộ hồ sơ khách hàng với CRM, gửi tin nhắn, điều phối agent và nhận cập nhật trên máy chủ của bạn. Trong Subiz, **user** là khách hàng và **agent** là nhân viên của doanh nghiệp. Một **hội thoại** (conversation) kết nối những người tham gia với tin nhắn và lịch sử sự kiện của họ. ## Bắt đầu từ đây 1. Đọc [các khái niệm cốt lõi bên dưới](#mối-quan-hệ-giữa-các-đối-tượng) để hiểu các đối tượng và ID bạn sẽ dùng. 2. Làm theo [Xác thực](/developers/vi/get-started/authentication) để tạo access token cho tài khoản của bạn. 3. [Kiểm tra token bằng `/4.1/me`](/developers/vi/get-started/authentication#kiểm-tra-access-token), rồi chọn một tác vụ bên dưới. Giữ token trên máy chủ của bạn. Yêu cầu dùng quyền của agent đã tạo token. Thay ID và giá trị mẫu bằng dữ liệu của tài khoản bạn đang tích hợp. ## Chọn tác vụ | Tôi muốn… | Bắt đầu với | | --- | --- | | Đồng bộ hồ sơ khách hàng | [Tạo khách hàng](/developers/vi/api-reference/users/create) hoặc [cập nhật thông tin khách hàng](/developers/vi/api-reference/users/update). | | Trả lời trong một hội thoại có sẵn | [Gửi tin nhắn vào hội thoại](/developers/vi/api-reference/messages/send), dùng ID hội thoại. | | Gửi qua kênh của khách hàng | [Gửi tin nhắn cho khách hàng](/developers/vi/api-reference/messages/send-to-user), dùng ID khách hàng và đích đến trên kênh. | | Điều phối agent | [Mời agent](/developers/vi/api-reference/conversations/invite-agent) tham gia, hoặc [giao agent](/developers/vi/api-reference/conversations/assign-agent) phụ trách hội thoại. | | Phản ứng khi khách hàng hoặc tin nhắn thay đổi | [Thiết lập máy nhận webhook](/developers/vi/webhooks/receiving) và đọc [ví dụ dữ liệu sự kiện](/developers/vi/webhooks/payloads). | Với nội dung phong phú, xem [Định dạng tin nhắn](/developers/vi/messages/formats) cho văn bản, block và liên kết, và [Tệp đính kèm](/developers/vi/messages/attachments) cho ảnh, video, âm thanh và tệp. ## Mối quan hệ giữa các đối tượng Khi Alex liên hệ với doanh nghiệp của bạn, Alex là một **user**. Sam, nhân viên trả lời, là một **agent**. Cuộc trao đổi của họ diễn ra trong một **hội thoại**. Mỗi tin nhắn được mang trong một **sự kiện** (event). | Đối tượng | Đại diện cho | | --- | --- | | Account | Tài khoản doanh nghiệp mà tích hợp của bạn kết nối tới. | | User | Hồ sơ khách hàng, gồm thuộc tính và định danh kênh. | | Agent | Nhân viên phục vụ khách hàng. | | Conversation | Một tương tác có người tham gia, người phụ trách và lịch sử sự kiện. | | Event | Một việc đã xảy ra, như một tin nhắn hoặc một lần giao việc. | | Message | Văn bản, block phong phú hoặc tệp đính kèm bên trong một sự kiện. | Các ví dụ hiển thị một số trường được chọn từ schema đối tượng dùng chung của Subiz. Chúng dùng giá trị giả lập và ID nhất quán; đây không phải phản hồi API đầy đủ hay body của yêu cầu tạo. Mỗi endpoint quy định trường nào được nhận hoặc trả về. Trường rỗng hoặc tùy chọn có thể bị lược bỏ. **Không nhầm lẫn các ID.** ID khách hàng, ID hội thoại và ID hồ sơ bên ngoài chỉ những thứ khác nhau. Lưu ID tài khoản cùng ID tài nguyên khi tích hợp nhiều doanh nghiệp. ## Account `Account` đại diện cho một doanh nghiệp trong Subiz. Định danh của chính nó là `id`; các đối tượng khác tham chiếu tới nó qua `account_id`. `owner_id` là agent sở hữu tài khoản. ```json { "id": "account_example", "name": "Example Store", "owner_id": "agent_example", "state": "activated" } ``` Dùng access token của đúng tài khoản. Xem [Xác thực](/developers/vi/get-started/authentication). ## Agent `Agent` là một nhân viên trong tài khoản. Dùng `id` của agent khi mời agent hoặc đặt `assignee` của hội thoại. ```json { "id": "agent_example", "account_id": "account_example", "fullname": "Sam Example", "email": "sam@example.com", "state": "active" } ``` `fullname` là trường trực tiếp của agent. Tên khách hàng thì dùng thuộc tính. ## Khách hàng và định danh kênh `User` là một khách hàng. Khách hàng này có định danh Facebook: `channel_source` xác định trang (page), còn `profile_id` xác định hồ sơ trên trang đó. ```json { "id": "user_example", "account_id": "account_example", "channel": "facebook", "channel_source": "page_example", "profile_id": "profile_example", "attributes": [ { "key": "fullname", "text": "Alex Example" } ] } ``` Không nhầm `id` của Subiz với `profile_id`. Dùng [Tìm hoặc tạo theo định danh kênh](/developers/vi/api-reference/users/identity) để tìm user Subiz từ kênh, nguồn và hồ sơ. ### Thuộc tính Mỗi phần tử trong `user.attributes` là một `Attribute`. Tìm thuộc tính theo `key`, không theo vị trí trong mảng. Thuộc tính này lưu tên khách hàng: ```json { "key": "fullname", "text": "Alex Example" } ``` Đọc trường giá trị phù hợp với thuộc tính: `text`, `number`, `boolean` hoặc `datetime`. Giá trị `datetime` là chuỗi ngày giờ. Đừng giả định mọi thuộc tính đều dùng `text`. ### Touchpoint `Touchpoint` mô tả ngữ cảnh kênh của hội thoại hoặc đích đến của tin nhắn. Trong ví dụ Facebook này, `source` là trang và `id` là hồ sơ của khách hàng trên trang đó: ```json { "channel": "facebook", "source": "page_example", "id": "profile_example" } ``` Các giá trị này tương ứng với `channel`, `channel_source` và `profile_id` của user ở trên. Ý nghĩa của `id` trong touchpoint phụ thuộc vào kênh; nó cũng có thể là một bình luận hoặc đích đến khác. Dùng giá trị của tích hợp đã kết nối, không dùng ID user của Subiz thay cho đích đến. ## Hội thoại, thành viên và người phụ trách `Conversation` có ID riêng, thành viên, ngữ cảnh kênh và lịch sử sự kiện. Một khách hàng có thể tham gia nhiều hội thoại. Ở đây, Sam vừa là thành viên vừa là agent phụ trách: ```json { "id": "conversation_example", "account_id": "account_example", "state": "active", "assignee": "agent_example", "members": [ { "id": "user_example", "type": "user", "membership": "active" }, { "id": "agent_example", "type": "agent", "conversation_id": "conversation_example", "membership": "active" } ], "touchpoint": { "channel": "facebook", "source": "page_example", "id": "profile_example" } } ``` `assignee` là agent phụ trách. Trường này có thể rỗng hoặc bị lược bỏ khi hội thoại chưa được giao. `members` mô tả việc tham gia; nó không đồng nghĩa với quyền phụ trách. ### Thành viên hội thoại `ConversationMember` xác định một người tham gia bằng `type` và `id`. `membership` ghi trạng thái tham gia của họ. ```json { "id": "agent_example", "type": "agent", "conversation_id": "conversation_example", "membership": "active" } ``` [Mời agent](/developers/vi/api-reference/conversations/invite-agent) thêm một agent có sẵn làm người tham gia. [Giao agent](/developers/vi/api-reference/conversations/assign-agent) thay đổi người phụ trách. Giao việc trực tiếp không thêm agent vào `members`. ## Tin nhắn và sự kiện ### Message `Message` chứa nội dung. Tin nhắn văn bản thuần này thuộc hội thoại ở trên: ```json { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hello Alex" } ``` Đây là đối tượng tin nhắn, không phải toàn bộ body của yêu cầu gửi. [Gửi tin nhắn vào hội thoại](/developers/vi/api-reference/messages/send) đặt nó trong `data.message` và lấy ID hội thoại từ URL. [Gửi tin nhắn cho khách hàng](/developers/vi/api-reference/messages/send-to-user) dùng cấu trúc yêu cầu khác và cần ngữ cảnh đích đến trên kênh. ### Dữ liệu sự kiện `Data` chứa đối tượng liên quan tới sự kiện. Với `message_sent`, nó chứa `message`: ```json { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hello Alex" } } ``` Các loại sự kiện khác có thể mang `user` hoặc `conversation`. Kiểm tra `type` của sự kiện trước khi truy cập trường lồng nhau. ### Tác nhân Đối tượng `By` (tùy chọn) xác định ai gây ra sự kiện. Nó xuất hiện dưới dạng `event.by`: ```json { "id": "agent_example", "type": "agent" } ``` `type` có thể là user, agent hoặc bot. Tác nhân không nhất thiết là người phụ trách hội thoại. Một số sự kiện không có `by` hoặc chỉ có ngữ cảnh thiết bị mà không có ID tác nhân. ### Event `Event` kết hợp định danh, loại, thời gian, tác nhân và dữ liệu. Đây là ví dụ đầy đủ bao quanh tin nhắn ở trên: ```json { "id": "event_example_1", "account_id": "account_example", "created": 1794614400000, "type": "message_sent", "by": { "id": "agent_example", "type": "agent" }, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hello Alex" } } } ``` `created` là thời điểm Subiz ghi nhận, tính bằng mili giây Unix. `event_time`, nếu có, là thời điểm xảy ra gốc. `id` của event định danh sự kiện; đừng thay bằng ID tin nhắn hay ID hội thoại lồng bên trong. [Lịch sử hội thoại](/developers/vi/api-reference/conversations/history) chứa sự kiện, không chỉ tin nhắn. Một sự kiện `message_sent` hoặc một phản hồi gửi thành công không tự nó xác nhận tin đã tới kênh bên ngoài. ## Tin nhắn định dạng phong phú bằng block Hướng dẫn đầy đủ về văn bản thuần, liên kết và kiểu chữ có trong [Định dạng tin nhắn](/developers/vi/messages/formats). ### Block `Block` là một nút trong cây nội dung phong phú. `type` chọn loại nút, `content` chứa các nút con, và nút văn bản dùng `text`. Nút văn bản có thể có `bold`, `italic` hoặc `underline`. ```json { "type": "paragraph", "content": [ { "type": "text", "text": "Hello " }, { "type": "text", "text": "Alex", "bold": true } ] } ``` Nội dung này hiển thị là “Hello **Alex**”. Block là một đối tượng JSON, không phải chuỗi HTML. ### Tin nhắn phong phú Đặt block vào `message.block` và đặt `format` là `block`: ```json { "conversation_id": "conversation_example", "format": "block", "block": { "type": "paragraph", "content": [ { "type": "text", "text": "Hello " }, { "type": "text", "text": "Alex", "bold": true } ] } } ``` Subiz có thể tạo văn bản thuần từ block mà vẫn giữ cây block. Lưu cây block nếu bạn cần định dạng. Mô hình này cũng hỗ trợ ảnh, liên kết, danh sách và bảng; cách hiển thị phụ thuộc vào kênh đích. ### Tệp đính kèm Xem [Tệp đính kèm](/developers/vi/messages/attachments) để có ví dụ về ảnh, video, âm thanh, tệp và nội dung tương tác. Mỗi phần tử trong `message.attachments` là một `Attachment`. Ví dụ tệp này dùng URL giả lập; `size` tính bằng byte: ```json { "type": "file", "mimetype": "application/pdf", "url": "https://example.com/guide.pdf", "name": "guide.pdf", "size": 2048 } ``` Đặt đối tượng đính kèm trong mảng `attachments`, không đặt trong `block.content`. Tin nhắn có thể có tệp đính kèm ngay cả khi `text` rỗng. ## Webhook kết nối hệ thống của bạn Lời gọi API yêu cầu thực hiện hành động; webhook thông báo sự kiện cho tích hợp của bạn. Một lần gửi webhook bọc các sự kiện trong mảng `events`. Cùng sự kiện ví dụ ở trên sẽ có dạng: ```json { "events": [ { "id": "event_example_1", "account_id": "account_example", "created": 1794614400000, "type": "message_sent", "by": { "id": "agent_example", "type": "agent" }, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hello Alex" } } } ] } ``` Một lần gửi có thể chứa nhiều sự kiện. Xác minh chữ ký, sau đó xử lý từng sự kiện theo `type` và loại trùng theo `(account_id, id)`. Xem [Nhận sự kiện webhook](/developers/vi/webhooks/receiving) để thiết lập và [Ví dụ dữ liệu sự kiện](/developers/vi/webhooks/payloads) cho các loại sự kiện khác. Phần bao của lần gửi không phải là đối tượng cấu hình Webhook. ## Yêu cầu API và phiên bản Gửi yêu cầu tới `https://api.subiz.com.vn`. Mỗi trang endpoint hiển thị URL đầy đủ, phương thức HTTP, header và body JSON khi cần. Tài liệu này bao gồm API **4.0** và **4.1**. Dùng đúng phiên bản trong URL của từng endpoint như đã ghi; các thao tác khác nhau có thể dùng phiên bản khác nhau. Xem [Nhật ký thay đổi](/developers/vi/changelog) để biết cập nhật tài liệu và thông báo thay đổi API. ## Trước khi chạy thật - Đọc [Giới hạn sử dụng](/developers/vi/get-started/usage-limits) để biết hạn mức theo token, tài khoản và tin nhắn của agent. Xếp hàng yêu cầu và tuân theo `Retry-After` khi bị giới hạn. - Làm theo [Xử lý lỗi](/developers/vi/get-started/errors) để xử lý thất bại. Sau khi gửi tin nhắn bị hết thời gian chờ, kiểm tra kết quả trước khi thử lại để tránh trùng lặp. - Khi nhận webhook, [xác minh chữ ký và xử lý sự kiện trùng lặp](/developers/vi/webhooks/receiving). ## Dùng với công cụ của bạn Đọc [trang này dưới dạng Markdown](/developers/vi/index.md). Với công cụ AI, dùng [mục lục tài liệu](/developers/llms.txt) hoặc [toàn bộ tài liệu](/developers/llms-full.txt). --- # Authentication Authorize API requests with a Bearer access token. API 4.0 · 4.1 ## Get an access token 1. Sign in to Subiz and open [Personal access token](https://app.subiz.com.vn/apikey). 2. Click **Create token**. 3. Select the **Account** you want to connect. Enter a **Note**, such as `CRM integration`, and choose an **Expiration**. 4. Click **Create token** to confirm. 5. Click **Copy token** and save it securely before closing the dialog. **The token is shown only once.** If you lose it, create a new one. Each token belongs to the account selected during creation. Requests made with this token act as your agent in that account. Your agent's permissions still apply; creating a token does not grant extra access. ## Test your access token In your API client, send this request. Replace `YOUR_ACCESS_TOKEN` with the token you copied. No request body is needed. ```http GET https://api.subiz.com.vn/4.1/me Authorization: Bearer YOUR_ACCESS_TOKEN ``` **Expected result:** `200 OK` with your agent profile as JSON. Example below shows selected fields with placeholder values: ```json { "id": "YOUR_AGENT_ID", "account_id": "YOUR_ACCOUNT_ID", "fullname": "Example Agent" } ``` Check that `account_id` matches the account you want to connect. `id` identifies the agent making the request. A successful check confirms access to `/me`, not every API operation. Token checks also count toward [usage limits](/developers/get-started/usage-limits). If `/me` returns `429`, wait for the `Retry-After` interval before testing again. ## Replace or revoke a token To replace an expired or lost token, create a new one and update your integration. Test it with `/me`, then delete the old token if it is still listed. To revoke a token, open [Personal access token](https://app.subiz.com.vn/apikey), open its **…** menu, choose **Delete token**, and confirm. Deletion cannot be undone. If a token is exposed, revoke it before creating a replacement. Keep the token on your server, for example in an environment variable. Do not put it in browser code, public repositories, or URLs. ## If authentication fails Check that the token is correct, has not expired or been deleted, and belongs to the account you are accessing. Keep the `Bearer ` prefix, including its space. Authentication failures can return HTTP `400`. Read the [JSON error response](/developers/get-started/errors) before retrying. ## Next step [Send a message](/developers/api-reference/messages/send) using your token and an existing conversation ID. --- # Xác thực Ủy quyền yêu cầu API bằng Bearer access token. API 4.0 · 4.1 ## Lấy access token 1. Đăng nhập Subiz và mở [Mã truy cập cá nhân](https://app.subiz.com.vn/apikey). 2. Nhấn **Tạo mã truy cập**. 3. Chọn **Tài khoản** cần kết nối. Nhập **Ghi chú**, ví dụ `CRM integration`, và chọn **Thời hạn hết hạn**. 4. Nhấn **Tạo mã** để xác nhận. 5. Nhấn **Sao chép mã** và lưu an toàn trước khi đóng hộp thoại. **Token chỉ hiển thị một lần.** Nếu làm mất, hãy tạo token mới. Mỗi token thuộc tài khoản đã chọn khi tạo. Yêu cầu gửi bằng token này hoạt động với tư cách agent của bạn trong tài khoản đó. Quyền của agent vẫn được áp dụng; tạo token không cấp thêm quyền. ## Kiểm tra access token Trong công cụ gọi API, gửi yêu cầu sau. Thay `YOUR_ACCESS_TOKEN` bằng token vừa sao chép. Không cần body. ```http GET https://api.subiz.com.vn/4.1/me Authorization: Bearer YOUR_ACCESS_TOKEN ``` **Kết quả mong đợi:** `200 OK` cùng hồ sơ agent của bạn dưới dạng JSON. Ví dụ dưới đây hiển thị một số trường với giá trị mẫu: ```json { "id": "YOUR_AGENT_ID", "account_id": "YOUR_ACCOUNT_ID", "fullname": "Example Agent" } ``` Kiểm tra `account_id` trùng với tài khoản bạn muốn kết nối. `id` là agent đang gửi yêu cầu. Kiểm tra thành công chỉ xác nhận quyền truy cập `/me`, không phải mọi thao tác API. Yêu cầu kiểm tra token cũng được tính vào [giới hạn sử dụng](/developers/vi/get-started/usage-limits). Nếu `/me` trả `429`, hãy chờ hết khoảng `Retry-After` rồi mới thử lại. ## Thay thế hoặc thu hồi token Để thay token hết hạn hoặc bị mất, tạo token mới và cập nhật tích hợp. Kiểm tra token mới bằng `/me`, sau đó xóa token cũ nếu nó vẫn còn trong danh sách. Để thu hồi token, mở [Mã truy cập cá nhân](https://app.subiz.com.vn/apikey), mở menu **…** của token, chọn **Xóa mã truy cập** và xác nhận. Không thể hoàn tác thao tác xóa. Nếu token bị lộ, hãy thu hồi trước khi tạo token thay thế. Lưu token phía máy chủ, chẳng hạn trong biến môi trường. Không đặt token trong mã trình duyệt, kho mã nguồn công khai hoặc URL. ## Nếu xác thực thất bại Kiểm tra token có đúng, còn hạn, chưa bị xóa và thuộc tài khoản đang truy cập. Giữ nguyên tiền tố `Bearer `, gồm cả dấu cách. Lỗi xác thực có thể trả HTTP `400`. Đọc [phản hồi lỗi JSON](/developers/vi/get-started/errors) trước khi thử lại. ## Bước tiếp theo [Gửi tin nhắn](/developers/vi/api-reference/messages/send) bằng token và ID hội thoại đã có. --- # Usage limits Understand token and account request limits, payload sizes, and retry timing. API 4.0 · 4.1 Check two things before sending requests: **how often you call the API** and **how much data each request contains**. A slower request rate does not fix an oversized payload. ## Rate limits Authenticated agent requests have two layers of limits: | Scope | Requests per second | Requests per day | | --- | --- | --- | | Each agent access token | 100 | 144,000 | | All API keys in one account, combined | 100 | 864,000 | **Personal access tokens created in Subiz are subject to both limits.** The token limit is checked first, then the shared account limit. For example, two API keys sending 60 requests each in the same second exceed their account's combined 100-request limit. The token allowance follows the exact token across endpoints and accounts. Different tokens have separate token allowances; API keys for the same account still share the account allowance. Agent login and OAuth tokens have the per-token limit but do not consume the account's API-key allowance. ### Counting and resets - The per-second limit uses a fixed calendar second. - Daily limits reset at **00:00 UTC** (07:00 in Vietnam), not 24 hours after the first request. - Requests that reach an operation count even if that operation later fails. This includes token checks with `/4.1/me`. Counters currently apply per gateway instance and reset when it restarts. These are not globally synchronized quotas. Keep your integration within the listed limits rather than relying on traffic reaching different instances. Use a queue, limit concurrent requests, and increase traffic gradually. Use [webhooks](/developers/webhooks/receiving) for updates instead of repeatedly fetching the same records. ### Message sending limits Sending as a human agent also uses a shared allowance for that **agent in that account**: | Per second | Per minute | Per day | | --- | --- | --- | | 5 messages | 60 messages | 5,000 messages | All of the agent's tokens and devices share this allowance, across conversations and both [conversation sends](/developers/api-reference/messages/send) and [customer sends](/developers/api-reference/messages/send-to-user). Changing the sender in the request body does not change whose allowance is used. Internal messages count too; typing, seen, and other non-message events do not. The second and minute windows are fixed calendar windows; the day resets at 00:00 UTC. These counters also apply per gateway instance. For customer-send requests, each candidate in `messages` counts, even though the service stops after the first successful send. **Include at most five candidates per request.** This is not a bulk-send operation; use one candidate when targeting one destination. The limiter checks the entire candidate array before sending; if it rejects the request, none of its candidates are forwarded. These are attempt limits: reserved allowance is not refunded after a rejected request or a backend failure. ### Detect throttling Exceeding a token, account, or agent message allowance returns **HTTP `429 Too Many Requests`** before the operation runs. The response includes `rate_limit` in `error.code` and these headers: | Header | Value | | --- | --- | | `Retry-After` | Seconds to wait: `1` for a per-second limit, seconds until the next minute for the message-per-minute limit, or seconds until 00:00 UTC for a daily limit. | | `Cache-Control` | `no-store` | | `Content-Type` | `application/json` | Example of a per-second rejection, showing selected response fields: ```http HTTP/1.1 429 Too Many Requests Retry-After: 1 Cache-Control: no-store Content-Type: application/json { "code": "rate_limit,limit_exceeded,invalid_input", "class": 400, "error": { "code": "rate_limit,limit_exceeded,invalid_input" } } ``` The body's legacy `class: 400` does not change the HTTP `429` status. See [Errors](/developers/get-started/errors#error-response). The limiter does not return `ratelimit-limit`, `ratelimit-remaining`, or `ratelimit-reset`. Other operation-specific throttles can still return HTTP `400` with `rate_limit` and no `Retry-After`; handle those responses too. ### Retry safely 1. Pause the affected work and reduce concurrency. 2. If the response includes `Retry-After`, wait at least that long. 3. Otherwise, use increasing delays with a small random offset. Set a maximum number of attempts. 4. Before retrying a message send after a timeout or lost response, check whether the message was already created. Repeating it can send a duplicate. Read each retry's response: waiting does not guarantee acceptance if another limit has been reached or other callers are using the shared allowance. See [Errors](/developers/get-started/errors#when-to-retry) for other failure types. ## Message limits The conversation message validator applies these limits to messages sent through the API: | Field | Maximum | When exceeded | | --- | --- | --- | | `data.message.text` | 1,524,288 UTF-8 bytes | `payload_too_large` | | `data.message.attachments` | 50 entries | `limit_exceeded` | | `data.message.fields` | 540 entries | `limit_exceeded` | | Each `fields[].key` | 42,428 UTF-8 bytes | `limit_exceeded` | | Each `fields[].value` | 1,524,288 UTF-8 bytes | `limit_exceeded` | Text length is measured in **bytes**, not visible characters. Emoji and accented characters can use more than one byte. The text limit applies to the message's `text` field during validation, not the total JSON request size. These are Subiz validation ceilings, not recommended message sizes or guarantees of delivery on every channel. Keep messages short. Connected channels can impose additional restrictions on content and media. The attachment count is not a file-size allowance; see [Attachments](/developers/messages/attachments). ## Customer attribute limits Customer creation and attribute updates check the size of the attribute input. The normal attribute-update flow checks normalized values: | Data | Maximum | | --- | --- | | Attributes in the validated input | 1,000 entries | | Each attribute's `text`, `datetime`, and all `other_values` combined | 2,048 UTF-8 bytes | Exceeding either limit produces `payload_too_large`. Reduce the affected input before retrying. Splitting a long value across `other_values` does not bypass the combined size limit. See [Create a customer](/developers/api-reference/users/create) and [Update customer details](/developers/api-reference/users/update) for supported fields. ## Plan and channel allowances Request throttling, payload validation, and account or channel allowances are different constraints. This page does not define a universal monthly message quota, customer quota, or file-size limit. Check the relevant account plan and channel requirements before a large import or messaging job. If failures persist, send Subiz support the endpoint, request time, traffic rate, and error details. Remove access tokens and customer data first. --- # Giới hạn sử dụng Hiểu giới hạn yêu cầu theo token và tài khoản, kích thước dữ liệu và thời điểm thử lại. API 4.0 · 4.1 Kiểm tra hai điều trước khi gửi yêu cầu: **bạn gọi API thường xuyên tới mức nào** và **mỗi yêu cầu chứa bao nhiêu dữ liệu**. Gọi chậm hơn không khắc phục được dữ liệu quá lớn. ## Giới hạn tốc độ Yêu cầu đã xác thực của agent có hai lớp giới hạn: | Phạm vi | Yêu cầu mỗi giây | Yêu cầu mỗi ngày | | --- | --- | --- | | Mỗi access token của agent | 100 | 144.000 | | Tất cả API key trong một tài khoản, cộng chung | 100 | 864.000 | **Mã truy cập cá nhân tạo trong Subiz chịu cả hai giới hạn.** Giới hạn theo token được kiểm tra trước, sau đó tới giới hạn chung của tài khoản. Ví dụ, hai API key cùng gửi 60 yêu cầu trong cùng một giây sẽ vượt giới hạn chung 100 yêu cầu của tài khoản. Hạn mức theo token gắn với đúng token đó trên mọi endpoint và tài khoản. Các token khác nhau có hạn mức token riêng; các API key của cùng tài khoản vẫn dùng chung hạn mức tài khoản. Token đăng nhập và OAuth của agent chịu giới hạn theo token nhưng không tiêu hao hạn mức API key của tài khoản. ### Cách đếm và đặt lại - Giới hạn mỗi giây dùng giây lịch cố định. - Giới hạn ngày được đặt lại lúc **00:00 UTC** (07:00 giờ Việt Nam), không phải 24 giờ sau yêu cầu đầu tiên. - Yêu cầu đã tới thao tác vẫn được tính ngay cả khi thao tác đó thất bại sau đó. Điều này gồm cả yêu cầu kiểm tra token bằng `/4.1/me`. Bộ đếm hiện áp dụng riêng cho từng instance gateway và được đặt lại khi instance khởi động lại. Đây không phải hạn mức đồng bộ toàn cục. Hãy giữ tích hợp trong giới hạn đã nêu thay vì trông chờ lưu lượng được chia sang các instance khác nhau. Dùng hàng đợi, giới hạn số yêu cầu đồng thời và tăng lưu lượng từ từ. Dùng [webhook](/developers/vi/webhooks/receiving) để nhận cập nhật thay vì liên tục lấy lại cùng một bản ghi. ### Giới hạn gửi tin nhắn Gửi tin với tư cách agent còn dùng một hạn mức chung cho **agent đó trong tài khoản đó**: | Mỗi giây | Mỗi phút | Mỗi ngày | | --- | --- | --- | | 5 tin nhắn | 60 tin nhắn | 5.000 tin nhắn | Mọi token và thiết bị của agent dùng chung hạn mức này, trên mọi hội thoại và cả hai cách [gửi vào hội thoại](/developers/vi/api-reference/messages/send) và [gửi cho khách hàng](/developers/vi/api-reference/messages/send-to-user). Đổi người gửi trong body yêu cầu không làm thay đổi hạn mức của ai được sử dụng. Tin nhắn nội bộ cũng được tính; sự kiện đang gõ, đã xem và các sự kiện không phải tin nhắn khác thì không. Cửa sổ giây và phút là cửa sổ lịch cố định; ngày được đặt lại lúc 00:00 UTC. Các bộ đếm này cũng áp dụng riêng cho từng instance gateway. Với yêu cầu gửi cho khách hàng, mỗi ứng viên trong `messages` đều được tính, dù dịch vụ dừng lại sau lần gửi thành công đầu tiên. **Chỉ đưa tối đa năm ứng viên vào mỗi yêu cầu.** Đây không phải thao tác gửi hàng loạt; dùng một ứng viên khi nhắm tới một đích đến. Bộ giới hạn kiểm tra toàn bộ mảng ứng viên trước khi gửi; nếu yêu cầu bị từ chối thì không ứng viên nào được chuyển tiếp. Đây là giới hạn theo lượt thử: hạn mức đã giữ chỗ không được hoàn lại sau một yêu cầu bị từ chối hoặc lỗi phía backend. ### Nhận biết khi bị điều tiết Vượt hạn mức theo token, tài khoản hoặc tin nhắn của agent sẽ trả **HTTP `429 Too Many Requests`** trước khi thao tác được thực hiện. Phản hồi có `rate_limit` trong `error.code` và các header sau: | Header | Giá trị | | --- | --- | | `Retry-After` | Số giây cần chờ: `1` với giới hạn mỗi giây, số giây tới phút tiếp theo với giới hạn tin nhắn mỗi phút, hoặc số giây tới 00:00 UTC với giới hạn ngày. | | `Cache-Control` | `no-store` | | `Content-Type` | `application/json` | Ví dụ một lần bị từ chối do giới hạn mỗi giây, hiển thị một số trường của phản hồi: ```http HTTP/1.1 429 Too Many Requests Retry-After: 1 Cache-Control: no-store Content-Type: application/json { "code": "rate_limit,limit_exceeded,invalid_input", "class": 400, "error": { "code": "rate_limit,limit_exceeded,invalid_input" } } ``` Trường cũ `class: 400` trong body không thay đổi trạng thái HTTP `429`. Xem [Xử lý lỗi](/developers/vi/get-started/errors#phản-hồi-lỗi). Bộ giới hạn không trả `ratelimit-limit`, `ratelimit-remaining` hay `ratelimit-reset`. Các cơ chế điều tiết riêng của từng thao tác vẫn có thể trả HTTP `400` với `rate_limit` và không có `Retry-After`; hãy xử lý cả những phản hồi đó. ### Thử lại an toàn 1. Tạm dừng công việc bị ảnh hưởng và giảm số yêu cầu đồng thời. 2. Nếu phản hồi có `Retry-After`, chờ ít nhất khoảng thời gian đó. 3. Nếu không, dùng độ trễ tăng dần kèm một khoảng ngẫu nhiên nhỏ. Đặt số lần thử tối đa. 4. Trước khi gửi lại tin nhắn sau khi hết thời gian chờ hoặc mất phản hồi, kiểm tra xem tin nhắn đã được tạo chưa. Gửi lại có thể tạo tin trùng. Đọc phản hồi của mỗi lần thử lại: chờ đợi không đảm bảo được chấp nhận nếu một giới hạn khác đã bị chạm hoặc nơi gọi khác đang dùng hạn mức chung. Xem [Xử lý lỗi](/developers/vi/get-started/errors#khi-nào-thử-lại) cho các loại lỗi khác. ## Giới hạn tin nhắn Bộ kiểm tra tin nhắn hội thoại áp dụng các giới hạn sau cho tin nhắn gửi qua API: | Trường | Tối đa | Khi vượt | | --- | --- | --- | | `data.message.text` | 1.524.288 byte UTF-8 | `payload_too_large` | | `data.message.attachments` | 50 phần tử | `limit_exceeded` | | `data.message.fields` | 540 phần tử | `limit_exceeded` | | Mỗi `fields[].key` | 42.428 byte UTF-8 | `limit_exceeded` | | Mỗi `fields[].value` | 1.524.288 byte UTF-8 | `limit_exceeded` | Độ dài văn bản được tính bằng **byte**, không phải số ký tự hiển thị. Emoji và ký tự có dấu có thể dùng nhiều hơn một byte. Giới hạn văn bản áp dụng cho trường `text` của tin nhắn khi kiểm tra, không phải tổng kích thước yêu cầu JSON. Đây là ngưỡng kiểm tra của Subiz, không phải kích thước tin nhắn khuyến nghị hay cam kết gửi được trên mọi kênh. Hãy giữ tin nhắn ngắn. Các kênh đã kết nối có thể có thêm hạn chế về nội dung và media. Số lượng tệp đính kèm không phải hạn mức dung lượng tệp; xem [Tệp đính kèm](/developers/vi/messages/attachments). ## Giới hạn thuộc tính khách hàng Việc tạo khách hàng và cập nhật thuộc tính kiểm tra kích thước dữ liệu thuộc tính đầu vào. Luồng cập nhật thuộc tính thông thường kiểm tra giá trị đã chuẩn hóa: | Dữ liệu | Tối đa | | --- | --- | | Số thuộc tính trong dữ liệu được kiểm tra | 1.000 phần tử | | Tổng `text`, `datetime` và mọi `other_values` của mỗi thuộc tính | 2.048 byte UTF-8 | Vượt một trong hai giới hạn sẽ trả `payload_too_large`. Giảm dữ liệu bị ảnh hưởng trước khi thử lại. Tách một giá trị dài vào `other_values` không vượt qua được giới hạn tổng kích thước. Xem [Tạo khách hàng](/developers/vi/api-reference/users/create) và [Cập nhật thông tin khách hàng](/developers/vi/api-reference/users/update) để biết các trường được hỗ trợ. ## Hạn mức theo gói và kênh Điều tiết yêu cầu, kiểm tra dữ liệu và hạn mức của tài khoản hoặc kênh là các ràng buộc khác nhau. Trang này không định nghĩa hạn mức tin nhắn hằng tháng, hạn mức khách hàng hay giới hạn dung lượng tệp chung. Kiểm tra gói tài khoản và yêu cầu của kênh liên quan trước khi nhập dữ liệu lớn hoặc gửi tin hàng loạt. Nếu lỗi vẫn tiếp diễn, gửi cho bộ phận hỗ trợ Subiz endpoint, thời điểm gửi yêu cầu, tốc độ lưu lượng và chi tiết lỗi. Xóa access token và dữ liệu khách hàng trước khi gửi. --- # Errors Read API error responses, fix requests, and decide when to retry. API 4.0 · 4.1 Read the **HTTP status and JSON error body** together. Token, account, and agent message allowances return HTTP `429`. Invalid input, denied access, and some other operation-specific limits can return HTTP `400`. ## Error response The following example shows selected fields from a payload-size error. The sizes are illustrative: ```http HTTP/1.1 400 Bad Request Content-Type: application/json { "code": "payload_too_large,invalid_input,internal", "class": 400, "error": { "code": "payload_too_large,invalid_input,internal", "attrs": { "current_size": { "type": "number", "value": "2049" }, "maximum_size": { "type": "number", "value": "2048" } } } } ``` | Field | How to use it | | --- | --- | | `error.code` | Comma-separated error codes. Split on commas and match individual values. | | `error.message` | Human-readable messages, commonly keyed by `en_US` and `vi_VN`. Do not use message text for program logic. | | `error.attrs` | Optional details such as a field name, current size, or maximum size. Each value has a `type` and a string `value`; numeric values are encoded as strings. | | `error.id` | Error occurrence identifier, when present. Include it in a support report. | | `error.number` | Diagnostic grouping code, when present. Include it alongside the ID. | | Top-level `code` | Repeats the error codes in the standard response envelope. | | Top-level `class` | Legacy classification. Use the actual HTTP status and error codes instead. | The gateway can append `internal` to a more specific error. Its presence alone does **not** mean a request is safe to retry. In the example above, reduce the attribute size first. ## Common error codes This is a practical subset, not an exhaustive list. A response can contain several of these codes. | Code | What to do | | --- | --- | | `invalid_input` | Check the JSON body, required fields, and value types. | | `invalid_field` | Correct the named field, such as an unsupported message format. | | `access_deny` | Check the token's account and the issuing agent's permissions or conversation access. | | `access_token_expired` | Create a replacement token and update your integration. | | `locked_agent`, `locked_account` | Ask an account administrator to check the agent or account status. | | `missing_resource` | Check the resource ID and account. Repeating the same request will not create the missing resource. | | `conversation_ended` | Check the conversation state before sending an ordinary message. | | `invalid_integration` | Check that the conversation's channel integration is still connected. | | `payload_too_large` | Reduce the data identified by the error. See [Usage limits](/developers/get-started/usage-limits). | | `limit_exceeded` | Check the affected count or capacity. Waiting does not fix a structural limit. | | `rate_limit` | Slow down. Token, account, and agent message limits return HTTP `429` with `Retry-After` in seconds; daily exhaustion requires waiting until 00:00 UTC. | | `service_unavailable`, `timeout`, `retryable` | Treat as potentially temporary; follow the retry guidance below. | For authentication problems, [test the token with `/4.1/me`](/developers/get-started/authentication#test-your-access-token). A successful token check does not grant access to every operation. ## HTTP status codes | Status | Handling | | --- | --- | | `400` | Inspect `error.code`. Authentication, permissions, validation, and some limits use this status. | | `429` | Token or account usage limit, or another throttle. Honor `Retry-After` and reduce traffic. The body's legacy `class` may still be `400`. | | `500` | Server failure. The standard gateway uses this for `service_unavailable`, among other failures. | Also handle other non-success statuses and network failures. A proxy or failed connection may return an empty or non-JSON body. Keep the status and a sanitized response excerpt instead of failing while parsing the error. ## When to retry - **Invalid data or denied access:** fix the request, token, or permissions first. - **Rate limiting:** queue the work and use [delayed retries](/developers/get-started/usage-limits#retry-safely). - **Temporary failure on a read:** use increasing delays with jitter and a fixed attempt limit. - **Timeout or lost response on a write:** the operation may have succeeded. Check the resulting state before resubmitting. For a message send, inspect [message history](/developers/api-reference/conversations/history) or received [webhook events](/developers/webhooks/payloads). If the outcome remains unclear, stop automatic retries and reconcile it. Do not assume every endpoint supports an idempotency key. ## Get help Include the HTTP method and endpoint, request time with timezone, status, and `error.code`. Add `error.id` and `error.number` if available. Share only the relevant, sanitized request fields; never include the access token. --- # Xử lý lỗi Đọc phản hồi lỗi API, sửa yêu cầu và quyết định khi nào thử lại. API 4.0 · 4.1 Đọc **mã trạng thái HTTP và body lỗi JSON** cùng nhau. Hạn mức theo token, tài khoản và tin nhắn của agent trả HTTP `429`. Dữ liệu không hợp lệ, bị từ chối truy cập và một số giới hạn riêng của từng thao tác có thể trả HTTP `400`. ## Phản hồi lỗi Ví dụ sau hiển thị một số trường của lỗi vượt kích thước dữ liệu. Các kích thước chỉ mang tính minh họa: ```http HTTP/1.1 400 Bad Request Content-Type: application/json { "code": "payload_too_large,invalid_input,internal", "class": 400, "error": { "code": "payload_too_large,invalid_input,internal", "attrs": { "current_size": { "type": "number", "value": "2049" }, "maximum_size": { "type": "number", "value": "2048" } } } } ``` | Trường | Cách dùng | | --- | --- | | `error.code` | Các mã lỗi phân tách bằng dấu phẩy. Tách theo dấu phẩy và so khớp từng giá trị. | | `error.message` | Thông điệp dễ đọc, thường theo khóa `en_US` và `vi_VN`. Không dùng nội dung thông điệp cho logic chương trình. | | `error.attrs` | Chi tiết tùy chọn như tên trường, kích thước hiện tại hoặc kích thước tối đa. Mỗi giá trị có `type` và `value` dạng chuỗi; giá trị số cũng được mã hóa thành chuỗi. | | `error.id` | Định danh của lần lỗi, nếu có. Gửi kèm khi báo cáo hỗ trợ. | | `error.number` | Mã nhóm chẩn đoán, nếu có. Gửi kèm cùng ID. | | `code` ở cấp ngoài cùng | Lặp lại các mã lỗi trong phần bao phản hồi chuẩn. | | `class` ở cấp ngoài cùng | Phân loại cũ. Hãy dùng mã trạng thái HTTP thực tế và mã lỗi. | Gateway có thể thêm `internal` vào một lỗi cụ thể hơn. Chỉ riêng sự có mặt của nó **không** có nghĩa là có thể thử lại an toàn. Trong ví dụ trên, hãy giảm kích thước thuộc tính trước. ## Mã lỗi thường gặp Đây là một tập con thực dụng, không phải danh sách đầy đủ. Một phản hồi có thể chứa nhiều mã trong số này. | Mã | Cần làm gì | | --- | --- | | `invalid_input` | Kiểm tra body JSON, trường bắt buộc và kiểu giá trị. | | `invalid_field` | Sửa trường được nêu tên, ví dụ định dạng tin nhắn không được hỗ trợ. | | `access_deny` | Kiểm tra tài khoản của token và quyền của agent tạo token, hoặc quyền truy cập hội thoại. | | `access_token_expired` | Tạo token thay thế và cập nhật tích hợp. | | `locked_agent`, `locked_account` | Nhờ quản trị viên tài khoản kiểm tra trạng thái agent hoặc tài khoản. | | `missing_resource` | Kiểm tra ID tài nguyên và tài khoản. Lặp lại cùng yêu cầu sẽ không tạo ra tài nguyên còn thiếu. | | `conversation_ended` | Kiểm tra trạng thái hội thoại trước khi gửi tin nhắn thông thường. | | `invalid_integration` | Kiểm tra tích hợp kênh của hội thoại vẫn còn kết nối. | | `payload_too_large` | Giảm dữ liệu được lỗi chỉ ra. Xem [Giới hạn sử dụng](/developers/vi/get-started/usage-limits). | | `limit_exceeded` | Kiểm tra số lượng hoặc dung lượng bị ảnh hưởng. Chờ đợi không khắc phục được giới hạn về cấu trúc. | | `rate_limit` | Giảm tốc độ. Giới hạn theo token, tài khoản và tin nhắn của agent trả HTTP `429` kèm `Retry-After` tính bằng giây; hết hạn mức ngày thì phải chờ tới 00:00 UTC. | | `service_unavailable`, `timeout`, `retryable` | Coi là có thể tạm thời; làm theo hướng dẫn thử lại bên dưới. | Với lỗi xác thực, [kiểm tra token bằng `/4.1/me`](/developers/vi/get-started/authentication#kiểm-tra-access-token). Kiểm tra token thành công không có nghĩa là được truy cập mọi thao tác. ## Mã trạng thái HTTP | Trạng thái | Cách xử lý | | --- | --- | | `400` | Xem `error.code`. Xác thực, phân quyền, kiểm tra dữ liệu và một số giới hạn dùng trạng thái này. | | `429` | Giới hạn sử dụng theo token hoặc tài khoản, hoặc một cơ chế điều tiết khác. Tuân theo `Retry-After` và giảm lưu lượng. Trường `class` cũ trong body vẫn có thể là `400`. | | `500` | Lỗi máy chủ. Gateway chuẩn dùng trạng thái này cho `service_unavailable`, cùng các lỗi khác. | Hãy xử lý cả các trạng thái không thành công khác và lỗi mạng. Proxy hoặc kết nối lỗi có thể trả body rỗng hoặc không phải JSON. Lưu lại trạng thái và một đoạn phản hồi đã lược bỏ dữ liệu nhạy cảm thay vì thất bại khi phân tích lỗi. ## Khi nào thử lại - **Dữ liệu không hợp lệ hoặc bị từ chối truy cập:** sửa yêu cầu, token hoặc quyền trước. - **Bị giới hạn tốc độ:** đưa công việc vào hàng đợi và dùng [thử lại có độ trễ](/developers/vi/get-started/usage-limits#thử-lại-an-toàn). - **Lỗi tạm thời khi đọc:** dùng độ trễ tăng dần có jitter và giới hạn số lần thử cố định. - **Hết thời gian chờ hoặc mất phản hồi khi ghi:** thao tác có thể đã thành công. Kiểm tra trạng thái kết quả trước khi gửi lại. Với việc gửi tin nhắn, kiểm tra [lịch sử tin nhắn](/developers/vi/api-reference/conversations/history) hoặc các [sự kiện webhook](/developers/vi/webhooks/payloads) đã nhận. Nếu vẫn chưa rõ kết quả, dừng thử lại tự động và đối chiếu. Đừng giả định mọi endpoint đều hỗ trợ khóa idempotency. ## Nhận hỗ trợ Gửi kèm phương thức HTTP và endpoint, thời điểm gửi yêu cầu kèm múi giờ, trạng thái và `error.code`. Thêm `error.id` và `error.number` nếu có. Chỉ chia sẻ các trường liên quan của yêu cầu đã lược bỏ dữ liệu nhạy cảm; không bao giờ gửi kèm access token. --- # User and attribute format Understand the customer object and how attribute values are stored. API 4.0 · 4.1 In the API, a customer is a `User`. Most customer data, such as name, email, and phone, is stored in its `attributes` array. This page describes both objects. All IDs and values below are illustrative. ## User The examples below are selected fields of a `User` object, as returned by [Get customer details](/developers/api-reference/users/retrieve): ```json { "id": "user_example", "account_id": "account_example", "channel": "facebook", "channel_source": "page_example", "profile_id": "profile_example", "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "emails", "text": "alex@example.com" } ], "created": 1763107200000, "updated": 1763193600000 } ``` | Field | Type | Description | | --- | --- | --- | | `id` | string | Subiz user ID. Use it in customer and message endpoints. | | `account_id` | string | Account the customer belongs to. | | `attributes` | array | Customer data. See [Attribute](#attribute). | | `channel` | string | Channel the customer came from, such as `facebook` or `zalo`. | | `channel_source` | string | Connected page or account on that channel. | | `profile_id` | string | Customer's ID on that channel. | | `labels` | array | Labels added to the customer in Subiz. | | `created`, `updated` | integer | Unix timestamps in milliseconds. | `channel`, `channel_source`, and `profile_id` together form the customer's channel identity. Keep them separate from the Subiz `id`. See [Find or create by channel identity](/developers/api-reference/users/identity). The object has more fields than shown. Ignore fields your integration does not use. ## Attribute Each item in `attributes` stores one piece of customer data: ```json { "key": "fullname", "text": "Alex Example", "modified": 1763193600000 } ``` | Field | Type | Description | | --- | --- | --- | | `key` | string | Attribute key, such as `fullname`. Identifies the attribute. | | `type` | string | Read-only. `text`, `number`, `boolean`, or `datetime`. | | `text` | string | Value of a `text` attribute. | | `number` | number | Value of a `number` attribute. | | `boolean` | boolean | Value of a `boolean` attribute. | | `datetime` | string | Value of a `datetime` attribute, in RFC 3339 format. | | `other_values` | array of strings | Additional values of a text attribute, such as more email addresses. | | `modified` | integer | When the value last changed, in Unix milliseconds. | Each attribute uses exactly one value field, chosen by its type. In requests, send only `key` and the matching value field. ## Value types Use the value field that matches the attribute's type. **Text** — names, emails, phone numbers, and other strings: ```json { "key": "job_title", "text": "Purchasing manager" } ``` **Number** — a decimal number, not a string: ```json { "key": "loyalty_points", "number": 1250 } ``` **Boolean** — `true` or `false`: ```json { "key": "newsletter_opt_in", "boolean": true } ``` **Datetime** — an RFC 3339 date-time string, including the time zone: ```json { "key": "birthdate", "datetime": "1990-05-20T00:00:00Z" } ``` `loyalty_points` and `newsletter_opt_in` are examples of custom attributes. They exist only if your account defines them. ## Multiple values Some text attributes, such as `emails` and `phones`, can hold more than one value. The primary value is in `text`; the others are in `other_values`: ```json { "key": "emails", "text": "alex@example.com", "other_values": [ "alex.work@example.com" ] } ``` When you need a single email or phone number, use `text`. To find a customer by any of their addresses, check both fields. ## Built-in attributes Every account has these attributes: | Key | Type | Description | | --- | --- | --- | | `fullname` | text | Full name. | | `display_name` | text | Display name. | | `emails` | text | Email addresses. | | `phones` | text | Phone numbers. | | `address`, `city`, `district` | text | Address. | | `gender` | text | Gender. | | `job_title` | text | Job title. | | `birthdate` | datetime | Date of birth. | | `avatar_url` | text | Profile picture URL. | | `timezone` | text | Customer's time zone. | Subiz maintains some built-in attributes and they are read-only, for example `created`, `modified`, `seen`, `total_conversations`, and `last_message_sent`. You can read them, but you cannot change them. ## Custom attributes Your account can define its own attributes in addition to the built-in ones. Use the exact key from your account, and send values of the attribute's type. ## Read attributes safely - **Find attributes by `key`.** The order of the array is not fixed. - **Handle missing attributes.** An attribute can be absent when the customer has no value for it. - **Expect omitted defaults.** Empty strings, `0`, and `false` are omitted from JSON. A `boolean` attribute without a `boolean` field is `false`. - **Read by type.** Do not assume every value is in `text`. ## Write attributes [Create a customer](/developers/api-reference/users/create) and [Update customer details](/developers/api-reference/users/update) take an `attributes` array in this format: ```json { "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "birthdate", "datetime": "1990-05-20T00:00:00Z" } ] } ``` Send only `key` and the value. Read-only fields such as `type` and `modified` are set by Subiz. Size limits apply; see [Customer attribute limits](/developers/get-started/usage-limits#customer-attribute-limits). --- # Định dạng khách hàng và thuộc tính Hiểu đối tượng khách hàng và cách lưu giá trị thuộc tính. API 4.0 · 4.1 Trong API, khách hàng là một `User`. Phần lớn dữ liệu khách hàng, như tên, email và số điện thoại, được lưu trong mảng `attributes`. Trang này mô tả cả hai đối tượng. Mọi ID và giá trị bên dưới chỉ mang tính minh họa. ## User Ví dụ dưới đây là một số trường của đối tượng `User`, như được trả về bởi [Lấy thông tin khách hàng](/developers/vi/api-reference/users/retrieve): ```json { "id": "user_example", "account_id": "account_example", "channel": "facebook", "channel_source": "page_example", "profile_id": "profile_example", "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "emails", "text": "alex@example.com" } ], "created": 1763107200000, "updated": 1763193600000 } ``` | Trường | Kiểu | Mô tả | | --- | --- | --- | | `id` | string | ID user Subiz. Dùng trong các endpoint khách hàng và tin nhắn. | | `account_id` | string | Tài khoản mà khách hàng thuộc về. | | `attributes` | array | Dữ liệu khách hàng. Xem [Thuộc tính](#thuộc-tính). | | `channel` | string | Kênh khách hàng đến từ, như `facebook` hoặc `zalo`. | | `channel_source` | string | Trang hoặc tài khoản đã kết nối trên kênh đó. | | `profile_id` | string | ID của khách hàng trên kênh đó. | | `labels` | array | Nhãn đã gắn cho khách hàng trong Subiz. | | `created`, `updated` | integer | Dấu thời gian Unix tính bằng mili giây. | `channel`, `channel_source` và `profile_id` cùng tạo thành định danh kênh của khách hàng. Không nhầm chúng với `id` của Subiz. Xem [Tìm hoặc tạo theo định danh kênh](/developers/vi/api-reference/users/identity). Đối tượng có nhiều trường hơn ví dụ. Bỏ qua các trường tích hợp của bạn không dùng. ## Thuộc tính Mỗi phần tử trong `attributes` lưu một mẩu dữ liệu khách hàng: ```json { "key": "fullname", "text": "Alex Example", "modified": 1763193600000 } ``` | Trường | Kiểu | Mô tả | | --- | --- | --- | | `key` | string | Khóa thuộc tính, như `fullname`. Xác định thuộc tính. | | `type` | string | Chỉ đọc. `text`, `number`, `boolean` hoặc `datetime`. | | `text` | string | Giá trị của thuộc tính `text`. | | `number` | number | Giá trị của thuộc tính `number`. | | `boolean` | boolean | Giá trị của thuộc tính `boolean`. | | `datetime` | string | Giá trị của thuộc tính `datetime`, theo định dạng RFC 3339. | | `other_values` | array of strings | Các giá trị bổ sung của thuộc tính văn bản, như thêm địa chỉ email. | | `modified` | integer | Thời điểm giá trị thay đổi gần nhất, tính bằng mili giây Unix. | Mỗi thuộc tính dùng đúng một trường giá trị, chọn theo kiểu của nó. Trong yêu cầu, chỉ gửi `key` và trường giá trị tương ứng. ## Kiểu giá trị Dùng trường giá trị khớp với kiểu của thuộc tính. **Text** — tên, email, số điện thoại và các chuỗi khác: ```json { "key": "job_title", "text": "Purchasing manager" } ``` **Number** — số thập phân, không phải chuỗi: ```json { "key": "loyalty_points", "number": 1250 } ``` **Boolean** — `true` hoặc `false`: ```json { "key": "newsletter_opt_in", "boolean": true } ``` **Datetime** — chuỗi ngày giờ RFC 3339, có múi giờ: ```json { "key": "birthdate", "datetime": "1990-05-20T00:00:00Z" } ``` `loyalty_points` và `newsletter_opt_in` là ví dụ thuộc tính tùy chỉnh. Chúng chỉ tồn tại nếu tài khoản của bạn định nghĩa. ## Nhiều giá trị Một số thuộc tính văn bản, như `emails` và `phones`, có thể chứa nhiều giá trị. Giá trị chính nằm trong `text`; các giá trị khác nằm trong `other_values`: ```json { "key": "emails", "text": "alex@example.com", "other_values": [ "alex.work@example.com" ] } ``` Khi chỉ cần một email hoặc số điện thoại, dùng `text`. Để tìm khách hàng theo bất kỳ địa chỉ nào của họ, kiểm tra cả hai trường. ## Thuộc tính có sẵn Mọi tài khoản đều có các thuộc tính sau: | Khóa | Kiểu | Mô tả | | --- | --- | --- | | `fullname` | text | Họ và tên. | | `display_name` | text | Tên hiển thị. | | `emails` | text | Địa chỉ email. | | `phones` | text | Số điện thoại. | | `address`, `city`, `district` | text | Địa chỉ. | | `gender` | text | Giới tính. | | `job_title` | text | Chức danh. | | `birthdate` | datetime | Ngày sinh. | | `avatar_url` | text | URL ảnh đại diện. | | `timezone` | text | Múi giờ của khách hàng. | Subiz tự quản lý một số thuộc tính có sẵn và chúng là chỉ đọc, ví dụ `created`, `modified`, `seen`, `total_conversations` và `last_message_sent`. Bạn đọc được nhưng không thay đổi được chúng. ## Thuộc tính tùy chỉnh Tài khoản của bạn có thể định nghĩa thêm thuộc tính riêng ngoài các thuộc tính có sẵn. Dùng đúng khóa trong tài khoản và gửi giá trị theo kiểu của thuộc tính. ## Đọc thuộc tính an toàn - **Tìm thuộc tính theo `key`.** Thứ tự của mảng không cố định. - **Xử lý thuộc tính bị thiếu.** Thuộc tính có thể không có khi khách hàng chưa có giá trị. - **Lường trước giá trị mặc định bị lược bỏ.** Chuỗi rỗng, `0` và `false` bị lược khỏi JSON. Thuộc tính `boolean` không có trường `boolean` nghĩa là `false`. - **Đọc theo kiểu.** Đừng giả định mọi giá trị đều nằm trong `text`. ## Ghi thuộc tính [Tạo khách hàng](/developers/vi/api-reference/users/create) và [Cập nhật thông tin khách hàng](/developers/vi/api-reference/users/update) nhận mảng `attributes` theo định dạng này: ```json { "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "birthdate", "datetime": "1990-05-20T00:00:00Z" } ] } ``` Chỉ gửi `key` và giá trị. Các trường chỉ đọc như `type` và `modified` do Subiz đặt. Có giới hạn kích thước; xem [Giới hạn thuộc tính khách hàng](/developers/vi/get-started/usage-limits#giới-hạn-thuộc-tính-khách-hàng). --- # Create a customer Create a customer record with attributes and an optional channel identity. API 4.0 In the API, a customer is a **user**. Agents are your staff and are not created here. Use this endpoint to add a customer from your system, such as a CRM contact or a new sign-up. If the customer comes from a connected channel such as Facebook or Zalo, use [Find or create by channel identity](/developers/api-reference/users/identity) instead to avoid duplicates. ## Before you begin - Get a [Bearer access token](/developers/get-started/authentication). The customer is created in the token's account. - Use attribute keys defined in your account, with values of the matching type. ## Request body | Field | Type | Description | | --- | --- | --- | | `attributes` | array | Customer data, one item per attribute. | | `attributes[].key` | string | Attribute key, such as `fullname`. | | `attributes[].text` | string | Value for text attributes. Use `number`, `boolean`, or `datetime` for other types. | | `channel` | string | Optional. Channel of an external identity, such as `facebook`. | | `channel_source` | string | Optional. Connected page or account on that channel. | | `profile_id` | string | Optional. Customer's ID on that channel. | Other fields, such as `id` or `account_id`, are ignored. ```json { "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "emails", "text": "alex@example.com" }, { "key": "phones", "text": "+84900000000" } ] } ``` ## Common attributes These built-in keys exist in every account. See [User and attribute format](/developers/users/format) for value types and multiple values. | Key | Type | Description | | --- | --- | --- | | `fullname` | text | Full name. | | `display_name` | text | Display name. | | `emails` | text | Email address. | | `phones` | text | Phone number. | | `address`, `city`, `district` | text | Address. | | `gender` | text | Gender. | | `job_title` | text | Job title. | | `birthdate` | datetime | Date of birth. | Some built-in attributes, such as `created` or `last_message_sent`, are set by Subiz and are read-only. ## Response A successful request returns HTTP `200` with the new customer. Selected fields: ```json { "id": "user_example", "account_id": "account_example", "attributes": [ { "key": "fullname", "text": "Alex Example" } ] } ``` Store the `id`. You need it to [read](/developers/api-reference/users/retrieve), [update](/developers/api-reference/users/update), or [message](/developers/api-reference/messages/send-to-user) this customer. Each request creates a new record. To change an existing customer, use [Update customer details](/developers/api-reference/users/update) instead of creating it again. ## Limits and errors A request can contain up to 1,000 attributes, and each value up to 2,048 bytes. See [Customer attribute limits](/developers/get-started/usage-limits#customer-attribute-limits) and [Errors](/developers/get-started/errors). ## HTTP request Replace `YOUR_ACCESS_TOKEN` with your token. ```http POST https://api.subiz.com.vn/4.0/users Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "attributes": [ { "key": "fullname", "text": "Alex Example" } ] } ``` --- # Tạo khách hàng Tạo hồ sơ khách hàng với thuộc tính và định danh kênh tùy chọn. API 4.0 Trong API, khách hàng là một **user**. Agent là agent của bạn và không được tạo ở đây. Dùng endpoint này để thêm khách hàng từ hệ thống của bạn, như một liên hệ trong CRM hoặc người mới đăng ký. Nếu khách hàng đến từ kênh đã kết nối như Facebook hoặc Zalo, hãy dùng [Tìm hoặc tạo theo định danh kênh](/developers/vi/api-reference/users/identity) để tránh trùng lặp. ## Trước khi bắt đầu - Lấy [Bearer access token](/developers/vi/get-started/authentication). Khách hàng được tạo trong tài khoản của token. - Dùng khóa thuộc tính đã định nghĩa trong tài khoản, với giá trị đúng kiểu. ## Body yêu cầu | Trường | Kiểu | Mô tả | | --- | --- | --- | | `attributes` | array | Dữ liệu khách hàng, mỗi phần tử là một thuộc tính. | | `attributes[].key` | string | Khóa thuộc tính, như `fullname`. | | `attributes[].text` | string | Giá trị cho thuộc tính văn bản. Dùng `number`, `boolean` hoặc `datetime` cho các kiểu khác. | | `channel` | string | Tùy chọn. Kênh của định danh bên ngoài, như `facebook`. | | `channel_source` | string | Tùy chọn. Trang hoặc tài khoản đã kết nối trên kênh đó. | | `profile_id` | string | Tùy chọn. ID của khách hàng trên kênh đó. | Các trường khác, như `id` hoặc `account_id`, bị bỏ qua. ```json { "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "emails", "text": "alex@example.com" }, { "key": "phones", "text": "+84900000000" } ] } ``` ## Thuộc tính thường dùng Các khóa có sẵn này tồn tại trong mọi tài khoản. Xem [Định dạng khách hàng và thuộc tính](/developers/vi/users/format) để biết kiểu giá trị và cách lưu nhiều giá trị. | Khóa | Kiểu | Mô tả | | --- | --- | --- | | `fullname` | text | Họ và tên. | | `display_name` | text | Tên hiển thị. | | `emails` | text | Địa chỉ email. | | `phones` | text | Số điện thoại. | | `address`, `city`, `district` | text | Địa chỉ. | | `gender` | text | Giới tính. | | `job_title` | text | Chức danh. | | `birthdate` | datetime | Ngày sinh. | Một số thuộc tính có sẵn, như `created` hoặc `last_message_sent`, do Subiz đặt và là chỉ đọc. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng khách hàng mới. Một số trường: ```json { "id": "user_example", "account_id": "account_example", "attributes": [ { "key": "fullname", "text": "Alex Example" } ] } ``` Lưu lại `id`. Bạn cần nó để [đọc](/developers/vi/api-reference/users/retrieve), [cập nhật](/developers/vi/api-reference/users/update) hoặc [nhắn tin](/developers/vi/api-reference/messages/send-to-user) cho khách hàng này. Mỗi yêu cầu tạo một bản ghi mới. Để thay đổi khách hàng đã có, dùng [Cập nhật thông tin khách hàng](/developers/vi/api-reference/users/update) thay vì tạo lại. ## Giới hạn và lỗi Một yêu cầu có thể chứa tối đa 1.000 thuộc tính, và mỗi giá trị tối đa 2.048 byte. Xem [Giới hạn thuộc tính khách hàng](/developers/vi/get-started/usage-limits#giới-hạn-thuộc-tính-khách-hàng) và [Xử lý lỗi](/developers/vi/get-started/errors). ## Yêu cầu HTTP Thay `YOUR_ACCESS_TOKEN` bằng token của bạn. ```http POST https://api.subiz.com.vn/4.0/users Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "attributes": [ { "key": "fullname", "text": "Alex Example" } ] } ``` --- # Get customer details Read a customer's profile and attributes by Subiz user ID. API 4.0 Use this endpoint to read a customer's current profile, for example before syncing it to your CRM. ## Request Send a `GET` request with the customer's Subiz user ID in the path. There is no request body. | Parameter | Type | Description | | --- | --- | --- | | `uid` (path) | string | Subiz user ID, as returned when the customer was created. | The ID must be a Subiz user ID. Other values, such as an email address, return an error. If you only know the customer's channel identity, use [Find or create by channel identity](/developers/api-reference/users/identity). ## Response A successful request returns HTTP `200` with the customer. Selected fields: ```json { "id": "user_example", "account_id": "account_example", "channel": "facebook", "channel_source": "page_example", "profile_id": "profile_example", "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "emails", "text": "alex@example.com" } ] } ``` | Field | Description | | --- | --- | | `id` | Subiz user ID. | | `attributes` | Customer data. Find each attribute by `key`, not by position. | | `channel`, `channel_source`, `profile_id` | Channel identity, when the customer came from a connected channel. | | `created`, `updated` | Unix timestamps in milliseconds. | Read the value field that matches the attribute type: `text`, `number`, `boolean`, or `datetime`. Empty fields are omitted, and the object has more fields than shown. ## HTTP request Replace `YOUR_UID` with the user ID and `YOUR_ACCESS_TOKEN` with your token. ```http GET https://api.subiz.com.vn/4.0/users/YOUR_UID Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Lấy thông tin khách hàng Đọc hồ sơ và thuộc tính của khách hàng theo ID user Subiz. API 4.0 Dùng endpoint này để đọc hồ sơ hiện tại của khách hàng, ví dụ trước khi đồng bộ sang CRM. ## Yêu cầu Gửi yêu cầu `GET` với ID user Subiz của khách hàng trong đường dẫn. Không có body. | Tham số | Kiểu | Mô tả | | --- | --- | --- | | `uid` (đường dẫn) | string | ID user Subiz, như được trả về khi tạo khách hàng. | ID phải là ID user Subiz. Giá trị khác, như địa chỉ email, sẽ trả lỗi. Nếu chỉ biết định danh kênh của khách hàng, dùng [Tìm hoặc tạo theo định danh kênh](/developers/vi/api-reference/users/identity). ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng khách hàng. Một số trường: ```json { "id": "user_example", "account_id": "account_example", "channel": "facebook", "channel_source": "page_example", "profile_id": "profile_example", "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "emails", "text": "alex@example.com" } ] } ``` | Trường | Mô tả | | --- | --- | | `id` | ID user Subiz. | | `attributes` | Dữ liệu khách hàng. Tìm từng thuộc tính theo `key`, không theo vị trí. | | `channel`, `channel_source`, `profile_id` | Định danh kênh, khi khách hàng đến từ kênh đã kết nối. | | `created`, `updated` | Dấu thời gian Unix tính bằng mili giây. | Đọc trường giá trị khớp với kiểu thuộc tính: `text`, `number`, `boolean` hoặc `datetime`. Trường rỗng bị lược bỏ, và đối tượng có nhiều trường hơn ví dụ. ## Yêu cầu HTTP Thay `YOUR_UID` bằng ID user và `YOUR_ACCESS_TOKEN` bằng token của bạn. ```http GET https://api.subiz.com.vn/4.0/users/YOUR_UID Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Update customer details Change a customer's attributes, such as name, email, or phone. API 4.1 Use this endpoint to keep a customer in sync with your system, for example after the customer changes their email in your CRM. ## Request body Send only the attributes you want to change. | Field | Type | Description | | --- | --- | --- | | `uid` (path) | string | Subiz user ID. | | `attributes` | array | Attributes to change. Each item has a `key` and a value. | | `attributes[].key` | string | Attribute key, such as `fullname`. See [Common attributes](/developers/api-reference/users/create#common-attributes). | | `attributes[].text` | string | New value for text attributes. Use `number`, `boolean`, or `datetime` for other types; see [Value types](/developers/users/format#value-types). | ```json { "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "emails", "text": "alex.new@example.com" } ] } ``` Subiz reads only a few fields from the body, mainly `attributes`. Other fields, such as `id`, `created`, or `labels`, are ignored, so you cannot change them here. Do not send back a whole customer object you read earlier. ## Response A successful request returns HTTP `200` with the updated customer. Selected fields: ```json { "id": "user_example", "account_id": "account_example", "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "emails", "text": "alex.new@example.com" } ] } ``` When customer data changes, subscribed webhooks receive a `user_info_updated` event. Rapid updates can be combined into one event. See [Customer information updated](/developers/webhooks/payloads#customer-information-updated). ## Limits and errors A request can contain up to 1,000 attributes, and each value up to 2,048 bytes. See [Customer attribute limits](/developers/get-started/usage-limits#customer-attribute-limits). An invalid `uid` returns an error. If you only have the customer's channel identity, first get the user ID with [Find or create by channel identity](/developers/api-reference/users/identity). See [Errors](/developers/get-started/errors) for the error format. ## HTTP request Replace `YOUR_UID` with the user ID and `YOUR_ACCESS_TOKEN` with your token. ```http POST https://api.subiz.com.vn/4.1/users/YOUR_UID Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "attributes": [ { "key": "fullname", "text": "Alex Example" } ] } ``` --- # Cập nhật thông tin khách hàng Thay đổi thuộc tính của khách hàng, như tên, email hoặc số điện thoại. API 4.1 Dùng endpoint này để giữ khách hàng đồng bộ với hệ thống của bạn, ví dụ sau khi khách hàng đổi email trong CRM. ## Body yêu cầu Chỉ gửi các thuộc tính bạn muốn thay đổi. | Trường | Kiểu | Mô tả | | --- | --- | --- | | `uid` (đường dẫn) | string | ID user Subiz. | | `attributes` | array | Các thuộc tính cần thay đổi. Mỗi phần tử có `key` và một giá trị. | | `attributes[].key` | string | Khóa thuộc tính, như `fullname`. Xem [Thuộc tính thường dùng](/developers/vi/api-reference/users/create#thuộc-tính-thường-dùng). | | `attributes[].text` | string | Giá trị mới cho thuộc tính văn bản. Dùng `number`, `boolean` hoặc `datetime` cho kiểu khác; xem [Kiểu giá trị](/developers/vi/users/format#kiểu-giá-trị). | ```json { "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "emails", "text": "alex.new@example.com" } ] } ``` Subiz chỉ đọc một vài trường từ body, chủ yếu là `attributes`. Các trường khác, như `id`, `created` hoặc `labels`, bị bỏ qua nên bạn không thể thay đổi chúng ở đây. Đừng gửi lại toàn bộ đối tượng khách hàng đã đọc trước đó. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng khách hàng đã cập nhật. Một số trường: ```json { "id": "user_example", "account_id": "account_example", "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "emails", "text": "alex.new@example.com" } ] } ``` Khi dữ liệu khách hàng thay đổi, webhook đã đăng ký nhận sự kiện `user_info_updated`. Các cập nhật liên tiếp nhanh có thể được gộp thành một sự kiện. Xem [Thông tin khách hàng được cập nhật](/developers/vi/webhooks/payloads#thông-tin-khách-hàng-được-cập-nhật). ## Giới hạn và lỗi Một yêu cầu có thể chứa tối đa 1.000 thuộc tính, và mỗi giá trị tối đa 2.048 byte. Xem [Giới hạn thuộc tính khách hàng](/developers/vi/get-started/usage-limits#giới-hạn-thuộc-tính-khách-hàng). `uid` không hợp lệ sẽ trả lỗi. Nếu chỉ có định danh kênh của khách hàng, trước tiên lấy ID user bằng [Tìm hoặc tạo theo định danh kênh](/developers/vi/api-reference/users/identity). Xem [Xử lý lỗi](/developers/vi/get-started/errors) để biết định dạng lỗi. ## Yêu cầu HTTP Thay `YOUR_UID` bằng ID user và `YOUR_ACCESS_TOKEN` bằng token của bạn. ```http POST https://api.subiz.com.vn/4.1/users/YOUR_UID Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "attributes": [ { "key": "fullname", "text": "Alex Example" } ] } ``` --- # Find or create by channel identity Get the Subiz customer for a Facebook, Zalo, or other channel profile. API 4.1 Use this endpoint when you know a customer's identity on a channel, such as their Facebook profile on your page, but not their Subiz user ID. It returns the existing customer, or creates one if none exists. ## Channel identity A channel identity has three parts, all in the URL path: | Parameter | Type | Description | | --- | --- | --- | | `accid` (path) | string | Your account ID. | | `channel` (path) | string | Channel, such as `facebook` or `zalo`. | | `source` (path) | string | Connected page or account on that channel, such as a Facebook page ID. | | `id` (path) | string | Customer's profile ID on that channel. | Use values from your connected integration. Do not put a Subiz user ID in `id`. There is no request body. ## Find without creating Use `GET` on the same path to look up a customer without creating one: ```http GET https://api.subiz.com.vn/4.1/accounts/YOUR_ACCID/contact-profiles/YOUR_CHANNEL/sources/YOUR_SOURCE/YOUR_ID Authorization: Bearer YOUR_ACCESS_TOKEN ``` Use `POST`, shown at the end of this page, to find the customer or create them. ## Response Both methods return HTTP `200` with the customer. Selected fields: ```json { "id": "user_example", "account_id": "account_example", "channel": "facebook", "channel_source": "page_example", "profile_id": "profile_example", "attributes": [ { "key": "fullname", "text": "Alex Example" } ] } ``` Store the Subiz `id` together with the channel identity. Use the `id` to [get](/developers/api-reference/users/retrieve) or [update](/developers/api-reference/users/update) the customer. Subiz may normalize or merge customer identities. If a lookup fails temporarily, retry it rather than creating a separate customer with [Create a customer](/developers/api-reference/users/create). ## Send without resolving first To message a customer by channel identity, you can skip this step. [Send to a customer](/developers/api-reference/messages/send-to-user#identify-the-customer) accepts `channel`, `channel_source`, and `profile_id` directly. ## HTTP request Replace `YOUR_ACCID`, `YOUR_CHANNEL`, `YOUR_SOURCE`, `YOUR_ID`, and `YOUR_ACCESS_TOKEN` with your values. ```http POST https://api.subiz.com.vn/4.1/accounts/YOUR_ACCID/contact-profiles/YOUR_CHANNEL/sources/YOUR_SOURCE/YOUR_ID Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json {} ``` --- # Tìm hoặc tạo theo định danh kênh Lấy khách hàng Subiz tương ứng với hồ sơ Facebook, Zalo hoặc kênh khác. API 4.1 Dùng endpoint này khi bạn biết định danh của khách hàng trên một kênh, như hồ sơ Facebook của họ trên trang của bạn, nhưng chưa biết ID user Subiz. Endpoint trả về khách hàng đã có, hoặc tạo mới nếu chưa có. ## Định danh kênh Định danh kênh gồm ba phần, đều nằm trong đường dẫn URL: | Tham số | Kiểu | Mô tả | | --- | --- | --- | | `accid` (đường dẫn) | string | ID tài khoản của bạn. | | `channel` (đường dẫn) | string | Kênh, như `facebook` hoặc `zalo`. | | `source` (đường dẫn) | string | Trang hoặc tài khoản đã kết nối trên kênh đó, như ID trang Facebook. | | `id` (đường dẫn) | string | ID hồ sơ của khách hàng trên kênh đó. | Dùng giá trị từ tích hợp đã kết nối. Không đặt ID user Subiz vào `id`. Không có body. ## Tìm mà không tạo Dùng `GET` trên cùng đường dẫn để tìm khách hàng mà không tạo mới: ```http GET https://api.subiz.com.vn/4.1/accounts/YOUR_ACCID/contact-profiles/YOUR_CHANNEL/sources/YOUR_SOURCE/YOUR_ID Authorization: Bearer YOUR_ACCESS_TOKEN ``` Dùng `POST`, ở cuối trang này, để tìm hoặc tạo khách hàng. ## Phản hồi Cả hai phương thức đều trả HTTP `200` cùng khách hàng. Một số trường: ```json { "id": "user_example", "account_id": "account_example", "channel": "facebook", "channel_source": "page_example", "profile_id": "profile_example", "attributes": [ { "key": "fullname", "text": "Alex Example" } ] } ``` Lưu `id` của Subiz cùng với định danh kênh. Dùng `id` để [lấy thông tin](/developers/vi/api-reference/users/retrieve) hoặc [cập nhật](/developers/vi/api-reference/users/update) khách hàng. Subiz có thể chuẩn hóa hoặc gộp định danh khách hàng. Nếu việc tìm kiếm tạm thời thất bại, hãy thử lại thay vì tạo một khách hàng riêng bằng [Tạo khách hàng](/developers/vi/api-reference/users/create). ## Gửi tin mà không cần tìm trước Để nhắn tin cho khách hàng theo định danh kênh, bạn có thể bỏ qua bước này. [Gửi tin nhắn cho khách hàng](/developers/vi/api-reference/messages/send-to-user#xác-định-khách-hàng) nhận trực tiếp `channel`, `channel_source` và `profile_id`. ## Yêu cầu HTTP Thay `YOUR_ACCID`, `YOUR_CHANNEL`, `YOUR_SOURCE`, `YOUR_ID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http POST https://api.subiz.com.vn/4.1/accounts/YOUR_ACCID/contact-profiles/YOUR_CHANNEL/sources/YOUR_SOURCE/YOUR_ID Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json {} ``` --- # List conversations List conversations through the Subiz API. API 4.1 ## Before you begin Use a [Bearer access token](/developers/get-started/authentication) for the intended account. Replace all `YOUR_…` placeholders with real identifiers. Mutation requests change real data. ## Find a customer's conversations Use `user_id` to select a customer. The example requests up to 20 conversations. The service defaults a zero or omitted limit to 20 and caps positive limits at 200. | Query parameter | Type | Purpose | | --- | --- | --- | | `user_id` | string | Customer whose conversations you need. | | `agent_id` | string | Agent filter for the service's agent-listing branch. | | `limit` | integer | Requested number of results. | User credentials are restricted to their own user identity. Unknown and connector credentials are rejected by this service method. Filter combinations follow service-specific branches; do not assume all filters compose freely. ## Result The response contains a `conversations` array. Read an individual conversation with [Retrieve a conversation](/developers/api-reference/conversations/retrieve). This route does not establish an offset-based pagination contract or a `next_cursor` response field. ## HTTP request Replace the `YOUR_…` placeholders with your values. Send the headers shown below and, when present, the JSON body. Check the HTTP status before using the response. ```http GET https://api.subiz.com.vn/4.1/conversations?user_id=YOUR_USER_ID&limit=20 Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Liệt kê hội thoại Tìm các hội thoại của khách hàng. API 4.1 ## Trước khi bắt đầu Dùng [Bearer access token](/developers/vi/get-started/authentication) của đúng tài khoản. Thay toàn bộ chỗ điền `YOUR_…` bằng ID thực. Yêu cầu thay đổi dữ liệu sẽ tác động lên dữ liệu thật. ## Tìm hội thoại của khách hàng Dùng `user_id` để chọn khách hàng. Ví dụ yêu cầu tối đa 20 hội thoại. Dịch vụ dùng 20 khi `limit` bằng 0 hoặc bị bỏ qua; giới hạn dương được chặn ở 200. | Tham số truy vấn | Kiểu | Mục đích | | --- | --- | --- | | `user_id` | string | Khách hàng cần tìm hội thoại. | | `agent_id` | string | Bộ lọc trong nhánh liệt kê theo agent. | | `limit` | integer | Số kết quả yêu cầu. | Thông tin xác thực loại user chỉ truy cập danh tính của chính user. Loại unknown và connector bị từ chối ở phương thức dịch vụ này. Các tổ hợp bộ lọc chạy theo nhánh xử lý riêng; không giả định mọi bộ lọc có thể kết hợp tự do. ## Kết quả Phản hồi chứa mảng `conversations`. Đọc một hội thoại qua [Lấy hội thoại](/developers/vi/api-reference/conversations/retrieve). Route này không xác lập cơ chế phân trang theo offset hay trường phản hồi `next_cursor`. ## Yêu cầu HTTP Thay các giá trị `YOUR_…` bằng thông tin của bạn. Gửi các header bên dưới và body JSON nếu có. Kiểm tra mã trạng thái HTTP trước khi sử dụng phản hồi. ```http GET https://api.subiz.com.vn/4.1/conversations?user_id=YOUR_USER_ID&limit=20 Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Get conversation details Read a conversation's state, members, owner, and channel. API 4.0 Use this endpoint to check a conversation before acting on it: who participates, who owns it, and which channel it uses. ## Request Send a `GET` request with the conversation ID in the path. There is no request body. Subiz reads the conversation in the account of your [access token](/developers/get-started/authentication). | Parameter | Type | Description | | --- | --- | --- | | `cid` (path) | string | Conversation ID. | ## Response A successful request returns HTTP `200` with a `Conversation` object. Selected fields: ```json { "id": "conversation_example", "account_id": "account_example", "created": 1763107200000, "state": "active", "assignee": "agent_example", "members": [ { "id": "user_example", "type": "user", "membership": "active" }, { "id": "agent_example", "type": "agent", "conversation_id": "conversation_example", "membership": "active" } ], "touchpoint": { "channel": "facebook", "source": "page_example", "id": "profile_example" } } ``` | Field | Description | | --- | --- | | `id` | Conversation ID. | | `state` | Current state, such as `active` or `ended`. | | `assignee` | Agent responsible for the conversation. Omitted when unassigned. | | `members` | Participants. Each has a `type` (`user` for the customer, `agent` for staff), an `id`, and a `membership` state. | | `touchpoint` | Channel the conversation happens on. | | `created`, `ended` | Unix timestamps in milliseconds. `ended` is omitted while the conversation is open. | | `last_message_sent` | The latest non-internal message event, when present. | Empty fields are omitted. The object has more fields than shown; ignore those your integration does not use. ## Next steps - Read the messages with [Read message history](/developers/api-reference/conversations/history). - Add an agent as a participant with [Invite an agent](/developers/api-reference/conversations/invite-agent). - Change the owner with [Assign an agent](/developers/api-reference/conversations/assign-agent). Being a member and being the `assignee` are separate. An agent can own a conversation without being in `members`. ## HTTP request Replace `YOUR_CID` with the conversation ID and `YOUR_ACCESS_TOKEN` with your token. ```http GET https://api.subiz.com.vn/4.0/conversations/YOUR_CID Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Lấy thông tin hội thoại Đọc trạng thái, thành viên, người phụ trách và kênh của hội thoại. API 4.0 Dùng endpoint này để kiểm tra một hội thoại trước khi thao tác: ai tham gia, ai phụ trách và hội thoại diễn ra trên kênh nào. ## Yêu cầu Gửi yêu cầu `GET` với ID hội thoại trong đường dẫn. Không có body. Subiz đọc hội thoại trong tài khoản của [access token](/developers/vi/get-started/authentication). | Tham số | Kiểu | Mô tả | | --- | --- | --- | | `cid` (đường dẫn) | string | ID hội thoại. | ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng một đối tượng `Conversation`. Một số trường: ```json { "id": "conversation_example", "account_id": "account_example", "created": 1763107200000, "state": "active", "assignee": "agent_example", "members": [ { "id": "user_example", "type": "user", "membership": "active" }, { "id": "agent_example", "type": "agent", "conversation_id": "conversation_example", "membership": "active" } ], "touchpoint": { "channel": "facebook", "source": "page_example", "id": "profile_example" } } ``` | Trường | Mô tả | | --- | --- | | `id` | ID hội thoại. | | `state` | Trạng thái hiện tại, như `active` hoặc `ended`. | | `assignee` | Agent phụ trách hội thoại. Bị lược bỏ khi chưa giao. | | `members` | Người tham gia. Mỗi người có `type` (`user` cho khách hàng, `agent` cho agent), `id` và trạng thái `membership`. | | `touchpoint` | Kênh mà hội thoại diễn ra. | | `created`, `ended` | Dấu thời gian Unix tính bằng mili giây. `ended` bị lược bỏ khi hội thoại còn mở. | | `last_message_sent` | Sự kiện tin nhắn không nội bộ gần nhất, nếu có. | Trường rỗng bị lược bỏ. Đối tượng có nhiều trường hơn ví dụ; bỏ qua những trường tích hợp của bạn không dùng. ## Bước tiếp theo - Đọc tin nhắn bằng [Đọc lịch sử tin nhắn](/developers/vi/api-reference/conversations/history). - Thêm agent làm người tham gia bằng [Mời agent](/developers/vi/api-reference/conversations/invite-agent). - Đổi người phụ trách bằng [Giao agent](/developers/vi/api-reference/conversations/assign-agent). Là thành viên và là `assignee` là hai việc riêng. Agent có thể phụ trách hội thoại mà không nằm trong `members`. ## Yêu cầu HTTP Thay `YOUR_CID` bằng ID hội thoại và `YOUR_ACCESS_TOKEN` bằng token của bạn. ```http GET https://api.subiz.com.vn/4.0/conversations/YOUR_CID Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Read message history List the messages and other events in a conversation. API 4.0 Use this endpoint to read what happened in a conversation: messages from the customer and agents, plus other conversation events. ## Request Send a `GET` request with the conversation ID in the path. There is no request body. | Parameter | Type | Description | | --- | --- | --- | | `cid` (path) | string | Conversation ID. | | `start_id` (query) | string | Optional. Event ID to page from. | | `limit` (query) | integer | Optional. Number of events to request. | To read further, pass an event ID from your previous result as `start_id`. The response has no `next_cursor` or total; do not page by offset. ## Response A successful request returns HTTP `200` with a JSON **array** of events. There is no wrapper object. Selected fields: ```json [ { "id": "event_example", "account_id": "account_example", "type": "message_sent", "created": 1763107200000, "by": { "id": "user_example", "type": "user" }, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hi, is my order ready?" } } } ] ``` Treat an empty or `null` result as no events. ## Read events correctly - **Check `type` first.** Not every event is a message. Read `data.message` only for message events such as `message_sent`. - **Check the sender.** `by.type` tells you whether a customer (`user`) or staff member (`agent`) acted, and `by.id` identifies them. - **Check the format.** A message can be plain text, a block tree, or attachments only. See [Message formats](/developers/messages/formats) and [Attachments](/developers/messages/attachments). - **Deduplicate by `id`.** When syncing history with [webhook events](/developers/webhooks/payloads), use the event `id` to avoid storing a message twice. `created` is in Unix milliseconds. ## HTTP request Replace `YOUR_CID` with the conversation ID and `YOUR_ACCESS_TOKEN` with your token. Add `start_id` or `limit` to the query string when needed. ```http GET https://api.subiz.com.vn/4.0/conversations/YOUR_CID/messages Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Đọc lịch sử tin nhắn Liệt kê tin nhắn và các sự kiện khác trong một hội thoại. API 4.0 Dùng endpoint này để đọc những gì đã diễn ra trong hội thoại: tin nhắn của khách hàng và agent, cùng các sự kiện hội thoại khác. ## Yêu cầu Gửi yêu cầu `GET` với ID hội thoại trong đường dẫn. Không có body. | Tham số | Kiểu | Mô tả | | --- | --- | --- | | `cid` (đường dẫn) | string | ID hội thoại. | | `start_id` (query) | string | Tùy chọn. ID sự kiện để bắt đầu trang. | | `limit` (query) | integer | Tùy chọn. Số sự kiện cần lấy. | Để đọc tiếp, truyền một ID sự kiện từ kết quả trước làm `start_id`. Phản hồi không có `next_cursor` hay tổng số; đừng phân trang bằng offset. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng một **mảng** JSON các sự kiện. Không có đối tượng bọc ngoài. Một số trường: ```json [ { "id": "event_example", "account_id": "account_example", "type": "message_sent", "created": 1763107200000, "by": { "id": "user_example", "type": "user" }, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hi, is my order ready?" } } } ] ``` Coi kết quả rỗng hoặc `null` là không có sự kiện nào. ## Đọc sự kiện đúng cách - **Kiểm tra `type` trước.** Không phải sự kiện nào cũng là tin nhắn. Chỉ đọc `data.message` với sự kiện tin nhắn như `message_sent`. - **Kiểm tra người gửi.** `by.type` cho biết khách hàng (`user`) hay agent (`agent`) đã thực hiện, và `by.id` xác định người đó. - **Kiểm tra định dạng.** Tin nhắn có thể là văn bản thuần, cây block hoặc chỉ có tệp đính kèm. Xem [Định dạng tin nhắn](/developers/vi/messages/formats) và [Tệp đính kèm](/developers/vi/messages/attachments). - **Loại trùng theo `id`.** Khi đồng bộ lịch sử với [sự kiện webhook](/developers/vi/webhooks/payloads), dùng `id` của sự kiện để tránh lưu một tin nhắn hai lần. `created` tính bằng mili giây Unix. ## Yêu cầu HTTP Thay `YOUR_CID` bằng ID hội thoại và `YOUR_ACCESS_TOKEN` bằng token của bạn. Thêm `start_id` hoặc `limit` vào query string khi cần. ```http GET https://api.subiz.com.vn/4.0/conversations/YOUR_CID/messages Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Invite an agent Add an existing agent to a conversation as a participant. API 4.0 Use this endpoint to bring another staff member into a conversation, for example a specialist who needs to help. The agent must already have a Subiz account. ## Invite, assign, or route? | You want to | Use | | --- | --- | | Add an agent as a participant | This endpoint. | | Make an agent responsible for the conversation | [Assign an agent](/developers/api-reference/conversations/assign-agent). | | Add a new staff member to your account | The Subiz app. This endpoint does not create agents or send account invitations. | | Let Subiz pick an agent automatically | Automatic routing. This endpoint always uses the agent you specify. | Inviting an agent does not change the conversation's `assignee`. ## Request body The body is a conversation member. | Field | Type | Description | | --- | --- | --- | | `cid` (path) | string | Conversation ID. | | `type` | string | Set to `agent`. | | `id` | string | ID of the existing agent to invite. | ```json { "type": "agent", "id": "agent_example" } ``` Subiz sets the account from your [access token](/developers/get-started/authentication) and the conversation from the path. ## Response A successful request returns HTTP `200` with an empty object: ```json {} ``` Subiz records a `conversation_invited` event in the conversation. To confirm the result, [get the conversation](/developers/api-reference/conversations/retrieve) and check that the agent appears in `members`: ```json { "id": "agent_example", "type": "agent", "conversation_id": "conversation_example", "membership": "active" } ``` ## HTTP request Replace `YOUR_CID` with the conversation ID, `YOUR_AGENT_ID` with the agent ID, and `YOUR_ACCESS_TOKEN` with your token. ```http POST https://api.subiz.com.vn/4.0/conversations/YOUR_CID/members Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "type": "agent", "id": "YOUR_AGENT_ID" } ``` --- # Mời agent tham gia Thêm một agent có sẵn vào hội thoại với vai trò người tham gia. API 4.0 Dùng endpoint này để đưa một agent khác vào hội thoại, ví dụ một chuyên viên cần hỗ trợ. Agent đó phải đã có tài khoản Subiz. ## Mời, giao hay tự động phân bổ? | Bạn muốn | Dùng | | --- | --- | | Thêm agent làm người tham gia | Endpoint này. | | Giao cho agent phụ trách hội thoại | [Giao agent](/developers/vi/api-reference/conversations/assign-agent). | | Thêm agent mới vào tài khoản | Ứng dụng Subiz. Endpoint này không tạo agent hay gửi lời mời tham gia tài khoản. | | Để Subiz tự chọn agent | Phân bổ tự động. Endpoint này luôn dùng đúng agent bạn chỉ định. | Mời agent không thay đổi `assignee` của hội thoại. ## Body yêu cầu Body là một thành viên hội thoại. | Trường | Kiểu | Mô tả | | --- | --- | --- | | `cid` (đường dẫn) | string | ID hội thoại. | | `type` | string | Đặt là `agent`. | | `id` | string | ID của agent có sẵn cần mời. | ```json { "type": "agent", "id": "agent_example" } ``` Subiz lấy tài khoản từ [access token](/developers/vi/get-started/authentication) và hội thoại từ đường dẫn. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng một đối tượng rỗng: ```json {} ``` Subiz ghi một sự kiện `conversation_invited` vào hội thoại. Để xác nhận kết quả, [lấy thông tin hội thoại](/developers/vi/api-reference/conversations/retrieve) và kiểm tra agent đã có trong `members`: ```json { "id": "agent_example", "type": "agent", "conversation_id": "conversation_example", "membership": "active" } ``` ## Yêu cầu HTTP Thay `YOUR_CID` bằng ID hội thoại, `YOUR_AGENT_ID` bằng ID agent và `YOUR_ACCESS_TOKEN` bằng token của bạn. ```http POST https://api.subiz.com.vn/4.0/conversations/YOUR_CID/members Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "type": "agent", "id": "YOUR_AGENT_ID" } ``` --- # Assign an agent Make a specific agent responsible for a conversation. API 4.0 Use this endpoint to set the conversation's owner, the `assignee`, to a specific agent. Use it for handoffs, for example when your CRM decides which salesperson handles a customer. ## Before you begin - Get a [Bearer access token](/developers/get-started/authentication) and your account ID. - Get the ID of an existing agent in the account. ## Request body | Field | Type | Description | | --- | --- | --- | | `accid` (path) | string | Your account ID. | | `cid` (path) | string | Conversation to assign. | | `assignee` | string | ID of the agent who should own the conversation. | ```json { "assignee": "agent_example" } ``` This route updates conversation information. Send only `assignee` for an assignment. ## Response A successful request returns HTTP `200` with the updated `Conversation`. Selected fields: ```json { "id": "conversation_example", "account_id": "account_example", "state": "active", "assignee": "agent_example" } ``` When the owner changes, Subiz emits a `conversation_assigned` event. Subscribed webhooks receive it; see [Conversation assigned](/developers/webhooks/payloads#conversation-assigned). ## Assignment is not participation Assigning an agent does not add them to `members`. If the agent should also participate, [invite the agent](/developers/api-reference/conversations/invite-agent) as well. ## Clear the assignment Send an empty `assignee` and add `x-fields=assignee` to the query string: ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/conversations/YOUR_CID?x-fields=assignee Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "assignee": "" } ``` `x-fields` lists the fields to update. Without it, an empty value is treated as "not provided" and the owner stays unchanged. Clearing an owner emits `conversation_unassigned`. ## Automatic routing is different `POST /4.1/conversations/{cid}/assign` asks Subiz to run automatic assignment again. It does not accept an agent ID. Use the endpoint on this page to choose a specific agent. ## HTTP request Replace `YOUR_ACCID`, `YOUR_CID`, `YOUR_AGENT_ID`, and `YOUR_ACCESS_TOKEN` with your values. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/conversations/YOUR_CID Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "assignee": "YOUR_AGENT_ID" } ``` --- # Giao agent phụ trách Giao cho một agent cụ thể phụ trách hội thoại. API 4.0 Dùng endpoint này để đặt người phụ trách hội thoại, tức `assignee`, là một agent cụ thể. Dùng khi chuyển giao, ví dụ khi CRM của bạn quyết định nhân viên bán hàng nào chăm sóc khách hàng. ## Trước khi bắt đầu - Lấy [Bearer access token](/developers/vi/get-started/authentication) và ID tài khoản. - Lấy ID của một agent có sẵn trong tài khoản. ## Body yêu cầu | Trường | Kiểu | Mô tả | | --- | --- | --- | | `accid` (đường dẫn) | string | ID tài khoản của bạn. | | `cid` (đường dẫn) | string | Hội thoại cần giao. | | `assignee` | string | ID agent sẽ phụ trách hội thoại. | ```json { "assignee": "agent_example" } ``` Route này cập nhật thông tin hội thoại. Khi giao việc, chỉ gửi `assignee`. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng `Conversation` đã cập nhật. Một số trường: ```json { "id": "conversation_example", "account_id": "account_example", "state": "active", "assignee": "agent_example" } ``` Khi người phụ trách thay đổi, Subiz phát sự kiện `conversation_assigned`. Webhook đã đăng ký sẽ nhận được; xem [Hội thoại được giao](/developers/vi/webhooks/payloads#hội-thoại-được-giao). ## Giao việc không phải là tham gia Giao agent không thêm họ vào `members`. Nếu agent cũng cần tham gia, hãy [mời agent](/developers/vi/api-reference/conversations/invite-agent) nữa. ## Bỏ giao việc Gửi `assignee` rỗng và thêm `x-fields=assignee` vào query string: ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/conversations/YOUR_CID?x-fields=assignee Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "assignee": "" } ``` `x-fields` liệt kê các trường cần cập nhật. Nếu thiếu, giá trị rỗng được coi là "không cung cấp" và người phụ trách giữ nguyên. Bỏ người phụ trách sẽ phát sự kiện `conversation_unassigned`. ## Phân bổ tự động là việc khác `POST /4.1/conversations/{cid}/assign` yêu cầu Subiz chạy lại phân bổ tự động. Nó không nhận ID agent. Dùng endpoint trên trang này để chọn một agent cụ thể. ## Yêu cầu HTTP Thay `YOUR_ACCID`, `YOUR_CID`, `YOUR_AGENT_ID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/conversations/YOUR_CID Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "assignee": "YOUR_AGENT_ID" } ``` --- # Message formats Write plain text and rich messages with blocks, links, and text formatting. API 4.0 · 4.1 Message content lives in `data.message` inside an event. Use `format: "plaintext"` for plain text or `format: "block"` for structured content. Add files through the separate [attachments array](/developers/messages/attachments). The JSON examples below are message objects or blocks, as labeled. The final example shows a complete HTTP request. All names, IDs, and URLs are illustrative. ## Plain text Set `format` to `plaintext` and put the content in `text`: ```json { "format": "plaintext", "text": "Hello Alex!\nHow can we help?" } ``` `\n` adds a line break. HTML tags or Markdown markers in this field do not define Subiz block formatting. For bold text or a labeled link, use a block message. ## Block messages Set `format` to `block` and put a **JSON object** in `block`: ```json { "format": "block", "block": { "type": "paragraph", "content": [ { "type": "text", "text": "Hello " }, { "type": "text", "text": "Alex", "bold": true } ] } } ``` The content reads “Hello **Alex**”. A block is a tree: `type` selects the node, `content` contains child nodes, and text nodes store their content in `text`. Do not stringify the block into `text`. Subiz can derive plain text from the tree, but keep `block` when you need its formatting. ## Bold and regular text Apply formatting to individual text nodes. For regular text, omit `bold` or set it to `false`; there is no separate `light` flag. | Field | Effect when `true` | | --- | --- | | `bold` | Bold text. | | `italic` | Italic text. | | `underline` | Underlined text. | | `strike_through` | Struck-through text. | This is a block object to place in `message.block`: ```json { "type": "paragraph", "content": [ { "type": "text", "text": "Regular. " }, { "type": "text", "text": "Bold. ", "bold": true }, { "type": "text", "text": "Italic. ", "italic": true }, { "type": "text", "text": "Underlined. ", "underline": true }, { "type": "text", "text": "Struck through.", "strike_through": true } ] } ``` Each node controls its own text. A regular node after a bold node returns to regular text. You can combine flags, such as `bold: true` and `italic: true`, on one text node. Regular weight does not mean a lighter text color. ## Links inside a block Use a `link` node with `text` for the visible label and `href` for the destination. Put the link alongside other nodes in the paragraph's `content` array: ```json { "type": "paragraph", "content": [ { "type": "text", "text": "Read our " }, { "type": "link", "text": "delivery guide", "href": "https://example.com/delivery" }, { "type": "text", "text": " before ordering." } ] } ``` The result is “Read our [delivery guide](https://example.com/delivery) before ordering.” The link label goes directly in `text`, not in child nodes. Use an absolute HTTPS URL for a web destination. An inline link is different from a [link-preview attachment](/developers/messages/attachments#link-previews), which carries a separate title and description. ## Paragraphs and line breaks Use `hard_break` for a line break inside a paragraph. To group several paragraphs, place them in a `div` block: ```json { "type": "div", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Hello Alex," }, { "type": "hard_break" }, { "type": "text", "text": "Your order is ready." } ] }, { "type": "paragraph", "content": [ { "type": "text", "text": "Thank you!" } ] } ] } ``` This displays a greeting, the order update on the next line, and a separate thank-you paragraph. Exact spacing depends on the renderer and destination channel. ## Send a block message Use the [Send to a conversation](/developers/api-reference/messages/send) endpoint. Replace the conversation ID and access token before sending: ```http POST https://api.subiz.com.vn/4.1/conversations/YOUR_CONVERSATION_ID/messages Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "type": "message_sent", "data": { "message": { "format": "block", "block": { "type": "paragraph", "content": [ { "type": "text", "text": "Hello " }, { "type": "text", "text": "Alex", "bold": true } ] } } } } ``` For [Send to a customer](/developers/api-reference/messages/send-to-user), use the same message content inside that endpoint's event structure and supply the channel destination. Its outer request body is different. ## Read messages without losing content When reading API responses or webhook events: - Check `format` before interpreting content. Preserve unknown formats if your integration cannot render them. - Keep the block tree if formatting matters; `text` alone loses links and styling. - Check `attachments` even when `text` is empty. - Test your target channel. The shared block schema does not guarantee that every channel renders every node or formatting flag. Continue with [Attachments](/developers/messages/attachments) for images, video, audio, and other message content. --- # Định dạng tin nhắn Viết tin nhắn văn bản thuần và tin nhắn phong phú với block, liên kết và định dạng chữ. API 4.0 · 4.1 Nội dung tin nhắn nằm trong `data.message` bên trong một sự kiện. Dùng `format: "plaintext"` cho văn bản thuần hoặc `format: "block"` cho nội dung có cấu trúc. Thêm tệp qua [mảng attachments](/developers/vi/messages/attachments) riêng. Các ví dụ JSON bên dưới là đối tượng tin nhắn hoặc block, như đã ghi chú. Ví dụ cuối cùng là một yêu cầu HTTP đầy đủ. Mọi tên, ID và URL chỉ mang tính minh họa. ## Văn bản thuần Đặt `format` là `plaintext` và đưa nội dung vào `text`: ```json { "format": "plaintext", "text": "Hello Alex!\nHow can we help?" } ``` `\n` tạo một dấu xuống dòng. Thẻ HTML hay ký hiệu Markdown trong trường này không tạo định dạng block của Subiz. Để có chữ đậm hoặc liên kết có nhãn, hãy dùng tin nhắn block. ## Tin nhắn block Đặt `format` là `block` và đưa một **đối tượng JSON** vào `block`: ```json { "format": "block", "block": { "type": "paragraph", "content": [ { "type": "text", "text": "Hello " }, { "type": "text", "text": "Alex", "bold": true } ] } } ``` Nội dung hiển thị là “Hello **Alex**”. Block là một cây: `type` chọn loại nút, `content` chứa các nút con, và nút văn bản lưu nội dung trong `text`. Đừng chuyển block thành chuỗi rồi đưa vào `text`. Subiz có thể tạo văn bản thuần từ cây block, nhưng hãy giữ `block` khi bạn cần định dạng của nó. ## Chữ đậm và chữ thường Áp dụng định dạng cho từng nút văn bản. Với chữ thường, bỏ `bold` hoặc đặt nó là `false`; không có cờ `light` riêng. | Trường | Tác dụng khi `true` | | --- | --- | | `bold` | Chữ đậm. | | `italic` | Chữ nghiêng. | | `underline` | Chữ gạch chân. | | `strike_through` | Chữ gạch ngang. | Đây là một đối tượng block để đặt vào `message.block`: ```json { "type": "paragraph", "content": [ { "type": "text", "text": "Regular. " }, { "type": "text", "text": "Bold. ", "bold": true }, { "type": "text", "text": "Italic. ", "italic": true }, { "type": "text", "text": "Underlined. ", "underline": true }, { "type": "text", "text": "Struck through.", "strike_through": true } ] } ``` Mỗi nút quyết định định dạng chữ của chính nó. Nút chữ thường đứng sau nút chữ đậm sẽ trở lại chữ thường. Bạn có thể kết hợp nhiều cờ, như `bold: true` và `italic: true`, trên cùng một nút văn bản. Chữ thường không có nghĩa là màu chữ nhạt hơn. ## Liên kết trong block Dùng nút `link` với `text` là nhãn hiển thị và `href` là đích đến. Đặt liên kết cạnh các nút khác trong mảng `content` của đoạn văn: ```json { "type": "paragraph", "content": [ { "type": "text", "text": "Read our " }, { "type": "link", "text": "delivery guide", "href": "https://example.com/delivery" }, { "type": "text", "text": " before ordering." } ] } ``` Kết quả là “Read our [delivery guide](https://example.com/delivery) before ordering.” Nhãn liên kết đặt trực tiếp trong `text`, không đặt trong nút con. Dùng URL HTTPS tuyệt đối cho đích đến trên web. Liên kết trong dòng khác với [tệp đính kèm xem trước liên kết](/developers/vi/messages/attachments#xem-trước-liên-kết), loại mang tiêu đề và mô tả riêng. ## Đoạn văn và xuống dòng Dùng `hard_break` để xuống dòng trong một đoạn văn. Để nhóm nhiều đoạn văn, đặt chúng trong một block `div`: ```json { "type": "div", "content": [ { "type": "paragraph", "content": [ { "type": "text", "text": "Hello Alex," }, { "type": "hard_break" }, { "type": "text", "text": "Your order is ready." } ] }, { "type": "paragraph", "content": [ { "type": "text", "text": "Thank you!" } ] } ] } ``` Nội dung này hiển thị lời chào, thông báo đơn hàng ở dòng tiếp theo và một đoạn cảm ơn riêng. Khoảng cách chính xác phụ thuộc vào trình hiển thị và kênh đích. ## Gửi tin nhắn block Dùng endpoint [Gửi tin nhắn vào hội thoại](/developers/vi/api-reference/messages/send). Thay ID hội thoại và access token trước khi gửi: ```http POST https://api.subiz.com.vn/4.1/conversations/YOUR_CONVERSATION_ID/messages Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "type": "message_sent", "data": { "message": { "format": "block", "block": { "type": "paragraph", "content": [ { "type": "text", "text": "Hello " }, { "type": "text", "text": "Alex", "bold": true } ] } } } } ``` Với [Gửi tin nhắn cho khách hàng](/developers/vi/api-reference/messages/send-to-user), dùng cùng nội dung tin nhắn bên trong cấu trúc sự kiện của endpoint đó và cung cấp đích đến trên kênh. Body bên ngoài của yêu cầu đó khác. ## Đọc tin nhắn mà không mất nội dung Khi đọc phản hồi API hoặc sự kiện webhook: - Kiểm tra `format` trước khi diễn giải nội dung. Giữ nguyên các định dạng chưa biết nếu tích hợp của bạn không hiển thị được. - Giữ cây block nếu định dạng quan trọng; chỉ dùng `text` sẽ mất liên kết và kiểu chữ. - Kiểm tra `attachments` ngay cả khi `text` rỗng. - Thử nghiệm trên kênh đích. Schema block dùng chung không đảm bảo mọi kênh đều hiển thị mọi loại nút hay cờ định dạng. Tiếp tục với [Tệp đính kèm](/developers/vi/messages/attachments) cho ảnh, video, âm thanh và các nội dung tin nhắn khác. --- # Agent format Understand the agent object: identity, contact details, role, and state. API 4.1 An `Agent` is a staff member in your Subiz account. Agents reply to customers, join conversations, and own conversations as the `assignee`. Customers are `User` objects, not agents. All IDs and values below are illustrative. To get agents, see [List agents](/developers/api-reference/agents/list) and [Get agent details](/developers/api-reference/agents/retrieve). ## Agent Selected fields of an `Agent`: ```json { "id": "agent_example", "account_id": "account_example", "type": "agent", "state": "active", "fullname": "Sam Example", "email": "sam@example.com", "phone": "+84900000001", "avatar_url": "https://example.com/avatars/sam.png", "lang": "en", "timezone": "Asia/Ho_Chi_Minh", "scopes": [ "supervisor" ], "invited_by": "agent_owner_example", "joined": 1763107200000, "modified": 1763193600000 } ``` | Field | Type | Description | | --- | --- | --- | | `id` | string | Agent ID. Use it as `assignee` when [assigning a conversation](/developers/api-reference/conversations/assign-agent), or as the member `id` when [inviting an agent](/developers/api-reference/conversations/invite-agent). | | `account_id` | string | The account the agent belongs to. | | `type` | string | `agent` for a staff member, or `bot`. Empty means `agent`. | | `state` | string | Agent state. See [States](#states). | | `fullname` | string | Display name. | | `email` | string | Email address. | | `phone` | string | Phone number. | | `avatar_url`, `avatar_url_128` | string | Avatar image, and a 128×128 version. | | `gender` | string | `male` or `female`, when set. | | `lang` | string | Preferred language. | | `timezone` | string | Time zone. | | `scopes` | array | Account-level roles, such as `owner` or `supervisor`. | | `invited_by` | string | ID of the agent who invited this agent. | | `client_id` | string | For bots: the ID of the bot. | | `extension` | integer | Phone extension number, when set. | | `joined`, `modified` | integer | Timestamps when the agent joined the account and when the record last changed. | Empty fields are omitted, and the object has more fields than shown. `account_id` is the account's ID; the account object itself uses `id`. ## States | `state` | Meaning | | --- | --- | | `pending` | Invited, waiting for the invitation to be accepted. | | `active` | Active staff member. | | `inactive` | Deactivated. | | `deleted` | Removed from the account. | When you choose an agent to invite or assign, pick one whose `type` is `agent` and whose `state` is `active`. ## Agents and customers | | Agent | User | | --- | --- | --- | | Who | Your staff | Your customers | | Name | `fullname` field | `fullname` attribute | | In a conversation | Member or `assignee` | Member | See [User and attribute format](/developers/users/format) for the customer object. --- # Send to a conversation Send a message into an existing conversation. API 4.1 Use this endpoint when you already have a conversation ID. To contact a customer through a channel identity instead, use [Send to a customer](/developers/api-reference/messages/send-to-user). ## Before you send - Get a [Bearer access token](/developers/get-started/authentication). - Find the conversation ID, for example from a [webhook event](/developers/webhooks/payloads) or [Get conversation details](/developers/api-reference/conversations/retrieve). - Use a test conversation while developing. Each successful request sends a real message. ## Request body The body is an event. The message goes in `data.message`. | Field | Type | Description | | --- | --- | --- | | `cid` (path) | string | Conversation to send to. | | `type` | string | Optional. Defaults to `message_sent`. | | `data.message.format` | string | `plaintext` or `block`. See [Message formats](/developers/messages/formats). | | `data.message.text` | string | Message text for `plaintext`. | | `data.message.block` | object | Block tree for `block` messages. | | `data.message.attachments` | array | Optional files, buttons, or cards. See [Attachments](/developers/messages/attachments). | A plain-text message: ```json { "type": "message_sent", "data": { "message": { "format": "plaintext", "text": "Hello! How can we help?" } } } ``` ## Fields Subiz sets You do not need to send these fields. Subiz sets them for every request: - `created`: the current time, in Unix milliseconds. - `account_id`: the account of your access token. - `data.message.conversation_id` and `data.conversation.id`: the `cid` from the URL. Values in the body are replaced. ## Response A successful request returns HTTP `200` with the sent event as JSON, without an extra wrapper. Selected fields: ```json { "id": "event_example", "account_id": "account_example", "type": "message_sent", "created": 1763107200000, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hello! How can we help?" } } } ``` Empty fields are omitted. Store the event `id` if you need to match the message later in [message history](/developers/api-reference/conversations/history) or webhook events. A `200` response means Subiz accepted the message. It does not confirm delivery to an external channel such as Facebook or Zalo. ## Limits - Message sends made with an agent's token count toward that agent's allowance: 5 per second, 60 per minute, and 5,000 per UTC day. See [Message sending limits](/developers/get-started/usage-limits#message-sending-limits). - Text, attachment, and field sizes are limited. See [Message limits](/developers/get-started/usage-limits#message-limits). ## Errors and retries Check the HTTP status before reading the body. Requests can fail because of invalid JSON, authentication, a blocked sender, rate limits (`429`), or validation in the conversation service. See [Errors](/developers/get-started/errors). Do not retry blindly after a timeout. The message may already have been sent, and this endpoint has no idempotency key. Check message history first. ## HTTP request Replace `YOUR_CID` with the conversation ID and `YOUR_ACCESS_TOKEN` with your token. ```http POST https://api.subiz.com.vn/4.1/conversations/YOUR_CID/messages Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "type": "message_sent", "data": { "message": { "text": "Hello! How can we help?", "format": "plaintext" } } } ``` --- # Attachments Add images, video, audio, files, and interactive content to a message. API 4.0 · 4.1 Attachments live in the `attachments` array of a message, alongside `text` or `block`. Each item is an `Attachment` object. ## Choose an attachment type For media and documents, use **`type: "file"`**. The `mimetype` distinguishes an image, video, audio clip, or document; do not use `type: "image"` or `type: "video"` for these file examples. | Content | Attachment `type` | Content field | | --- | --- | --- | | Image | `file` | `mimetype: "image/jpeg"` or another image MIME type. | | Video | `file` | `mimetype: "video/mp4"`, for example. | | Audio | `file` | `mimetype: "audio/mpeg"`, for example. | | Document | `file` | `mimetype: "application/pdf"`, for example. | | Link preview | `link` | `url`, `title`, and `description`. | | Buttons | `button` | `buttons` array. | | Quick replies | `quick_replies` | `quick_replies` array. | | Cards | `generic` | `elements` array. | These are common attachment shapes supported by the Subiz model and renderers. Destination channels can restrict formats, actions, and media. The examples use synthetic metadata and placeholder URLs; replace them with real assets before sending. ## File fields | Field | Meaning | | --- | --- | | `url` | Source URL of the file. Use a URL Subiz can retrieve directly. | | `mimetype` | MIME type, such as `image/jpeg`. Match the actual file content. | | `name` | File name, including its extension when applicable. | | `size` | File size in bytes. | | `thumbnail_url` | Thumbnail URL, when available. | | `width`, `height` | Image dimensions in pixels, when available. | | `duration` | Audio or video duration in seconds, when available. | Optional metadata can be omitted when unknown. Subiz processes file attachments and can replace the source URL and metadata with stored file information. Preserve the returned values instead of assuming the response matches the request exactly. ## Images A JPEG image attachment: ```json { "type": "file", "mimetype": "image/jpeg", "url": "https://example.com/photo.jpg", "name": "photo.jpg", "size": 245760, "width": 1200, "height": 800 } ``` PNG or GIF files use their actual MIME types, such as `image/png` or `image/gif`. Rendering and animation support depend on the destination. ## Video An MP4 video attachment with a preview image: ```json { "type": "file", "mimetype": "video/mp4", "url": "https://example.com/demo.mp4", "name": "demo.mp4", "thumbnail_url": "https://example.com/demo-preview.jpg", "size": 5242880, "duration": 30 } ``` `thumbnail_url` is a preview, not the video source. The video itself belongs in `url`. Container and codec support depend on the channel and player. ## Audio An MP3 audio attachment: ```json { "type": "file", "mimetype": "audio/mpeg", "url": "https://example.com/voice.mp3", "name": "voice.mp3", "size": 262144, "duration": 12 } ``` `duration` is measured in seconds, unlike the millisecond timestamps used by events. Other audio files must use their correct MIME type. ## Documents and other files A downloadable PDF attachment: ```json { "type": "file", "mimetype": "application/pdf", "url": "https://example.com/guide.pdf", "name": "guide.pdf", "size": 2048 } ``` For other documents, keep `type: "file"` and use the matching MIME type and file name. A document attachment is not a block node. ## Link previews Use `link` for a separate preview rather than a link embedded in formatted text: ```json { "type": "link", "url": "https://example.com/delivery", "title": "Delivery guide", "description": "Delivery options and estimated timelines." } ``` For a labeled link inside a sentence, use a [link block](/developers/messages/formats#links-inside-a-block) instead. ## Buttons A `button` attachment contains a `buttons` array. This example uses a `MessageButton` with `type: "url_button"`: ```json { "type": "button", "buttons": [ { "type": "url_button", "title": "View delivery guide", "url": "https://example.com/delivery" } ] } ``` The button's visible label is `title`, and its destination is `url`. Support for button actions depends on the channel. ## Quick replies A `quick_replies` attachment offers suggested responses. Each `QuickReply` has a visible `title`; `payload` carries your application-specific value: ```json { "type": "quick_replies", "quick_replies": [ { "content_type": "text", "title": "Track my order", "payload": "track_order" }, { "content_type": "text", "title": "Talk to support", "payload": "contact_support" } ] } ``` These payload strings are example values for your integration, not built-in Subiz commands. Receiving and handling the selection depends on the channel; do not assume it arrives as an ordinary text message. ## Cards A `generic` attachment contains an `elements` array. Each `GenericElementTemplate` can have a title, subtitle, image, and buttons: ```json { "type": "generic", "elements": [ { "title": "Delivery options", "subtitle": "Choose the delivery service for your order.", "image_url": "https://example.com/delivery.jpg", "buttons": [ { "type": "url_button", "title": "See options", "url": "https://example.com/delivery" } ] } ] } ``` The schema supports multiple elements, but the destination determines how many it accepts and how it displays them. This page does not define a universal card or button limit. ## Send an attachment Wrap the attachment in `data.message.attachments` and send it to an existing conversation. The text and the image are part of the same message: ```http POST https://api.subiz.com.vn/4.1/conversations/YOUR_CONVERSATION_ID/messages Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "type": "message_sent", "data": { "message": { "format": "plaintext", "text": "Here is the product photo.", "attachments": [ { "type": "file", "mimetype": "image/jpeg", "url": "https://example.com/photo.jpg", "name": "photo.jpg", "size": 245760, "width": 1200, "height": 800 } ] } } } ``` The example URLs are placeholders. Use a retrievable HTTPS file URL, not a local path, browser `blob:` URL, or a page that requires your browser's login. Check that the actual file is available before sending. See [Send to a conversation](/developers/api-reference/messages/send) for the endpoint and [Message formats](/developers/messages/formats) for combining attachments with text or a block. ## Read attachment payloads Process every item in `attachments`. For file attachments, inspect `mimetype`; for structured attachments, inspect `type` before reading nested fields. A message with no text may still contain an image, audio, or a document. The wider schema also includes channel-specific and application-specific attachments. Preserve types your integration does not recognize instead of treating every attachment as a file. Refer to [webhook payloads](/developers/webhooks/payloads) when consuming message events. --- # Định dạng agent Hiểu đối tượng agent: định danh, thông tin liên hệ, vai trò và trạng thái. API 4.1 `Agent` là một nhân viên trong tài khoản Subiz của bạn. Agent trả lời khách hàng, tham gia hội thoại và phụ trách hội thoại với vai trò `assignee`. Khách hàng là đối tượng `User`, không phải agent. Mọi ID và giá trị bên dưới chỉ mang tính minh họa. Để lấy agent, xem [Lấy danh sách agent](/developers/vi/api-reference/agents/list) và [Lấy thông tin agent](/developers/vi/api-reference/agents/retrieve). ## Agent Một số trường của `Agent`: ```json { "id": "agent_example", "account_id": "account_example", "type": "agent", "state": "active", "fullname": "Sam Example", "email": "sam@example.com", "phone": "+84900000001", "avatar_url": "https://example.com/avatars/sam.png", "lang": "en", "timezone": "Asia/Ho_Chi_Minh", "scopes": [ "supervisor" ], "invited_by": "agent_owner_example", "joined": 1763107200000, "modified": 1763193600000 } ``` | Trường | Kiểu | Mô tả | | --- | --- | --- | | `id` | string | ID agent. Dùng làm `assignee` khi [giao hội thoại](/developers/vi/api-reference/conversations/assign-agent), hoặc làm `id` thành viên khi [mời agent](/developers/vi/api-reference/conversations/invite-agent). | | `account_id` | string | Tài khoản mà agent thuộc về. | | `type` | string | `agent` cho agent, hoặc `bot`. Rỗng nghĩa là `agent`. | | `state` | string | Trạng thái agent. Xem [Trạng thái](#trạng-thái). | | `fullname` | string | Tên hiển thị. | | `email` | string | Địa chỉ email. | | `phone` | string | Số điện thoại. | | `avatar_url`, `avatar_url_128` | string | Ảnh đại diện, và bản kích thước 128×128. | | `gender` | string | `male` hoặc `female`, nếu đã đặt. | | `lang` | string | Ngôn ngữ ưa dùng. | | `timezone` | string | Múi giờ. | | `scopes` | array | Vai trò cấp tài khoản, như `owner` hoặc `supervisor`. | | `invited_by` | string | ID của agent đã mời agent này. | | `client_id` | string | Với bot: ID của bot. | | `extension` | integer | Số máy lẻ, nếu đã đặt. | | `joined`, `modified` | integer | Thời điểm agent tham gia tài khoản và thời điểm bản ghi thay đổi gần nhất. | Trường rỗng bị lược bỏ, và đối tượng có nhiều trường hơn ví dụ. `account_id` là ID của tài khoản; bản thân đối tượng tài khoản dùng `id`. ## Trạng thái | `state` | Ý nghĩa | | --- | --- | | `pending` | Đã được mời, đang chờ chấp nhận lời mời. | | `active` | Đang hoạt động. | | `inactive` | Đã bị vô hiệu hóa. | | `deleted` | Đã bị xóa khỏi tài khoản. | Khi chọn agent để mời hoặc giao việc, hãy chọn người có `type` là `agent` và `state` là `active`. ## Agent và khách hàng | | Agent | User | | --- | --- | --- | | Là ai | Nhân viên của bạn | Khách hàng của bạn | | Tên | Trường `fullname` | Thuộc tính `fullname` | | Trong hội thoại | Thành viên hoặc `assignee` | Thành viên | Xem [Định dạng khách hàng và thuộc tính](/developers/vi/users/format) cho đối tượng khách hàng. --- # Gửi tin nhắn vào hội thoại Gửi tin nhắn vào một hội thoại có sẵn. API 4.1 Dùng endpoint này khi bạn đã có ID hội thoại. Để liên hệ khách hàng qua định danh kênh, hãy dùng [Gửi tin nhắn cho khách hàng](/developers/vi/api-reference/messages/send-to-user). ## Trước khi gửi - Lấy [Bearer access token](/developers/vi/get-started/authentication). - Tìm ID hội thoại, ví dụ từ [sự kiện webhook](/developers/vi/webhooks/payloads) hoặc [Lấy thông tin hội thoại](/developers/vi/api-reference/conversations/retrieve). - Dùng một hội thoại thử nghiệm khi phát triển. Mỗi yêu cầu thành công đều gửi một tin nhắn thật. ## Body yêu cầu Body là một sự kiện. Tin nhắn đặt trong `data.message`. | Trường | Kiểu | Mô tả | | --- | --- | --- | | `cid` (đường dẫn) | string | Hội thoại cần gửi tới. | | `type` | string | Tùy chọn. Mặc định là `message_sent`. | | `data.message.format` | string | `plaintext` hoặc `block`. Xem [Định dạng tin nhắn](/developers/vi/messages/formats). | | `data.message.text` | string | Nội dung văn bản cho `plaintext`. | | `data.message.block` | object | Cây block cho tin nhắn `block`. | | `data.message.attachments` | array | Tùy chọn: tệp, nút bấm hoặc thẻ. Xem [Tệp đính kèm](/developers/vi/messages/attachments). | Một tin nhắn văn bản thuần: ```json { "type": "message_sent", "data": { "message": { "format": "plaintext", "text": "Hello! How can we help?" } } } ``` ## Trường do Subiz đặt Bạn không cần gửi các trường này. Subiz đặt chúng cho mọi yêu cầu: - `created`: thời điểm hiện tại, tính bằng mili giây Unix. - `account_id`: tài khoản của access token. - `data.message.conversation_id` và `data.conversation.id`: giá trị `cid` trong URL. Giá trị trong body sẽ bị thay thế. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng sự kiện đã gửi dưới dạng JSON, không có lớp bọc thêm. Một số trường: ```json { "id": "event_example", "account_id": "account_example", "type": "message_sent", "created": 1763107200000, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Hello! How can we help?" } } } ``` Trường rỗng bị lược bỏ. Lưu `id` của sự kiện nếu bạn cần đối chiếu tin nhắn sau này trong [lịch sử tin nhắn](/developers/vi/api-reference/conversations/history) hoặc sự kiện webhook. Phản hồi `200` nghĩa là Subiz đã nhận tin nhắn. Nó không xác nhận tin đã tới kênh bên ngoài như Facebook hoặc Zalo. ## Giới hạn - Tin nhắn gửi bằng token của agent được tính vào hạn mức của agent đó: 5 tin mỗi giây, 60 tin mỗi phút và 5.000 tin mỗi ngày UTC. Xem [Giới hạn gửi tin nhắn](/developers/vi/get-started/usage-limits#giới-hạn-gửi-tin-nhắn). - Kích thước văn bản, tệp đính kèm và trường bị giới hạn. Xem [Giới hạn tin nhắn](/developers/vi/get-started/usage-limits#giới-hạn-tin-nhắn). ## Lỗi và thử lại Kiểm tra mã trạng thái HTTP trước khi đọc body. Yêu cầu có thể thất bại do JSON không hợp lệ, lỗi xác thực, người gửi bị chặn, giới hạn tốc độ (`429`) hoặc kiểm tra dữ liệu ở dịch vụ hội thoại. Xem [Xử lý lỗi](/developers/vi/get-started/errors). Đừng thử lại mù quáng sau khi hết thời gian chờ. Tin nhắn có thể đã được gửi, và endpoint này không có khóa idempotency. Hãy kiểm tra lịch sử tin nhắn trước. ## Yêu cầu HTTP Thay `YOUR_CID` bằng ID hội thoại và `YOUR_ACCESS_TOKEN` bằng token của bạn. ```http POST https://api.subiz.com.vn/4.1/conversations/YOUR_CID/messages Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "type": "message_sent", "data": { "message": { "text": "Hello! How can we help?", "format": "plaintext" } } } ``` --- # Tệp đính kèm Thêm ảnh, video, âm thanh, tệp và nội dung tương tác vào tin nhắn. API 4.0 · 4.1 Tệp đính kèm nằm trong mảng `attachments` của tin nhắn, cạnh `text` hoặc `block`. Mỗi phần tử là một đối tượng `Attachment`. ## Chọn loại đính kèm Với media và tài liệu, dùng **`type: "file"`**. `mimetype` phân biệt ảnh, video, đoạn âm thanh hay tài liệu; không dùng `type: "image"` hoặc `type: "video"` cho các ví dụ tệp này. | Nội dung | `type` của đính kèm | Trường nội dung | | --- | --- | --- | | Ảnh | `file` | `mimetype: "image/jpeg"` hoặc kiểu MIME ảnh khác. | | Video | `file` | Ví dụ `mimetype: "video/mp4"`. | | Âm thanh | `file` | Ví dụ `mimetype: "audio/mpeg"`. | | Tài liệu | `file` | Ví dụ `mimetype: "application/pdf"`. | | Xem trước liên kết | `link` | `url`, `title` và `description`. | | Nút bấm | `button` | Mảng `buttons`. | | Trả lời nhanh | `quick_replies` | Mảng `quick_replies`. | | Thẻ | `generic` | Mảng `elements`. | Đây là các dạng đính kèm phổ biến được mô hình và trình hiển thị của Subiz hỗ trợ. Kênh đích có thể hạn chế định dạng, hành động và media. Các ví dụ dùng metadata giả lập và URL mẫu; hãy thay bằng tài nguyên thật trước khi gửi. ## Trường của tệp | Trường | Ý nghĩa | | --- | --- | | `url` | URL nguồn của tệp. Dùng URL mà Subiz tải trực tiếp được. | | `mimetype` | Kiểu MIME, như `image/jpeg`. Phải khớp với nội dung thực của tệp. | | `name` | Tên tệp, kèm phần mở rộng nếu có. | | `size` | Dung lượng tệp tính bằng byte. | | `thumbnail_url` | URL ảnh thu nhỏ, nếu có. | | `width`, `height` | Kích thước ảnh tính bằng pixel, nếu có. | | `duration` | Thời lượng âm thanh hoặc video tính bằng giây, nếu có. | Có thể bỏ metadata tùy chọn khi không biết. Subiz xử lý tệp đính kèm và có thể thay URL nguồn cùng metadata bằng thông tin tệp đã lưu. Hãy giữ các giá trị được trả về thay vì giả định phản hồi giống hệt yêu cầu. ## Ảnh Một tệp đính kèm ảnh JPEG: ```json { "type": "file", "mimetype": "image/jpeg", "url": "https://example.com/photo.jpg", "name": "photo.jpg", "size": 245760, "width": 1200, "height": 800 } ``` Tệp PNG hoặc GIF dùng đúng kiểu MIME của chúng, như `image/png` hoặc `image/gif`. Việc hiển thị và hỗ trợ ảnh động phụ thuộc vào kênh đích. ## Video Một tệp đính kèm video MP4 có ảnh xem trước: ```json { "type": "file", "mimetype": "video/mp4", "url": "https://example.com/demo.mp4", "name": "demo.mp4", "thumbnail_url": "https://example.com/demo-preview.jpg", "size": 5242880, "duration": 30 } ``` `thumbnail_url` là ảnh xem trước, không phải nguồn video. Bản thân video đặt trong `url`. Hỗ trợ định dạng và codec phụ thuộc vào kênh và trình phát. ## Âm thanh Một tệp đính kèm âm thanh MP3: ```json { "type": "file", "mimetype": "audio/mpeg", "url": "https://example.com/voice.mp3", "name": "voice.mp3", "size": 262144, "duration": 12 } ``` `duration` tính bằng giây, khác với dấu thời gian mili giây của sự kiện. Các tệp âm thanh khác phải dùng đúng kiểu MIME. ## Tài liệu và tệp khác Một tệp đính kèm PDF có thể tải xuống: ```json { "type": "file", "mimetype": "application/pdf", "url": "https://example.com/guide.pdf", "name": "guide.pdf", "size": 2048 } ``` Với tài liệu khác, giữ `type: "file"` và dùng kiểu MIME cùng tên tệp tương ứng. Tài liệu đính kèm không phải là một nút block. ## Xem trước liên kết Dùng `link` cho một khung xem trước riêng thay vì liên kết nằm trong văn bản có định dạng: ```json { "type": "link", "url": "https://example.com/delivery", "title": "Delivery guide", "description": "Delivery options and estimated timelines." } ``` Với liên kết có nhãn nằm trong câu, hãy dùng [liên kết trong block](/developers/vi/messages/formats#liên-kết-trong-block). ## Nút bấm Đính kèm `button` chứa mảng `buttons`. Ví dụ này dùng một `MessageButton` với `type: "url_button"`: ```json { "type": "button", "buttons": [ { "type": "url_button", "title": "View delivery guide", "url": "https://example.com/delivery" } ] } ``` Nhãn hiển thị của nút là `title`, và đích đến là `url`. Việc hỗ trợ hành động của nút phụ thuộc vào kênh. ## Trả lời nhanh Đính kèm `quick_replies` đưa ra các câu trả lời gợi ý. Mỗi `QuickReply` có `title` hiển thị; `payload` mang giá trị riêng của ứng dụng bạn: ```json { "type": "quick_replies", "quick_replies": [ { "content_type": "text", "title": "Track my order", "payload": "track_order" }, { "content_type": "text", "title": "Talk to support", "payload": "contact_support" } ] } ``` Các chuỗi payload này là giá trị ví dụ cho tích hợp của bạn, không phải lệnh có sẵn của Subiz. Việc nhận và xử lý lựa chọn phụ thuộc vào kênh; đừng giả định nó tới dưới dạng một tin nhắn văn bản thông thường. ## Thẻ Đính kèm `generic` chứa mảng `elements`. Mỗi `GenericElementTemplate` có thể có tiêu đề, phụ đề, ảnh và nút bấm: ```json { "type": "generic", "elements": [ { "title": "Delivery options", "subtitle": "Choose the delivery service for your order.", "image_url": "https://example.com/delivery.jpg", "buttons": [ { "type": "url_button", "title": "See options", "url": "https://example.com/delivery" } ] } ] } ``` Schema hỗ trợ nhiều phần tử, nhưng kênh đích quyết định nhận bao nhiêu và hiển thị ra sao. Trang này không định nghĩa giới hạn chung về số thẻ hay số nút. ## Gửi tệp đính kèm Đặt đính kèm trong `data.message.attachments` và gửi vào một hội thoại có sẵn. Văn bản và ảnh thuộc cùng một tin nhắn: ```http POST https://api.subiz.com.vn/4.1/conversations/YOUR_CONVERSATION_ID/messages Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "type": "message_sent", "data": { "message": { "format": "plaintext", "text": "Here is the product photo.", "attachments": [ { "type": "file", "mimetype": "image/jpeg", "url": "https://example.com/photo.jpg", "name": "photo.jpg", "size": 245760, "width": 1200, "height": 800 } ] } } } ``` URL trong ví dụ là URL mẫu. Dùng URL HTTPS tải được, không dùng đường dẫn cục bộ, URL `blob:` của trình duyệt hoặc trang cần đăng nhập trên trình duyệt của bạn. Kiểm tra tệp thực sự có sẵn trước khi gửi. Xem [Gửi tin nhắn vào hội thoại](/developers/vi/api-reference/messages/send) cho endpoint và [Định dạng tin nhắn](/developers/vi/messages/formats) để kết hợp đính kèm với văn bản hoặc block. ## Đọc dữ liệu đính kèm Xử lý mọi phần tử trong `attachments`. Với tệp, xem `mimetype`; với đính kèm có cấu trúc, xem `type` trước khi đọc trường lồng nhau. Tin nhắn không có văn bản vẫn có thể chứa ảnh, âm thanh hoặc tài liệu. Schema đầy đủ còn có các loại đính kèm riêng theo kênh và theo ứng dụng. Hãy giữ nguyên các loại mà tích hợp của bạn không nhận ra thay vì coi mọi đính kèm là tệp. Tham khảo [dữ liệu webhook](/developers/vi/webhooks/payloads) khi xử lý sự kiện tin nhắn. --- # List agents Get the agents in your account, for example to find an agent ID. API 4.1 Use this endpoint to get the agents in your account, for example to find the agent ID to use when you [invite an agent](/developers/api-reference/conversations/invite-agent) or [assign an agent](/developers/api-reference/conversations/assign-agent). The account comes from your access token. There are no request parameters and no request body. ## Response A successful request returns HTTP `200` with a JSON **array** of agents, not an object: ```json [ { "id": "agent_example", "account_id": "account_example", "type": "agent", "state": "active", "fullname": "Sam Example", "email": "sam@example.com", "scopes": [ "supervisor" ] }, { "id": "agent_second_example", "account_id": "account_example", "type": "agent", "state": "pending", "fullname": "Jamie Example", "email": "jamie@example.com" } ] ``` This example shows selected fields. See [Agent format](/developers/agents/format) for every field and `state` value. The list is not paginated. Filter the array in your code. For example, keep agents whose `state` is `active` before you show them as choices for assignment. ## Other paths `GET https://api.subiz.com.vn/4.0/agents` and `GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/agents` return the same list. ## HTTP request Replace `YOUR_ACCESS_TOKEN` with your token. ```http GET https://api.subiz.com.vn/4.1/agents Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Send to a customer Send a message to a customer through a connected channel. API 4.0 Use this endpoint to message a customer through a channel identity, such as a Facebook or Zalo profile. You do not need a conversation ID. If you already have one, [Send to a conversation](/developers/api-reference/messages/send) is simpler. ## Before you send - Get a [Bearer access token](/developers/get-started/authentication) and your account ID. - Know the customer's channel identity: channel, source, and profile ID from your connected integration. - Use a test customer while developing. Each successful request sends a real message. ## Identify the customer Choose one of two options: - **Subiz user ID.** Put the customer's ID in the `uid` path segment. - **Channel identity.** Set `channel`, `channel_source`, and `profile_id` at the top level of the body. Subiz finds the customer with that identity, or creates one, and uses that customer instead of the path `uid`. Both `channel` and `profile_id` are needed for the second option. Otherwise the path `uid` is used. ## Request body | Field | Type | Description | | --- | --- | --- | | `accid` (path) | string | Your account ID. | | `uid` (path) | string | Customer ID. Ignored when the channel identity is set. | | `channel` | string | Optional. Channel of the identity, such as `facebook` or `zalo`. | | `channel_source` | string | Optional. Connected page or account, such as a Facebook page ID. | | `profile_id` | string | Optional. Customer's ID on that channel. | | `messages` | array | Message events to try, in order. Up to five. | | `messages[].type` | string | Use `message_sent`. | | `messages[].touchpoint` | object | Where to deliver: `channel`, `source`, and `id`. | | `messages[].data.message` | object | Message content. See [Message formats](/developers/messages/formats). | A touchpoint describes one destination: ```json { "channel": "facebook", "source": "page_example", "id": "profile_example" } ``` `source` is the connected page or account. The meaning of `id` depends on the channel; it is usually the customer's profile ID there. Use values from your integration, not the Subiz user ID. ## Fallback destinations `messages` is a list of alternatives, not a batch. Subiz tries each item in order and stops after the first successful send. Use this to fall back to another channel, for example Zalo when Facebook fails. To reach one destination, send one item. With an agent's token, arrays longer than five are rejected, and every item counts toward the [message sending limits](/developers/get-started/usage-limits#message-sending-limits), even if it is never sent. Subiz can stop early if the customer has unsubscribed from the channel. ## Response A successful request returns HTTP `200` with one event: the message that was sent. It does not list results for the other items. Selected fields: ```json { "id": "event_example", "account_id": "account_example", "type": "message_sent", "created": 1763107200000, "data": { "message": { "format": "plaintext", "text": "Hello! How can we help?" } } } ``` A `200` response does not confirm delivery by the external channel. ## Errors and retries Check the HTTP status before reading the body. The send can also be rejected by the channel, for example when the integration is disconnected or the channel does not allow the message. See [Errors](/developers/get-started/errors). Do not retry blindly after a timeout; the message may already have been sent. ## HTTP request Replace the `YOUR_…` placeholders. Add `channel`, `channel_source`, and `profile_id` at the top level to identify the customer by channel identity instead of `uid`. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/users/YOUR_UID/messages Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "messages": [ { "type": "message_sent", "touchpoint": { "channel": "YOUR_CHANNEL", "source": "YOUR_SOURCE", "id": "YOUR_PROFILE_ID" }, "data": { "message": { "text": "Hello! How can we help?", "format": "plaintext" } } } ] } ``` --- # Lấy danh sách agent Lấy các agent trong tài khoản, ví dụ để tìm ID agent. API 4.1 Dùng endpoint này để lấy các agent trong tài khoản, ví dụ để tìm ID agent dùng khi [mời agent](/developers/vi/api-reference/conversations/invite-agent) hoặc [giao agent](/developers/vi/api-reference/conversations/assign-agent). Tài khoản được lấy từ access token. Không có tham số và không có body. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng một **mảng** JSON các agent, không phải một đối tượng: ```json [ { "id": "agent_example", "account_id": "account_example", "type": "agent", "state": "active", "fullname": "Sam Example", "email": "sam@example.com", "scopes": [ "supervisor" ] }, { "id": "agent_second_example", "account_id": "account_example", "type": "agent", "state": "pending", "fullname": "Jamie Example", "email": "jamie@example.com" } ] ``` Ví dụ này hiển thị một số trường. Xem [Định dạng agent](/developers/vi/agents/format) để biết mọi trường và giá trị `state`. Danh sách không phân trang. Lọc mảng trong code của bạn. Ví dụ, chỉ giữ agent có `state` là `active` trước khi hiển thị làm lựa chọn để giao việc. ## Đường dẫn khác `GET https://api.subiz.com.vn/4.0/agents` và `GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/agents` trả về cùng danh sách. ## Yêu cầu HTTP Thay `YOUR_ACCESS_TOKEN` bằng token của bạn. ```http GET https://api.subiz.com.vn/4.1/agents Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Gửi tin nhắn cho khách hàng Gửi tin nhắn cho khách hàng qua một kênh đã kết nối. API 4.0 Dùng endpoint này để nhắn cho khách hàng qua định danh kênh, như hồ sơ Facebook hoặc Zalo. Bạn không cần ID hội thoại. Nếu đã có, [Gửi tin nhắn vào hội thoại](/developers/vi/api-reference/messages/send) sẽ đơn giản hơn. ## Trước khi gửi - Lấy [Bearer access token](/developers/vi/get-started/authentication) và ID tài khoản. - Biết định danh kênh của khách hàng: kênh, nguồn và ID hồ sơ từ tích hợp đã kết nối. - Dùng một khách hàng thử nghiệm khi phát triển. Mỗi yêu cầu thành công đều gửi một tin nhắn thật. ## Xác định khách hàng Chọn một trong hai cách: - **ID user Subiz.** Đặt ID khách hàng vào phân đoạn `uid` của đường dẫn. - **Định danh kênh.** Đặt `channel`, `channel_source` và `profile_id` ở cấp ngoài cùng của body. Subiz tìm khách hàng có định danh đó, hoặc tạo mới, và dùng khách hàng này thay cho `uid` trong đường dẫn. Cách thứ hai cần cả `channel` và `profile_id`. Nếu thiếu, `uid` trong đường dẫn được dùng. ## Body yêu cầu | Trường | Kiểu | Mô tả | | --- | --- | --- | | `accid` (đường dẫn) | string | ID tài khoản của bạn. | | `uid` (đường dẫn) | string | ID khách hàng. Bị bỏ qua khi có định danh kênh. | | `channel` | string | Tùy chọn. Kênh của định danh, như `facebook` hoặc `zalo`. | | `channel_source` | string | Tùy chọn. Trang hoặc tài khoản đã kết nối, như ID trang Facebook. | | `profile_id` | string | Tùy chọn. ID của khách hàng trên kênh đó. | | `messages` | array | Các sự kiện tin nhắn sẽ thử, theo thứ tự. Tối đa năm. | | `messages[].type` | string | Dùng `message_sent`. | | `messages[].touchpoint` | object | Nơi gửi tới: `channel`, `source` và `id`. | | `messages[].data.message` | object | Nội dung tin nhắn. Xem [Định dạng tin nhắn](/developers/vi/messages/formats). | Một touchpoint mô tả một đích đến: ```json { "channel": "facebook", "source": "page_example", "id": "profile_example" } ``` `source` là trang hoặc tài khoản đã kết nối. Ý nghĩa của `id` phụ thuộc vào kênh; thường là ID hồ sơ của khách hàng trên kênh đó. Dùng giá trị từ tích hợp của bạn, không dùng ID user Subiz. ## Đích đến dự phòng `messages` là danh sách phương án thay thế, không phải gửi hàng loạt. Subiz thử từng phần tử theo thứ tự và dừng sau lần gửi thành công đầu tiên. Dùng cách này để chuyển sang kênh khác, ví dụ Zalo khi Facebook thất bại. Để gửi tới một đích, chỉ đưa một phần tử. Với token của agent, mảng dài hơn năm phần tử bị từ chối, và mọi phần tử đều được tính vào [giới hạn gửi tin nhắn](/developers/vi/get-started/usage-limits#giới-hạn-gửi-tin-nhắn), kể cả khi không bao giờ được gửi. Subiz có thể dừng sớm nếu khách hàng đã hủy đăng ký nhận tin trên kênh đó. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng một sự kiện: tin nhắn đã được gửi. Phản hồi không liệt kê kết quả của các phần tử khác. Một số trường: ```json { "id": "event_example", "account_id": "account_example", "type": "message_sent", "created": 1763107200000, "data": { "message": { "format": "plaintext", "text": "Hello! How can we help?" } } } ``` Phản hồi `200` không xác nhận kênh bên ngoài đã chuyển tin tới khách hàng. ## Lỗi và thử lại Kiểm tra mã trạng thái HTTP trước khi đọc body. Việc gửi cũng có thể bị kênh từ chối, ví dụ khi tích hợp đã ngắt kết nối hoặc kênh không cho phép tin nhắn đó. Xem [Xử lý lỗi](/developers/vi/get-started/errors). Đừng thử lại mù quáng sau khi hết thời gian chờ; tin nhắn có thể đã được gửi. ## Yêu cầu HTTP Thay các giá trị `YOUR_…`. Thêm `channel`, `channel_source` và `profile_id` ở cấp ngoài cùng để xác định khách hàng theo định danh kênh thay vì `uid`. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/users/YOUR_UID/messages Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "messages": [ { "type": "message_sent", "touchpoint": { "channel": "YOUR_CHANNEL", "source": "YOUR_SOURCE", "id": "YOUR_PROFILE_ID" }, "data": { "message": { "text": "Hello! How can we help?", "format": "plaintext" } } } ] } ``` --- # Get agent details Get one agent in your account by agent ID. API 4.0 Use this endpoint to get one agent by ID, for example to show the name of a conversation's `assignee`. Put the agent ID in the path. The account comes from your access token. There is no request body. ## Response A successful request returns HTTP `200` with an `Agent` object: ```json { "id": "agent_example", "account_id": "account_example", "type": "agent", "state": "active", "fullname": "Sam Example", "email": "sam@example.com", "avatar_url": "https://example.com/avatars/sam.png", "scopes": [ "supervisor" ] } ``` This example shows selected fields. See [Agent format](/developers/agents/format) for every field. ## Fields depend on your permissions If the agent who owns the token can view agents in the account, the response contains the full agent object. Otherwise, the response contains only these fields: ```json { "id": "agent_example", "account_id": "account_example", "fullname": "Sam Example", "avatar_url": "https://example.com/avatars/sam.png" } ``` Use a token with permission to view agents if your integration needs `state`, `email`, or other fields. If no agent has this ID, the request returns an error. See [Errors](/developers/get-started/errors). ## Other path `GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/agents/YOUR_AGID` behaves the same way. ## HTTP request Replace `YOUR_AGID` and `YOUR_ACCESS_TOKEN` with your values. ```http GET https://api.subiz.com.vn/4.0/agents/YOUR_AGID Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Lấy thông tin agent Lấy một agent trong tài khoản theo ID agent. API 4.0 Dùng endpoint này để lấy một agent theo ID, ví dụ để hiển thị tên của `assignee` trong hội thoại. Đặt ID agent trong đường dẫn. Tài khoản được lấy từ access token. Không có body. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng một đối tượng `Agent`: ```json { "id": "agent_example", "account_id": "account_example", "type": "agent", "state": "active", "fullname": "Sam Example", "email": "sam@example.com", "avatar_url": "https://example.com/avatars/sam.png", "scopes": [ "supervisor" ] } ``` Ví dụ này hiển thị một số trường. Xem [Định dạng agent](/developers/vi/agents/format) để biết mọi trường. ## Trường trả về phụ thuộc vào quyền Nếu agent sở hữu token có quyền xem agent trong tài khoản, phản hồi chứa đầy đủ đối tượng agent. Nếu không, phản hồi chỉ chứa các trường sau: ```json { "id": "agent_example", "account_id": "account_example", "fullname": "Sam Example", "avatar_url": "https://example.com/avatars/sam.png" } ``` Dùng token có quyền xem agent nếu tích hợp của bạn cần `state`, `email` hoặc các trường khác. Nếu không có agent nào có ID này, yêu cầu trả lỗi. Xem [Xử lý lỗi](/developers/vi/get-started/errors). ## Đường dẫn khác `GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/agents/YOUR_AGID` hoạt động giống hệt. ## Yêu cầu HTTP Thay `YOUR_AGID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http GET https://api.subiz.com.vn/4.0/agents/YOUR_AGID Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Order format Understand the order object: items, customer, shipping, amounts, and statuses. API 4.0 An `Order` records what a customer bought: the items, prices, shipping details, payment, and status. This page describes the order object and its nested objects. All IDs and values below are illustrative. To work with orders, see [Create an order](/developers/api-reference/orders/create), [List orders](/developers/api-reference/orders/list), [Get order details](/developers/api-reference/orders/retrieve), and [Update an order](/developers/api-reference/orders/update). ## Order Selected fields of an `Order`: ```json { "id": "order_example", "account_id": "account_example", "number": "1001", "status": "open", "payment_status": "unpaid", "currency": "VND", "user": { "id": "user_example" }, "items": [ { "id": "item_example", "quantity": 2, "product": { "id": "product_example", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000 }, "total": 240000 } ], "shipping": { "address": { "fullname": "Alex Example", "phone": "+84900000000", "address": "12 Example Street", "district": "District 1", "region": "Ho Chi Minh City", "country_code": "VN" }, "nominal_fee": 30000 }, "subtotal": 240000, "total": 270000, "payment_made": 0, "note": "Please deliver after 5 pm.", "related_conversations": [ "conversation_example" ], "created": 1763107200000, "updated": 1763107200000 } ``` | Field | Type | Description | | --- | --- | --- | | `id` | string | Subiz order ID. | | `number` | string | Human-readable order number. | | `user` | object | The customer who placed the order. See [User and attribute format](/developers/users/format). | | `items` | array | Products in the order. See [Order item](#order-item). | | `shipping` | object | Delivery address and fee. See [Shipping](#shipping). | | `currency` | string | Currency of all amounts in the order. Empty means the account's base currency. | | `status` | string | Order status. See [Statuses](#statuses). New orders default to `open`. | | `payment_status` | string | `unpaid` or `paid`. Computed from payments recorded on the order. | | `note` | string | Note visible on the order. | | `private_note` | string | Internal note for staff. | | `related_conversations` | array | IDs of conversations linked to this order. | | `source_id` | string | ID of the order in your source system, if any. | | `fields` | object | Additional fields as string key–value pairs. | | `is_draft` | boolean | `true` for a draft order. | | `created`, `updated` | integer | Unix timestamps in milliseconds. | Empty fields are omitted, and the object has more fields than shown. ## Order item Each item in `items` is one order line: ```json { "id": "item_example", "quantity": 2, "product": { "id": "product_example", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000 }, "discount_type": "percentage", "discount_percentage": 1000, "total": 216000 } ``` | Field | Type | Description | | --- | --- | --- | | `quantity` | integer | Number of units. | | `product` | object | Copy of the product at the time of the order, including `price`. | | `name`, `sku` | string | Item name and SKU, for items that are not linked to a product. | | `discount_type` | string | `amount` or `percentage`. | | `discount_amount` | number | Discount for this line, when `discount_type` is `amount`. | | `discount_percentage` | integer | Discount for this line, when `discount_type` is `percentage`. Scaled by 100: `1000` means 10%. | | `total` | number | Line total: quantity × price, minus the line discount. Computed by Subiz. | | `note` | string | Note for this line. | The product inside an item is a copy. Later changes to the product do not change existing orders. Items without a `product` are not counted in the order totals. ## Shipping `shipping` holds the delivery details: ```json { "address": { "fullname": "Alex Example", "phone": "+84900000000", "street": "12 Example Street", "ward": "Ben Nghe", "district": "District 1", "region": "Ho Chi Minh City", "country_code": "VN" }, "nominal_fee": 30000, "note": "Call before delivery.", "weight": 500 } ``` | Field | Type | Description | | --- | --- | --- | | `address` | object | Recipient's name, phone, and address. `region` is the city or province. | | `nominal_fee` | number | Shipping fee charged in the order total. | | `note` | string | Delivery instructions. | | `weight` | integer | Package weight in grams. | | `length`, `width`, `height` | integer | Package size in centimeters. | | `shipping_code` | string | Tracking code from the shipping provider. | ## Amounts All amounts are numbers in the order's `currency`. Subiz computes `subtotal`, `total_tax`, and `total` from the items, discounts, shipping fee, and adjustment. | Field | Description | | --- | --- | | `subtotal` | Sum of line totals, after line discounts. | | `total_tax` | Total tax. | | `discount_type`, `discount_amount`, `discount_percentage` | Order-level discount, applied after tax. Percentage is scaled by 100. | | `adjustment` | Extra amount added to the total. | | `total` | Amount the customer pays. | | `payment_made` | Amount paid so far. | Use line-item discounts for discounts before tax, and the order-level discount for discounts after tax. Tax rates use a different scale: a `Tax` with `percentage: 2000` means 20%. Fields that start with `fpv_`, such as `fpv_total`, are computed fixed-point copies of the amounts. Read the regular amount fields instead, and do not send `fpv_` fields. ## Statuses `status` describes where the order is in your sales process: | Value | Meaning | | --- | --- | | `open` | New order. | | `unconfirmed` | Not yet agreed between your business and the customer. | | `closed` | Confirmed (won) order. | | `canceled` | Canceled (lost) order. `cancellation_note` and `cancellation_code` explain why. | `payment_status` and `shipping_status` are tracked separately. An order can be `closed` and still `unpaid`. ## Read orders safely - **Check `currency`** before comparing or summing amounts across orders. - **Expect omitted defaults.** Empty strings, `0`, and `false` are omitted from JSON. A missing `payment_made` means nothing has been paid. - **Use `user.id`** to link the order to the customer, and `related_conversations` to find the chat. - **Ignore unknown fields and values.** Skip fields and status values your integration does not recognize. --- # Định dạng đơn hàng Hiểu đối tượng đơn hàng: mặt hàng, khách hàng, giao hàng, số tiền và trạng thái. API 4.0 `Order` ghi lại những gì khách hàng đã mua: mặt hàng, giá, thông tin giao hàng, thanh toán và trạng thái. Trang này mô tả đối tượng đơn hàng và các đối tượng lồng bên trong. Mọi ID và giá trị bên dưới chỉ mang tính minh họa. Để làm việc với đơn hàng, xem [Tạo đơn hàng](/developers/vi/api-reference/orders/create), [Lấy danh sách đơn hàng](/developers/vi/api-reference/orders/list), [Lấy thông tin đơn hàng](/developers/vi/api-reference/orders/retrieve) và [Cập nhật đơn hàng](/developers/vi/api-reference/orders/update). ## Đơn hàng Một số trường của `Order`: ```json { "id": "order_example", "account_id": "account_example", "number": "1001", "status": "open", "payment_status": "unpaid", "currency": "VND", "user": { "id": "user_example" }, "items": [ { "id": "item_example", "quantity": 2, "product": { "id": "product_example", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000 }, "total": 240000 } ], "shipping": { "address": { "fullname": "Alex Example", "phone": "+84900000000", "address": "12 Example Street", "district": "District 1", "region": "Ho Chi Minh City", "country_code": "VN" }, "nominal_fee": 30000 }, "subtotal": 240000, "total": 270000, "payment_made": 0, "note": "Please deliver after 5 pm.", "related_conversations": [ "conversation_example" ], "created": 1763107200000, "updated": 1763107200000 } ``` | Trường | Kiểu | Mô tả | | --- | --- | --- | | `id` | string | ID đơn hàng Subiz. | | `number` | string | Mã đơn hàng dễ đọc. | | `user` | object | Khách hàng đặt đơn. Xem [Định dạng khách hàng và thuộc tính](/developers/vi/users/format). | | `items` | array | Sản phẩm trong đơn. Xem [Mặt hàng trong đơn](#mặt-hàng-trong-đơn). | | `shipping` | object | Địa chỉ và phí giao hàng. Xem [Giao hàng](#giao-hàng). | | `currency` | string | Đơn vị tiền tệ của mọi số tiền trong đơn. Rỗng nghĩa là tiền tệ gốc của tài khoản. | | `status` | string | Trạng thái đơn. Xem [Trạng thái](#trạng-thái). Đơn mới mặc định là `open`. | | `payment_status` | string | `unpaid` hoặc `paid`. Được tính từ các khoản thanh toán đã ghi nhận trên đơn. | | `note` | string | Ghi chú hiển thị trên đơn. | | `private_note` | string | Ghi chú nội bộ cho agent. | | `related_conversations` | array | ID các hội thoại liên kết với đơn này. | | `source_id` | string | ID của đơn trong hệ thống nguồn của bạn, nếu có. | | `fields` | object | Trường bổ sung dạng cặp khóa–giá trị kiểu chuỗi. | | `is_draft` | boolean | `true` với đơn nháp. | | `created`, `updated` | integer | Dấu thời gian Unix tính bằng mili giây. | Trường rỗng bị lược bỏ, và đối tượng có nhiều trường hơn ví dụ. ## Mặt hàng trong đơn Mỗi phần tử trong `items` là một dòng của đơn: ```json { "id": "item_example", "quantity": 2, "product": { "id": "product_example", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000 }, "discount_type": "percentage", "discount_percentage": 1000, "total": 216000 } ``` | Trường | Kiểu | Mô tả | | --- | --- | --- | | `quantity` | integer | Số lượng. | | `product` | object | Bản sao sản phẩm tại thời điểm đặt đơn, gồm cả `price`. | | `name`, `sku` | string | Tên và SKU của mặt hàng, với mặt hàng không liên kết sản phẩm. | | `discount_type` | string | `amount` hoặc `percentage`. | | `discount_amount` | number | Chiết khấu cho dòng này, khi `discount_type` là `amount`. | | `discount_percentage` | integer | Chiết khấu cho dòng này, khi `discount_type` là `percentage`. Nhân 100: `1000` nghĩa là 10%. | | `total` | number | Thành tiền của dòng: số lượng × giá, trừ chiết khấu dòng. Do Subiz tính. | | `note` | string | Ghi chú cho dòng này. | Sản phẩm bên trong mặt hàng là một bản sao. Thay đổi sản phẩm sau đó không làm thay đổi các đơn đã có. Mặt hàng không có `product` không được tính vào tổng tiền của đơn. ## Giao hàng `shipping` chứa thông tin giao hàng: ```json { "address": { "fullname": "Alex Example", "phone": "+84900000000", "street": "12 Example Street", "ward": "Ben Nghe", "district": "District 1", "region": "Ho Chi Minh City", "country_code": "VN" }, "nominal_fee": 30000, "note": "Call before delivery.", "weight": 500 } ``` | Trường | Kiểu | Mô tả | | --- | --- | --- | | `address` | object | Tên, số điện thoại và địa chỉ người nhận. `region` là tỉnh hoặc thành phố. | | `nominal_fee` | number | Phí giao hàng tính vào tổng tiền của đơn. | | `note` | string | Hướng dẫn giao hàng. | | `weight` | integer | Khối lượng kiện hàng tính bằng gam. | | `length`, `width`, `height` | integer | Kích thước kiện hàng tính bằng centimet. | | `shipping_code` | string | Mã vận đơn của đơn vị vận chuyển. | ## Số tiền Mọi số tiền là số theo `currency` của đơn. Subiz tính `subtotal`, `total_tax` và `total` từ mặt hàng, chiết khấu, phí giao hàng và khoản điều chỉnh. | Trường | Mô tả | | --- | --- | | `subtotal` | Tổng thành tiền các dòng, sau chiết khấu dòng. | | `total_tax` | Tổng thuế. | | `discount_type`, `discount_amount`, `discount_percentage` | Chiết khấu cấp đơn, áp dụng sau thuế. Phần trăm được nhân 100. | | `adjustment` | Khoản cộng thêm vào tổng tiền. | | `total` | Số tiền khách hàng phải trả. | | `payment_made` | Số tiền đã thanh toán đến hiện tại. | Dùng chiết khấu dòng cho chiết khấu trước thuế, và chiết khấu cấp đơn cho chiết khấu sau thuế. Thuế suất dùng thang khác: `Tax` với `percentage: 2000` nghĩa là 20%. Các trường bắt đầu bằng `fpv_`, như `fpv_total`, là bản sao số tiền dạng số dấu phẩy cố định do Subiz tính. Hãy đọc các trường số tiền thông thường, và không gửi trường `fpv_`. ## Trạng thái `status` mô tả vị trí của đơn trong quy trình bán hàng: | Giá trị | Ý nghĩa | | --- | --- | | `open` | Đơn mới. | | `unconfirmed` | Chưa được doanh nghiệp và khách hàng thống nhất. | | `closed` | Đơn đã chốt (thành công). | | `canceled` | Đơn đã hủy (thất bại). `cancellation_note` và `cancellation_code` giải thích lý do. | `payment_status` và `shipping_status` được theo dõi riêng. Đơn có thể `closed` mà vẫn `unpaid`. ## Đọc đơn hàng an toàn - **Kiểm tra `currency`** trước khi so sánh hoặc cộng số tiền giữa các đơn. - **Lường trước giá trị mặc định bị lược bỏ.** Chuỗi rỗng, `0` và `false` bị lược khỏi JSON. Thiếu `payment_made` nghĩa là chưa thanh toán gì. - **Dùng `user.id`** để liên kết đơn với khách hàng, và `related_conversations` để tìm hội thoại. - **Bỏ qua trường và giá trị chưa biết.** Bỏ qua các trường và giá trị trạng thái mà tích hợp của bạn không nhận ra. --- # Nhận sự kiện webhook Tạo webhook trong Subiz, xác minh các lần gửi và xử lý sự kiện an toàn. Webhook · Không phụ thuộc phiên bản API Webhook gửi các thay đổi trong tài khoản Subiz tới máy chủ của bạn. Dùng webhook để đồng bộ khách hàng với CRM hoặc phản ứng với tin nhắn mới mà không cần liên tục gọi API. ## Tạo webhook trong Subiz Trước tiên, chuẩn bị một endpoint HTTPS công khai nhận `POST`, như `https://example.com/webhooks/subiz`. URL này thuộc ứng dụng của bạn. 1. Đăng nhập đúng tài khoản Subiz và mở [cài đặt Webhook](https://app.subiz.com.vn/settings/webhooks). 2. Nhấn **Tạo webhook**. 3. Nhập URL nhận vào ô URL. 4. Chọn **Tùy chỉnh sự kiện** và chọn các sự kiện bạn cần. Để đồng bộ khách hàng, chọn `user_created` và `user_info_updated`. Thêm `message_sent` để nhận tin nhắn. Bỏ chọn những sự kiện không cần. 5. Giữ nguyên trạng thái bật gửi và nhấn **Tạo webhook**. 6. Trong danh sách, nhấn **Chỉnh sửa** ở webhook vừa lưu. Sao chép **Mật khẩu** (secret) vào cấu hình máy chủ của bạn. Subiz tạo giá trị này khi tạo webhook; hãy dùng giá trị đã lưu, kể cả khi bạn đã nhập giá trị khác trong form tạo. Giữ secret trên máy chủ của bạn. Nó tách biệt với API access token. Nếu không truy cập được phần cài đặt này, hãy nhờ quản trị viên Subiz cấp quyền webhook. Danh sách hiển thị webhook đã lưu. Khi máy nhận đã sẵn sàng, hãy cập nhật một khách hàng hoặc gửi một tin nhắn trong tài khoản đó và kiểm tra kết quả gửi. Chỉ các sự kiện đã chọn mới được gửi; tin nhắn sẽ không kích hoạt webhook chỉ đăng ký cập nhật khách hàng. ## Nhận yêu cầu HTTP Subiz gửi một đối tượng JSON chứa mảng `events`. Hãy xử lý mọi phần tử: một yêu cầu có thể mang nhiều sự kiện. Yêu cầu này dùng giá trị giả lập. `SIGNATURE_HEX` là giá trị mẫu, không phải chữ ký hợp lệ. ```http POST https://example.com/webhooks/subiz Content-Type: application/json User-Agent: Subiz-Hook/WEBHOOK_ID X-Subiz-Delivery: 42 X-Hub-Signature-256: sha256=SIGNATURE_HEX { "events": [ { "id": "event_example_1", "account_id": "account_example", "created": 1794614400000, "type": "message_sent", "by": { "id": "user_example", "type": "user" }, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Can you help with my order?" } } } ] } ``` | Header | Mục đích | | --- | --- | | `Content-Type` | `application/json`. | | `User-Agent` | `Subiz-Hook/` theo sau là ID webhook. Không chứng minh được tính xác thực. | | `X-Subiz-Delivery` | Xác định một lần gửi trong webhook đó. Dùng để tra lỗi, không dùng để loại trùng sự kiện. | | `X-Hub-Signature-256` | Chữ ký HMAC-SHA256 của body thô. | Yêu cầu webhook dùng secret chung để xác minh, không dùng Bearer token để gọi Subiz API. ## Xác minh chữ ký **Xác minh trước khi phân tích hoặc xử lý sự kiện.** Subiz ký đúng các byte của body bằng HMAC-SHA256 và secret của bạn. Chuỗi băm là hệ thập lục phân chữ thường, không phải Base64. 1. Giữ nguyên body thô. Đừng phân tích rồi tuần tự hóa lại JSON trước. 2. Yêu cầu `X-Hub-Signature-256` bắt đầu bằng `sha256=`. Tách phần còn lại theo dấu phẩy để lấy các chuỗi băm ứng viên. 3. Kiểm tra từng ứng viên: 64 ký tự thập lục phân. Từ chối chữ ký bị thiếu hoặc sai định dạng. 4. Tính HMAC-SHA256 với secret tin cậy của bạn làm khóa và body thô làm thông điệp. 5. Giải mã các chuỗi băm ứng viên thành byte và so sánh bằng phép so sánh thời gian hằng định. Chấp nhận nếu một chuỗi khớp; nếu không, từ chối yêu cầu. Đừng để trống **Mật khẩu**. Chữ ký tạo bằng khóa rỗng không xác thực được người gửi. Không bao giờ ghi log secret hoặc chọn secret dựa trên dữ liệu chưa được xác minh trong payload. ### Khi secret thay đổi Trong 24 giờ sau khi đổi secret, các lần gửi có thể chứa chữ ký cho cả secret hiện tại và secret trước đó: ```http X-Hub-Signature-256: sha256=NEW_SECRET_DIGEST,PREVIOUS_SECRET_DIGEST ``` Chỉ có một tiền tố `sha256=`. Chuỗi băm nào cũng có thể khớp với secret tin cậy của bạn. Hãy cập nhật secret của máy nhận trong khoảng thời gian này; chữ ký cũ sẽ không còn được gửi kèm sau khi hết hạn. ### Kiểm tra bộ xác minh ở máy cục bộ Dùng bộ dữ liệu kiểm thử công khai này, không dùng secret thật. Body là UTF-8 và **không có ký tự xuống dòng ở cuối**: | Đầu vào | Giá trị | | --- | --- | | Secret | `docs-example-secret` | | Body thô | `{"events":[]}` | Header mong đợi là: ```http X-Hub-Signature-256: sha256=145cedf7d7a150f4634f5fec31aef38195afc099c596a0f274fc5ef9c2136835 ``` Đây chỉ là bài kiểm tra chữ ký. Thêm một dấu cách hoặc dấu xuống dòng vào body phải làm chữ ký này thất bại. ## Xác nhận và xử lý **Nhận → Xác minh → Lưu → Phản hồi → Xử lý** 1. Xác minh chữ ký, sau đó phân tích JSON. Kiểm tra tài khoản và các trường tích hợp của bạn cần. 2. Lưu mọi sự kiện được chấp nhận vào bộ lưu trữ bền vững hoặc hàng đợi. Xử lý trùng lặp bằng `(account_id, id)` làm khóa sự kiện. 3. Trả `200 OK` sau khi lưu thành công. Làm các việc chậm, như cập nhật CRM, trong worker chạy nền. ```http HTTP/1.1 200 OK Content-Length: 0 ``` Bên gửi có **thời gian chờ 30 giây cho mỗi lần thử HTTP** và không đi theo chuyển hướng. Hãy phản hồi ngay khi sự kiện đã được lưu an toàn. Phản hồi thành công xác nhận cả lô, không chỉ sự kiện đầu tiên. Nếu lưu thất bại, hãy trả lỗi để lần gửi có thể được thử lại. Khi đã trả thành công, worker của bạn phải tự thử lại khi gặp lỗi. Lưu sự kiện cùng công việc chờ xử lý của nó trong một lần, để sự cố không khiến sự kiện bị đánh dấu đã xử lý mà công việc chưa được lên lịch. ## Gửi lại và sự kiện trùng lặp Một yêu cầu thất bại có thể được gửi lại. Điều này gồm cả trường hợp máy chủ của bạn đã lưu sự kiện nhưng Subiz không nhận được phản hồi. - Loại trùng theo ID sự kiện và ID tài khoản, không theo `X-Subiz-Delivery`: lần gửi lại có thể có ID gửi mới. - Trả thành công cho các sự kiện bạn đã chấp nhận an toàn. Đừng lặp lại tác động của chúng. - Bỏ qua an toàn các loại sự kiện không hỗ trợ; đừng làm hỏng cả lô chỉ vì xuất hiện loại mới. - Đừng phụ thuộc vào thứ tự tới hay việc gửi đúng một lần. Đối chiếu với bản ghi hiện tại khi cần. Ở đây không cam kết khoảng thời gian thử lại hay số lần thử cố định. Lỗi kéo dài có thể làm dừng việc gửi, và các sự kiện cũ trong hàng đợi có thể bị hủy. Hãy khắc phục sớm; đừng coi hàng đợi webhook là kho lưu trữ sự kiện lâu dài. ## Kiểm thử và xử lý sự cố Sau khi tạo webhook, kích hoạt một sự kiện đã chọn trong tài khoản thử nghiệm. Kiểm tra máy nhận đã xác minh, lưu, trả `200` và thực hiện cập nhật mong muốn **đúng một lần**. Phát lại cùng sự kiện ở máy cục bộ để kiểm tra loại trùng, và đổi một byte trong body để kiểm tra việc từ chối. Mở webhook trong Subiz để xem các lần gửi gần đây và phản hồi HTTP của chúng. So sánh với log của máy nhận và worker. | Vấn đề | Kiểm tra | | --- | --- | | Không có lần gửi nào | Đúng tài khoản Subiz, đã bật gửi và đã chọn sự kiện trong webhook. | | Yêu cầu không tới được máy nhận | URL, DNS, chứng chỉ HTTPS, tường lửa, và mọi bước đăng nhập hay chuyển hướng phía trước endpoint. | | Chữ ký không khớp | Cùng secret ở hai phía, đúng các byte body thô, giải mã hex và xử lý nhiều chuỗi băm. | | Hết thời gian chờ hoặc lỗi máy chủ | Lưu lô trước khi phản hồi; chuyển việc chậm sang worker. Kiểm tra hàng đợi và cơ sở dữ liệu. | | Trả `200` nhưng CRM không thay đổi | Lỗi worker, loại sự kiện không hỗ trợ, ánh xạ trường và trạng thái loại trùng. | | Việc gửi dừng sau sự cố | Sửa máy nhận, nhờ quản trị viên Subiz kiểm tra trạng thái webhook và đối chiếu dữ liệu còn thiếu. | Ghi log ID lần gửi, ID sự kiện và kết quả xử lý. Tránh ghi log secret và dữ liệu khách hàng không cần thiết. Tiếp theo: [Ví dụ dữ liệu sự kiện](/developers/vi/webhooks/payloads). --- # Receive webhook events Create a webhook in Subiz, verify deliveries, and process events safely. Webhook · Not tied to an API route version A webhook sends changes in your Subiz account to your server. Use it to sync customers with your CRM or react to new messages without polling the API. ## Create a webhook in Subiz First, prepare a public HTTPS endpoint that accepts `POST`, such as `https://example.com/webhooks/subiz`. This URL belongs to your application. 1. Sign in to the intended Subiz account and open [Webhook settings](https://app.subiz.com.vn/settings/webhooks). 2. Click **Add a webhook**. 3. Enter your receiving URL in the URL field. 4. Choose **Custom event** and select the events you need. For customer synchronization, select `user_created` and `user_info_updated`. Add `message_sent` to receive messages. Clear any selections you do not need. 5. Leave delivery enabled and click **Create webhook**. 6. In the list, click **Edit** for the saved webhook. Copy its **Secret** into your server configuration. Subiz generates this value when creating the webhook; use the saved value, even if you entered a different one in the creation form. Keep the secret on your server. It is separate from your API access token. If you cannot access these settings, ask your Subiz administrator for webhook permissions. The list shows the saved webhook. Once your receiver is ready, make a customer update or send a message in that account and check the delivery result. Only selected events are delivered; a message will not trigger a webhook subscribed only to customer updates. ## Receive an HTTP request Subiz sends a JSON object containing an `events` array. Process every item: one request can carry several events. This request uses synthetic values. `SIGNATURE_HEX` is a placeholder, not a valid signature. ```http POST https://example.com/webhooks/subiz Content-Type: application/json User-Agent: Subiz-Hook/WEBHOOK_ID X-Subiz-Delivery: 42 X-Hub-Signature-256: sha256=SIGNATURE_HEX { "events": [ { "id": "event_example_1", "account_id": "account_example", "created": 1794614400000, "type": "message_sent", "by": { "id": "user_example", "type": "user" }, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Can you help with my order?" } } } ] } ``` | Header | Purpose | | --- | --- | | `Content-Type` | `application/json`. | | `User-Agent` | `Subiz-Hook/` followed by the webhook ID. It does not prove authenticity. | | `X-Subiz-Delivery` | Identifies a delivery within that webhook. Use it for troubleshooting, not event deduplication. | | `X-Hub-Signature-256` | HMAC-SHA256 signature of the raw request body. | Webhook requests use the shared secret for verification, not the Bearer token used to call the Subiz API. ## Verify the signature **Verify before parsing or processing events.** Subiz signs the exact body bytes using HMAC-SHA256 and your secret. The digest is lowercase hexadecimal, not Base64. 1. Keep the raw request body. Do not parse and re-serialize JSON first. 2. Require `X-Hub-Signature-256` to start with `sha256=`. Split the remaining value on commas to get the candidate digests. 3. Validate each candidate: 64 hexadecimal characters. Reject missing or malformed signatures. 4. Calculate HMAC-SHA256 with your trusted secret as the key and the raw body as the message. 5. Decode the candidate digests into bytes and compare with a constant-time comparison. Accept if one matches; otherwise reject the request. Do not leave **Secret** empty. A signature made with an empty key does not authenticate the sender. Never log your secret or select a secret based on unverified payload data. ### When the secret changes For 24 hours after a secret change, deliveries can contain signatures for both the current and previous secrets: ```http X-Hub-Signature-256: sha256=NEW_SECRET_DIGEST,PREVIOUS_SECRET_DIGEST ``` There is one `sha256=` prefix. Either digest may match your trusted secret. Update your receiver's secret during this window; the old signature stops being included after it expires. ### Check your verifier locally Use this public test vector, not a production secret. The body is UTF-8 with **no trailing newline**: | Input | Value | | --- | --- | | Secret | `docs-example-secret` | | Raw body | `{"events":[]}` | The expected header is: ```http X-Hub-Signature-256: sha256=145cedf7d7a150f4634f5fec31aef38195afc099c596a0f274fc5ef9c2136835 ``` This is a signature test only. Adding a space or newline to the body must make this signature fail. ## Acknowledge and process **Receive → Verify → Store → Respond → Process** 1. Verify the signature, then parse the JSON. Check the account and the fields your integration needs. 2. Save all accepted events to durable storage or a queue. Handle duplicates using `(account_id, id)` as the event key. 3. Return `200 OK` after storage succeeds. Do slow work, such as CRM updates, in a background worker. ```http HTTP/1.1 200 OK Content-Length: 0 ``` The sender has a **30-second timeout per HTTP attempt** and does not follow redirects. Respond as soon as the events are safely stored. A successful response acknowledges the whole batch, not just the first event. If storage fails, return an error so the delivery can be retried. Once you return success, your worker must retry its own failures. Store the event and its pending work together so a crash cannot leave an event marked as handled without scheduling the work. ## Retries and duplicate events A failed request can be sent again. This includes cases where your server saved the events but Subiz did not receive the response. - Deduplicate by event ID and account ID, not `X-Subiz-Delivery`: a retry can have a new delivery ID. - Return success for events you have already safely accepted. Do not repeat their side effects. - Ignore unsupported event types safely; do not fail the entire batch just because a new type appears. - Do not depend on arrival order or exactly-once delivery. Reconcile with current records when necessary. There is no fixed retry interval or attempt count promised here. Extended failures can stop delivery, and old queued events can be discarded. Recover promptly; do not treat the webhook queue as a permanent event archive. ## Test and troubleshoot After creating the webhook, trigger one selected event in a test account. Check that your receiver verifies it, stores it, returns `200`, and performs the intended update **once**. Replay the same event locally to check deduplication, and change one body byte to check rejection. Open the webhook in Subiz to inspect recent deliveries and their HTTP responses. Compare them with your receiver and worker logs. | Problem | Check | | --- | --- | | No delivery | Correct Subiz account, delivery enabled, and the event selected in the webhook. | | Request never reaches your receiver | URL, DNS, HTTPS certificate, firewall, and any login or redirect in front of the endpoint. | | Signature mismatch | Same secret on both sides, exact raw body bytes, hex decoding, and multiple-digest handling. | | Timeout or server error | Store the batch before responding; move slow work to a worker. Check queue and database availability. | | `200` but no CRM change | Worker failures, unsupported event types, field mapping, and deduplication state. | | Delivery stopped after an outage | Fix the receiver, check the webhook status with your Subiz administrator, and reconcile any missing data. | Log delivery IDs, event IDs, and processing outcomes. Avoid logging secrets and unnecessary customer data. Next: [Event payload examples](/developers/webhooks/payloads). --- # Create an order Create an order for an existing customer. API 4.0 Use this endpoint to record a sale in Subiz, for example when an order is placed in your shop or CRM. See [Order format](/developers/orders/format) for all fields. ## Before you begin - Get a [Bearer access token](/developers/get-started/authentication) and your account ID. - Get the customer's Subiz user ID. Every order needs a customer. Use [Find or create by channel identity](/developers/api-reference/users/identity) or [Create a customer](/developers/api-reference/users/create) first if needed. ## Request body | Field | Type | Description | | --- | --- | --- | | `user.id` | string | Required. ID of an existing customer. | | `items` | array | Order lines. Each has a `quantity` and a `product` with `name`, `sku`, and `price`. | | `source_id` | string | Recommended. Your own order ID. See [Avoid duplicates](#avoid-duplicates). | | `currency` | string | Currency of the amounts, such as `VND`. Empty means the account's base currency. | | `shipping` | object | Delivery address and `nominal_fee`. | | `status` | string | Optional. `open` (default), `unconfirmed`, `closed`, or `canceled`. | | `number` | string | Optional. Order number. Must not already be used by another order. | | `note`, `private_note` | string | Optional notes. | | `discount_type`, `discount_amount`, `discount_percentage` | | Optional order-level discount. | Line items keep the product data you send, including `price`. Send the price you charged; Subiz does not look it up again. If a line has `product.source_id` but no `product.id`, Subiz links it to the catalog product with that source ID and uses the catalog data. If no such product exists, Subiz creates one named after the source ID, without a price. ## Fields Subiz sets Do not send these fields; Subiz sets or computes them: - `id`, `created`, `created_by`, `updated`. - `subtotal`, `total_tax`, `total`, and line `total`, computed from the items, discounts, shipping fee, and adjustment. - `payment_made` and `payment_status`, computed from payments recorded on the order. A new order is `unpaid`. - `user.attributes`: if you omit the customer's `fullname` or `phones`, Subiz copies them from the customer record. - `pipeline_stage`: if you send no pipeline, the order starts in the first stage of the default sales pipeline. ## Avoid duplicates Set `source_id` to the order's ID in your system. If an order with the same `source_id` already exists, Subiz **replaces that order** with the fields you send instead of creating another one. This makes retries safe. Always send the complete order. Without `source_id`, every request creates a new order. Do not retry blindly after a timeout; first check with [List orders](/developers/api-reference/orders/list). ## Response A successful request returns HTTP `200` with the saved order, including its `id` and computed totals. Selected fields: ```json { "id": "order_example", "account_id": "account_example", "source_id": "crm-1001", "status": "open", "payment_status": "unpaid", "currency": "VND", "user": { "id": "user_example" }, "subtotal": 240000, "total": 270000, "created": 1763107200000 } ``` Store the `id` to [read](/developers/api-reference/orders/retrieve) or [update](/developers/api-reference/orders/update) the order later. ## Errors | Problem | Result | | --- | --- | | `user.id` is missing | Error naming the missing `user`. | | Customer does not exist | Not-found error for the user. | | `status` is not one of the four values above | Invalid-input error for `status`. | | `number` already used | The request fails. Use a new number or omit it. | See [Errors](/developers/get-started/errors) for the error format. ## HTTP request Replace `YOUR_ACCID`, `YOUR_USER_ID`, `YOUR_SOURCE_ORDER_ID`, and `YOUR_ACCESS_TOKEN` with your values. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "source_id": "YOUR_SOURCE_ORDER_ID", "user": { "id": "YOUR_USER_ID" }, "currency": "VND", "items": [ { "quantity": 2, "product": { "name": "Ceramic mug", "sku": "MUG-01", "price": 120000 } } ], "shipping": { "address": { "fullname": "Alex Example", "phone": "+84900000000", "address": "12 Example Street", "region": "Ho Chi Minh City", "country_code": "VN" }, "nominal_fee": 30000 } } ``` --- # Tạo đơn hàng Tạo đơn hàng cho một khách hàng đã có. API 4.0 Dùng endpoint này để ghi nhận một giao dịch bán trong Subiz, ví dụ khi có đơn đặt trong cửa hàng hoặc CRM của bạn. Xem [Định dạng đơn hàng](/developers/vi/orders/format) để biết mọi trường. ## Trước khi bắt đầu - Lấy [Bearer access token](/developers/vi/get-started/authentication) và ID tài khoản. - Lấy ID user Subiz của khách hàng. Mọi đơn hàng đều cần khách hàng. Dùng [Tìm hoặc tạo theo định danh kênh](/developers/vi/api-reference/users/identity) hoặc [Tạo khách hàng](/developers/vi/api-reference/users/create) trước nếu cần. ## Body yêu cầu | Trường | Kiểu | Mô tả | | --- | --- | --- | | `user.id` | string | Bắt buộc. ID của một khách hàng đã có. | | `items` | array | Các dòng của đơn. Mỗi dòng có `quantity` và một `product` với `name`, `sku` và `price`. | | `source_id` | string | Nên có. ID đơn hàng của riêng bạn. Xem [Tránh trùng lặp](#tránh-trùng-lặp). | | `currency` | string | Đơn vị tiền tệ của các số tiền, như `VND`. Rỗng nghĩa là tiền tệ gốc của tài khoản. | | `shipping` | object | Địa chỉ giao hàng và `nominal_fee`. | | `status` | string | Tùy chọn. `open` (mặc định), `unconfirmed`, `closed` hoặc `canceled`. | | `number` | string | Tùy chọn. Mã đơn hàng. Không được trùng với đơn khác. | | `note`, `private_note` | string | Ghi chú tùy chọn. | | `discount_type`, `discount_amount`, `discount_percentage` | | Chiết khấu cấp đơn tùy chọn. | Các dòng giữ nguyên dữ liệu sản phẩm bạn gửi, kể cả `price`. Hãy gửi đúng giá đã bán; Subiz không tra cứu lại giá. Nếu một dòng có `product.source_id` nhưng không có `product.id`, Subiz liên kết nó với sản phẩm trong danh mục có source ID đó và dùng dữ liệu trong danh mục. Nếu chưa có sản phẩm như vậy, Subiz tạo một sản phẩm mang tên là source ID, không có giá. ## Trường do Subiz đặt Không gửi các trường sau; Subiz tự đặt hoặc tính: - `id`, `created`, `created_by`, `updated`. - `subtotal`, `total_tax`, `total` và `total` của từng dòng, được tính từ mặt hàng, chiết khấu, phí giao hàng và khoản điều chỉnh. - `payment_made` và `payment_status`, được tính từ các khoản thanh toán đã ghi nhận trên đơn. Đơn mới ở trạng thái `unpaid`. - `user.attributes`: nếu bạn bỏ trống `fullname` hoặc `phones` của khách hàng, Subiz sao chép từ hồ sơ khách hàng. - `pipeline_stage`: nếu bạn không gửi pipeline, đơn bắt đầu ở giai đoạn đầu tiên của pipeline bán hàng mặc định. ## Tránh trùng lặp Đặt `source_id` là ID của đơn trong hệ thống của bạn. Nếu đã có đơn cùng `source_id`, Subiz **thay thế đơn đó** bằng các trường bạn gửi thay vì tạo đơn mới. Điều này giúp thử lại an toàn. Luôn gửi đơn hàng đầy đủ. Nếu không có `source_id`, mỗi yêu cầu tạo một đơn mới. Đừng thử lại mù quáng sau khi hết thời gian chờ; hãy kiểm tra bằng [Lấy danh sách đơn hàng](/developers/vi/api-reference/orders/list) trước. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng đơn đã lưu, gồm `id` và các tổng tiền đã tính. Một số trường: ```json { "id": "order_example", "account_id": "account_example", "source_id": "crm-1001", "status": "open", "payment_status": "unpaid", "currency": "VND", "user": { "id": "user_example" }, "subtotal": 240000, "total": 270000, "created": 1763107200000 } ``` Lưu `id` để [đọc](/developers/vi/api-reference/orders/retrieve) hoặc [cập nhật](/developers/vi/api-reference/orders/update) đơn sau này. ## Lỗi | Vấn đề | Kết quả | | --- | --- | | Thiếu `user.id` | Lỗi nêu tên `user` bị thiếu. | | Khách hàng không tồn tại | Lỗi không tìm thấy user. | | `status` không thuộc bốn giá trị ở trên | Lỗi dữ liệu không hợp lệ cho `status`. | | `number` đã được dùng | Yêu cầu thất bại. Dùng mã khác hoặc bỏ trống. | Xem [Xử lý lỗi](/developers/vi/get-started/errors) để biết định dạng lỗi. ## Yêu cầu HTTP Thay `YOUR_ACCID`, `YOUR_USER_ID`, `YOUR_SOURCE_ORDER_ID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "source_id": "YOUR_SOURCE_ORDER_ID", "user": { "id": "YOUR_USER_ID" }, "currency": "VND", "items": [ { "quantity": 2, "product": { "name": "Ceramic mug", "sku": "MUG-01", "price": 120000 } } ], "shipping": { "address": { "fullname": "Alex Example", "phone": "+84900000000", "address": "12 Example Street", "region": "Ho Chi Minh City", "country_code": "VN" }, "nominal_fee": 30000 } } ``` --- # Ví dụ dữ liệu sự kiện Đọc sự kiện tin nhắn, khách hàng và hội thoại trong một lần gửi webhook. Webhook · Không phụ thuộc phiên bản API Các ví dụ dưới đây là payload rút gọn với giá trị giả lập. Chúng cho thấy các trường được hỗ trợ, không phải danh mục sự kiện đầy đủ hay cam kết rằng trường tùy chọn luôn có mặt. ## Chọn loại sự kiện | Sự kiện | Đối tượng dữ liệu | Dùng để | | --- | --- | --- | | `message_sent` | `data.message` | Nhận tin nhắn và liên kết chúng với hội thoại. | | `user_created` | `data.user` | Tạo hoặc liên kết hồ sơ khách hàng trong CRM. | | `user_info_updated` | `data.user` | Đồng bộ thông tin khách hàng. | | `conversation_assigned` | `data.conversation` | Cập nhật agent phụ trách. | | `conversation_unassigned` | `data.conversation` | Bỏ agent phụ trách. | Chọn ba loại đầu tiên trong **Tùy chỉnh sự kiện** khi [tạo webhook](/developers/vi/webhooks/receiving#tạo-webhook-trong-subiz). Sự kiện giao việc được backend hỗ trợ nhưng chưa có trong form tạo hiện tại; các ví dụ giao việc chỉ áp dụng cho những đăng ký đã được cấu hình sẵn cho các loại đó. ## Đọc phần bao của sự kiện | Trường | Ý nghĩa | | --- | --- | | `id` | ID sự kiện. Kết hợp với `account_id` để loại trùng khi xử lý. | | `account_id` | Tài khoản Subiz mà sự kiện thuộc về. | | `type` | Tên sự kiện. Dùng để chọn cách đọc `data`. | | `created` | Thời điểm Subiz ghi nhận sự kiện, tính bằng mili giây Unix. | | `event_time` | Thời điểm xảy ra gốc, nếu có, tính bằng mili giây Unix. Dùng `created` nếu không có. | | `by` | Ngữ cảnh tác nhân, nếu có. `by.type` là loại tác nhân; `by.id` xác định tác nhân. | | `data` | Dữ liệu của loại sự kiện này. | Các đường dẫn này tính từ mỗi phần tử trong `events`, ví dụ `events[0].id`. Đừng nhầm ID sự kiện với ID user, ID hội thoại hay header `X-Subiz-Delivery`. Trường có giá trị rỗng có thể bị lược bỏ. `by` có thể không có hoặc chỉ chứa ngữ cảnh như thông tin thiết bị. Kiểm tra những gì bộ xử lý của bạn cần và chấp nhận các trường bổ sung. ## Tin nhắn được gửi Sự kiện `message_sent` có thể là tin nhắn của khách hàng, câu trả lời của agent hoặc nội dung tự động. Bản thân nó không xác nhận tin đã tới kênh bên ngoài. ```json { "events": [ { "id": "event_example_1", "account_id": "account_example", "created": 1794614400000, "type": "message_sent", "by": { "id": "user_example", "type": "user" }, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Can you help with my order?" } } } ] } ``` Dùng `data.message.conversation_id` để liên kết tin nhắn với hội thoại. Kiểm tra `by.type` để phân biệt khách hàng (`user`) với agent (`agent`), và kiểm tra `data.message.is_internal` trước khi coi tin nhắn là hiển thị với khách hàng. Đừng tự động trả lời mọi sự kiện `message_sent`: chính câu trả lời của bạn cũng có thể kích hoạt loại sự kiện này. ### Block trong tin nhắn phong phú Khi `format` là `block`, đọc `data.message.block` như một cây. `content` chứa các nút con; nút văn bản có thể có định dạng như `bold`. ```json { "events": [ { "id": "event_example_2", "account_id": "account_example", "created": 1794614401000, "type": "message_sent", "by": { "id": "agent_example", "type": "agent" }, "data": { "message": { "conversation_id": "conversation_example", "format": "block", "text": "Hello Alex", "block": { "type": "paragraph", "content": [ { "type": "text", "text": "Hello " }, { "type": "text", "text": "Alex", "bold": true } ] } } } } ] } ``` Nội dung này hiển thị là “Hello **Alex**”. Giữ cây block khi lưu nội dung phong phú; chỉ dùng `text` sẽ mất định dạng. Tin nhắn cũng có thể chứa `attachments`, và tin nhắn không có văn bản chưa chắc đã rỗng. Xem [Tin nhắn định dạng phong phú bằng block](/developers/vi#tin-nhắn-định-dạng-phong-phú-bằng-block). ## Khách hàng được tạo `user_created` chứa khách hàng trong `data.user`. Dùng `(account_id, data.user.id)` làm tham chiếu Subiz trong CRM của bạn. Khách hàng là user, không phải agent. ```json { "events": [ { "id": "event_example_3", "account_id": "account_example", "created": 1794614399000, "type": "user_created", "data": { "user": { "id": "user_example", "account_id": "account_example", "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "created", "datetime": "2026-11-13T23:59:59Z" } ] } } } ] } ``` `attributes` là một mảng, không phải đối tượng có khóa theo tên. Tìm thuộc tính có `key` là `fullname`, rồi đọc `text`. Thuộc tính ngày dùng `datetime`; thuộc tính khác có thể dùng `number` hoặc `boolean`. Đừng dùng vị trí trong mảng để xác định trường. ## Thông tin khách hàng được cập nhật `user_info_updated` mang thông tin khách hàng trong `data.user`. Hãy coi đây là bản cập nhật để đồng bộ, không phải danh sách chỉ gồm các trường đã thay đổi. ```json { "events": [ { "id": "event_example_4", "account_id": "account_example", "created": 1794614402000, "type": "user_info_updated", "data": { "user": { "id": "user_example", "account_id": "account_example", "attributes": [ { "key": "fullname", "text": "Alex Example", "modified": 1794614402000, "by_type": "agent", "by": "agent_example" }, { "key": "created", "datetime": "2026-11-13T23:59:59Z" } ] } } } ] } ``` Ở đây, `modified` ghi thời điểm cập nhật thuộc tính, tính bằng mili giây Unix. `by` và `by_type` của nó mô tả ai đã cập nhật thuộc tính đó; chúng tách biệt với đối tượng `by` tùy chọn ở cấp sự kiện. Chỉ upsert các trường CRM của bạn dùng. Thuộc tính bị lược bỏ không phải là chỉ thị xóa giá trị trong CRM. Các cập nhật liên tiếp nhanh của cùng một khách hàng có thể được gộp trước khi gửi webhook, nên sự kiện này không phải là nhật ký đầy đủ mọi lần chỉnh sửa. Gọi [Lấy thông tin khách hàng](/developers/vi/api-reference/users/retrieve) khi bạn cần bản ghi mới nhất. ## Hội thoại được giao `conversation_assigned` mang ID hội thoại và agent phụ trách trong `data.conversation`. Đây là quyền phụ trách, không phải tư cách thành viên hay lời mời tham gia. ```json { "events": [ { "id": "event_example_5", "account_id": "account_example", "created": 1794614403000, "type": "conversation_assigned", "data": { "conversation": { "id": "conversation_example", "assignee": "agent_example" } } } ] } ``` ### Bỏ người phụ trách `conversation_unassigned` cho biết người phụ trách đã bị bỏ. Trong ví dụ này, `assignee` rỗng nên bị lược bỏ. Dùng loại sự kiện để nhận biết thay đổi; đừng coi mọi trường hợp thiếu `assignee` ở các loại sự kiện khác là chỉ thị bỏ người phụ trách. ```json { "events": [ { "id": "event_example_6", "account_id": "account_example", "created": 1794614404000, "type": "conversation_unassigned", "data": { "conversation": { "id": "conversation_example" } } } ] } ``` Xem [Giao agent phụ trách](/developers/vi/api-reference/conversations/assign-agent) cho thao tác hội thoại tương ứng. ## Xử lý một lô an toàn Với mỗi sự kiện, loại trùng theo `(account_id, id)`, phân luồng theo `type` và kiểm tra đối tượng `data` tương ứng. Một lô có thể chứa nhiều khách hàng hoặc hội thoại. Bỏ qua an toàn các loại sự kiện không hỗ trợ và đừng giả định thứ tự gửi khớp với thứ tự tạo. Lưu mọi công việc được chấp nhận trước khi xác nhận lô. Xem [Xác nhận và xử lý](/developers/vi/webhooks/receiving#xác-nhận-và-xử-lý) cho luồng của máy nhận. --- # Event payload examples Read message, customer, and conversation events in a webhook delivery. Webhook · Not tied to an API route version [Verify the request signature](/developers/webhooks/receiving#verify-the-signature) before reading these fields. Each request wraps one or more events in an `events` array. The examples below are shortened payloads with synthetic values. They show supported fields, not an exhaustive event catalog or a guarantee that optional fields are always present. ## Choose the event type | Event | Data object | Use it to | | --- | --- | --- | | `message_sent` | `data.message` | Receive messages and associate them with a conversation. | | `user_created` | `data.user` | Create or link a customer record in your CRM. | | `user_info_updated` | `data.user` | Synchronize customer information. | | `conversation_assigned` | `data.conversation` | Update the responsible agent. | | `conversation_unassigned` | `data.conversation` | Clear the responsible agent. | Select the first three types under **Custom event** when [creating a webhook](/developers/webhooks/receiving#create-a-webhook-in-subiz). Assignment events are supported by the backend but are not listed in the current creation form; the assignment examples apply only to subscriptions already configured for those types. ## Read the event envelope | Field | Meaning | | --- | --- | | `id` | Event ID. Combine with `account_id` to deduplicate processing. | | `account_id` | Subiz account that the event belongs to. | | `type` | Event name. Use it to choose how to read `data`. | | `created` | Time the event was recorded in Subiz, as Unix milliseconds. | | `event_time` | Original occurrence time, when provided, in Unix milliseconds. Fall back to `created` if absent. | | `by` | Actor context, when available. `by.type` identifies the actor type; `by.id` identifies the actor. | | `data` | Data for this event type. | These paths are relative to each item in `events`, for example `events[0].id`. Do not confuse the event ID with a user ID, conversation ID, or the `X-Subiz-Delivery` header. Fields with empty values can be omitted. `by` may be absent or contain only context such as device information. Validate what your handler needs and tolerate additional fields. ## Message sent A `message_sent` event can represent a customer message, an agent reply, or automated content. It does not by itself confirm delivery to an external channel. ```json { "events": [ { "id": "event_example_1", "account_id": "account_example", "created": 1794614400000, "type": "message_sent", "by": { "id": "user_example", "type": "user" }, "data": { "message": { "conversation_id": "conversation_example", "format": "plaintext", "text": "Can you help with my order?" } } } ] } ``` Use `data.message.conversation_id` to associate the message with a conversation. Check `by.type` to distinguish a customer (`user`) from an agent (`agent`), and check `data.message.is_internal` before treating a message as customer-facing. Do not automatically reply to every `message_sent` event: your own replies can trigger the same event type. ### Rich message blocks When `format` is `block`, read `data.message.block` as a tree. `content` contains child nodes; text nodes can include formatting such as `bold`. ```json { "events": [ { "id": "event_example_2", "account_id": "account_example", "created": 1794614401000, "type": "message_sent", "by": { "id": "agent_example", "type": "agent" }, "data": { "message": { "conversation_id": "conversation_example", "format": "block", "text": "Hello Alex", "block": { "type": "paragraph", "content": [ { "type": "text", "text": "Hello " }, { "type": "text", "text": "Alex", "bold": true } ] } } } } ] } ``` This renders “Hello **Alex**”. Keep the block tree when storing rich content; `text` alone loses formatting. Messages can also contain `attachments`, and a message without text is not necessarily empty. See [Rich messages with blocks](/developers#rich-messages-with-blocks). ## Customer created `user_created` contains the customer in `data.user`. Use `(account_id, data.user.id)` as your CRM's Subiz reference. Customers are users, not staff agents. ```json { "events": [ { "id": "event_example_3", "account_id": "account_example", "created": 1794614399000, "type": "user_created", "data": { "user": { "id": "user_example", "account_id": "account_example", "attributes": [ { "key": "fullname", "text": "Alex Example" }, { "key": "created", "datetime": "2026-11-13T23:59:59Z" } ] } } } ] } ``` `attributes` is an array, not an object keyed by name. Find the attribute whose `key` is `fullname`, then read `text`. Date attributes use `datetime`; other attributes can use `number` or `boolean`. Do not use array position to identify a field. ## Customer information updated `user_info_updated` carries customer information under `data.user`. Treat it as a synchronization update, not a list containing only changed fields. ```json { "events": [ { "id": "event_example_4", "account_id": "account_example", "created": 1794614402000, "type": "user_info_updated", "data": { "user": { "id": "user_example", "account_id": "account_example", "attributes": [ { "key": "fullname", "text": "Alex Example", "modified": 1794614402000, "by_type": "agent", "by": "agent_example" }, { "key": "created", "datetime": "2026-11-13T23:59:59Z" } ] } } } ] } ``` Here, `modified` records an attribute's update time in Unix milliseconds. Its `by` and `by_type` describe who updated that attribute; they are separate from the optional event-level `by` object. Upsert only the fields your CRM uses. An omitted attribute is not an instruction to delete its CRM value. Rapid updates to the same customer can be combined before webhook delivery, so this event is not a complete audit trail of every edit. Fetch [Get customer details](/developers/api-reference/users/retrieve) when you need the latest record. ## Conversation assigned `conversation_assigned` carries the conversation ID and responsible agent in `data.conversation`. This is ownership, not membership or an invitation to join. ```json { "events": [ { "id": "event_example_5", "account_id": "account_example", "created": 1794614403000, "type": "conversation_assigned", "data": { "conversation": { "id": "conversation_example", "assignee": "agent_example" } } } ] } ``` ### Ownership cleared `conversation_unassigned` indicates that ownership was cleared. The empty `assignee` is omitted in this example. Use the event type to recognize the change; do not treat every missing `assignee` on other event types as an instruction to clear ownership. ```json { "events": [ { "id": "event_example_6", "account_id": "account_example", "created": 1794614404000, "type": "conversation_unassigned", "data": { "conversation": { "id": "conversation_example" } } } ] } ``` See [Assign an agent](/developers/api-reference/conversations/assign-agent) for the corresponding conversation operation. ## Process a batch safely For each event, deduplicate by `(account_id, id)`, route by `type`, and validate the matching `data` object. A batch can contain several customers or conversations. Ignore unsupported event types safely and do not assume delivery order matches creation order. Store all accepted work before acknowledging the batch. See [Acknowledge and process](/developers/webhooks/receiving#acknowledge-and-process) for the receiver flow. --- # List orders Search orders by customer, status, date, and more. API 4.0 Use this endpoint to find orders, for example all open orders of one customer. Filters go in a JSON body. ## Filters All filters are optional and combined with AND. | Field | Type | Description | | --- | --- | --- | | `user_id` | string | Orders of this customer. | | `status` | string | Orders with this status. | | `statuses`, `not_statuses` | array | Orders with, or without, any of these statuses. | | `payment_status` | string | `paid` or `unpaid`. | | `shipping_statuses`, `not_shipping_statuses` | array | Filter by shipping status. | | `query` | string | Text search in order ID, number, notes, items, and the customer's name, email, and phone. | | `created_hour_from`, `created_hour_to` | integer | Creation time range, in **hours** since the Unix epoch (Unix seconds ÷ 3600). Both ends included. | | `is_draft` | boolean | `true` returns draft orders only. | | `tags` | array | Orders with any of these tag IDs. `["no"]` returns orders without tags. | | `salesperson` | array | Orders whose salesperson is any of these agent IDs. `["no"]` returns orders without a salesperson. | | `include_deleted` | boolean | Include deleted orders. Default `false`. | ## Sort and paginate | Field | Type | Description | | --- | --- | --- | | `order_by` | string | Field and direction, such as `created desc`. Fields: `created`, `issue_date`, `due_date`, `assigned`, `total`. Direction: `asc` or `desc` (default). | | `limit` | integer | Orders per page. Default and maximum: 200. | | `offset` | integer | Number of orders to skip. | To page, increase `offset` by `limit` until you have read `total` orders. Canceled and deleted orders are always sorted after other orders. ## Response A successful request returns HTTP `200`: ```json { "orders": [ { "id": "order_example", "status": "open", "payment_status": "unpaid", "currency": "VND", "user": { "id": "user_example" }, "total": 270000, "created": 1763107200000 } ], "total": 1, "total_value": 270000 } ``` | Field | Description | | --- | --- | | `orders` | Orders on this page. Omitted when the page is empty. | | `total` | Number of orders matching the filters, across all pages. | | `total_value` | Sum of `total` of all matching orders. Mixed currencies are added as plain numbers. | ## Who sees which orders Results depend on the agent who owns the token. Agents with permission to see all orders get every match. Other agents only get orders where they are the `salesperson` or are assigned to a pipeline stage. Use a token with full order access for integrations. ## GET alternative `GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders` accepts the same filters as query parameters, such as `?user_id=YOUR_USER_ID&limit=50`. The POST form is easier for array filters. ## HTTP request Replace `YOUR_ACCID`, `YOUR_USER_ID`, and `YOUR_ACCESS_TOKEN` with your values. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders-search Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "user_id": "YOUR_USER_ID", "statuses": [ "open", "closed" ], "order_by": "created desc", "limit": 50, "offset": 0 } ``` --- # Lấy danh sách đơn hàng Tìm đơn hàng theo khách hàng, trạng thái, ngày và nhiều tiêu chí khác. API 4.0 Dùng endpoint này để tìm đơn hàng, ví dụ mọi đơn đang mở của một khách hàng. Bộ lọc đặt trong body JSON. ## Bộ lọc Mọi bộ lọc đều tùy chọn và được kết hợp theo điều kiện AND. | Trường | Kiểu | Mô tả | | --- | --- | --- | | `user_id` | string | Đơn của khách hàng này. | | `status` | string | Đơn có trạng thái này. | | `statuses`, `not_statuses` | array | Đơn có, hoặc không có, một trong các trạng thái này. | | `payment_status` | string | `paid` hoặc `unpaid`. | | `shipping_statuses`, `not_shipping_statuses` | array | Lọc theo trạng thái giao hàng. | | `query` | string | Tìm văn bản trong ID, mã đơn, ghi chú, mặt hàng, và tên, email, số điện thoại của khách hàng. | | `created_hour_from`, `created_hour_to` | integer | Khoảng thời gian tạo, tính bằng **giờ** kể từ Unix epoch (số giây Unix ÷ 3600). Bao gồm cả hai đầu. | | `is_draft` | boolean | `true` chỉ trả đơn nháp. | | `tags` | array | Đơn có một trong các ID thẻ này. `["no"]` trả các đơn không có thẻ. | | `salesperson` | array | Đơn có nhân viên bán hàng là một trong các ID agent này. `["no"]` trả các đơn chưa có nhân viên bán hàng. | | `include_deleted` | boolean | Bao gồm đơn đã xóa. Mặc định `false`. | ## Sắp xếp và phân trang | Trường | Kiểu | Mô tả | | --- | --- | --- | | `order_by` | string | Trường và chiều sắp xếp, như `created desc`. Trường: `created`, `issue_date`, `due_date`, `assigned`, `total`. Chiều: `asc` hoặc `desc` (mặc định). | | `limit` | integer | Số đơn mỗi trang. Mặc định và tối đa: 200. | | `offset` | integer | Số đơn cần bỏ qua. | Để lật trang, tăng `offset` thêm `limit` cho tới khi đã đọc đủ `total` đơn. Đơn đã hủy và đã xóa luôn được xếp sau các đơn khác. ## Phản hồi Yêu cầu thành công trả HTTP `200`: ```json { "orders": [ { "id": "order_example", "status": "open", "payment_status": "unpaid", "currency": "VND", "user": { "id": "user_example" }, "total": 270000, "created": 1763107200000 } ], "total": 1, "total_value": 270000 } ``` | Trường | Mô tả | | --- | --- | | `orders` | Các đơn trong trang này. Bị lược bỏ khi trang rỗng. | | `total` | Số đơn khớp bộ lọc, trên mọi trang. | | `total_value` | Tổng `total` của mọi đơn khớp bộ lọc. Các loại tiền tệ khác nhau được cộng như số thông thường. | ## Ai thấy những đơn nào Kết quả phụ thuộc vào agent sở hữu token. Agent có quyền xem mọi đơn sẽ nhận mọi kết quả khớp. Agent khác chỉ nhận các đơn mà họ là `salesperson` hoặc được giao ở một giai đoạn pipeline. Dùng token có quyền xem toàn bộ đơn hàng cho tích hợp. ## Dùng GET `GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders` nhận các bộ lọc tương tự dưới dạng tham số query, như `?user_id=YOUR_USER_ID&limit=50`. Dạng POST dễ dùng hơn với bộ lọc kiểu mảng. ## Yêu cầu HTTP Thay `YOUR_ACCID`, `YOUR_USER_ID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders-search Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "user_id": "YOUR_USER_ID", "statuses": [ "open", "closed" ], "order_by": "created desc", "limit": 50, "offset": 0 } ``` --- # Get order details Read one order by its Subiz order ID. API 4.0 Use this endpoint to read the current state of an order, for example before updating it or after a payment. ## Request Send a `GET` request with no body. | Parameter | Type | Description | | --- | --- | --- | | `accid` (path) | string | Your account ID. | | `oid` (path) | string | Subiz order ID. | The token's agent needs permission to read orders. ## Response A successful request returns HTTP `200` with the order. Selected fields: ```json { "id": "order_example", "account_id": "account_example", "number": "1001", "source_id": "crm-1001", "status": "closed", "payment_status": "paid", "currency": "VND", "user": { "id": "user_example" }, "items": [ { "id": "item_example", "quantity": 2, "product": { "name": "Ceramic mug", "sku": "MUG-01", "price": 120000 }, "total": 240000 } ], "total": 270000, "payment_made": 270000, "closed": 1763193600000, "updated": 1763193600000 } ``` See [Order format](/developers/orders/format) for every field. `closed` is set when the order becomes `closed` or `canceled`. If no order has this ID, the request returns a not-found error. See [Errors](/developers/get-started/errors). ## HTTP request Replace `YOUR_ACCID`, `YOUR_OID`, and `YOUR_ACCESS_TOKEN` with your values. ```http GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders/YOUR_OID Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Lấy thông tin đơn hàng Đọc một đơn hàng theo ID đơn hàng Subiz. API 4.0 Dùng endpoint này để đọc trạng thái hiện tại của đơn hàng, ví dụ trước khi cập nhật hoặc sau khi thanh toán. ## Yêu cầu Gửi yêu cầu `GET` không có body. | Tham số | Kiểu | Mô tả | | --- | --- | --- | | `accid` (đường dẫn) | string | ID tài khoản của bạn. | | `oid` (đường dẫn) | string | ID đơn hàng Subiz. | Agent sở hữu token cần có quyền xem đơn hàng. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng đơn hàng. Một số trường: ```json { "id": "order_example", "account_id": "account_example", "number": "1001", "source_id": "crm-1001", "status": "closed", "payment_status": "paid", "currency": "VND", "user": { "id": "user_example" }, "items": [ { "id": "item_example", "quantity": 2, "product": { "name": "Ceramic mug", "sku": "MUG-01", "price": 120000 }, "total": 240000 } ], "total": 270000, "payment_made": 270000, "closed": 1763193600000, "updated": 1763193600000 } ``` Xem [Định dạng đơn hàng](/developers/vi/orders/format) để biết mọi trường. `closed` được đặt khi đơn chuyển sang `closed` hoặc `canceled`. Nếu không có đơn nào có ID này, yêu cầu trả lỗi không tìm thấy. Xem [Xử lý lỗi](/developers/vi/get-started/errors). ## Yêu cầu HTTP Thay `YOUR_ACCID`, `YOUR_OID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders/YOUR_OID Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Update an order Change selected fields of an order, such as its status or note. API 4.0 Use this endpoint to change an order, for example to close it when the customer confirms, or to cancel it. ## Always list the fields to change Add `x-fields` to the query string with a comma-separated list of the fields you send: ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders/YOUR_OID?x-fields=status,note ``` Only the listed fields change. **Without `x-fields`, the body replaces the whole order.** Every field you leave out is cleared, including items, shipping, and notes. If you must send a full order, [read it](/developers/api-reference/orders/retrieve) first and send it back with your changes. ## Request body Send the new values of the fields listed in `x-fields`: ```json { "status": "closed", "note": "Customer confirmed by phone." } ``` Common changes: | Field | Notes | | --- | --- | | `status` | `open`, `unconfirmed`, `closed`, or `canceled`. | | `items` | Replaces all lines. Totals are recomputed. | | `shipping` | Replaces the shipping details. | | `note`, `private_note` | Order notes. | | `salesperson` | Agent ID responsible for the order. | | `cancellation_note`, `cancellation_code` | Reason when canceling. | Do not put `source_id` in the update body. If it matches another order, that order is updated instead. ## What Subiz does - Recomputes `subtotal`, `total_tax`, `total`, `payment_made`, and `payment_status`. Values you send for these are ignored. - Keeps `created`, `created_by`, and the order's tags and agents unchanged. - When the status changes to `closed` or `canceled`, sets `closed`. For `canceled`, also sets `cancelled_at` and `cancelled_by`. - If the order is `closed` or `canceled` after the update and has a shipping code, Subiz tries to cancel the shipment with the shipping provider. This also happens when you edit an order that was already closed. Do not update closed orders with active shipments unless you intend this. ## Response A successful request returns HTTP `200` with the full updated order. Selected fields: ```json { "id": "order_example", "status": "closed", "note": "Customer confirmed by phone.", "payment_status": "unpaid", "total": 270000, "closed": 1763193600000, "updated": 1763193600000 } ``` ## Errors | Problem | Result | | --- | --- | | No order with this ID | Not-found error. | | `status` is not one of the four values | Invalid-input error for `status`. | See [Errors](/developers/get-started/errors). ## HTTP request Replace `YOUR_ACCID`, `YOUR_OID`, and `YOUR_ACCESS_TOKEN` with your values. Change `x-fields` to match the fields in your body. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders/YOUR_OID?x-fields=status,note Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "status": "closed", "note": "Customer confirmed by phone." } ``` --- # Cập nhật đơn hàng Thay đổi một số trường của đơn hàng, như trạng thái hoặc ghi chú. API 4.0 Dùng endpoint này để thay đổi đơn hàng, ví dụ chốt đơn khi khách hàng xác nhận, hoặc hủy đơn. ## Luôn liệt kê các trường cần thay đổi Thêm `x-fields` vào query string với danh sách các trường bạn gửi, phân tách bằng dấu phẩy: ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders/YOUR_OID?x-fields=status,note ``` Chỉ các trường được liệt kê mới thay đổi. **Nếu không có `x-fields`, body sẽ thay thế toàn bộ đơn hàng.** Mọi trường bạn bỏ trống sẽ bị xóa, kể cả mặt hàng, giao hàng và ghi chú. Nếu buộc phải gửi đơn đầy đủ, hãy [đọc đơn](/developers/vi/api-reference/orders/retrieve) trước rồi gửi lại kèm thay đổi. ## Body yêu cầu Gửi giá trị mới của các trường đã liệt kê trong `x-fields`: ```json { "status": "closed", "note": "Customer confirmed by phone." } ``` Các thay đổi thường gặp: | Trường | Ghi chú | | --- | --- | | `status` | `open`, `unconfirmed`, `closed` hoặc `canceled`. | | `items` | Thay thế mọi dòng. Tổng tiền được tính lại. | | `shipping` | Thay thế thông tin giao hàng. | | `note`, `private_note` | Ghi chú của đơn. | | `salesperson` | ID agent phụ trách đơn. | | `cancellation_note`, `cancellation_code` | Lý do khi hủy. | Đừng đưa `source_id` vào body cập nhật. Nếu nó trùng với đơn khác, đơn đó sẽ bị cập nhật thay vì đơn này. ## Subiz làm gì - Tính lại `subtotal`, `total_tax`, `total`, `payment_made` và `payment_status`. Giá trị bạn gửi cho các trường này bị bỏ qua. - Giữ nguyên `created`, `created_by`, cùng thẻ và agent của đơn. - Khi trạng thái chuyển sang `closed` hoặc `canceled`, đặt `closed`. Với `canceled`, đặt thêm `cancelled_at` và `cancelled_by`. - Nếu sau khi cập nhật đơn ở trạng thái `closed` hoặc `canceled` và có mã vận đơn, Subiz sẽ thử hủy vận đơn với đơn vị vận chuyển. Điều này cũng xảy ra khi bạn sửa một đơn đã đóng từ trước. Đừng cập nhật đơn đã đóng có vận đơn đang hoạt động trừ khi bạn chủ ý làm vậy. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng toàn bộ đơn hàng đã cập nhật. Một số trường: ```json { "id": "order_example", "status": "closed", "note": "Customer confirmed by phone.", "payment_status": "unpaid", "total": 270000, "closed": 1763193600000, "updated": 1763193600000 } ``` ## Lỗi | Vấn đề | Kết quả | | --- | --- | | Không có đơn nào có ID này | Lỗi không tìm thấy. | | `status` không thuộc bốn giá trị | Lỗi dữ liệu không hợp lệ cho `status`. | Xem [Xử lý lỗi](/developers/vi/get-started/errors). ## Yêu cầu HTTP Thay `YOUR_ACCID`, `YOUR_OID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/orders/YOUR_OID?x-fields=status,note Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "status": "closed", "note": "Customer confirmed by phone." } ``` --- # Changelog Track documentation updates and confirmed API changes. API 4.0 · 4.1 ## Reading API versions Each endpoint page displays its API route version, such as **API 4.0** or **API 4.1**, above the title. Use the exact HTTP method and URL shown on that page. A different version number is not a reason to replace the version in an existing URL. Shared guides list the versions they cover. Webhook receiving and payload pages describe delivery to your server, so they are not tied to a version in a Subiz API route. ## 2026-11-17 — Documentation update **Documentation only · No API behavior change announced** - Rewrote the English Conversations & Messages endpoint pages: Send to a conversation, Send to a customer, Get conversation details, Read message history, Invite an agent, and Assign an agent. Pages now include response examples, limits, and next steps. - Rewrote the English Customers (Users) pages: Create a customer, Get customer details, Update customer details, and Find or create by channel identity. Pages now list the built-in customer attributes and include response examples. - Added the English User and attribute format page under Customers (Users), covering the User and Attribute objects, value types, multiple values, and built-in attributes. - Added English Orders pages: Order format, Create an order, List orders, Get order details, and Update an order. They replace the Orders navigation outline. - Added English Products pages: Product format, Create a product, List products, Get product details, and Update a product. They replace the Products navigation outline. - Added English Agents pages: Agent format, List agents, and Get agent details. - Send to a customer now documents identifying the customer by channel identity with top-level `channel`, `channel_source`, and `profile_id`. - Added Vietnamese versions of every page, including all pages listed above. Use the language menu in the header to switch. ## 2026-11-14 — Documentation update **Documentation only · No API behavior change announced** - Added API version labels to individual pages. - Added English Usage limits and Errors guides with verified payload limits, error response fields, and retry guidance. - Updated usage-limit guidance for per-token, shared account, and per-agent message allowances, UTC daily resets, and HTTP 429 responses with Retry-After. - Added this changelog for documentation updates and future confirmed API changes. - Expanded the English webhook guides with signature verification, delivery handling, and customer event payloads. The Vietnamese webhook translation is awaiting an update. - Added Orders and Products as navigation outlines awaiting verified articles. This entry does not claim that any API operation was introduced or deprecated on this date. No API 4.2 operation is documented yet. ## API change announcements No source-confirmed API release history has been added yet. Future entries will identify the affected API versions and operations, the effective date, whether the change is breaking, and any required migration steps. --- # Nhật ký thay đổi Theo dõi cập nhật tài liệu và các thay đổi API đã được xác nhận. API 4.0 · 4.1 ## Đọc phiên bản API Mỗi trang endpoint hiển thị phiên bản route API, như **API 4.0** hoặc **API 4.1**, phía trên tiêu đề. Dùng đúng phương thức HTTP và URL ghi trên trang đó. Số phiên bản khác nhau không phải lý do để đổi phiên bản trong một URL đang dùng. Các hướng dẫn dùng chung liệt kê những phiên bản chúng bao gồm. Trang nhận webhook và dữ liệu sự kiện mô tả việc gửi tới máy chủ của bạn, nên không gắn với phiên bản trong route API của Subiz. ## 17/11/2026 — Cập nhật tài liệu **Chỉ thay đổi tài liệu · Không thông báo thay đổi hành vi API** - Viết lại các trang endpoint tiếng Anh trong nhóm Hội thoại và tin nhắn: Gửi tin nhắn vào hội thoại, Gửi tin nhắn cho khách hàng, Lấy thông tin hội thoại, Đọc lịch sử tin nhắn, Mời agent tham gia và Giao agent phụ trách. Các trang nay có ví dụ phản hồi, giới hạn và bước tiếp theo. - Viết lại các trang tiếng Anh trong nhóm Khách hàng: Tạo khách hàng, Lấy thông tin khách hàng, Cập nhật thông tin khách hàng và Tìm hoặc tạo theo định danh kênh. Các trang nay liệt kê thuộc tính khách hàng có sẵn và có ví dụ phản hồi. - Thêm trang tiếng Anh Định dạng khách hàng và thuộc tính trong nhóm Khách hàng, mô tả đối tượng User và Attribute, kiểu giá trị, nhiều giá trị và thuộc tính có sẵn. - Thêm các trang tiếng Anh về Đơn hàng: Định dạng đơn hàng, Tạo đơn hàng, Lấy danh sách đơn hàng, Lấy thông tin đơn hàng và Cập nhật đơn hàng. Các trang này thay cho phần khung điều hướng Đơn hàng. - Thêm các trang tiếng Anh về Sản phẩm: Định dạng sản phẩm, Tạo sản phẩm, Lấy danh sách sản phẩm, Lấy thông tin sản phẩm và Cập nhật sản phẩm. Các trang này thay cho phần khung điều hướng Sản phẩm. - Thêm các trang tiếng Anh về Agent: Định dạng agent, Lấy danh sách agent và Lấy thông tin agent. - Gửi tin nhắn cho khách hàng nay mô tả cách xác định khách hàng theo định danh kênh bằng `channel`, `channel_source` và `profile_id` ở cấp ngoài cùng. - Thêm bản tiếng Việt cho mọi trang, gồm tất cả các trang nêu trên. Dùng menu ngôn ngữ ở đầu trang để chuyển đổi. ## 14/11/2026 — Cập nhật tài liệu **Chỉ thay đổi tài liệu · Không thông báo thay đổi hành vi API** - Thêm nhãn phiên bản API cho từng trang. - Thêm hướng dẫn tiếng Anh Giới hạn sử dụng và Xử lý lỗi, với giới hạn dữ liệu đã kiểm chứng, các trường của phản hồi lỗi và hướng dẫn thử lại. - Cập nhật hướng dẫn giới hạn sử dụng cho hạn mức theo token, hạn mức chung của tài khoản và hạn mức tin nhắn theo agent, việc đặt lại hằng ngày theo UTC và phản hồi HTTP 429 kèm Retry-After. - Thêm nhật ký thay đổi này cho các cập nhật tài liệu và thay đổi API đã xác nhận trong tương lai. - Mở rộng hướng dẫn webhook tiếng Anh với xác minh chữ ký, xử lý lần gửi và dữ liệu sự kiện khách hàng. Bản dịch tiếng Việt cho phần webhook khi đó đang chờ cập nhật. - Thêm Đơn hàng và Sản phẩm làm khung điều hướng chờ bài viết đã kiểm chứng. Mục này không khẳng định có thao tác API nào được giới thiệu hay ngừng hỗ trợ vào ngày này. Chưa có thao tác API 4.2 nào được ghi tài liệu. ## Thông báo thay đổi API Chưa có lịch sử phát hành API nào được xác nhận từ mã nguồn. Các mục sau này sẽ nêu phiên bản và thao tác API bị ảnh hưởng, ngày có hiệu lực, thay đổi có phá vỡ tương thích hay không và các bước chuyển đổi cần thiết. --- # Product format Understand the product object: price, stock, availability, variants, and images. API 4.0 A `Product` is an item in your Subiz catalog. Order items can be linked to catalog products. This page describes the product object. All IDs and values below are illustrative. To work with products, see [Create a product](/developers/api-reference/products/create), [List products](/developers/api-reference/products/list), [Get product details](/developers/api-reference/products/retrieve), and [Update a product](/developers/api-reference/products/update). ## Product Selected fields of a `Product`: ```json { "id": "product_example", "account_id": "account_example", "source_id": "shop-sku-mug-01", "name": "Ceramic mug", "sku": "MUG-01", "barcode": "8930000000001", "description": "A 350 ml ceramic mug.", "category": "kitchen", "brand": "Example Home", "url": "https://shop.example.com/products/ceramic-mug", "price": 120000, "market_price": 150000, "currency": "VND", "stock": 25, "availability": "in_stock", "visibility": "published", "condition": "new", "images": [ "https://example.com/images/mug.jpg" ], "props": [ { "key": "color", "value": "white" } ], "product_group_id": "product_example", "created": 1763107200000, "updated": 1763107200000 } ``` | Field | Type | Description | | --- | --- | --- | | `id` | string | Subiz product ID. Generated by Subiz. | | `source_id` | string | ID of the product in your system. Used to avoid duplicates. | | `name` | string | Required. Product name. | | `sku`, `barcode` | string | Stock-keeping unit and barcode. | | `description` | string | Product description. | | `category` | string | Category. At most 255 bytes. | | `brand` | string | Brand name. | | `url` | string | Product page on your website. | | `price` | number | Selling price. | | `market_price` | number | Reference price before discount, such as a list price. | | `currency` | string | Currency of the prices. | | `stock` | integer | Units in stock. | | `availability` | string | See [Availability](#availability). | | `visibility` | string | `published` (default) or `hidden`. | | `condition` | string | `new`, `refurbished`, or `used`. | | `image`, `images` | string, array | Main image URL and additional image URLs. | | `videos` | array | Video URLs. | | `props` | array | Attributes as `key`/`value` pairs, such as color or size. | | `note` | string | Internal note. | | `weight`, `weight_unit` | number, string | Weight and its unit, `g` or `kg`. | | `dimension_length`, `dimension_width`, `dimension_height` | number | Package size. | | `product_group_id` | string | Variant group. See [Variants](#variants). | | `created`, `updated` | integer | Unix timestamps in milliseconds. Set by Subiz. | | `created_by`, `updated_by` | string | ID of the agent who created or last changed the product. Set by Subiz. | Empty fields are omitted, and the object has more fields than shown. ## Availability `availability` is one of these values. An empty value is allowed. | Value | Meaning | | --- | --- | | `in_stock` | In stock. | | `out_of_stock` | Out of stock. | | `online_only` | Sold online only. | | `pre_order` | Available for pre-order. | | `pre_sale` | Available for pre-sale. | | `sold_out` | Sold out. | Subiz lowercases and trims the value. Any other value is rejected. ## Images When you send a new image URL in `image` or `images`, Subiz downloads it, stores a resized JPEG copy, and saves the copy's URL instead of yours. The image URLs you read back are therefore different from the ones you sent. If an image cannot be downloaded, the request fails. ## Variants Variants of the same product, such as sizes or colors, share a `product_group_id`. A product without a group gets its own `id` as `product_group_id`. When you save a product, Subiz copies these fields to every other product in the same group: `name`, `description`, `url`, `handle`, `category`, `brand`, `note`, `condition`, `visibility`, `images`, `videos`, and `options`. Keep fields that differ per variant, such as `sku`, `price`, `stock`, and `props`, on each variant. [Get product details](/developers/api-reference/products/retrieve) also returns `num_variants` and up to five `other_variants`. ## Products in orders An order item holds a copy of the product at the time of the order. Changing a product does not change existing orders. See [Order format](/developers/orders/format#order-item). --- # Định dạng sản phẩm Hiểu đối tượng sản phẩm: giá, tồn kho, tình trạng hàng, biến thể và hình ảnh. API 4.0 `Product` là một mặt hàng trong danh mục Subiz của bạn. Mặt hàng trong đơn có thể liên kết với sản phẩm trong danh mục. Trang này mô tả đối tượng sản phẩm. Mọi ID và giá trị bên dưới chỉ mang tính minh họa. Để làm việc với sản phẩm, xem [Tạo sản phẩm](/developers/vi/api-reference/products/create), [Lấy danh sách sản phẩm](/developers/vi/api-reference/products/list), [Lấy thông tin sản phẩm](/developers/vi/api-reference/products/retrieve) và [Cập nhật sản phẩm](/developers/vi/api-reference/products/update). ## Sản phẩm Một số trường của `Product`: ```json { "id": "product_example", "account_id": "account_example", "source_id": "shop-sku-mug-01", "name": "Ceramic mug", "sku": "MUG-01", "barcode": "8930000000001", "description": "A 350 ml ceramic mug.", "category": "kitchen", "brand": "Example Home", "url": "https://shop.example.com/products/ceramic-mug", "price": 120000, "market_price": 150000, "currency": "VND", "stock": 25, "availability": "in_stock", "visibility": "published", "condition": "new", "images": [ "https://example.com/images/mug.jpg" ], "props": [ { "key": "color", "value": "white" } ], "product_group_id": "product_example", "created": 1763107200000, "updated": 1763107200000 } ``` | Trường | Kiểu | Mô tả | | --- | --- | --- | | `id` | string | ID sản phẩm Subiz. Do Subiz tạo. | | `source_id` | string | ID của sản phẩm trong hệ thống của bạn. Dùng để tránh trùng lặp. | | `name` | string | Bắt buộc. Tên sản phẩm. | | `sku`, `barcode` | string | Mã SKU và mã vạch. | | `description` | string | Mô tả sản phẩm. | | `category` | string | Danh mục. Tối đa 255 byte. | | `brand` | string | Thương hiệu. | | `url` | string | Trang sản phẩm trên website của bạn. | | `price` | number | Giá bán. | | `market_price` | number | Giá tham chiếu trước giảm giá, như giá niêm yết. | | `currency` | string | Đơn vị tiền tệ của giá. | | `stock` | integer | Số lượng tồn kho. | | `availability` | string | Xem [Tình trạng hàng](#tình-trạng-hàng). | | `visibility` | string | `published` (mặc định) hoặc `hidden`. | | `condition` | string | `new`, `refurbished` hoặc `used`. | | `image`, `images` | string, array | URL ảnh chính và các URL ảnh bổ sung. | | `videos` | array | URL video. | | `props` | array | Thuộc tính dạng cặp `key`/`value`, như màu sắc hoặc kích cỡ. | | `note` | string | Ghi chú nội bộ. | | `weight`, `weight_unit` | number, string | Khối lượng và đơn vị, `g` hoặc `kg`. | | `dimension_length`, `dimension_width`, `dimension_height` | number | Kích thước kiện hàng. | | `product_group_id` | string | Nhóm biến thể. Xem [Biến thể](#biến-thể). | | `created`, `updated` | integer | Dấu thời gian Unix tính bằng mili giây. Do Subiz đặt. | | `created_by`, `updated_by` | string | ID agent đã tạo hoặc thay đổi sản phẩm gần nhất. Do Subiz đặt. | Trường rỗng bị lược bỏ, và đối tượng có nhiều trường hơn ví dụ. ## Tình trạng hàng `availability` là một trong các giá trị sau. Cho phép giá trị rỗng. | Giá trị | Ý nghĩa | | --- | --- | | `in_stock` | Còn hàng. | | `out_of_stock` | Hết hàng. | | `online_only` | Chỉ bán online. | | `pre_order` | Nhận đặt trước. | | `pre_sale` | Mở bán trước. | | `sold_out` | Đã bán hết. | Subiz chuyển giá trị sang chữ thường và bỏ khoảng trắng thừa. Giá trị khác bị từ chối. ## Hình ảnh Khi bạn gửi URL ảnh mới trong `image` hoặc `images`, Subiz tải ảnh về, lưu một bản sao JPEG đã thay đổi kích thước và lưu URL của bản sao thay cho URL của bạn. Vì vậy URL ảnh bạn đọc lại sẽ khác URL đã gửi. Nếu không tải được ảnh, yêu cầu thất bại. ## Biến thể Các biến thể của cùng một sản phẩm, như kích cỡ hoặc màu sắc, dùng chung `product_group_id`. Sản phẩm không thuộc nhóm nào sẽ lấy chính `id` của nó làm `product_group_id`. Khi bạn lưu một sản phẩm, Subiz sao chép các trường sau sang mọi sản phẩm khác trong cùng nhóm: `name`, `description`, `url`, `handle`, `category`, `brand`, `note`, `condition`, `visibility`, `images`, `videos` và `options`. Giữ các trường khác nhau theo biến thể, như `sku`, `price`, `stock` và `props`, trên từng biến thể. [Lấy thông tin sản phẩm](/developers/vi/api-reference/products/retrieve) còn trả về `num_variants` và tối đa năm `other_variants`. ## Sản phẩm trong đơn hàng Mặt hàng trong đơn giữ một bản sao của sản phẩm tại thời điểm đặt đơn. Thay đổi sản phẩm không làm thay đổi các đơn đã có. Xem [Định dạng đơn hàng](/developers/vi/orders/format#mặt-hàng-trong-đơn). --- # Create a product Add a product to your catalog, or update it by your own product ID. API 4.0 Use this endpoint to add a product to your Subiz catalog, for example when you sync products from your shop. See [Product format](/developers/products/format) for all fields. ## Before you begin - Get a [Bearer access token](/developers/get-started/authentication) and your account ID. - The token's agent needs permission to create **and** update products. ## Request body | Field | Type | Description | | --- | --- | --- | | `name` | string | Required. Product name. | | `source_id` | string | Recommended. Your own product ID. See [Avoid duplicates](#avoid-duplicates). | | `sku` | string | Stock-keeping unit. | | `price`, `market_price` | number | Selling price and reference price. | | `currency` | string | Currency of the prices, such as `VND`. | | `stock` | integer | Units in stock. | | `availability` | string | `in_stock`, `out_of_stock`, `online_only`, `pre_order`, `pre_sale`, or `sold_out`. | | `visibility` | string | `published` (default) or `hidden`. | | `condition` | string | `new`, `refurbished`, or `used`. | | `description`, `category`, `brand`, `url` | string | Optional details. `category` is at most 255 bytes. | | `image`, `images` | string, array | Image URLs. Subiz stores its own copies. See [Images](/developers/products/format#images). | | `props` | array | Attributes as `key`/`value` pairs. | | `product_group_id` | string | Optional. Put the product in an existing variant group. See [Variants](/developers/products/format#variants). | Do not send `id`. Subiz ignores it and generates one. Subiz also sets `created`, `created_by`, `updated`, and `updated_by`. ## Avoid duplicates Before creating a product, Subiz looks for an existing product: 1. If you send `source_id`, Subiz looks for a product with the same `source_id`. 2. If you do not send `source_id`, Subiz looks for a product with the same `sku`. If one is found, Subiz **replaces that product** with the fields you send instead of creating another one. Fields you leave out are cleared. Always send the complete product. Set `source_id` to the product's ID in your system. This makes retries safe. Without `source_id` and `sku`, every request creates a new product. ## Response A successful request returns HTTP `200` with the saved product. Selected fields: ```json { "id": "product_example", "account_id": "account_example", "source_id": "shop-sku-mug-01", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000, "currency": "VND", "stock": 25, "availability": "in_stock", "visibility": "published", "product_group_id": "product_example", "created": 1763107200000, "updated": 1763107200000 } ``` Store the `id` to [read](/developers/api-reference/products/retrieve) or [update](/developers/api-reference/products/update) the product later. ## Errors | Problem | Result | | --- | --- | | `name` is missing | Invalid-input error naming `name`. | | `category` is longer than 255 bytes | Invalid-input error naming `category`. | | `availability`, `visibility`, or `condition` has another value | Invalid-field error naming the field. | | An image URL cannot be downloaded | The request fails. | | Missing permission | Permission error. | See [Errors](/developers/get-started/errors) for the error format. ## HTTP request Replace `YOUR_ACCID` and `YOUR_ACCESS_TOKEN` with your values. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "source_id": "YOUR_SOURCE_PRODUCT_ID", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000, "currency": "VND", "stock": 25, "availability": "in_stock" } ``` --- # Tạo sản phẩm Thêm sản phẩm vào danh mục, hoặc cập nhật theo ID sản phẩm của bạn. API 4.0 Dùng endpoint này để thêm sản phẩm vào danh mục Subiz, ví dụ khi đồng bộ sản phẩm từ cửa hàng của bạn. Xem [Định dạng sản phẩm](/developers/vi/products/format) để biết mọi trường. ## Trước khi bắt đầu - Lấy [Bearer access token](/developers/vi/get-started/authentication) và ID tài khoản. - Agent sở hữu token cần quyền tạo **và** cập nhật sản phẩm. ## Body yêu cầu | Trường | Kiểu | Mô tả | | --- | --- | --- | | `name` | string | Bắt buộc. Tên sản phẩm. | | `source_id` | string | Nên có. ID sản phẩm của riêng bạn. Xem [Tránh trùng lặp](#tránh-trùng-lặp). | | `sku` | string | Mã SKU. | | `price`, `market_price` | number | Giá bán và giá tham chiếu. | | `currency` | string | Đơn vị tiền tệ của giá, như `VND`. | | `stock` | integer | Số lượng tồn kho. | | `availability` | string | `in_stock`, `out_of_stock`, `online_only`, `pre_order`, `pre_sale` hoặc `sold_out`. | | `visibility` | string | `published` (mặc định) hoặc `hidden`. | | `condition` | string | `new`, `refurbished` hoặc `used`. | | `description`, `category`, `brand`, `url` | string | Thông tin tùy chọn. `category` tối đa 255 byte. | | `image`, `images` | string, array | URL ảnh. Subiz lưu bản sao riêng. Xem [Hình ảnh](/developers/vi/products/format#hình-ảnh). | | `props` | array | Thuộc tính dạng cặp `key`/`value`. | | `product_group_id` | string | Tùy chọn. Đưa sản phẩm vào một nhóm biến thể có sẵn. Xem [Biến thể](/developers/vi/products/format#biến-thể). | Đừng gửi `id`. Subiz bỏ qua và tự tạo ID. Subiz cũng tự đặt `created`, `created_by`, `updated` và `updated_by`. ## Tránh trùng lặp Trước khi tạo sản phẩm, Subiz tìm sản phẩm đã có: 1. Nếu bạn gửi `source_id`, Subiz tìm sản phẩm có cùng `source_id`. 2. Nếu bạn không gửi `source_id`, Subiz tìm sản phẩm có cùng `sku`. Nếu tìm thấy, Subiz **thay thế sản phẩm đó** bằng các trường bạn gửi thay vì tạo sản phẩm mới. Các trường bạn bỏ trống sẽ bị xóa. Luôn gửi sản phẩm đầy đủ. Đặt `source_id` là ID của sản phẩm trong hệ thống của bạn. Điều này giúp thử lại an toàn. Nếu không có cả `source_id` lẫn `sku`, mỗi yêu cầu tạo một sản phẩm mới. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng sản phẩm đã lưu. Một số trường: ```json { "id": "product_example", "account_id": "account_example", "source_id": "shop-sku-mug-01", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000, "currency": "VND", "stock": 25, "availability": "in_stock", "visibility": "published", "product_group_id": "product_example", "created": 1763107200000, "updated": 1763107200000 } ``` Lưu `id` để [đọc](/developers/vi/api-reference/products/retrieve) hoặc [cập nhật](/developers/vi/api-reference/products/update) sản phẩm sau này. ## Lỗi | Vấn đề | Kết quả | | --- | --- | | Thiếu `name` | Lỗi dữ liệu không hợp lệ nêu tên `name`. | | `category` dài hơn 255 byte | Lỗi dữ liệu không hợp lệ nêu tên `category`. | | `availability`, `visibility` hoặc `condition` có giá trị khác | Lỗi trường không hợp lệ nêu tên trường. | | Không tải được URL ảnh | Yêu cầu thất bại. | | Thiếu quyền | Lỗi phân quyền. | Xem [Xử lý lỗi](/developers/vi/get-started/errors) để biết định dạng lỗi. ## Yêu cầu HTTP Thay `YOUR_ACCID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "source_id": "YOUR_SOURCE_PRODUCT_ID", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000, "currency": "VND", "stock": 25, "availability": "in_stock" } ``` --- # List products Search your catalog by text, SKU, price, availability, and more. API 4.0 Use this endpoint to find products in your catalog, for example to look up a product by SKU or to read the whole catalog. Filters go in a JSON body. ## Filters All filters are optional and combined with AND. | Field | Type | Description | | --- | --- | --- | | `query` | string | Text search in name, ID, SKU, `source_id`, URL, description, brand, and note. Ignores case. | | `sku` | string | Products with exactly this SKU. | | `source_id` | string | Products with exactly this `source_id`. | | `category` | string | Products in exactly this category. | | `visibility` | string | `published` or `hidden`. | | `availability` | string | `instock` returns products with `stock` above 0. `out_of_stock` returns products with `stock` of 0. | | `price_gte`, `price_lte` | number | Minimum and maximum `price`. | | `props` | array | `key`/`value` pairs. A product must have every pair, with the exact value. | | `grouped` | boolean | `true` returns one product per variant group instead of every variant. | | `variant_of` | string | A product ID. Returns all products in its variant group, including itself. Other filters are ignored. | The `availability` filter uses `stock`, not the product's `availability` field. Note the spelling `instock`. ## Paginate | Field | Type | Description | | --- | --- | --- | | `limit` | integer | Products per page. Default 100, maximum 1000. Values outside 1–1000 use 100. | | `anchor` | string | `next_anchor` from the previous page. Omit for the first page. | Products are sorted by `id` in descending order. To read every page, send the `next_anchor` of each response as `anchor` in the next request. Stop when a response has no `products`. Use `anchor`, not `offset`. `offset` only skips products within the first `limit` results, so it does not page through the catalog. ## Response A successful request returns HTTP `200`: ```json { "products": [ { "id": "product_example", "source_id": "shop-sku-mug-01", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000, "currency": "VND", "stock": 25, "availability": "in_stock", "visibility": "published" } ], "total": 1, "next_anchor": "product_example" } ``` | Field | Description | | --- | --- | | `products` | Products on this page. Omitted when the page is empty. | | `total` | Number of products matching the filters, across all pages. | | `next_anchor` | Send as `anchor` to get the next page. | ## Permissions The token's agent needs permission to read products. Without it, the request does not return a list: it returns at most one best match for `query` in a `product` field. Use a token with product read access for integrations. ## GET alternative `GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products` accepts the same filters as query parameters, such as `?sku=MUG-01`. The POST form is easier for `props`. ## HTTP request Replace `YOUR_ACCID` and `YOUR_ACCESS_TOKEN` with your values. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products-search Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "query": "mug", "visibility": "published", "limit": 100 } ``` --- # Lấy danh sách sản phẩm Tìm trong danh mục theo từ khóa, SKU, giá, tồn kho và nhiều tiêu chí khác. API 4.0 Dùng endpoint này để tìm sản phẩm trong danh mục, ví dụ tra cứu sản phẩm theo SKU hoặc đọc toàn bộ danh mục. Bộ lọc đặt trong body JSON. ## Bộ lọc Mọi bộ lọc đều tùy chọn và được kết hợp theo điều kiện AND. | Trường | Kiểu | Mô tả | | --- | --- | --- | | `query` | string | Tìm văn bản trong tên, ID, SKU, `source_id`, URL, mô tả, thương hiệu và ghi chú. Không phân biệt hoa thường. | | `sku` | string | Sản phẩm có đúng SKU này. | | `source_id` | string | Sản phẩm có đúng `source_id` này. | | `category` | string | Sản phẩm thuộc đúng danh mục này. | | `visibility` | string | `published` hoặc `hidden`. | | `availability` | string | `instock` trả sản phẩm có `stock` lớn hơn 0. `out_of_stock` trả sản phẩm có `stock` bằng 0. | | `price_gte`, `price_lte` | number | `price` tối thiểu và tối đa. | | `props` | array | Các cặp `key`/`value`. Sản phẩm phải có mọi cặp, với giá trị khớp chính xác. | | `grouped` | boolean | `true` trả một sản phẩm cho mỗi nhóm biến thể thay vì mọi biến thể. | | `variant_of` | string | Một ID sản phẩm. Trả mọi sản phẩm trong nhóm biến thể của nó, kể cả chính nó. Các bộ lọc khác bị bỏ qua. | Bộ lọc `availability` dựa vào `stock`, không dựa vào trường `availability` của sản phẩm. Lưu ý cách viết `instock`. ## Phân trang | Trường | Kiểu | Mô tả | | --- | --- | --- | | `limit` | integer | Số sản phẩm mỗi trang. Mặc định 100, tối đa 1000. Giá trị ngoài khoảng 1–1000 sẽ dùng 100. | | `anchor` | string | `next_anchor` từ trang trước. Bỏ trống ở trang đầu tiên. | Sản phẩm được sắp xếp theo `id` giảm dần. Để đọc mọi trang, gửi `next_anchor` của mỗi phản hồi làm `anchor` trong yêu cầu kế tiếp. Dừng khi phản hồi không có `products`. Dùng `anchor`, không dùng `offset`. `offset` chỉ bỏ qua sản phẩm trong `limit` kết quả đầu tiên, nên không lật trang được danh mục. ## Phản hồi Yêu cầu thành công trả HTTP `200`: ```json { "products": [ { "id": "product_example", "source_id": "shop-sku-mug-01", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000, "currency": "VND", "stock": 25, "availability": "in_stock", "visibility": "published" } ], "total": 1, "next_anchor": "product_example" } ``` | Trường | Mô tả | | --- | --- | | `products` | Các sản phẩm trong trang này. Bị lược bỏ khi trang rỗng. | | `total` | Số sản phẩm khớp bộ lọc, trên mọi trang. | | `next_anchor` | Gửi làm `anchor` để lấy trang tiếp theo. | ## Phân quyền Agent sở hữu token cần quyền xem sản phẩm. Nếu không có quyền, yêu cầu không trả về danh sách: nó trả tối đa một kết quả khớp nhất với `query` trong trường `product`. Dùng token có quyền xem sản phẩm cho tích hợp. ## Dùng GET `GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products` nhận các bộ lọc tương tự dưới dạng tham số query, như `?sku=MUG-01`. Dạng POST dễ dùng hơn với `props`. ## Yêu cầu HTTP Thay `YOUR_ACCID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products-search Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "query": "mug", "visibility": "published", "limit": 100 } ``` --- # Get product details Read one product by its Subiz product ID. API 4.0 Use this endpoint to read the current state of a product, for example before updating it. ## Request Send a `GET` request with no body. | Parameter | Type | Description | | --- | --- | --- | | `accid` (path) | string | Your account ID. | | `pid` (path) | string | Subiz product ID. | The token's agent needs permission to read products. To find a product by your own ID or SKU, use [List products](/developers/api-reference/products/list) with `source_id` or `sku`. ## Response A successful request returns HTTP `200` with the product. Selected fields: ```json { "id": "product_example", "account_id": "account_example", "source_id": "shop-sku-mug-01", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000, "currency": "VND", "stock": 25, "availability": "in_stock", "visibility": "published", "product_group_id": "product_example", "num_variants": 1, "other_variants": [ { "id": "product_variant_example", "name": "Ceramic mug", "sku": "MUG-01-BLUE", "price": 120000, "product_group_id": "product_example" } ], "updated": 1763107200000 } ``` See [Product format](/developers/products/format) for every field. This endpoint also returns: | Field | Description | | --- | --- | | `num_variants` | Number of other products in the same variant group. | | `other_variants` | Up to five of those products. | If no product has this ID, the request returns a not-found error. See [Errors](/developers/get-started/errors). ## HTTP request Replace `YOUR_ACCID`, `YOUR_PID`, and `YOUR_ACCESS_TOKEN` with your values. ```http GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products/YOUR_PID Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Lấy thông tin sản phẩm Đọc một sản phẩm theo ID sản phẩm Subiz. API 4.0 Dùng endpoint này để đọc trạng thái hiện tại của sản phẩm, ví dụ trước khi cập nhật. ## Yêu cầu Gửi yêu cầu `GET` không có body. | Tham số | Kiểu | Mô tả | | --- | --- | --- | | `accid` (đường dẫn) | string | ID tài khoản của bạn. | | `pid` (đường dẫn) | string | ID sản phẩm Subiz. | Agent sở hữu token cần quyền xem sản phẩm. Để tìm sản phẩm theo ID riêng của bạn hoặc SKU, dùng [Lấy danh sách sản phẩm](/developers/vi/api-reference/products/list) với `source_id` hoặc `sku`. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng sản phẩm. Một số trường: ```json { "id": "product_example", "account_id": "account_example", "source_id": "shop-sku-mug-01", "name": "Ceramic mug", "sku": "MUG-01", "price": 120000, "currency": "VND", "stock": 25, "availability": "in_stock", "visibility": "published", "product_group_id": "product_example", "num_variants": 1, "other_variants": [ { "id": "product_variant_example", "name": "Ceramic mug", "sku": "MUG-01-BLUE", "price": 120000, "product_group_id": "product_example" } ], "updated": 1763107200000 } ``` Xem [Định dạng sản phẩm](/developers/vi/products/format) để biết mọi trường. Endpoint này còn trả về: | Trường | Mô tả | | --- | --- | | `num_variants` | Số sản phẩm khác trong cùng nhóm biến thể. | | `other_variants` | Tối đa năm sản phẩm trong số đó. | Nếu không có sản phẩm nào có ID này, yêu cầu trả lỗi không tìm thấy. Xem [Xử lý lỗi](/developers/vi/get-started/errors). ## Yêu cầu HTTP Thay `YOUR_ACCID`, `YOUR_PID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http GET https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products/YOUR_PID Authorization: Bearer YOUR_ACCESS_TOKEN ``` --- # Update a product Change a product's price, stock, availability, or other fields. API 4.0 Use this endpoint to change a product, for example to update its price or stock after a change in your shop. ## Always list the fields to change Add `x-fields` to the query string with a comma-separated list of the fields you send: ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products/YOUR_PID?x-fields=price,stock ``` Only the listed fields change. **Without `x-fields`, the body replaces the whole product.** Every field you leave out is cleared, including images and description. If you must send a full product, [read it](/developers/api-reference/products/retrieve) first and send it back with your changes. ## Always send `name` Every request body must contain a non-empty `name`, even when you do not change it. Without `name`, the request fails. If `name` is not in `x-fields`, the name you send is only checked, not saved. ## Request body Send `name` and the new values of the fields listed in `x-fields`: ```json { "name": "Ceramic mug", "price": 99000, "stock": 40 } ``` Common changes: | Field | Notes | | --- | --- | | `price`, `market_price` | Prices. | | `stock` | Units in stock. | | `availability` | `in_stock`, `out_of_stock`, `online_only`, `pre_order`, `pre_sale`, or `sold_out`. Checked even when not listed in `x-fields`. | | `visibility` | `published` or `hidden`. | | `images` | Replaces all images. Subiz stores its own copies. See [Images](/developers/products/format#images). | | `props` | Replaces all attributes. | Subiz sets `updated` and `updated_by`. It keeps `created` and `created_by` unchanged. Values you send for these fields are ignored. ## Changes to variants Some fields are shared by all variants in a group. When you change `name`, `description`, `url`, `handle`, `category`, `brand`, `note`, `condition`, `visibility`, `images`, `videos`, or `options`, Subiz applies the change to every other product with the same `product_group_id`. See [Variants](/developers/products/format#variants). ## Use an existing product ID If no product has the ID in the path, Subiz does not return a not-found error. It looks for a product with the `source_id` (or, without `source_id`, the `sku`) in your body and updates it. If none matches, it **creates a new product with a new ID**. Check the `id` in the response. To make sure the product exists, [read it](/developers/api-reference/products/retrieve) first. ## Response A successful request returns HTTP `200` with the full updated product. Selected fields: ```json { "id": "product_example", "name": "Ceramic mug", "sku": "MUG-01", "price": 99000, "stock": 40, "availability": "in_stock", "updated": 1763193600000 } ``` ## Errors | Problem | Result | | --- | --- | | `name` missing or empty | Invalid-input error naming `name`. | | `category` is longer than 255 bytes | Invalid-input error naming `category`. | | `availability`, `visibility`, or `condition` has another value | Invalid-field error naming the field. | | An image URL cannot be downloaded | The request fails. | | Missing permission to update products | Permission error. | See [Errors](/developers/get-started/errors). ## HTTP request Replace `YOUR_ACCID`, `YOUR_PID`, and `YOUR_ACCESS_TOKEN` with your values. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products/YOUR_PID?x-fields=price,stock Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "name": "Ceramic mug", "price": 99000, "stock": 40 } ``` --- # Cập nhật sản phẩm Thay đổi giá, tồn kho, tình trạng hàng hoặc các trường khác của sản phẩm. API 4.0 Dùng endpoint này để thay đổi sản phẩm, ví dụ cập nhật giá hoặc tồn kho sau khi cửa hàng của bạn thay đổi. ## Luôn liệt kê các trường cần thay đổi Thêm `x-fields` vào query string với danh sách các trường bạn gửi, phân tách bằng dấu phẩy: ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products/YOUR_PID?x-fields=price,stock ``` Chỉ các trường được liệt kê mới thay đổi. **Nếu không có `x-fields`, body sẽ thay thế toàn bộ sản phẩm.** Mọi trường bạn bỏ trống sẽ bị xóa, kể cả ảnh và mô tả. Nếu buộc phải gửi sản phẩm đầy đủ, hãy [đọc sản phẩm](/developers/vi/api-reference/products/retrieve) trước rồi gửi lại kèm thay đổi. ## Luôn gửi `name` Mọi body yêu cầu phải có `name` không rỗng, kể cả khi bạn không đổi tên. Thiếu `name`, yêu cầu sẽ thất bại. Nếu `name` không có trong `x-fields`, tên bạn gửi chỉ được kiểm tra chứ không được lưu. ## Body yêu cầu Gửi `name` và giá trị mới của các trường đã liệt kê trong `x-fields`: ```json { "name": "Ceramic mug", "price": 99000, "stock": 40 } ``` Các thay đổi thường gặp: | Trường | Ghi chú | | --- | --- | | `price`, `market_price` | Giá. | | `stock` | Số lượng tồn kho. | | `availability` | `in_stock`, `out_of_stock`, `online_only`, `pre_order`, `pre_sale` hoặc `sold_out`. Được kiểm tra kể cả khi không có trong `x-fields`. | | `visibility` | `published` hoặc `hidden`. | | `images` | Thay thế mọi ảnh. Subiz lưu bản sao riêng. Xem [Hình ảnh](/developers/vi/products/format#hình-ảnh). | | `props` | Thay thế mọi thuộc tính. | Subiz đặt `updated` và `updated_by`. Subiz giữ nguyên `created` và `created_by`. Giá trị bạn gửi cho các trường này bị bỏ qua. ## Thay đổi lan sang biến thể Một số trường dùng chung cho mọi biến thể trong nhóm. Khi bạn đổi `name`, `description`, `url`, `handle`, `category`, `brand`, `note`, `condition`, `visibility`, `images`, `videos` hoặc `options`, Subiz áp dụng thay đổi cho mọi sản phẩm khác có cùng `product_group_id`. Xem [Biến thể](/developers/vi/products/format#biến-thể). ## Dùng ID sản phẩm đã có Nếu không có sản phẩm nào mang ID trong đường dẫn, Subiz không trả lỗi không tìm thấy. Subiz tìm sản phẩm theo `source_id` (hoặc theo `sku` nếu không có `source_id`) trong body và cập nhật sản phẩm đó. Nếu không khớp sản phẩm nào, Subiz **tạo một sản phẩm mới với ID mới**. Kiểm tra `id` trong phản hồi. Để chắc chắn sản phẩm tồn tại, hãy [đọc sản phẩm](/developers/vi/api-reference/products/retrieve) trước. ## Phản hồi Yêu cầu thành công trả HTTP `200` cùng toàn bộ sản phẩm đã cập nhật. Một số trường: ```json { "id": "product_example", "name": "Ceramic mug", "sku": "MUG-01", "price": 99000, "stock": 40, "availability": "in_stock", "updated": 1763193600000 } ``` ## Lỗi | Vấn đề | Kết quả | | --- | --- | | Thiếu hoặc rỗng `name` | Lỗi dữ liệu không hợp lệ nêu tên `name`. | | `category` dài hơn 255 byte | Lỗi dữ liệu không hợp lệ nêu tên `category`. | | `availability`, `visibility` hoặc `condition` có giá trị khác | Lỗi trường không hợp lệ nêu tên trường. | | Không tải được URL ảnh | Yêu cầu thất bại. | | Thiếu quyền cập nhật sản phẩm | Lỗi phân quyền. | Xem [Xử lý lỗi](/developers/vi/get-started/errors). ## Yêu cầu HTTP Thay `YOUR_ACCID`, `YOUR_PID` và `YOUR_ACCESS_TOKEN` bằng giá trị của bạn. ```http POST https://api.subiz.com.vn/4.0/accounts/YOUR_ACCID/products/YOUR_PID?x-fields=price,stock Authorization: Bearer YOUR_ACCESS_TOKEN Content-Type: application/json { "name": "Ceramic mug", "price": 99000, "stock": 40 } ```