Skip to content

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 ↗

Có tài liệu Open API (hồ sơ API) không? — CÓ. CNV Work có đặc tả OpenAPI 3.0 đầy đủ cho CRM Partner API — lead, deal, liên hệ, công ty, hoạt động, hoá đơn, báo giá, thanh toán, sản phẩm, gói đăng ký: từng endpoint, trường dữ liệu, scope và ví dụ.
• Bản đọc cho người: huongdan.cnvwork.com/api-crm
• Bản cho máy: https://api.cnvwork.com/api/v1/partner/crm/openapi.json — nhập thẳng vào Postman, Swagger hoặc công cụ sinh mã.
Đặc tả sinh tự động từ mã nguồn API — tệp openapi.json trên api.cnvwork.com luôn là bản mới nhất. Bảng tóm tắt 33 endpoint nằm ở mục Danh sách endpoint bên dưới. Muốn gọi API thì quản trị workspace cấp một API key theo hướng dẫn trên trang này.
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à chỉ thấy khung «Kết nối API đang tắt». Kiểm tra trước cho đỡ mất thời gian.

1 · Workspace phải bật «Kết nối API» ​

Kết nối API của workspace mặc định đang tắt. Khi tắt, trang API Keys (và cả trang Webhooks) không hiện bảng key mà hiện khung «Kết nối API đang tắt cho workspace này», nút Tạo key mới cũng ẩn đi.

  1. Bước 1 — Chủ sở hữu hoặc quản trị workspace mở trang API Keys

    Vào Hệ thống → API Keys.

  2. Bước 2 — Bấm «Bật kết nối API»

    Nút nằm ngay trong khung «Kết nối API đang tắt». Hiện thông báo «Đã bật kết nối API cho workspace» là xong — bảng key và nút Tạo key mới hiện ra, làm tiếp Tạo một key mới. Bật một lần là dùng được cho cả API Keys lẫn Webhooks.

Ai bấm được: chỉ chủ sở hữu hoặc quản trị workspace. Người khác mở trang sẽ thấy dòng «Chỉ chủ sở hữu hoặc quản trị workspace bật được. Anh/chị nhờ chủ sở hữu đăng nhập và bấm Bật kết nối API tại trang này.» — tick thêm quyền ở Phân quyền không làm hiện nút này, phải nhờ đúng chủ sở hữu hoặc quản trị bấm.

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:

Ô tickCho phép
XemMở trang, xem danh sách key (tên, prefix, scope, trạng thái)
TạoCấp key mới
XóaThu 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
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ênTê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ế.
Prefix8 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.
ScopesQuyền của key. Hiện tối đa 3 nhãn, còn lại gom thành +N.
ExpiresNgà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 usedLầ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.
StatusActive đ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 — ô nhóm CRM ghi tên dễ đọc (vd Ghi Contact (tạo/sửa), Đọc Hóa đơn) kèm mã quyền nhỏ bên dưới (vd crm_contacts:write). 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) ​

PresetGồm những quyềnDùng khi
Read-only inboxconversations:read, messages:readHệ thống ngoài chỉ cần đọc hội thoại và tin nhắn
Send messageconversations:read, messages:read, messages:sendHệ thống ngoài cần gửi tin cho khách
Conversations + AIconversations:*, messages:*, ai:read, ai:invokeBot/trợ lý ngoài vừa đọc vừa trả lời, có gọi AI
KB readkb:readChỉ đọc kho tài liệu (Knowledge Base)
Webhooks readwebhooks:readCô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:readBáo cáo/BI kéo dữ liệu CRM về, không ghi
CRM Lead đọc+ghicrm_leads:read, crm_leads:writeWebsite hoặc landing page đẩy lead vào CRM
CRM Sales fullcrm_leads:*, crm_deals:*, crm_contacts:*, crm_companies:*, crm_activities:*Đồng bộ hai chiều toàn bộ CRM bán hàng
CRM Finance đọccrm_invoices:read, crm_quotations:read, crm_payments:readKế 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ềnNghĩ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:manageXem / quản lý kênh kết nối (Zalo, Facebook…)
ai:read · ai:invokeXem 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:manageXem / quản lý trợ lý AI
webhooks:read · webhooks:manageXem / 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ềnNghĩa
crm_leads:read · crm_leads:writeLead — đọc / tạo và sửa
crm_deals:read · crm_deals:writeCơ hội bán hàng (Deal)
crm_contacts:read · crm_contacts:writeNgười liên hệ
crm_companies:read · crm_companies:writeCông ty khách hàng
crm_activities:read · crm_activities:writeHoạ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:readHoá đơn · Báo giá · Thanh toán — chỉ đọc
crm_products:read · crm_subscriptions:readSả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.

Nối từ CNV CDP ​

