By Tín Nguyễn Đăng • Written date: 06/29/2025 22:43:14
Related Insights
Was this content helpful to you?
This note documents the current v3 API contract behind the platform utilities. It focuses on the shared gateway structure, service-based request routing, and the response handling rules used by the client so integration and operational behavior stay consistent over time.
All current utilities route through the same v3 gateway and require an API Key in the JSON body. Requests use Content-Type: application/json, while routing is handled by service and payload structure rather than separate endpoints for each utility.
POST /api/v3
This endpoint is the shared submission layer for the current utilities. In the client flow, each request starts with action: "add", username: "", a normalized national_market value ("vi" or "en"), and a utility-specific service id.
The current client logic uses one common request contract and then adjusts a few fields per utility. Core fields include action, key, username, national_market, service, link, comments, and quantity.
The exact payload branch is selected by service id together with fields such as link, comments, or images_data.
In practice, link, comments, and quantity are reused differently depending on the selected service:
link with a fixed quantity.comments.voice_data, with quantity derived from rounded audio duration.images_data, with a fixed quantity of 1.comments, with quantity based on trimmed character length.The client reads response.text() first, then attempts JSON parsing, and falls back to the raw text as a message when parsing fails. A request is treated as successful only when response.ok is true and the returned payload does not include an error field.
Depending on the service, the client reads result data from message, order, voice, text_vip, or text. For text-returning utilities, text_vip is preferred when both text fields are available.
Example Request
POST /api/v3
Content-Type: application/json
{
"action": "add",
"comments": ["comment_1", "comment_2"],
"key": "YOUR_API_KEY",
"link": "<SERVICE_LINK_VALUE>",
"quantity": 1000,
"service": "<SERVICE_ID>"
}Example Response (Success)
{
"order": 98412
}Example Response (Error)
{
"error": "quantity_less_than_min"
}All current utilities use the same v3 gateway. Requests are separated by service id and payload shape, not by different backend endpoints. The client also blocks repeated submissions at the start of each request flow to reduce duplicate sends.