Bắt đầu với TinoPage Builder

TinoPage Builder dựng website cho cơ sở kinh doanh bằng AI: khách kể về cơ sở, AI chọn mẫu và viết nội dung, khách sửa tiếp trong trình sửa của TinoPage Builder. Website nhận liên hệ, đơn hàng và chạy trên tên miền riêng. API của dịch vụ cho ứng dụng của bạn xem hạn mức, tạo website bằng AI, đăng, tạm ngưng, xoá website, gắn tên miền riêng, xem liên hệ, đơn hàng và mở TinoPage Builder bằng vé đăng nhập một lần.

Cập nhật: 2026-10-26. Nguồn: module TinoPage Builder của Tino và API của TinoPage Builder.

Gọi API

• Chỉ các tham số ghi ở từng route được chuyển tiếp. Tino kiểm dạng trước khi gọi TinoPage Builder: ID website không phải UUID, tên miền sai dạng, query hay body lạ trả 400 INVALID_REQUEST, details.field chỉ trường.
• ID website trong đường dẫn là UUID; tên miền trong đường dẫn viết chữ thường.
• Sửa nội dung website (trang, khối, ảnh, mặt hàng) và xử lý liên hệ, đơn hàng làm trong TinoPage Builder: mở bằng vé đăng nhập.

Từ 27/10/2026 các route TinoPage Builder cũng gọi được qua gateway /v1: https://api.tino.vn/v1/service/<id dịch vụ>/builder/… với token ứng dụng OAuth (tinoat_, quyền builder:read, builder:write) hoặc token API cá nhân (tinopat_), cùng body và câu trả lời. Riêng vé đăng nhập (POST …/builder/login) không mở qua /v1: chỉ token đăng nhập lấy được.

Token đăng nhập là token khách dùng ở khu vực khách hàng tino.vn; SDK lấy được bằng đăng nhập mã OTP:

from tino_userapi import TinoClient

client = TinoClient()
client.request_login_otp("you@example.com")
client.verify_login_otp("you@example.com", input("Mã OTP: "))
print(client.request("GET", "/service/100003/builder/overview"))

100003 là ID dịch vụ TinoPage Builder: cách tìm ở mục dưới.

Tìm dịch vụ TinoPage Builder

Mỗi khách Tino có một tài khoản TinoPage Builder, gắn với dịch vụ TinoPage Builder đã mua.

1. Lấy ứng viên ở Danh sách dịch vụ (product_type) hoặc Chi tiết dịch vụ (ptype): giá trị tinobuilderpanel. Dịch vụ không có giá trị này thì xem acc_module: TinoPage Builder. So không phân biệt hoa thường, bỏ khoảng trắng, _, -.
2. Gọi Tổng quan tài khoản (GET /service/<id>/builder/overview):

Hạn mức theo dịch vụ

TinoPage Builder không bán theo gói cố định: hạn mức theo dịch vụ đã mua, nằm ở config.effective của Tổng quan tài khoản. Đọc hạn mức từ API, đừng ghi cứng: số có thể đổi khi dịch vụ đổi. -1 là không giới hạn.

• Số đang dùng: usage của Tổng quan tài khoản (sites, sites_paused, sites_published) và pages, items, domains (used, limit) của từng website.
• Hết số website: tạo website trả 409 LIMIT_EXCEEDED, details.key là sites; hết số tên miền: domains_per_site.
• Sau khi hạ hạn mức hoặc dịch vụ chấm dứt, tài khoản giữ chạy các website cũ nhất trong số sites; website còn lại bị hệ thống tạm ngưng (paused: true, paused_reason: over_limit): trang công khai báo website tạm ngưng, không nhận liên hệ, đơn hàng. Nâng hạn mức hoặc xoá bớt website thì website tạm ngưng chạy lại, cũ nhất trước. Trang, mặt hàng, tên miền vượt hạn mức không bị xoá, chỉ không thêm mới được.
• Dịch vụ tạm ngưng: chỉ đọc. Thao tác ghi trả 403 ACCOUNT_SUSPENDED; GET và vé đăng nhập vẫn dùng được (vào chỉ xem). Dịch vụ đã chấm dứt: thao tác ghi và vé đăng nhập trả 403 ACCOUNT_TERMINATED.

Tạo website bằng AI

Tạo website bằng AI nhận intake: thông tin cơ sở kinh doanh để AI chọn mẫu và viết nội dung.

• Ô ngoài bảng, ô không phải chuỗi hoặc quá dài trả 400 INVALID_REQUEST (details.field: intake hoặc intake.<ô>). Thiếu ô bắt buộc, số điện thoại hay email sai trả 422 VALIDATION_FAILED, details theo intake.<ô> kèm lý do tiếng Việt.
• Lượt tạo chạy nền 1–5 phút: lệnh tạo trả HTTP 202 với state: running. Hỏi Tiến độ tạo website vài giây một lần tới khi state là done (site_id là website mới) hoặc failed (message là lý do tiếng Việt).
• Mỗi tài khoản một lượt tạo tại một thời điểm: lượt thứ hai trả 409 CREATION_IN_PROGRESS. Tính năng AI tạm dừng trả 503 AI_UNAVAILABLE.
• Kết quả lượt tạo giữ 1 giờ; sau đó (hoặc khi máy chủ khởi động lại) Tiến độ tạo website trả idle, website đã tạo vẫn có ở Danh sách website.
• Tiến độ có thể có thêm step (queued, design, write, images, build) và mode (design, merge) khi xong: chỉ để hiện tiến độ, đừng rẽ nhánh theo hai khoá này.

Đăng, tạm ngưng, xoá website

