API Keys

API key là chìa khoá cấp cho phần mềm, không phải cho người. Khi công ty bạn muốn một hệ thống bên ngoài — website bán hàng, phần mềm kế toán, ERP, hay công cụ do đội IT tự viết — đọc và ghi dữ liệu trong CNV Work mà không cần ai ngồi đăng nhập, bạn cấp cho nó một API key.

Trang này viết cho hai người đọc. Quản trị đọc từ đầu đến hết năm quy tắc an toàn: cần gì trước khi tạo, tạo thế nào, chọn quyền ra sao, thu hồi khi nào. Lập trình viên nhận key thì nhảy thẳng xuống Dành cho lập trình viên: địa chỉ API, ví dụ lệnh gọi, phân trang, giới hạn tốc độ, bảng mã lỗi.

Đường dẫn: Hệ thống → API Keys

Mở trang API Keys ↗   Đặc tả CRM Partner API ↗

Bốn thứ hay bị nhầm với nhau.
API Keys (trang này) — chìa khoá để phần mềm khác gọi vào CNV Work lấy hoặc ghi dữ liệu.
Webhooks — chiều ngược lại: CNV Work tự đẩy sự kiện ra ngoài ngay khi có việc xảy ra (lead mới, deal thắng). Hai thứ này thường dùng chung một tích hợp.
Kết nối MCP — nối trợ lý AI (Claude…) vào workspace để hỏi bằng tiếng Việt; dùng loại khoá riêng, không phải API key.
Khoá trong mục Tích hợp (Claude, Google, Microsoft…) — đó là khoá dịch vụ bên kia cấp cho bạn, ngược chiều hoàn toàn với trang này.

Trước khi tạo key — hai điều kiện

Thiếu điều kiện nào thì hoặc bạn không thấy mục API Keys trong menu, hoặc mở được trang mà bấm gì cũng báo lỗi khó hiểu. Kiểm tra trước cho đỡ mất thời gian.

1 · Workspace phải được bật "API ngoài"

Khả năng gọi API từ bên ngoài đi kèm gói dịch vụ — module API Keys hoặc Webhooks. Workspace chưa có gói nào trong hai gói đó thì mọi thao tác trên trang này bị chặn từ máy chủ, kể cả khi bạn là chủ workspace.

Dấu hiệu nhận ra: bảng danh sách hiện trống trơn như chưa có key nào, và khi bấm Tạo key mới thì hiện thông báo đỏ "org chưa bật external API access". Lúc đó liên hệ CNV hoặc xem Gói dịch vụ → Gói & Thanh toán để bổ sung gói.

2 · Vai trò của bạn phải có ô "API Keys"

Trong bảng Phân quyền, dòng API Keys có ba ô thực sự có tác dụng:

Ô tick	Cho phép
Xem	Mở trang, xem danh sách key (tên, prefix, scope, trạng thái)
Tạo	Cấp key mới
Xóa	Thu hồi key đang chạy

Quy tắc: từ 14/09/2026, vai trò hệ thống Nhân viên không còn ô Tạo. Chỉ chủ/admin workspace, vai trò Quản lý, hoặc vai trò được admin tick thêm tay mới cấp được key. Đây là thay đổi có chủ ý — đọc lý do ở mục năm quy tắc an toàn.

🖼️ Hướng dẫn sử dụng (kèm hình ảnh)

Màn hình danh sách

Trang API Keys khi chưa có khoá nào — ① mục API Keys trong nhóm Tích hợp của menu Hệ thống · ② nút Tạo key mới

Mỗi dòng là một khoá đang tồn tại. Sáu cột đọc như sau:

