Giới thiệu Pancake CRM API — Vị trí trong hệ sinh thái Pancake, cấu hình api_key, tổng quan endpoint

TL;DR: Pancake CRM là một sản phẩm trong hệ sinh thái Pancake — bên cạnh Pancake chat đa kênh (quản lý hội thoại FB/IG/Zalo), CRM phục vụ flow sales pipeline + customer management với tính năng hoàn toàn khác. Base URL https://crm.pancake.vn/api, xác thực bằng api_key truyền trong query param (KHÔNG phải Bearer header, KHÔNG phải page_access_token của Page). Multi-tenant theo workspace. Cung cấp 6 nhóm endpoint: Records (lead/account/contact), Orders, Tickets, Sources, Tags (CRM-scope), và Webhook realtime cho record event. Đây là pillar đầu tiên của cluster Pancake CRM — các bài sau sẽ cover từng endpoint sâu hơn.

Hệ sinh thái Pancake gồm nhiều sản phẩm chuyên biệt cho từng khía cạnh vận hành kinh doanh — chat đa kênh (Pancake chat — đã có cluster 6 bài API), POS bán hàng, CRM quản lý khách hàng/sales pipeline, và một số sản phẩm khác. Mỗi sản phẩm có API + token riêng nhưng cùng share concept "page/workspace + dashboard quản trị".

Bài này mở pillar mới về Pancake CRM — sản phẩm có chức năng khác hoàn toàn với chat (entity là lead/contact/order/ticket thay vì conversation/message). Nhiều dev mới integrate hay nhầm 2 sản phẩm dùng chung API, dẫn tới gọi sai endpoint, sai token. Bài này phân biệt rõ và hướng dẫn kết nối lần đầu.

1. Vị trí của CRM trong hệ sinh thái Pancake

Pancake không phải là 1 sản phẩm duy nhất — đây là bộ sản phẩm (suite) phục vụ vận hành shop/doanh nghiệp, mỗi sản phẩm tách biệt về dữ liệu và API:

Trong bài này tập trung vào CRM — sản phẩm có chức năng và data model khác hoàn toàn với chat:

Khi nào dùng sản phẩm nào?

• Chỉ Pancake chat — shop nhỏ chỉ cần reply chat khách, chưa cần pipeline sales phức tạp
• Chỉ Pancake CRM — team sales B2B làm lead/deal/order, không có flow chat trực tiếp với khách
• Cả 2 song song — phổ biến nhất với shop bán hàng ở VN: Pancake chat quản hội thoại thời gian thực, CRM quản đơn hàng + lead funnel + báo cáo. Có thể tự build integration đẩy data chat → CRM (sẽ có bài tutorial riêng trong cluster).

2. Tính năng nổi bật của Pancake CRM

Trước khi đi vào API, hiểu sản phẩm làm gì sẽ giúp bạn map endpoint với use case thực tế:

2.1. Tập trung dữ liệu khách hàng đa kênh

Pancake CRM thu thập lead từ Facebook, Instagram, Zalo, TikTok, Website, Shopee, Google Ads... vào 1 nền tảng duy nhất. Mỗi lead/contact có pipeline trạng thái (Lead mới → Đang liên hệ → Đang chăm sóc → Đóng deal), gắn nguồn, tag, priority để team sales follow up theo thứ tự ưu tiên.

→ Liên quan API: Records (lead/account/contact), Sources (attribution kênh), Tags (phân loại). Bài Records CRUD sẽ cover sâu hơn pattern sync lead từ form landing page về CRM.

2.2. Automation chăm sóc + Conversion API quảng cáo

CRM có workflow automation no-code trong dashboard: trigger khi khách thực hiện hành động → tự gửi email/SMS/ZNS/thông báo cho sales. Bổ sung Conversion API đẩy event chuyển đổi từ CRM về Facebook/TikTok Ads → tối ưu cost-per-conversion (giảm chi phí quảng cáo).

→ Liên quan API: Webhook (trigger từ event record change), Records (đọc state để fire automation). Lưu ý: phần automation no-code ở dashboard không expose hết qua API — chỉ event trigger.

2.3. Phù hợp đa ngành

Pancake CRM được dùng cho nhiều ngành đặc thù: Bất động sản (quản lý lịch xem nhà), TMĐT (lịch sử mua, ưu đãi cá nhân hoá), Y tế (giảm tỉ lệ bệnh nhân bỏ hẹn), Du lịch (booking lifecycle + chăm sóc sau tour).

