---
title: "API rút gọn link: tích hợp 1Go bằng curl và JavaScript"
description: "API rút gọn link 1Go: tạo API key đúng quyền, gọi endpoint bằng curl và JavaScript, xử lý lỗi, tránh tạo trùng và bảo vệ key khi tích hợp backend."
url: https://1go.vn/blog/api-rut-gon-link
author: "Đội ngũ 1Go.vn"
published: 2026-10-25
updated: 2026-10-26
category: "Developers & AI"
tags: ["API", "MCP"]
---

# 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ỳ.

***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ì](https://1go.vn/blog/rut-gon-link-la-gi).

[API, CLI và MCP của 1Go](https://1go.vn/tinh-nang/api-mcp) 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ì](https://1go.vn/blog/mcp-la-gi) giải thích cụ thể lựa chọn dành cho trợ lý AI.

![Backend gửi yêu cầu API và nhận link ngắn để lưu vào hệ thống](https://cdn.1go.vn/media/26/onego-tn-api-mcp.webp)

## 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](https://docs.1go.vn/huong-dan/ket-noi/), 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](https://open.1go.vn/bat-dau/xac-thuc/).

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](https://open.1go.vn/), 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](https://open.1go.vn/bat-dau/goi-api-dau-tien/) 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:

```bash
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:

```bash
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](https://open.1go.vn/huong-dan/tao-link/) để 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.

```js
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](https://open.1go.vn/huong-dan/xu-ly-loi/) 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](https://open.1go.vn/huong-dan/gui-lai-an-toan/) 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](https://open.1go.vn/cli/ma-thoat/) 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](https://1go.vn/bang-gia), 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í](https://1go.vn/signup) để 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**.

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

### Có thể dùng API rút gọn link với key chỉ đọc không?

Được. Key chỉ đọc cho phép lấy dữ liệu trong phạm vi được cấp; thao tác tạo link yêu cầu quyền ghi.

### Khi tạo link, có bắt buộc gửi trường nào ngoài url không?

Không. Chỉ `url` là bắt buộc; ví dụ có thêm `title`, còn domain và slug có thể bỏ để dùng domain mặc định và slug tự sinh.

### Có thể xem lại API key đã mất không?

Không. 1Go chỉ hiện key đầy đủ lúc tạo và chỉ lưu bản băm; bạn cần tạo key mới, cập nhật tích hợp rồi thu hồi key cũ.

### Có nên gọi API trực tiếp từ frontend không?

Không. Hãy giữ API key ở backend và chỉ trả về frontend phần dữ liệu cần hiển thị.