Cột	Ý nghĩa
Tên	Tên bạn đặt lúc tạo. Đây là thứ duy nhất giúp bạn nhớ key này đang nằm ở hệ thống nào — đặt cho tử tế.
Prefix	8 ký tự đầu của khoá, ví dụ live_aB3…. Dùng để đối chiếu: khi lập trình viên hỏi "key nào đang lỗi", họ đọc 8 ký tự đầu, bạn dò đúng dòng. Không phải khoá rút gọn, không dùng để gọi API được.
Scopes	Quyền của key. Hiện tối đa 3 nhãn, còn lại gom thành +N.
Expires	Ngày hết hạn, hoặc "không hết hạn". Qua ngày này key tự chết, không cần ai làm gì.
Last used	Lần cuối key được dùng để gọi API. Trống nghĩa là chưa từng dùng — dấu hiệu tốt để dọn key thừa.
Status	Active đang dùng được · Revoked đã thu hồi (dòng vẫn nằm lại để lưu vết, không xoá được).

Tạo một key mới

1. Bước 1 — Bấm "Tạo key mới"

   Nút nằm góc trên bên phải. Cửa sổ Tạo API key mới hiện ra.

2. Bước 2 — Đặt tên key (bắt buộc)

   Tối đa 100 ký tự. Đặt theo hệ thống sẽ dùng nó, không đặt theo người: "Website bán hàng — đẩy lead", "Phần mềm kế toán — đọc hoá đơn". Sáu tháng sau khi cần thu hồi, cái tên này là thứ duy nhất cho bạn biết tắt nó thì cái gì ngừng chạy.

3. Bước 3 — Chọn ngày hết hạn (tuỳ chọn)

   Để trống là không bao giờ hết hạn. Với đối tác ngoài công ty hoặc key làm thử, nên đặt hạn — đó là cái phanh tự động cho thứ mà người ta hay quên dọn.

4. Bước 4 — Chọn quyền cho key

   Hàng Quick presets là các bộ quyền dựng sẵn, bấm một cái là tick xong cả nhóm. Muốn chi li thì tick từng ô ở hai nhóm Inbox và CRM (Partner API) bên dưới. Phải có ít nhất 1 quyền, nhiều nhất 20. Chi tiết từng quyền ở mục sau.

5. Bước 5 — Bấm "Tạo API key"

   Nút chỉ sáng khi đã có tên và ít nhất một quyền được tick.

💡 Mẹo: mỗi hệ thống kết nối vào nên có key riêng, đừng dùng chung một key cho ba phần mềm. Khi một bên trục trặc hoặc hết hợp đồng, bạn thu hồi đúng cái của bên đó mà không làm chết hai bên còn lại.

Chép khoá ngay — chỉ hiện đúng một lần

Tạo xong, một khung vàng hiện lên đầu trang chứa khoá đầy đủ kèm nút Copy. Đây là lần duy nhất bạn nhìn thấy nó: hệ thống chỉ giữ lại bản mã hoá một chiều, nên không ai — kể cả CNV — đọc lại được khoá đã cấp.

1. Bấm Copy ngay

   Dán vào nơi lưu bí mật của đội kỹ thuật (trình quản lý mật khẩu, biến môi trường của máy chủ), không dán vào chat nhóm, email hay file Excel dùng chung.

2. Giao cho đúng người

   Gửi cho lập trình viên phụ trách tích hợp qua kênh riêng tư, kèm đường dẫn phần dành cho lập trình viên của trang này.

3. Lỡ mất thì tạo cái mới

   Không có đường khôi phục. Thu hồi key cũ, tạo key mới, cập nhật lại phía hệ thống đang dùng.

Thu hồi một key

Bấm Revoke ở cuối dòng. Hệ thống hỏi lại "API key sẽ KHÔNG dùng được nữa. Hành động này không thể hoàn tác." — xác nhận là xong.

Key chết ngay lập tức: mọi lệnh gọi tiếp theo mang khoá đó nhận lỗi 401. Dòng key vẫn nằm lại trong bảng với trạng thái Revoked để lưu vết ai từng cấp cho ai.

