API rút gọn link: tích hợp 1Go bằng curl và JavaScript

API rút gọn link giúp phần mềm tạo và quản lý link ngắn qua yêu cầu HTTP, phù hợp để tích hợp vào backend, bot hoặc tác vụ định kỳ. Với 1Go, bạn dùng API key để xác thực và nhận link ngắn trong phản hồi. Trong bài viết này, 1Go sẽ hướng dẫn cách cấp quyền, gọi API bằng curl và JavaScript, xử lý lỗi và tránh tạo link trùng.

1. Khi nào nên dùng API rút gọn link?

API phù hợp khi hệ thống cần tạo link theo một sự kiện rõ ràng, chẳng hạn có sản phẩm mới, xuất bản tài liệu hoặc chuẩn bị tin nhắn gửi khách. Ứng dụng của bạn xử lý logic nghiệp vụ, còn 1Go tạo địa chỉ ngắn để sử dụng trong quy trình đó.

Khi tích hợp rút gọn link vào backend, bot Telegram hay cron job, hãy xác định URL đích lấy từ đâu, lúc nào tạo link và nơi lưu kết quả. Mỗi link cần được liên kết với bản ghi nghiệp vụ tương ứng để hạn chế tạo trùng khi tác vụ chạy lại. Nếu cần tìm hiểu cơ chế chuyển hướng trước khi triển khai, bạn có thể đọc bài rút gọn link là gì.

API, CLI và MCP của 1Go hỗ trợ các cách làm việc khác nhau. API dành cho chương trình gọi trực tiếp, CLI phù hợp khi thao tác trong terminal, còn MCP cho phép trợ lý AI chọn thao tác theo yêu cầu. Bài MCP là gì giải thích cụ thể lựa chọn dành cho trợ lý AI.

2. Chuẩn bị API key và quyền truy cập trên 1Go

2.1. API key có những quyền và hạn dùng nào?

Theo tài liệu Kết nối công cụ và API, chủ sở hữu và quản trị viên workspace là những vai trò được quản lý API key. 1Go khuyến nghị tách key theo tác vụ để cấp quyền phù hợp cho từng hệ thống.

Thiết lập	Lựa chọn trong 1Go	Nên chọn thế nào
Quyền	Chỉ đọc hoặc Đọc & ghi	Đọc báo cáo thì chỉ đọc; tạo link cần quyền ghi
Phạm vi	Giới hạn theo domain hoặc mọi domain	Chỉ chọn domain mà tích hợp thật sự dùng
Hạn dùng	30, 90, 365 ngày hoặc không hết hạn	Mặc định 90 ngày; nên có lịch thay key
Lưu trữ	1Go chỉ giữ bản băm	Lưu key đầy đủ ngay lúc tạo vì không xem lại được

Các scope kỹ thuật được tách thành links:read, links:write, domains:read và analytics:read. Quyền Đọc & ghi vẫn chịu giới hạn bởi phạm vi key và quyền của người tạo; bạn có thể xem chi tiết trong tài liệu xác thực của 1Go.

Ví dụ, key có quyền ghi trên domain A không được thao tác với domain B. Khi gặp lỗi truy cập, hãy đối chiếu cả scope lẫn domain trước khi cân nhắc mở rộng quyền.

2.2. Cách tạo API key trong dashboard

Bạn cần chọn quyền theo đúng tác vụ: đọc dữ liệu hoặc tạo link. Quy trình tạo key gồm các bước sau:

1. Bước 1: Vào Tích hợp → Developers → API keys, chọn Tạo API key.
2. Bước 2: Nhập Tên key gắn với nơi sử dụng, chẳng hạn “Backend tạo link tài liệu”.
3. Bước 3: Tắt Chỉ đọc nếu cần tạo link; giữ tùy chọn này khi tích hợp chỉ lấy dữ liệu.
4. Bước 4: Trong Phạm vi domain, chọn Giới hạn theo domain và đánh dấu các domain cần truy cập.
5. Bước 5: Đặt Hạn dùng, sau đó bấm Tạo key.
6. Bước 6: Lưu key có tiền tố 1go_live_ vào kho bí mật hoặc biến môi trường backend. Đánh dấu Tôi đã lưu key ở nơi an toàn rồi chọn Đóng.

