# API LinkedIn và Trợ lý AI (MCP)
Mọi thao tác bạn thực hiện trên các trang LinkedIn đều có thể được thực hiện từ tập lệnh hoặc trợ lý AI: khách hàng tiềm năng, hàng đợi yêu cầu kết nối, quy tắc ICP của bạn (bao gồm cả quốc gia bạn chấp nhận và quy mô mạng lưới của khách hàng tiềm năng), hộp thư đến, các tác nhân AI và cài đặt của bạn.
Không có gì mới cần thiết lập. Nó sử dụng **cùng một khóa API như phần còn lại của DM Champ**, vì vậy nếu bạn đã gọi API của chúng tôi hoặc đã kết nối trợ lý AI, bạn đã sẵn sàng.
## Tìm khóa của bạn ở đâu
Cài đặt → Tích hợp → Khóa API. Nếu bạn chưa có, hãy nhấp vào **Tạo khóa API**. Các bước đầy đủ có trong [Truy cập API](api-access.md).
Không có khóa LinkedIn riêng biệt để tạo, xoay vòng hoặc thu hồi. Khóa này hoạt động như bạn, với cùng các quyền mà bạn có trong ứng dụng, vì vậy hãy coi nó như mật khẩu. Việc thu hồi khóa trong Cài đặt sẽ ngắt kết nối ngay lập tức mọi tập lệnh và trợ lý đang kết nối.
## Gọi API trực tiếp
- **URL cơ sở:** `https://app.sdrpilot.ai/api/v1`
- **Tiêu đề:** `X-API-Key: YOUR_API_KEY`
- **Mô tả máy có thể đọc được:** `https://app.sdrpilot.ai/api/v1/docs/openapi.yaml`
(cũng có sẵn dưới dạng `.json`)
Tài liệu OpenAPI là công khai và mô tả mọi lộ trình, vì vậy hầu hết các công cụ API và trình tạo mã có thể nhập trực tiếp mà không cần khóa.
`Authorization: Bearer YOUR_API_KEY` cũng hoạt động. Điều bạn không thể làm là gửi sai khóa và hy vọng nó sẽ chuyển sang thứ khác: một khi khóa đã được trình bày, câu trả lời sẽ dựa trên khóa đó.
Điều gì sẽ xảy ra khi có lỗi:
| Phản hồi | Ý nghĩa |
|---|---|
| `401` | Khóa bị thiếu, sai định dạng hoặc không được chấp nhận. |
| `403` | Khóa hợp lệ, nhưng tài khoản đó không có không gian làm việc LinkedIn hoặc chưa được phép truy cập. |
| `429` | Quá nhiều lần thử bị từ chối trong một phút đối với khóa đó. Hãy chậm lại. |
| `502` `dmchamp_unreachable` | Chúng tôi không thể kiểm tra khóa của bạn vào lúc này. Nó không bao giờ được coi là hợp lệ. Hãy thử lại. |
## Kết nối trợ lý AI
Các công cụ LinkedIn nằm trên cùng điểm cuối MCP với DM Champ, sử dụng cùng một khóa API, vì vậy trợ lý bạn đã kết nối sẽ tự động nhận diện chúng. Nếu bạn chưa kết nối, hãy làm theo [Kết nối Trợ lý AI (MCP)](connect-ai-clients.md) và sử dụng điểm cuối được liệt kê ở đó.
::: master-only
Điểm cuối là `https://mcp.youraiconnector.com/mcp`, được xác thực bằng tiêu đề `X-API-Key`, chính xác như được mô tả trong Kết nối Trợ lý AI (MCP).
:::
Các công cụ LinkedIn đều có tiền tố **`linkedin_`**, vì vậy bạn có thể dễ dàng nhận ra chúng trong danh sách công cụ của trợ lý và dễ dàng yêu cầu theo tên ("sử dụng các công cụ LinkedIn để cho tôi biết những gì đang được xếp hàng"). Không có quyền hạn cho từng công cụ: một công cụ có thể thực hiện bất cứ điều gì bạn có thể làm trong ứng dụng.
## Ví dụ 1 — chỉ chấp nhận khách hàng tiềm năng từ một số quốc gia nhất định
Hồ sơ ICP của bạn chứa các quy tắc mà khách hàng tiềm năng phải vượt qua. Điều này thiết lập danh sách cho phép gồm Hà Lan và Bỉ. Mã quốc gia gồm hai chữ cái, viết hoa.
```bash
curl -X PUT https://app.sdrpilot.ai/api/v1/icp/YOUR_ICP_ID/filters \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"countries":{"mode":"allow","codes":["NL","BE"]}}'
```
Hai điều cần lưu ý. Phần nội dung là tập hợp **hoàn chỉnh** các quy tắc, không phải là bản vá: một quy tắc bạn bỏ qua sẽ bị tắt. Và câu trả lời bao gồm một khối `impact_on_queue` cho biết có bao nhiêu yêu cầu kết nối đã xếp hàng sẽ không vượt qua các quy tắc mới, ví dụ như `{"examined": 389, "would_withdraw": 155}`.
Việc lưu các quy tắc không tự động rút lại bất kỳ yêu cầu nào.
Trong một trợ lý, bạn chỉ cần nói: "Đặt ICP của tôi để chỉ chấp nhận Hà Lan và Bỉ, và cho tôi biết điều đó sẽ ảnh hưởng thế nào đến hàng đợi của tôi."
## Ví dụ 2 — xem những gì đang được xếp hàng
Các yêu cầu kết nối đã được phê duyệt nhưng chưa được gửi:
```bash
curl -s "https://app.sdrpilot.ai/api/v1/connections/queue?status=queued&limit=100" \
-H "X-API-Key: YOUR_API_KEY"
```
Mỗi hàng hiển thị tên, tiêu đề, công ty, vị trí, quốc gia, số lượng kết nối và người theo dõi của người đó, cùng với điểm số. Bạn có thể thu hẹp danh sách bằng `country`, `min_score`, `max_score` và `source`, và chuyển trang bằng `limit` và `cursor`. Chỉ các yêu cầu đang xếp hàng và đang chờ phê duyệt mới xuất hiện ở đây. Các yêu cầu đã gửi là lịch sử và không thể thay đổi.
## Ví dụ 3 — rút lại tất cả những người nằm ngoài quốc gia của bạn
Sau khi thay đổi quy tắc, hãy kiểm tra lại hàng đợi dựa trên các quy tắc đó. Nếu không có `apply=true`, đây chỉ là bản xem trước và không thay đổi bất cứ điều gì:
```bash
curl -X POST "https://app.sdrpilot.ai/api/v1/connections/queue/rescreen" \
-H "X-API-Key: YOUR_API_KEY"
```
Bạn sẽ nhận lại thông tin về số lượng đã kiểm tra, số lượng sẽ bị rút lại và phân tích chi tiết theo từng quy tắc, chẳng hạn như `country` và `network_too_small` (mạng lưới của khách hàng tiềm năng nhỏ hơn mức tối thiểu của bạn). Bạn hài lòng với kết quả đó? Hãy chạy lại với `?apply=true` và các yêu cầu đó sẽ được rút lại.
```bash
curl -X POST "https://app.sdrpilot.ai/api/v1/connections/queue/rescreen?apply=true" \
-H "X-API-Key: YOUR_API_KEY"
```
Nếu bạn muốn rút lại một nhóm cụ thể, hãy đăng các id thay thế, hoặc một bộ lọc như `{"filter":{"status":"queued","country":"NG"}}` để loại bỏ mọi thứ khớp với điều kiện đó. Gửi id hoặc bộ lọc, không gửi cả hai.
## Khắc phục sự cố
- **`401` trên mỗi cuộc gọi** — khóa bị thiếu hoặc sai. Hãy sao chép lại từ Cài đặt → Tích hợp → Khóa API.
- **`403` mặc dù khóa hoạt động ở nơi khác** — tài khoản đó không được liên kết với không gian làm việc LinkedIn, hoặc LinkedIn chưa được bật cho tài khoản đó.
- **`502 dmchamp_unreachable`** — một lỗi tạm thời khi kiểm tra khóa của bạn. Không có gì được thông qua; hãy thử lại.
- **Một quy tắc không khớp với bất kỳ thứ gì** — mã quốc gia phải ở dạng hai chữ cái viết hoa (`NL`, không phải `Netherlands` hoặc `nl`), và mã ngôn ngữ phải ở dạng chữ thường.
- **Trợ lý không hiển thị công cụ LinkedIn nào** — hãy kết nối lại để trợ lý tải lại danh sách công cụ và kiểm tra xem bạn có đang sử dụng cùng một khóa API hay không.
---
## Các bước tiếp theo
- [Kết nối Trợ lý AI (MCP)](connect-ai-clients.md) — thiết lập Claude, ChatGPT hoặc Cursor với khóa của bạn.
- [Truy cập API](api-access.md) — tạo hoặc xoay vòng khóa được sử dụng cho việc này.