Thu hồi ngay, không chần chừ, khi: đối tác kết thúc hợp đồng · lập trình viên giữ khoá nghỉ việc · khoá bị dán nhầm vào mã nguồn công khai hay chat nhóm · cột Last used trống nhiều tháng mà không ai nhận là của mình. Key sống mãi mà không ai quản mới là rủi ro, chứ không phải việc thu hồi.

Chọn quyền (scope) cho đúng

Scope trả lời hai câu: đụng vào nhóm dữ liệu nào và được đọc hay được ghi. Viết theo dạng nhóm:hành_động — ví dụ crm_leads:read là chỉ đọc Lead, crm_leads:write là tạo và sửa Lead. Dấu sao crm_leads:* nghĩa là cả đọc lẫn ghi của nhóm đó.

Bộ dựng sẵn (Quick presets)

Preset	Gồm những quyền	Dùng khi
Read-only inbox	conversations:read, messages:read	Hệ thống ngoài chỉ cần đọc hội thoại và tin nhắn
Send message	conversations:read, messages:read, messages:send	Hệ thống ngoài cần gửi tin cho khách
Conversations + AI	conversations:*, messages:*, ai:read, ai:invoke	Bot/trợ lý ngoài vừa đọc vừa trả lời, có gọi AI
KB read	kb:read	Chỉ đọc kho tài liệu (Knowledge Base)
Webhooks read	webhooks:read	Công cụ giám sát muốn xem danh sách webhook
CRM đọc tất cả	crm_leads:read, crm_deals:read, crm_contacts:read, crm_companies:read, crm_activities:read	Báo cáo/BI kéo dữ liệu CRM về, không ghi
CRM Lead đọc+ghi	crm_leads:read, crm_leads:write	Website hoặc landing page đẩy lead vào CRM
CRM Sales full	crm_leads:*, crm_deals:*, crm_contacts:*, crm_companies:*, crm_activities:*	Đồng bộ hai chiều toàn bộ CRM bán hàng
CRM Finance đọc	crm_invoices:read, crm_quotations:read, crm_payments:read	Kế toán đối soát hoá đơn, báo giá, thanh toán

Toàn bộ quyền chọn được

Nhóm Inbox — hội thoại đa kênh, tin nhắn, kênh, AI, kho tài liệu, webhook:

Quyền	Nghĩa
conversations:read · conversations:write	Đọc / cập nhật hội thoại
messages:read · messages:send	Đọc tin nhắn / gửi tin nhắn
channels:read · channels:manage	Xem / quản lý kênh kết nối (Zalo, Facebook…)
ai:read · ai:invoke	Xem cấu hình AI / gọi AI trả lời
kb:read · kb:write	Đọc / ghi kho tài liệu huấn luyện
agents:read · agents:manage	Xem / quản lý trợ lý AI
webhooks:read · webhooks:manage	Xem / quản lý webhook

Nhóm CRM (Partner API) — dành cho đối tác thứ ba đọc và ghi dữ liệu CRM:

Quyền	Nghĩa
crm_leads:read · crm_leads:write	Lead — đọc / tạo và sửa
crm_deals:read · crm_deals:write	Cơ hội bán hàng (Deal)
crm_contacts:read · crm_contacts:write	Người liên hệ
crm_companies:read · crm_companies:write	Công ty khách hàng
crm_activities:read · crm_activities:write	Hoạt động chăm sóc (gọi, gặp, ghi chú) — ghi là tạo mới, không sửa được hoạt động cũ
crm_invoices:read · crm_quotations:read · crm_payments:read	Hoá đơn · Báo giá · Thanh toán — chỉ đọc
crm_products:read · crm_subscriptions:read	Sản phẩm · Gói đăng ký — chỉ đọc

Quy tắc: nhóm tài chính (hoá đơn, báo giá, thanh toán, sản phẩm, gói) chỉ có quyền đọc — không hệ thống bên ngoài nào tạo hay sửa được hoá đơn qua API. Đây là chốt cố định, không phải thiếu sót.