Các ví dụ trong bài lấy key từ biến môi trường ONEGO_API_KEY. Bạn cần lưu đầy đủ key ngay khi tạo để cấu hình cho backend.

Lưu ý: Không đưa key vào JavaScript chạy trên trình duyệt, ứng dụng phát hành công khai hoặc query string. Việc 1Go chỉ lưu bản băm không bảo vệ được key đầy đủ nếu key bị lộ từ phía ứng dụng của bạn.

3. URL shortener API của 1Go dùng endpoint và body nào?

Thông tin endpoint, header và trường dữ liệu dưới đây theo đặc tả công khai trên cổng developer 1Go, cập nhật ngày 25/10/2026. URL shortener API sử dụng địa chỉ gốc https://api.1go.vn; hướng dẫn gọi API đầu tiên trình bày quy trình từ kiểm tra key đến tạo link.

Nhu cầu	Phương thức và đường dẫn	Ghi chú
Kiểm tra danh tính	GET /v1/whoami	Xác minh workspace và phạm vi truy cập
Tạo link	POST /v1/links	Body JSON bắt buộc có url
Thử yêu cầu tạo	POST /v1/links?dry_run=true	Kiểm tra rồi hoàn tác, không lưu link

Yêu cầu xác thực bằng header Authorization: Bearer. Trong body, url là địa chỉ đích bắt buộc; title, slug và domain là các trường tùy chọn. Nếu bỏ domain, API dùng domain mặc định của workspace; nếu bỏ slug, hệ thống tự sinh slug.

Key vẫn phải có quyền sử dụng domain được chọn, kể cả domain mặc định. Các ví dụ chỉ gửi url và title để tránh xung đột slug khi bắt đầu; bạn cần thay URL minh họa bằng địa chỉ công khai của mình. Body không chấp nhận trường ngoài schema, vì vậy không thay url bằng destination hoặc long_url.

4. Cách gọi API rút gọn link bằng curl và JavaScript

4.1. Kiểm tra và tạo link bằng curl

1Go khuyến nghị kiểm tra xác thực trước, sau đó kiểm tra dữ liệu để dễ xác định nguyên nhân lỗi. Thực hiện lần lượt các bước dưới đây:

1. Bước 1: Nạp ONEGO_API_KEY vào terminal từ nơi lưu bí mật.
2. Bước 2: Gửi yêu cầu chỉ đọc sau để kiểm tra key:

curl --fail-with-body --silent --show-error \
  'https://api.1go.vn/v1/whoami' \
  -H "Authorization: Bearer ${ONEGO_API_KEY}"

3. Bước 3: Dùng chế độ chạy thử để kiểm tra body trước khi tạo link:

curl --fail-with-body --silent --show-error \
  --request POST \
  'https://api.1go.vn/v1/links?dry_run=true' \
  -H "Authorization: Bearer ${ONEGO_API_KEY}" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://example.com/huong-dan","title":"Hướng dẫn sử dụng"}'

4. Bước 4: Kiểm tra phản hồi; khi sẵn sàng tạo thật, bỏ ?dry_run=true và gửi lại yêu cầu tới /v1/links.
5. Bước 5: Lưu id để quản lý và short_url để chia sẻ sau khi tạo thật. Địa chỉ trả về ở chế độ chạy thử chưa phải link đã lưu nên không dùng để gửi cho khách.

Chế độ chạy thử không quét an toàn URL; trường scan có giá trị skipped_dry_run. Link được tạo thật có trạng thái kiểm tra riêng. Trước khi tự động gửi kết quả, hãy đọc hướng dẫn tạo link bằng API để xử lý đúng trạng thái này.

4.2. Tạo link bằng JavaScript fetch

Ví dụ dưới đây dùng backend Node.js có sẵn fetch và đọc key từ biến môi trường. Yêu cầu này tạo link thật, khác với lệnh curl chạy thử ở trên.

