Open API · API Key

Cấp và quản lý API key

Dành cho quản trị viên NextX CRM. Khi bạn cấp khóa cho một đối tác, website của họ đẩy được khách hàng tiềm năng thẳng vào CRM mà không cần ai nhập tay.

Mở tài liệu tích hợp cho lập trình viên

API key là gì

Chuỗi ký tự thay cho tài khoản đăng nhập khi hai phần mềm nói chuyện với nhau.

API key là một chuỗi ký tự dùng thay cho tài khoản đăng nhập khi hai phần mềm nói chuyện với nhau. Khóa gắn với workspace của bạn: dữ liệu đẩy vào chỉ nằm trong công ty bạn, đối tác không nhìn thấy hay chạm được sang workspace khác.

Khóa dùng cho nhóm API tích hợp CRM: đẩy lead vào, tra danh sách trường, đọc danh sách và chi tiết khách hàng, và cập nhật khách theo số điện thoại (chỉ ghi đè các trường được gửi). Không có thao tác xóa. Khóa tạo từ màn Cài đặt CRM hiện không giới hạn quyền nên dùng được cả nhóm API này.

Ai cầm khóa là đẩy được dữ liệu vào CRM của bạn và đọc được danh sách khách hàng. Hãy coi khóa như mật khẩu: chỉ gửi cho đúng người phụ trách kỹ thuật bên đối tác, qua kênh riêng tư.

Tạo khóa

Đăng nhập NextX CRM bằng tài khoản có quyền quản trị.

· Vào Cài đặt (menu Hệ thống ở cuối thanh bên trái).
· Chọn nhóm Phân hệ CRM → mục API Keys & Webhooks.
· Bấm Tạo khóa, đặt tên gợi nhớ theo đối tác (ví dụ: “Website Chứng khoán ABC”).
· Sao chép khóa hiện ra và lưu lại ngay.

Khóa chỉ hiển thị đúng một lần lúc vừa tạo. Đóng cửa sổ đi là không xem lại được — khi đó chỉ còn cách tạo khóa mới và thu hồi khóa cũ.

Khóa mới có dạng nxk_ + 72 ký tự (phần cuối là mã kiểm, gõ sai một ký tự là bị từ chối ngay). Danh sách chỉ hiện phần đầu (vd nxk_3f9a) để bạn nhận ra khóa nào là khóa nào. Khóa tạo trước 14/10/2026 (64 ký tự, không có nxk_) vẫn dùng bình thường.

Chỉ tài khoản có quyền iam.api_keys.manage mới xem, tạo và thu hồi được khóa. Nhân viên thường không thấy mục này.

Gửi khóa cho đối tác

Gửi kèm hai thứ: API key vừa tạo, và đường dẫn tới tài liệu tích hợp dành cho lập trình viên.

Nên gửi khóa và tài liệu qua hai kênh khác nhau — ví dụ tài liệu qua email, khóa qua tin nhắn trực tiếp cho người phụ trách kỹ thuật.

Mở tài liệu tích hợp cho lập trình viên →

Kiểm tra dữ liệu đã về

Đề nghị đối tác gửi thử một khách hàng mẫu.

· Vào mục Liên hệ trong CRM, sắp xếp theo ngày tạo mới nhất.
· Bản ghi mới hiện ra kèm nguồn mà đối tác khai báo (ví dụ: Website).
· Kiểm tra cột người phụ trách — hệ thống tự chia theo cấu hình phân bổ của công ty.

Nếu chưa cấu hình tự phân bổ, lead vẫn được lưu nhưng chưa có người phụ trách.

Trường tùy chỉnh

Nếu bạn muốn nhận thêm thông tin ngoài họ tên, số điện thoại và email — ví dụ dòng xe quan tâm, gói dịch vụ, mã nhân viên giới thiệu — hãy tạo trường tùy chỉnh trước.