💡 Mẹo chọn quyền: hỏi lập trình viên đúng một câu — "hệ thống của bên bạn cần đọc gì và ghi gì?" — rồi tick vừa đúng chừng đó. Sau này cần thêm thì tạo key mới: quyền của một key đã cấp không sửa được.

Key mạnh hơn bạn tưởng — năm quy tắc an toàn

Điều quan trọng nhất trên trang này. API key không thuộc về nhân viên nào, nên nó không bị lọc dữ liệu theo người hay theo team như khi một nhân viên đăng nhập. Một key mang conversations:read đọc được mọi hội thoại của workspace; key mang crm_leads:read đọc được mọi lead, kể cả lead của người khác. Cấp key là cấp quyền ở mức toàn công ty trong phạm vi scope đó — chính vì vậy quyền Tạo key đã được gỡ khỏi vai trò Nhân viên.

1. Mỗi hệ thống một key riêng. Thu hồi được từng cái mà không làm gãy phần còn lại.
2. Cấp vừa đủ quyền. Bên kia chỉ đọc lead thì đừng tick crm_leads:write, càng không tick cả cụm CRM Sales full.
3. Đặt hạn cho key của người ngoài. Đối tác, freelancer, bản chạy thử — đặt ngày hết hạn ngay từ đầu.
4. Khoá là bí mật như mật khẩu. Không commit vào Git, không dán vào chat nhóm, không nhúng vào web hay app chạy trên máy khách (người dùng mở xem được mã nguồn là lấy được khoá). Chỗ đúng của nó là biến môi trường trên máy chủ.
5. Nghi lộ là thu hồi, hỏi sau. Thu hồi rồi cấp key mới mất chưa tới một phút; một khoá lọt ra ngoài thì đọc sạch dữ liệu trong phạm vi scope của nó.

💡 Key không chạm được mọi thứ: hệ thống chỉ mở đúng vài bề mặt dành cho bên ngoài (CRM Partner API, Inbox, Webhooks, Báo cáo, Tệp tin). Gọi vào phần nội bộ — nhân sự, lương, chấm công, người dùng — thì key luôn bị từ chối, dù tick quyền gì đi nữa.

Dành cho lập trình viên

Phần này dành cho người nhận khoá và viết mã gọi API.

Địa chỉ và cách xác thực

Base URL	https://api.cnvwork.com/api/v1
Xác thực	Header X-Api-Key: <khoá> trên mọi request
Dạng khoá	live_ + chuỗi ngẫu nhiên (bản production). Môi trường thử nghiệm dùng tiền tố dev_ / test_
Đặc tả đầy đủ	huongdan.cnvwork.com/api-crm — bản đọc được cho người · openapi.json — bản cho máy (Postman, sinh mã)

Gọi thử một phát cho chắc — endpoint whoami trả về workspace và danh sách scope của chính khoá đang dùng:

curl -s https://api.cnvwork.com/api/v1/partner/crm/_me \
  -H "X-Api-Key: live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "object": "crm.api_identity",
  "tenant_id": "…",
  "actor_type": "api_key",
  "key_prefix": "live_aB3",
  "scopes": ["crm_leads:read", "crm_leads:write"]
}

Bề mặt mà API key được phép gọi

Hệ thống chạy nguyên tắc cấm trước, mở sau: khoá chỉ đi được vào đúng các tiền tố dưới đây. Mọi đường dẫn khác bị chặn ngay ở cửa xác thực với 403 scope_required kèm details.scope: "user_only" — bị chặn vì đường dẫn, không phải vì thiếu scope, nên tick thêm quyền cũng vô ích.

Tiền tố	Nội dung
/api/v1/partner/crm	CRM Partner API — bề mặt chính, có OpenAPI đầy đủ
/api/v1/inbox	Inbox đa kênh — hội thoại, tin nhắn, kênh, AI, kho tài liệu
/api/v1/webhooks · /api/v1/webhook-deliveries	Đăng ký webhook, xem và gửi lại lịch sử
/api/v1/api-keys	Tự quản lý khoá (xem, thu hồi)
/api/v1/reports	Báo cáo Inbox
/api/v1/storage	Tải lên và phục vụ tệp đính kèm