→ Liên quan API: Orders (đơn hàng / booking), Tickets (task chăm sóc / hẹn lại), Records (lưu thông tin khách).

3. Workspace — concept đa tenant của Pancake CRM

Khác với Pancake chat (1 token = 1 fanpage), Pancake CRM tổ chức theo workspace:

• Workspace = 1 đơn vị isolation. Mỗi workspace có riêng: users, records, orders, tickets, tags, settings, api_key.
• 1 user có thể được mời vào nhiều workspace với role khác nhau (admin / member).
• Toàn bộ URL endpoint đều có dạng /workspaces/{workspace_id}/{resource}/... → workspace_id là path param bắt buộc.

Ví dụ thực tế:

• Công ty ABC có 1 workspace cho team Sales VN, 1 workspace riêng cho chi nhánh nước ngoài
• Mỗi workspace có lead pipeline + order pipeline riêng
• Reports không chéo giữa các workspace

Lấy workspace_id: vào dashboard CRM → URL bar có dạng crm.pancake.vn/workspaces/{workspace_id}/... — copy phần ID đó.

4. Lấy api_key

api_key là khoá xác thực per-workspace. Cách lấy:

1. Vào dashboard Pancake CRM → workspace muốn integrate
2. Cài đặt → Công cụ (Tools) → mục API key (cần quyền admin)
3. Bấm Tạo API key mới → đặt tên gợi nhớ (vd: "n8n integration", "Internal sync script")
4. Copy ngay — Pancake có thể không cho xem lại token sau khi đóng modal
5. Lưu vào secret manager (1Password, Bitwarden, .env)

Cách dùng — query param

?api_key=YOUR_API_KEY_HERE

5. Test connection — request đầu tiên

Verify api_key + workspace_id hoạt động bằng cách gọi endpoint list records đơn giản nhất:

curl -G "https://crm.pancake.vn/api/workspaces/$WORKSPACE_ID/lead/records" \
  --data-urlencode "api_key=$API_KEY"

Response thành công (HTTP 200)

{
  "cursor": "eyJwYWdlIjoxfQ==",
  "entries": [
    {
      "id": "lead_uuid_1",
      "name": "Nguyễn Văn A",
      "phone": "0901234567",
      "email": "nva@example.com",
      "created_at": "2026-06-15T10:30:00Z"
    }
  ]
}

Common errors khi setup lần đầu

6. Tổng quan 6 nhóm endpoint

3 record types được hỗ trợ qua Records API: lead, account, contact — tương đương standard CRM (lead = chưa qualified, contact = cá nhân đã verified, account = công ty/tổ chức).

7. Webhook overview

Pancake CRM có webhook realtime push HTTP POST tới endpoint bạn config mỗi khi có thay đổi record. Setup:

1. Vào workspace → Settings → Tools → tab Webhook - API
2. Nhập URL endpoint của bạn (phải HTTPS public)
3. Pancake test verify, nếu OK → save

Event types

Hiện tại chỉ có 1 event: record — fire khi bất kỳ record (lead/account/contact/order/ticket) bị CRUD.

Suspend policy ⚠

Pancake CRM tự động suspend webhook nếu trong 30 phút có:

• Error rate vượt 80% (trả response ngoài 2xx), VÀ
• Số request fail ≥ 300

Khi suspend, webhook ngừng push event cho tới khi bạn re-enable thủ công trong dashboard.

Best practices (giống pattern webhook Pancake chat)

• Trả HTTP 200 nhanh (dưới 5 giây) sau khi nhận request
• Xử lý async qua queue (Redis/SQS) — không xử lý trong handler
• Idempotent processing — Pancake có thể retry, design code chấp nhận duplicate
• Monitor uptime + error rate endpoint → alert sớm trước khi bị suspend

Chi tiết pattern webhook production-grade đã có trong bài Webhook & API gửi tin nhắn Pancake chat — apply tương tự cho CRM webhook.

8. Phân biệt CRM tags vs Pancake chat tags

Cả 2 sản phẩm đều có khái niệm "tag" nhưng khác nhau hoàn toàn về scope và schema:

Không có cross-sync tự động giữa 2 hệ tag — vì 2 sản phẩm tách biệt về data. Nếu cần tag "Đặt hàng" xuất hiện ở cả Pancake chat và CRM, phải tự build sync layer (thường qua webhook → middleware).