CNV CDP gửi dữ liệu khách sang CNV Work bằng node HTTP trong kịch bản tự động hoá của CDP (module Chiến dịch → Automation) — không cần viết mã. Ví dụ hay dùng: khách mới vào CDP hoặc vừa điền form thì tạo luôn Liên hệ hoặc Lead bên CNV Work.

  1. Bước 1 — Bên CNV Work: tạo API key có quyền ghi

    Kết nối API đang tắt thì chủ sở hữu hoặc quản trị workspace bấm Bật kết nối API trước (xem mục trên). Rồi tạo key theo hướng dẫn, ở nhóm CRM (Partner API) tick ô Ghi Contact (tạo/sửa) để tạo Liên hệ, hoặc Ghi Lead (tạo/sửa) để tạo Lead (hoặc bấm preset CRM Lead đọc+ghi). Chép khoá ngay — khoá chỉ hiện một lần.

  2. Bước 2 — Bên CNV CDP: thêm node HTTP vào kịch bản

    Mở kịch bản tự động hoá, thêm node HTTP sau bước kích hoạt (khách mới, điền form…).

  3. Bước 3 — Cấu hình node HTTP

    Method: POST.
    URL: https://api.cnvwork.com/api/v1/partner/crm/contacts để tạo Liên hệ, hoặc https://api.cnvwork.com/api/v1/partner/crm/leads để tạo Lead.
    Header — thêm đủ ba dòng: X-Api-Key = khoá vừa chép · Idempotency-Key = mã riêng của từng khách (chèn mã khách từ dữ liệu CDP, vd cdp- + mã khách) · Content-Type = application/json.
    Body (JSON) — chèn dữ liệu khách của CDP vào đúng chỗ, ví dụ: { "full_name": "<Tên khách>", "phone": "<Số điện thoại>", "source": "CNV CDP" }

  4. Bước 4 — Chạy thử với một khách

    Kích hoạt kịch bản cho một khách thử, rồi mở CRM → Liên hệ (hoặc Leads) bên CNV Work xem bản ghi đã vào chưa. Lỗi thì xem mã lỗi trả về ở node HTTP và đối chiếu bảng mã lỗi.

Kết nối này làm đượcLoại bản ghi
Tạo và sửaLead · Liên hệ · Công ty · Deal
Chỉ tạo (không sửa)Hoạt động chăm sóc
Chỉ đọc (không tạo, không sửa)Hoá đơn · Báo giá · Thanh toán · Sản phẩm · Gói đăng ký
Ba lỗi hay gặp khi nối từ CDP:
① Thiếu Idempotency-Key → mọi lượt gọi báo 400. Header này bắt buộc, chỉ gồm chữ, số, _, -, tối đa 64 ký tự. Gửi lại cùng khoá với cùng nội dung trong 24 giờ thì không tạo bản ghi thứ hai; cùng khoá mà nội dung khác thì báo 409.
② Gửi trường rỗng — ví dụ khách chưa có email mà Body vẫn có "email": "" → 400. Trường nào không chắc mọi khách đều có thì bỏ hẳn khỏi Body.
③ Gửi trường lạ → 400. Body chỉ nhận đúng các trường có trong đặc tả; full_name bắt buộc, tối thiểu 2 ký tự.
💡 Chiến dịch chạy cho hàng nghìn khách cùng lúc có thể chạm giới hạn 600 request/phút — chia đợt hoặc đặt node Trì hoãn trước node HTTP.

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 URLhttps://api.cnvwork.com/api/v1
Xác thựcHeader 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:

bash
curl -s https://api.cnvwork.com/api/v1/partner/crm/_me \
  -H "X-Api-Key: live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