CRM Partner API

Mười tài nguyên, quy ước Stripe-style: GET danh sách trả data[] kèm con trỏ, GET /{id} trả thẳng đối tượng.

Tài nguyên	Đọc	Ghi (POST tạo · PATCH sửa)
/leads /deals /contacts /companies	✅	✅
/activities	✅	✅ tạo (không sửa)
/invoices /quotations /payments /products /subscriptions	✅	❌

Ba endpoint phụ trợ: / (danh sách tài nguyên) · /_scopes (catalog scope) · /_me (thông tin khoá đang gọi).

Phân trang bằng con trỏ — limit mặc định 50, tối đa 100. Đọc hết bằng cách lặp next_cursor tới khi has_more là false:

curl -s "https://api.cnvwork.com/api/v1/partner/crm/leads?limit=100" \
  -H "X-Api-Key: $CNV_API_KEY"

{ "object": "list", "data": [ { "object": "crm.lead", "id": "…", "full_name": "…" } ],
  "has_more": true, "next_cursor": "eyJ…" }

Lọc thêm bằng status (không áp dụng cho /activities).

Ghi dữ liệu — bắt buộc header Idempotency-Key. Tạo một lead:

curl -s -X POST https://api.cnvwork.com/api/v1/partner/crm/leads \
  -H "X-Api-Key: $CNV_API_KEY" \
  -H "Idempotency-Key: web-form-2026-09-16-00042" \
  -H "Content-Type: application/json" \
  -d '{"full_name":"Nguyễn Văn A","phone":"0901234567","email":"a@example.com","source":"website"}'

Trường bắt buộc khi tạo: full_name (lead, contact) · title (deal) · name (company) · activity_type + entity_type + entity_id (activity). Thân request là danh sách trắng: gửi trường lạ thì nhận 400 chứ không bị bỏ qua im lặng.

Idempotency-Key

Điều	Chi tiết
Bắt buộc khi	Mọi POST / PATCH / DELETE gọi bằng API key. Thiếu → 400
Định dạng	Chữ, số, _, -; tối đa 64 ký tự
Hiệu lực	24 giờ. Gửi lại đúng khoá với đúng nội dung → nhận lại y nguyên kết quả lần đầu, không tạo bản ghi thứ hai
Xung đột	Cùng khoá nhưng nội dung khác → 409 idempotency_conflict

Thực tế nên sinh khoá từ định danh bên phía bạn (số đơn, id bản ghi), đừng dùng số ngẫu nhiên mới mỗi lần thử lại — như vậy mới chống được trùng khi mạng chập chờn.

Giới hạn tốc độ

Giới hạn mặc định	Mức
Mỗi phút	600 request
Mỗi ngày	100.000 request

Bộ đếm chạy trước bước xác thực khoá, nên nó tính theo địa chỉ IP gọi đến chứ không tách theo từng key: nhiều key chạy chung một máy chủ thì xài chung hạn mức, và đổi sang key khác trên cùng máy cũng không làm bộ đếm về 0.

Mọi phản hồi mang sẵn X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset. Khi vượt, máy chủ trả 429 kèm Retry-After (giây) và thân:

{ "error": { "code": "rate_limit_exceeded", "retry_after": 37 }, "request_id": "…" }

Đọc Retry-After rồi chờ đúng chừng đó — đừng thử lại ngay, vòng lặp thử lại dồn dập chỉ làm cạn hạn mức của cả workspace.

Bảng mã lỗi

Thân phản hồi lỗi luôn có dạng { "error": { "code", "message", "details" }, "request_id" }.

