Gọi API bên ngoài
Khoảng 15 phút. Làm xong, app của bạn gọi được API của hệ thống khác (ERP, dịch vụ đối tác), chuyển tiếp request tới một API có sẵn và ghi nhật ký mọi request.
Có hai cách. Cần gọi vài endpoint lẻ thì dùng fetch trong repository. Muốn thay dần một hệ thống cũ thì khai báo upstream. Khi đó, request nào app chưa có handler thì manh.run chuyển sang hệ thống thật.
1. Lưu key của dịch vụ ngoài
Không bao giờ ghi key vào code. Chủ app nhập key ở trang Secret (thanh bên, nhóm Kết nối), hoặc agent đặt qua MCP. Giá trị có hiệu lực ngay, không cần deploy lại. Agent chỉ thấy tên, không đọc được giá trị.
Trong code, đọc key bằng env.TÊN từ manh/env. Đặt lệnh đọc bên trong hàm để luôn lấy được giá trị mới nhất.
2. Gọi một endpoint bằng fetch
import { HTTPException } from "hono/http-exception";
import { fail } from "manh/errors";
import { env } from "manh/env";
export async function lookupTaxCode(taxCode: string) {
const key = env.TAX_API_KEY;
if (!key) throw new HTTPException(503, { message: "Chưa cấu hình TAX_API_KEY", cause: { code: "NOT_CONFIGURED" } });
const res = await fetch(`https://api.tracuu.example.vn/v1/company/${encodeURIComponent(taxCode)}`, {
headers: { authorization: `Bearer ${key}` },
signal: AbortSignal.timeout(8000), // đừng để request treo
});
if (res.status === 404) fail(404, "Không tìm thấy mã số thuế", "NOT_FOUND");
if (!res.ok) throw new HTTPException(502, { message: "Dịch vụ tra cứu đang lỗi", cause: { code: "UPSTREAM" } });
return res.json();
}Lỗi nghiệp vụ, như không tìm thấy mã số thuế, dùng fail từ manh/errors, vì fail dành cho mã 4xx. Lỗi cấu hình và lỗi của dịch vụ ngoài là mã 5xx, nên vẫn ném HTTPException. Cả hai cách đều trả về body { error, message, code } để giao diện hiện message.
3. Chuyển tiếp request tới một API có sẵn
File app/upstream.ts khai báo một hoặc nhiều tiền tố. prefix là đường dẫn trong app (có /api), còn origin là địa chỉ của hệ thống thật.
import { env } from "manh/env";
export default [
{ prefix: "/api/erp", origin: "https://erp.congty.vn/api" }, // auth: "forward" (mặc định)
{ prefix: "/api/pay", origin: "https://pay.partner.vn", auth: "service",
headers: { authorization: `Bearer ${env.PAY_TOKEN}` } }, // token lưu ở trang Secret
];- Nếu app có handler khớp method và đường dẫn thì handler đó luôn chạy trước.
- Request khớp một tiền tố mà chưa có handler thì manh.run chuyển sang
origin + phần còn lại của đường dẫn, giữ nguyên method, query, body và header, trừcookievàhost. manh.run xét tiền tố dài nhất trước. - Request không thuộc tiền tố nào thì trả 404 như bình thường.
Chọn cách xác thực:
"forward"chuyển headerAuthorizationcủa người dùng sang hệ thống thật. Dùng khi app không có đăng nhập riêng."service"bỏ header đó và gửiheaderscủa bạn (token dịch vụ lấy từ Secret). Dùng khi app tự có đăng nhập riêng.
4. Sửa dữ liệu hệ thống thật trả về
Viết handler cho đúng đường dẫn đó, gọi upstream(c) để lấy dữ liệu thật, rồi trả về dữ liệu bạn muốn.
import { upstream } from "manh/upstream";
export const schema = {};
export default async function handler(c) {
const rows = await (await upstream(c)).json(); // GET /api/erp/orders ở hệ thống thật
const today = new Date().toISOString();
return rows.map(({ costPrice, ...o }) => ({ ...o, overdue: o.dueDate < today })); // ẩn giá vốn, thêm cờ quá hạn
}Muốn gọi một đường dẫn khác thì dùng upstream(c, { path: "/api/erp/orders/" + id, method: "GET" }).
5. Giả lập endpoint chưa có
mock(c, data, { status, delay }) trả dữ liệu giả, không gọi hệ thống thật. Dùng khi phía đối tác chưa làm xong, hoặc khi muốn thử giao diện lúc gặp lỗi hay mạng chậm.
import { mock, upstream } from "manh/upstream";
import { SAMPLE_INVOICES } from "./sample";
export const schema = {};
export default async function handler(c) {
const mode = $mock?.["GET /api/erp/invoices"] ?? "real"; // "real" | "mock" | "error500" | "slow3s"
if (mode === "error500") return mock(c, { message: "ERP lỗi" }, { status: 500 });
if (mode === "slow3s") return mock(c, SAMPLE_INVOICES, { delay: 3000 });
if (mode === "mock") return mock(c, SAMPLE_INVOICES);
return upstream(c);
}$mock là một biến lưu trữ của app. Chủ app đổi chế độ ở mục Biến lưu trữ của project mà không cần deploy lại.
6. Xem nhật ký request
manh.run ghi lại mọi request /api của app: method, đường dẫn, mã trạng thái, nguồn (handler, upstream, mock, error), thời gian và body (tối đa 8 KB). Header authorization, cookie, x-api-key và các trường có tên như password, token, secret, otp bị che đi.
Chủ app xem nhật ký ở Vận hành › Lưu lượng. Agent đọc nhật ký qua MCP, rồi dựa vào dữ liệu thật để viết dữ liệu giả và test. Muốn không ghi body cho một mục upstream, thêm log: { bodies: false } vào mục đó.
Cần biết
- Bản xem trước trong không gian làm việc không gọi upstream, nên hãy thử trên app đã deploy.
originphải là địa chỉhttps://tới một tên miền công khai, không dùng IP,localhost,*.localhay*.internal. Sai thìcheckbáoupstream.origin-invalid.- Upstream chỉ dành cho API, không dùng để chuyển tiếp cả một website (HTML).
- Ghi token thẳng vào code thì
checktừ chối (code.hardcoded-secret). - Nhật ký lưu 7 ngày, tối đa 20.000 dòng.
Bước tiếp theo
- Đăng nhập và phân quyền — đăng nhập riêng khi dùng
auth: "service". - API handler — cách báo lỗi và trả kết quả.
- Email, AI, kho file — các dịch vụ dùng được ngay, không cần key.