• Đăng website đăng bản mới nhất, cũng là mở lại website đã tạm ngưng. Website paused trả 409 SITE_PAUSED: xoá bớt website khác hoặc nâng số website.
• Tạm ngưng website gỡ website khỏi mạng, nội dung giữ nguyên.
• Xoá website đưa website vào thùng rác (Tino khôi phục được theo yêu cầu qua hỗ trợ), gỡ tên miền riêng của website và trả lại một chỗ trong số website.
• Chi tiết website có todo: số liên hệ chưa gọi lại (leads_new) và đơn hàng chưa xác nhận (orders_new).

Tên miền riêng

1. Đăng website trước: website chưa đăng trả 409 SITE_NOT_PUBLISHED.
2. Gắn tên miền riêng với hostname (vd example.vn, banhang.example.vn): trả 201, tên miền ở status: pending kèm dns, các bản ghi khách cần đặt ở nơi quản lý DNS của tên miền.
3. Khách đặt bản ghi: CNAME về dns_target (tên @ và www với tên miền gốc, nhãn con với tên miền con) và TXT _tino-verify (giá trị tino-site-verify=…) chứng minh sở hữu. Tên bản ghi tính từ tên miền gốc. Lấy dns_target và giá trị TXT từ API, đừng ghi cứng.
4. TinoPage Builder tự kiểm lại tên miền pending theo lịch (next_check_at); Kiểm tra lại DNS kiểm ngay. Đủ CNAME và TXT thì status chuyển active, chứng chỉ HTTPS được cấp tự động (ssl_status: pending, active, error); www chuyển về tên miền gốc.

• cname_ok, txt_ok là kết quả lần kiểm gần nhất; error nói thiếu gì (tiếng Việt), rỗng khi đạt. checked_at là 0001-01-01T00:00:00Z khi chưa kiểm lần nào.
• owner_verified: true: chủ tên miền đã được xác nhận, không cần TXT (dns chỉ còn CNAME).
• Tự kiểm dừng sau 14 lần không đạt (khoảng 10 ngày); error ghi rõ, gọi Kiểm tra lại DNS để thử tiếp.
• Hết số tên miền của website: 409 LIMIT_EXCEEDED (details.key: domains_per_site); tên miền đang gắn website khác: 409 DOMAIN_TAKEN; không phải tên miền: 422 VALIDATION_FAILED (details.hostname).

Liên hệ và đơn hàng

Liên hệ và đơn hàng chỉ đọc: kind=lead (mặc định) là liên hệ từ biểu mẫu của website, kind=order là đơn hàng; mới trước, phân trang bằng page, per_page (mặc định 20, tối đa 50) kèm meta.

• Liên hệ: id, kind, name, phone, payload (nội dung biểu mẫu, khoá tuỳ mẫu website), source_page, status, created_at.
• Đơn hàng: id, code, name, phone, address, note, items (name, option, qty, subtotal), shipping, total (null khi website không ghi giá), payment (COD, Chuyển khoản hoặc chữ khác), status, status_label (nhãn tiếng Việt), created_at, sheet_error (lỗi gửi đơn sang Google Sheets, rỗng khi không có).
• Trạng thái lạ: hiện status_label nếu có, không thì giữ nguyên status.

Vé đăng nhập

Vé đăng nhập một lần mở TinoPage Builder đúng tài khoản của dịch vụ, không cần khách đăng nhập lại:

• target: me (mặc định) vào trang quản lý; target: editor vào trình sửa của site_id. Không gửi site_id: website cũ nhất của tài khoản (tài khoản chưa có website thì vào trang quản lý).
• Trả 201 {url, expires_at}: url là https trên máy chủ TinoPage Builder, dùng một lần, hiệu lực 120 giây. Mở ngay trong trình duyệt của chủ dịch vụ; không lưu, không gửi qua kênh khác. Ứng dụng chat tự xem trước link không làm mất vé.
• login_url của Tổng quan tài khoản không phải vé: link mở trang đăng nhập TinoPage Builder bằng tài khoản Tino, khách tự đăng nhập.

Gửi lại an toàn

Mọi lệnh ghi (tạo website, đăng, tạm ngưng, xoá, gắn, kiểm, gỡ tên miền, vé đăng nhập) nhận idempotency_key (8–64 ký tự A-Za-z0-9._:-); với DELETE, gửi ở query. Tạo một khoá cho mỗi lần bấm của khách:

• Mất kết nối giữa chừng thì gửi lại cùng khoá, cùng nội dung: nhận lại kết quả lần trước, lệnh không chạy lần hai. TinoPage Builder nhớ khoá 24 giờ; lần trước lỗi 5xx thì không nhớ, gửi lại sẽ chạy thật.
• Cùng khoá mà nội dung khác, hoặc lần trước còn đang chạy: 409 IDEMPOTENCY_CONFLICT. Tải lại dữ liệu trước khi thử với khoá mới.
• Không gửi khoá thì mỗi lần gọi là một lệnh mới.

Câu trả lời

Thành công: {"data": …}, data là câu trả lời của TinoPage Builder; danh sách có thêm meta (page, per_page, total, last_page). HTTP 200, 201 khi gắn tên miền và cấp vé đăng nhập, 202 khi nhận lệnh tạo website. Thời điểm theo RFC 3339; ID website là UUID.

Lỗi

{ "error": ["LIMIT_EXCEEDED"], "message": "Tài khoản đã dùng hết số website được phép. Nâng cấu hình dịch vụ trên Tino để tạo thêm website.", "details": { "key": "sites" }, "request_id": "…" }

Rẽ nhánh theo error[0], không theo message (câu tiếng Việt, có thể đổi). Mã viết hoa; invalid method (route không có cho dịch vụ này) chỉ có error. Khi báo lỗi cho Tino, gửi kèm request_id.