nextX

Tài liệu API

NextX Open Platform cho phép app / AI agent của đối tác truy cập dữ liệu workspace qua REST API, xác thực bằng OAuth2 client_credentials. Gateway: https://api.nextx.vn.

🚀 Bắt đầu nhanh (5 bước)Đẩy lead bằng API keyCắm vào AI agent (MCP)WebhookCông cụ AI

Tải về: OpenAPI · Postman · llms.txt · SDK Node · Python · Nhật ký thay đổi

1. Tổng quan

Mỗi tích hợp là một OAuth app (có client_id + client_secret). App đại diện cho AI agent / dịch vụ của bạn, hành động thay mặt một workspace đã cài app, và bị giới hạn đúng trong các scope mà workspace đó đồng ý (consent).

Vòng đời:

  1. Bạn tạo app trong console (tự chọn quyền, có khoá ngay, không chờ duyệt).
  2. Bạn tự Publish: máy chạy Publish checklist, đạt là Live trên App Marketplace — không ai duyệt tay.
  3. Workspace khách cài app + đồng ý (consent) tập scope.
  4. App đổi client_credentials → agent token (gắn workspace đó) → gọi API.

Token là ngắn hạn (1 giờ), scoped theo workspace, và thu hồi được khi workspace gỡ app — an toàn hơn API key tĩnh.

2. Gọi API

curl https://api.nextx.vn/api/v1/crm/contacts?page=1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
  • Mọi request đi qua gateway https://api.nextx.vn với header Authorization: Bearer.
  • Scope được kiểm theo hai tầng. Gateway chặn ở khoảng 25 route (Office, CRM contacts, Sales…): thiếu → 403 body có error: insufficient_scope và required (scope cần). Các route còn lại do service kiểm: thiếu → 403 với detail dạng Permission required: <scope>. Token thiếu/hết hạn/sai là 401 problem+json với errorCode: gateway.unauthorized.
  • Rate limit: mặc định 600 request/phút mỗi app → vượt trả 429 (đọc Retry-After).
  • Pagination: ?page=&pageSize= (mặc định pageSize 20; trần tối đa tuỳ endpoint — chung là 1000, riêng /crm/integrations/contacts là 200).

Ứng dụng & OAuth · Error code · Rate limit

3. API reference (62 endpoint)

Mỗi endpoint = 1 tool MCP = 1 scope. Bấm vào service để xem chi tiết: tham số, ví dụ curl, response.

CRM

9 endpoint →

Liên hệ, cơ hội/deal, hoạt động — dữ liệu khách hàng cốt lõi.

crm.contacts.viewcrm.contacts.createcrm.opportunities.viewcrm.opportunities.manage+2

Chat đa kênh

1 endpoint →

Gửi tin nhắn ra các kênh hội thoại (Zalo OA, …).

comm.conversations.handle

Bán hàng

6 endpoint →

Đơn hàng, sản phẩm, tồn kho, khách hàng (POS/bán hàng).

sales.orders.viewsales.products.viewsales.customers.view

Office

10 endpoint →

Bảng dữ liệu no-code (Base/Bitable) và luồng phê duyệt (Approval).

office.base.record.viewoffice.base.record.manageoffice.approval.instance.viewoffice.approval.instance.manage

Nhân sự

5 endpoint →

Thiết bị chấm công, lượt chấm công và lịch sử giờ giấc nhân sự.

hrm.attendance_devices.viewhrm.attendance_raw_punches.view

DMS

7 endpoint →

Danh mục, viếng thăm (check-in), kế hoạch ngày, điểm bán, đơn hàng và tuyến.

dms.catalog.viewdms.checkins.viewdms.daily_plans.viewdms.outlets.view+2

Tổng đài

7 endpoint →

Tổng đài viên, chiến dịch, call/IVR flow, số điện thoại, cuộc gọi và hàng đợi.

call.agents.viewcall.campaigns.viewcall.call_flows.viewcall.ivr_flows.view+3

Marketing

6 endpoint →

Chiến dịch email, mẫu email, tích hợp Google, báo cáo và hồ sơ người gửi.

marketing.email_campaigns.viewmarketing.email_templates.viewmarketing.integrations.viewmarketing.reports.view+1

Thanh toán

6 endpoint →

Chỉ đọc — payment intent, hoàn tiền, giao dịch, gói đăng ký và báo cáo thanh toán.

payment.intents.viewpayment.refunds.viewpayment.transactions.viewpayment.subscriptions.view+1

Hoá đơn điện tử

5 endpoint →

Chỉ đọc — hoá đơn điện tử, ký hiệu, báo cáo tổng hợp và cấu hình.

einvoice.invoices.vieweinvoice.series.vieweinvoice.reports.vieweinvoice.settings.view

4. Webhook

Nhận 33 loại sự kiện realtime qua HTTP push — mỗi dịch vụ một webhook (CRM/Sales/Office…) — payload envelope chuẩn ký HMAC-SHA256 (X-NextX-Signature-256), tối đa 8 lần giao (1 lần đầu + 7 lần retry, ~24 giờ).

contact.identifiedconversation.attribution_resolvedcontact.createdcontact.deletedcontact.updateddeal.woninvoice.cancelledinvoice.failed+25
Tài liệu Webhook đầy đủ → đăng ký · payload · signature · retry

5. MCP — cắm vào AI agent

Dùng nextx-mcp (Model Context Protocol server) để mọi trợ lý AI hỗ trợ MCP gọi được 62 tool NextX. Cấu hình credential 1 lần (như dán API key), phần đổi token được lo tự động.

Hướng dẫn MCP đầy đủ → cài đặt · cấu hình theo từng client · 62 tool

6. Tạo app & Publish

Tự tạo app ở Ứng dụng của tôi (đăng nhập tài khoản NextX). Nhận App ID + App Secret ngay — App Secret chỉ hiện 1 lần. App bắt đầu ở Development mode (chỉ bạn cài, tối đa 3 workspace); đạt Publish checklist tự động thì bấm Publish để mọi khách cài được. Không ai phải duyệt tay.