Chọn chế độ tích hợp

Chọn mode một lần cho mỗi client. Có thể mix mode giữa các app — cùng token và catalog.

Decision tree

Đã có FE Gommo dùng /v2 và /api/v2?
├─ CÓ → Mode C (chỉ đổi base URL gateway)
└─ KHÔNG
    ├─ Gọi thẳng Gommo upstream được? (khuyến nghị)
    │   ├─ CÓ → Mode A Direct (v2.api.gommo.net + api.gommo.net)
    │   └─ KHÔNG
    │       └─ Cần billing, BYOK, hoặc wait: true trên server self-host?
    │           ├─ CÓ → Mode B REST (/gateway/*)
    │           └─ KHÔNG → Mode A Direct (đơn giản nhất — không phụ thuộc gateway)

Theo use case

Use case	Khuyến nghị	Lý do
App/backend mới	Mode A	Public API, không phụ thuộc gateway
Mobile qua backend	Mode A	Direct upstream; tự poll
Script batch nội bộ	Mode A hoặc B	A = không infra; B = wait: true self-host
FE site-ai / Gommo legacy	Mode C	Đổi base URL tối thiểu
Cần billing/BYOK gateway	Mode B	chuyển khoản, BYOK, JSON errors
Playground dev	Mode A hoặc B/C	Playground hiện public URL; dev có thể proxy
Browser cross-origin + self-host	Mode B + CORS	REST + GATEWAY_CORS_ORIGIN
Agent / automation	Mode A hoặc Gommo MCP	HTTP direct hoặc MCP hosted

Trade-offs

Mode A — Direct (khuyến nghị)

Ưu: Không phụ thuộc gateway; latency thấp; host Gommo chính thức.
Nhược: Hai hostname; tự poll; domain trong mọi form.

Mode B — REST

Ưu: Một prefix; JSON; poll built-in; inject domain; billing/BYOK.
Nhược: Cần self-host gateway; khác shape Gommo raw.

Mode C — Proxy

Ưu: Drop-in FE Gommo; giữ envelope upstream.
Nhược: Client vẫn gửi domain; không có wait: true.

Chuyển mode sau này

Từ → Sang	Effort
A → B	Trung bình — trỏ gateway, JSON body
C → B	Trung bình — viết lại /gateway/*
B → A	Thấp — public hosts, form + poll client
B → C	Thấp cho media — map REST về /vi/v2

Token và slug giữ nguyên.

Checklist

• [ ] Đã list models và copy ratio từ response
• [ ] Biết domain gửi ở đâu (form client cho Mode A)
• [ ] Có chiến lược poll (3.5s × 80, hoặc gateway wait: true)
• [ ] CORS chỉ khi browser gọi self-host gateway (Mode B)
• [ ] Merchant token không ở client

Tiếp theo

→ Gommo public API · Integration modes · Quickstart