Bỏ qua nội dung
Quay lại Docs API Tích hợp an toàn

API: tích hợp tạo link & analytics

Tự động hoá tạo link, cấu hình rule và lấy thống kê. Dùng API key để xác thực và giới hạn quyền theo user.

Trang này là tài liệu “public”. Endpoint/field cụ thể bạn có thể map theo backend hiện tại.

Mục lục nhanh
Tạo tài khoản Đọc Getting started

Xác thực (API key)

API key nên được tạo trong dashboard và chỉ hiển thị 1 lần. Gửi key qua header để xác thực.

Header mẫu
Authorization: Bearer YOUR_API_KEY
Accept: application/json
  • Không hardcode API key trong frontend.
  • Rotate key định kỳ và revoke khi nghi ngờ lộ.
  • Giới hạn quyền theo user/project nếu có.

Base URL & versioning

Khuyến nghị đặt version để không phá vỡ tích hợp khi cập nhật.

Base URL gợi ý
https://1linkad.com/api/v1
  • Trả JSON chuẩn: ok/data/error.
  • Chuẩn hoá mã lỗi và message để dễ debug.

Rate limit & lỗi thường gặp

Đặt rate limit để bảo vệ hệ thống và tránh abuse.

  • 429429 Too Many Requests: vượt limit.
  • 401401 Unauthorized: thiếu/ sai API key.
  • 403403 Forbidden: key không đủ quyền.
  • 422422 Validation error: dữ liệu gửi lên không hợp lệ.
  • 500500: lỗi nội bộ (nên log trace_id).
  • Trả header X-RateLimit-* để client tự điều tiết.
  • Luôn trả trace_id trong lỗi để support nhanh.

Danh sách endpoint (gợi ý)

Các endpoint dưới đây là mẫu “tham chiếu”. Bạn map theo backend thực tế của bạn.

Links
POST /links
Tạo link (domain, slug, target_url, rules, tracking).
GET /links
Danh sách link (paging, filter).
GET /links/{id}
Chi tiết link.
PATCH /links/{id}
Cập nhật link/rules/tracking.
DELETE /links/{id}
Xoá link.
Domains
POST /domains
Thêm domain.
GET /domains
Danh sách domain.
POST /domains/{id}/verify
Verify DNS.
POST /domains/{id}/ssl
Bật SSL (nếu hỗ trợ).
Analytics
GET /analytics/links/{id}
Thống kê link theo thời gian (click, device, country, referrer).
GET /analytics/campaigns
Tổng hợp theo UTM campaign (nếu có).

Ví dụ cURL

Ví dụ minh hoạ create link + fetch analytics.

Tạo link (POST /links)
curl -X POST "https://1linkad.com/api/v1/links" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "go.example.com",
    "slug": "summer-sale",
    "target_url": "https://example.com/landing",
    "tracking": true,
    "redirect_code": 302,
    "rules": [
      {"if": {"country": ["VN"], "device": ["mobile"]}, "to": "https://example.com/vn-m"},
      {"if": {"country": ["VN"]}, "to": "https://example.com/vn"}
    ],
    "fallback_url": "https://example.com/default"
  }'
Lấy thống kê (GET /analytics/links/{id})
curl -X GET "https://1linkad.com/api/v1/analytics/links/123?from=2026-02-01&to=2026-02-11" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"
  • Luôn validate target_url và chống SSRF ở backend.
  • Nếu có rule phức tạp, hỗ trợ dry-run để test match.

Webhook/Postback (tuỳ chọn)

Nếu bạn cần gửi event về hệ thống của bạn (conversion/click), có thể dùng webhook/postback.

  • Ký HMAC signature để xác thực event.
  • Gửi retry với backoff khi nhận 5xx.
  • Cho phép user bật/tắt theo project.

Bảo mật khi tích hợp

Checklist tối thiểu để API an toàn:

  • Rate limit theo API key + IP.
  • Audit log: ai tạo/sửa/xoá link, khi nào.
  • Validate URL (chống SSRF), chặn schema lạ (file://, gopher://…).
  • CORS chỉ mở khi thật sự cần.
  • Trả trace_id cho mọi request để debug.

Câu hỏi thường gặp

Trong dashboard (mục API/Integrations). Key chỉ nên lưu ở backend của bạn.

Nên có rate limit để bảo vệ hệ thống. Nếu vượt sẽ nhận 429.

Có thể. Bạn map cấu trúc rules theo backend hiện tại (geo/device/time + fallback).

Muốn tích hợp API cho hệ thống của bạn?

Tạo API key và bắt đầu tạo link/analytics qua API.

Vào dashboard Đọc Getting started