async function createShortLink() {
  const apiKey = process.env.ONEGO_API_KEY;
  if (!apiKey) throw new Error('Thiếu ONEGO_API_KEY');

  const response = await fetch('https://api.1go.vn/v1/links', {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${apiKey}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      url: 'https://example.com/huong-dan',
      title: 'Hướng dẫn sử dụng',
    }),
  });

  if (!response.ok) {
    throw new Error(`1Go trả HTTP ${response.status}`);
  }

  const link = await response.json();
  return { id: link.id, shortUrl: link.short_url };
}

createShortLink()
  .then((link) => console.log(link.shortUrl))
  .catch((error) => {
    console.error(error.message);
    process.exitCode = 1;
  });

Khi đưa vào ứng dụng, hãy lưu kết quả cùng mã bản ghi nguồn và xử lý lỗi tại tầng tác vụ. Đoạn mã không tự gửi lại yêu cầu vì kết nối có thể mất sau khi máy chủ đã ghi thành công; gửi lại mà chưa kiểm soát có thể tạo link trùng.

5. Cách xử lý lỗi và gửi lại yêu cầu an toàn

1Go trả lỗi theo định dạng application/problem+json. Hướng dẫn xử lý lỗi khuyến nghị dựa vào mã lỗi ổn định để quyết định bước tiếp theo, vì nội dung thông báo có thể được điều chỉnh.

Mã lỗi	Cần kiểm tra
invalid_token	Key sai, hết hạn hoặc đã thu hồi
insufficient_scope	Thiếu quyền cho thao tác
domain_not_allowed	Domain nằm ngoài phạm vi key
slug_conflict	Slug đã có người dùng

API tạo link hỗ trợ Idempotency-Key để gửi lại cùng một yêu cầu an toàn. Với nhu cầu đồng bộ lâu dài theo bản ghi nghiệp vụ, bạn có thể dùng external_id kết hợp PUT /v1/links/upsert.

Các cơ chế này phục vụ những mục đích khác nhau, nên cần chọn theo cách ứng dụng quản lý dữ liệu. Hãy đọc hướng dẫn gửi lại an toàn trước khi bổ sung vòng thử lại.

6. CLI có những mã thoát nào và cần chuẩn bị gì khi vận hành?

6.1. Mã thoát để script nhận diện kết quả

Bảng mã thoát 1Go CLI công bố các giá trị dưới đây. Đây là mã của CLI 1Go, không áp dụng cho curl hoặc đoạn JavaScript trong bài.

Mã	Ý nghĩa
0	Thành công
1	Lỗi chung hoặc I/O cục bộ
2	Sai cú pháp, đối số hoặc thiếu xác nhận
3	Lỗi xác thực hoặc thiếu quyền
4	Không tìm thấy
5	Dữ liệu không hợp lệ hoặc xung đột
6	Vượt tần suất sau các lần thử lại
7	Lỗi mạng, timeout hoặc 5xx sau thử lại
8	Tác vụ hàng loạt chỉ thành công một phần
130	Bị ngắt bằng Ctrl-C

6.2. Kiểm tra hạn mức và thay key

Trước khi vận hành, hãy xem gói và hạn mức 1Go, chọn một domain để bắt đầu và lập lịch thay key. Gói Free có 10 API key để bạn phân chia cho từng môi trường.

Mẹo: Khi thay key, hãy tạo key mới, cập nhật backend rồi mới thu hồi key cũ. Việc thu hồi key cũ không làm dừng các link đã tạo.

7. Kết luận

API rút gọn link giúp tự động hóa việc tạo và quản lý địa chỉ ngắn trong ứng dụng. Để tích hợp ổn định, bạn cần cấp đúng quyền, lưu liên kết với bản ghi nguồn và kiểm soát việc gửi lại yêu cầu.

Bạn có thể đăng ký 1Go miễn phí để bắt đầu tích hợp, không cần thẻ thanh toán. Nếu cần hỗ trợ, hãy liên hệ đội ngũ 1Go qua hotline 0868 567 868.