1. Cài đặt → Phân hệ CRM → Trường tùy chỉnh.
2. Tạo trường với tên và kiểu dữ liệu phù hợp.
3. Báo đối tác gọi lại địa chỉ schema — họ sẽ thấy ngay mã trường mới.

Đối tác không cần bạn đọc mã trường qua điện thoại: hệ thống có sẵn một địa chỉ trả về đúng danh sách trường của công ty bạn.

Thu hồi khóa

Thu hồi ngay khi: đối tác ngừng hợp tác, nhân sự kỹ thuật bên đó nghỉ việc, hoặc bạn nghi ngờ khóa bị lộ.

1. Vào Cài đặt → Phân hệ CRM → API Keys & Webhooks.
2. Tìm khóa theo tên hoặc 8 ký tự đầu.
3. Bấm Thu hồi và xác nhận.

Khóa mất hiệu lực gần như ngay lập tức, mọi request dùng khóa đó bị từ chối. Dữ liệu đã đẩy vào trước đó vẫn giữ nguyên, không bị xóa.

Muốn đổi khóa mà không gián đoạn: tạo khóa mới, gửi đối tác, đợi họ xác nhận đã chuyển sang khóa mới, rồi mới thu hồi khóa cũ.

Nối n8n / Make

Không cần code: dùng node HTTP có sẵn và gửi API key ở header.

1. n8n: thêm node HTTP Request. Make: thêm module HTTP › Make a request.
2. Method POST, URL https://api.nextx.vn/api/v1/crm/integrations/leads (hoặc lệnh khác trong Tham chiếu API).
3. Header X-Api-Key = API key của workspace; Content-Type: application/json.
4. Body JSON theo lệnh — ví dụ đẩy lead: họ tên, số điện thoại, email, nguồn.

Cất API key ở mục Credentials (n8n) / Keys (Make), đừng dán thẳng vào node. Lệnh ghi nên kèm Idempotency-Key để chạy lại không tạo trùng.

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

Mấy câu khách hỏi nhiều nhất khi mới cấp khóa.

Đối tác gửi trùng một khách nhiều lần thì CRM có bị nhân đôi không?

Không. Hệ thống nhận ra trùng theo mã tham chiếu bên đối tác, sau đó tới số điện thoại, và trả về bản ghi cũ thay vì tạo thêm.

Số điện thoại gửi dạng +84912… có nhận được không?

Có. Hệ thống tự đưa 84912… và +84912… về dạng 0912… để khớp với dữ liệu đang có.

Một đối tác có cần nhiều khóa không?

Nên mỗi hệ thống một khóa riêng — ví dụ website và ứng dụng di động dùng hai khóa. Khi cần thu hồi thì chỉ ảnh hưởng đúng hệ thống đó.

Cấp khóa rồi thì đối tác xem được dữ liệu khách hàng của tôi không?

Có. Khóa tạo từ màn Cài đặt CRM đọc được danh sách và chi tiết khách hàng (GET /api/v1/crm/integrations/contacts) và cập nhật khách theo số điện thoại. Chỉ cấp khóa cho hệ thống bạn tin cậy, và thu hồi ngay khi không còn dùng.

Lỡ đóng cửa sổ chưa kịp copy khóa thì sao?

Tạo khóa mới rồi thu hồi khóa cũ. Không có cách nào xem lại khóa đã tạo.

Lead vào CRM nhưng nhân viên không thấy?

Kiểm tra cấu hình chia lead và scope dữ liệu của nhân viên đó. Lead luôn được lưu; ai nhìn thấy phụ thuộc quyền xem và người phụ trách.

Tóm tắt

Làm ở đâu trong phần mềm — tra nhanh.

Việc cần làm	Ở đâu
Tạo / thu hồi API key	Cài đặt → Phân hệ CRM → API Keys & Webhooks
Thêm trường tùy chỉnh	Cài đặt → Phân hệ CRM → Trường tùy chỉnh
Cấu hình tự chia lead	Khách hàng → Chia lead
Xem lead vừa nhận	Khách hàng → Liên hệ