json
{
  "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/crmCRM Partner API — bề mặt chính, có OpenAPI đầy đủ
/api/v1/inboxInbox đ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-keysTự quản lý khoá (xem, thu hồi)
/api/v1/reportsBáo cáo Inbox
/api/v1/storageTả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ĐọcGhi (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).

Danh sách endpoint ​

Mọi đường dẫn dưới đây nối sau https://api.cnvwork.com/api/v1/partner/crm. Chi tiết trường dữ liệu, ví dụ request/response xem ở đặc tả đầy đủ.

EndpointLàm gìScope cần có
GET /leadsDanh sách lead (phân trang con trỏ)crm_leads:read
POST /leadsTạo leadcrm_leads:write
GET /fields/leadsDanh sách trường tuỳ chỉnh của leadcrm_leads:read
GET /leads/{id}Xem một lead theo idcrm_leads:read
PATCH /leads/{id}Sửa leadcrm_leads:write
GET /dealsDanh sách deal (phân trang con trỏ)crm_deals:read
POST /dealsTạo dealcrm_deals:write
GET /fields/dealsDanh sách trường tuỳ chỉnh của dealcrm_deals:read
GET /deals/{id}Xem một deal theo idcrm_deals:read
PATCH /deals/{id}Sửa dealcrm_deals:write
GET /contactsDanh sách liên hệ (phân trang con trỏ)crm_contacts:read
POST /contactsTạo liên hệcrm_contacts:write
GET /fields/contactsDanh sách trường tuỳ chỉnh của liên hệcrm_contacts:read
GET /contacts/{id}Xem một liên hệ theo idcrm_contacts:read
PATCH /contacts/{id}Sửa liên hệcrm_contacts:write
GET /companiesDanh sách công ty (phân trang con trỏ)crm_companies:read
POST /companiesTạo công tycrm_companies:write
GET /fields/companiesDanh sách trường tuỳ chỉnh của công tycrm_companies:read
GET /companies/{id}Xem một công ty theo idcrm_companies:read
PATCH /companies/{id}Sửa công tycrm_companies:write
GET /activitiesDanh sách hoạt động (phân trang con trỏ)crm_activities:read
POST /activitiesTạo hoạt độngcrm_activities:write
GET /activities/{id}Xem một hoạt động theo idcrm_activities:read
GET /invoicesDanh sách hoá đơn (phân trang con trỏ)crm_invoices:read
GET /invoices/{id}Xem một hoá đơn theo idcrm_invoices:read
GET /quotationsDanh sách báo giá (phân trang con trỏ)crm_quotations:read
GET /quotations/{id}Xem một báo giá theo idcrm_quotations:read
GET /paymentsDanh sách thanh toán (phân trang con trỏ)crm_payments:read
GET /payments/{id}Xem một thanh toán theo idcrm_payments:read
GET /productsDanh sách sản phẩm (phân trang con trỏ)crm_products:read
GET /products/{id}Xem một sản phẩm theo idcrm_products:read
GET /subscriptionsDanh sách gói đăng ký (phân trang con trỏ)crm_subscriptions:read
GET /subscriptions/{id}Xem một gói đăng ký theo idcrm_subscriptions:read

Mỗi trường tuỳ chỉnh (custom field) mà workspace tự tạo cho lead, deal, liên hệ, công ty đọc được qua GET /fields/<tài nguyên> — khoá đọc được tài nguyên nào thì đọc được trường tuỳ chỉnh của tài nguyên đó.

Ngoài CRM Partner API, các bề mặt khác (Inbox, Webhooks, Báo cáo, Tệp tin) chưa có đặc tả OpenAPI công khai. Cần tích hợp các phần đó thì liên hệ đội hỗ trợ CNV Work để được hướng dẫn.

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:

bash
curl -s "https://api.cnvwork.com/api/v1/partner/crm/leads?limit=100" \
  -H "X-Api-Key: $CNV_API_KEY"
json
{ "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:

bash
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ềuChi tiết
Bắt buộc khiMọi POST / PATCH / DELETE gọi bằng API key. Thiếu → 400
Định dạngChữ, số, _, -; tối đa 64 ký tự
Hiệu lực24 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 độtCù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 địnhMức
Mỗi phút600 request
Mỗi ngày100.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:

json
{ "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" }.

HTTPerror.codeNghĩa và cách xử lý
401invalid_api_keyKhoá sai, đã thu hồi, hoặc đã hết hạn. Xin quản trị cấp khoá mới
403external_api_disabledWorkspace đang tắt kết nối API — chủ sở hữu hoặc quản trị workspace bấm Bật kết nối API ở trang API Keys. Không phải lỗi mã nguồn
403scope_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
403scope_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
400bad_inputDữ liệu sai, trường lạ, hoặc thiếu header Idempotency-Key. Chi tiết nằm trong details
409idempotency_conflictDùng lại Idempotency-Key cũ với nội dung khác
404lead_not_found, deal_not_found…Bản ghi không tồn tại, hoặc thuộc workspace khác
429rate_limit_exceededVượ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ặpNguyên nhân và cách xử lý
CNV Work có tài liệu Open API / hồ sơ API / API docs không?Có. Đặc tả OpenAPI 3.0 của CRM Partner API: bản đọc tại huongdan.cnvwork.com/api-crm, bản máy đọc tại https://api.cnvwork.com/api/v1/partner/crm/openapi.json. Danh sách endpoint xem mục trên.
Không thấy mục API Keys trong menuVai 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.
Trang API Keys hiện «Kết nối API đang tắt cho workspace này», không thấy nút Tạo key mớiWorkspace chưa bật kết nối API. Chủ sở hữu hoặc quản trị workspace bấm Bật kết nối API ngay trong khung đó (xem mục trên).
Không thấy nút Bật kết nối API, chỉ thấy dòng «Chỉ chủ sở hữu hoặc quản trị workspace bật được…»Bạn không phải chủ sở hữu hay quản trị workspace. Nhờ chủ sở hữu đăng nhập và bấm giúp — tick quyền ở Phân quyền không thay được.
Hệ thống bên ngoài đang chạy bỗng báo 403 external_api_disabledKết nối API của workspace đã bị tắt — mọi key ngừng gọi được cho tới khi bật lại. Chủ sở hữu hoặc quản trị bấm Bật kết nối API.
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ấpKhô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ị 403Nhữ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 401Kiể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ạyXem 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.
CNV Work có kết nối được với CNV CDP không?Được. Trong CNV CDP dựng kịch bản tự động hoá có node HTTP gọi CRM Partner API của CNV Work bằng API key — tạo Lead, Liên hệ, Công ty, Deal, Hoạt động. Không có nút bật sẵn trong menu. Cách làm: Nối từ CNV CDP.
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.

CNV Work — Nền tảng quản lý nhân sự & CRM