9. Pitfalls thường gặp khi mới integrate

10. FAQ

Q: Pancake chat và Pancake CRM dùng chung api/token được không?

A: Không. Đây là 2 sản phẩm khác nhau trong hệ sinh thái Pancake, mỗi sản phẩm có hệ thống auth riêng: chat dùng page_access_token (per-page), CRM dùng api_key (per-workspace). Phải lấy 2 token riêng nếu cần integrate cả 2 sản phẩm.

Q: Phải mua subscription riêng cho CRM không?

A: Có. Pancake CRM cần mua gói cước riêng, không nằm trong gói Pancake chat hay các sản phẩm khác trong hệ sinh thái. Liên hệ Pancake support để được tư vấn gói phù hợp với quy mô team + nhu cầu trước khi build integration.

Q: Pancake CRM có hỗ trợ migration từ HubSpot/Salesforce không?

A: Hiện tại Pancake CRM không có connector chính thức cho HubSpot/Salesforce. Bạn cần tự build (export CSV từ HubSpot/Salesforce → format chuẩn Pancake → POST Records upsert qua API). Bài sau về Records sẽ có pattern bulk import chi tiết.

Q: Rate limit của Pancake CRM API là bao nhiêu?

A: Tài liệu chính thức hiện không nêu con số cụ thể. Khuyến nghị throttle conservative: 5-10 req/giây/workspace, exponential backoff khi gặp 429. Test với volume thực tế trước khi production.

Q: Webhook có HMAC signature verification không?

A: Tài liệu webhook hiện tại không document cơ chế signature. Khuyến nghị tạm thời: dùng secret token trong URL path (vd: /webhook/pancake/<random_secret>) và verify path trước khi process. Liên hệ Pancake support nếu cần HMAC chính thức.

Q: Có sandbox / test environment riêng không?

A: Không có sandbox riêng. Best practice: tạo workspace test riêng với data giả, lấy api_key riêng cho test, switch sang production workspace khi go-live.

Q: Custom fields có support không (field tự định nghĩa cho lead/contact)?

A: Có, Pancake CRM hỗ trợ custom fields cấu hình trong dashboard. Khi gọi API Records, custom fields xuất hiện trong response như field bình thường. Bài Records CRUD sẽ cover schema chi tiết.

11. Tổng kết

• Pancake CRM là 1 sản phẩm trong hệ sinh thái Pancake, chức năng khác hoàn toàn với Pancake chat — auth riêng (api_key vs page_access_token), base URL riêng (crm.pancake.vn vs pages.fm).
• Workspace là đơn vị isolation — workspace_id là path param bắt buộc trong mọi endpoint.
• api_key truyền query param — cẩn thận log leak; rotation định kỳ; 1 api_key cho 1 integration.
• 6 nhóm endpoint: Records (lead/account/contact), Orders, Tickets, Sources, Tags, Webhook.
• Webhook event record + suspend policy nghiêm (80% error / 300 fails trong 30 min).
• Pattern webhook production-grade: trả 200 nhanh, async queue, idempotent — giống webhook Pancake chat.

Bài tiếp theo trong cluster sẽ đi sâu vào Records CRUD (lead/account/contact) — endpoint dùng nhiều nhất.

Bài viết liên quan

Cluster Pancake CRM (mới)

• Bài này — Giới thiệu Pancake CRM API (pillar)
• Roadmap: Records CRUD, Orders, Tickets, Webhook setup, Pancake chat ↔ CRM integration tutorial

Cluster Pancake chat (đã có)

• Giới thiệu Pancake — Nền tảng quản lý chat đa kênh — sản phẩm Page tổng quan
• Hướng dẫn kết nối Webhook & API gửi tin nhắn trên Pancake — base về Page Access Token + webhook
• Lấy danh sách hội thoại Pancake API
• Page Customers API — Đồng bộ khách hàng vào CRM
• 3 phương án truy xuất data Pancake
• Quản lý hội thoại Pancake API — Tag, Assign, Mark Read/Unread

Tài liệu chính thức

• Pancake CRM Developer Docs — OpenAPI spec đầy đủ
• Pancake chat Developer Docs — cluster chat

Last updated: 2026-06-17. Phiên bản API: Pancake CRM 2.0.0. Tham khảo OpenAPI spec để verify mọi thay đổi.