Tài liệu
Quickstart self-host, REST API và webhook cho 9Link — nền tảng link mã nguồn mở.
Tự host (quickstart)
Chạy trọn stack dev (Postgres · ClickHouse · Redis) rồi bật web + worker:
docker compose -p 9link-dev -f infra/docker-compose.yml up -d cp .env.example .env pnpm install && pnpm db:migrate && pnpm db:seed pnpm --filter web dev -- -p 3939 # dashboard pnpm --filter web worker # event ingest worker (separate terminal)
Deploy public dùng compose demo tự chứa — xem README trong repo: secret production bắt buộc (fail-closed) và checklist trước khi mở.
Chín trụ cột
| Rút gọn link | Short link thương hiệu, custom domain, bulk, REST API. |
| Mã QR & UTM | QR động có brand, UTM builder, deep link, OG preview. |
| Điều hướng thông minh | Định tuyến theo geo/thiết bị/ngôn ngữ/giờ, A/B, WhatsApp. |
| Trang bio | Link-in-bio và micro landing ngay trên chính link. |
| Thống kê | Analytics real-time, conversion, pixel, attribution. |
| A/B & tối ưu | A/B significance, funnel, gợi ý AI. |
| Kiếm tiền | Tip, checkout, paywall, affiliate auto-tag — Stripe của bạn. |
| Bảo mật & quyền | Password, hết hạn, giới hạn click, chống phishing, team, audit. |
| Tích hợp | REST API, webhook ký HMAC, n8n/Zapier. |
REST API
Mọi endpoint cần header Authorization: Bearer nlk_… — API key theo workspace, tạo tại /keys (token chỉ hiện đúng 1 lần).
| Endpoint | Scope | Mô tả |
|---|---|---|
POST /api/links | links.write | Tạo link |
GET /api/links | — | Liệt kê 100 link mới nhất |
PATCH /api/links/{id} | links.write | Sửa đích/key/domain — redirect cập nhật tức thì |
DELETE /api/links/{id} | links.write | Xoá link |
POST /api/links/bulk | links.write | Tạo hàng loạt (JSON array hoặc CSV, tối đa 100 dòng) |
GET | POST /api/pages | pages.read | pages.write | Liệt kê / tạo bio page |
GET | PATCH /api/pages/{id} | pages.read | pages.write | Đọc / cập nhật một page |
POST /api/pages/{id}/publish | pages.write | Bật/tắt publish page |
POST /api/keys | keys.write | Tạo API key (token trả đúng 1 lần) |
DELETE /api/keys/{id} | keys.write | Thu hồi API key |
POST /api/track/convert | — | Ghi conversion first-party (cid lấy từ ?9l_cid trên đích) |
Ví dụ
BASE=https://9link.com # or your self-hosted server
curl -sX POST $BASE/api/links -H "Authorization: Bearer nlk_..." \
-H "Content-Type: application/json" \
-d '{"url":"https://example.com","key":"promo"}'
# 201 { "link": { "id": "...", "domain": "...", "key": "promo", ... } }
curl -si $BASE/promo # 302 Location: https://example.comWebhook
Đăng ký endpoint https tại /connect — mỗi delivery là POST JSON ký HMAC-SHA256 trong header 9link-signature (verify trên raw body, tolerance 300 giây):
9link-signature: t=<unix>,v1=<hex HMAC-SHA256(secret, "<t>.<rawBody>")>
| Sự kiện | data | Mô tả |
|---|---|---|
link.created | { id, domain, key, url } | Tạo link (bulk N link = N delivery) |
link.updated | { id, domain, key, url } | Sửa link thành công (đích, key, cấu hình…). |
link.deleted | { id, domain, key } | Xoá link — không kèm đích, chỉ đủ để đối chiếu và dọn cache. |
page.published | { id, published } | Bật/tắt bio page |
page.unpublished | { id, published } | Trang bio chuyển sang tắt (đang bật → tắt). |
page.deleted | { id } | Xoá trang bio. |
sale.paid | { id, kind, amount, currency } | Sale monetize được thanh toán (xác nhận từ Stripe) |
Tiêu dùng an toàn: idempotent theo id, không bảo đảm thứ tự, retry backoff 1m→8h (5 lần), đối soát qua REST API khi nghi thiếu.