HTTP	error.code	Nghĩa và cách xử lý
401	invalid_api_key	Khoá sai, đã thu hồi, hoặc đã hết hạn. Xin quản trị cấp khoá mới
403	external_api_disabled	Workspace chưa bật API ngoài — cần bổ sung gói, không phải lỗi mã nguồn
403	scope_required details.scope: "user_only"	Đang gọi vào bề mặt nội bộ; API key không bao giờ vào được. Xem bảng bề mặt cho phép ở trên
403	scope_required details.scope: "crm_leads:read"	Khoá thiếu đúng scope đó. Tạo khoá mới với scope đúng — scope của khoá cũ không sửa được
400	bad_input	Dữ liệu sai, trường lạ, hoặc thiếu header Idempotency-Key. Chi tiết nằm trong details
409	idempotency_conflict	Dùng lại Idempotency-Key cũ với nội dung khác
404	lead_not_found, deal_not_found…	Bản ghi không tồn tại, hoặc thuộc workspace khác
429	rate_limit_exceeded	Vượt giới hạn tốc độ — chờ theo Retry-After

Mọi phản hồi lỗi đều kèm request_id. Khi báo sự cố cho CNV, gửi kèm mã đó cùng 8 ký tự đầu của khoá — đủ để tra đúng request mà không phải lộ khoá.

Nhận sự kiện thay vì hỏi liên tục

Cần biết ngay khi có lead mới hay deal thắng thì đừng gọi GET /leads mỗi phút. Đăng ký Webhooks để CNV Work chủ động đẩy sự kiện sang địa chỉ của bạn — nhẹ hơn cho cả hai bên và không tốn hạn mức.

Hỏi nhanh — đáp nhanh

Bạn gặp	Nguyên nhân và cách xử lý
Không thấy mục API Keys trong menu	Vai trò của bạn chưa có ô Xem của dòng API Keys. Nhờ quản trị tick thêm ở Phân quyền.
Bấm Tạo key mới thì báo "org chưa bật external API access"	Workspace chưa có gói mở API ngoài. Liên hệ CNV hoặc xem Gói dịch vụ → Gói & Thanh toán.
Bảng trống mà chắc chắn công ty đang dùng API	Cũng là lỗi trên: khi API ngoài bị tắt, danh sách không tải được nên trông hệt như chưa có key nào.
Lỡ đóng khung vàng, chưa kịp chép khoá	Không lấy lại được — hệ thống chỉ giữ bản mã hoá. Thu hồi khoá đó rồi tạo cái mới.
Muốn đổi quyền của một key đã cấp	Không sửa được. Tạo key mới với quyền đúng, chuyển hệ thống bên kia sang key mới, rồi thu hồi key cũ.
Nhân viên trước đây tạo được key, giờ không tạo được nữa	Đúng như thiết kế từ 14/09/2026. Cần thì admin tick lại ô Tạo cho vai trò đó ở Phân quyền.
Key gọi API nhân sự / chấm công thì bị 403	Những phần đó là nội bộ, API key không vào được, không liên quan tới scope đã tick. Xem bảng bề mặt cho phép.
Key vẫn Active mà gọi báo 401	Kiểm tra cột Expires (đã qua ngày thì key chết dù hiện Active trên dòng cũ) và xem có ai vừa thu hồi không.
Muốn biết key nào đang thực sự chạy	Xem cột Last used. Trống nhiều tháng thì gần như chắc chắn là key thừa — hỏi lại đội kỹ thuật rồi thu hồi.
Cần nối trợ lý AI như Claude vào workspace	Đó là Kết nối MCP, dùng loại khoá riêng, không phải trang này.

Xem thêm

• Hệ thống & Phân quyền — mục API Keys, Webhooks, Kết nối MCP và bảng Phân quyền.
• Webhooks — chiều ngược lại: hệ thống tự đẩy sự kiện ra ngoài.
• CRM bán hàng — hiểu Lead, Deal, Contact, Company trước khi đọc API của chúng.
• Đặc tả CRM Partner API — danh sách đầy đủ endpoint, trường dữ liệu và ví dụ, sinh thẳng từ mã nguồn API.