API v2 & Webhook
Hai cách lấy dữ liệu từ CRM sang hệ thống của bạn (báo cáo, AI…):
- Webhook: CRM tự đẩy dữ liệu sang URL của bạn ngay khi có khách hàng mới, cập nhật, ghi chú mới, lịch hẹn, cuộc gọi kết thúc.
- API: hệ thống của bạn chủ động lấy dữ liệu theo ngày (khách hàng, lịch hẹn, cuộc gọi).
Tên trường bằng tiếng Anh, giá trị đã đổi sang chữ (ví dụ "status": "Đã chốt" thay vì id). Admin đổi tên hoặc tắt từng trường trong Cài đặt → API & Webhook.
1. Xác thực
Gửi token API v2 trong header (không gửi trên URL):
Authorization: Bearer <TOKEN_API_V2>
# hoặc
X-API-Key: <TOKEN_API_V2>
Admin tạo token trong Cài đặt → API & Webhook. Token chỉ hiện một lần lúc tạo; tạo token mới thì token cũ hết hiệu lực ngay.
2. Giới hạn
Để không làm chậm CRM, mỗi CRM có giới hạn sau (FasterCRM cấu hình theo gói dịch vụ):
| Số lần gọi API / ngày | 300 lần (tính lại từ 00:00) |
| Số lần gọi / phút | 20 lần |
| Số dòng tối đa / lần gọi | 100 dòng (dùng page để lấy tiếp) |
| Khoảng ngày tối đa / lần gọi | 31 ngày |
| Số khách tối đa / lần import | 200 khách |
Mỗi kết quả có quota.remaining (số lượt còn lại hôm nay) và header X-RateLimit-Remaining. Hết lượt: HTTP 429 kèm Retry-After (giây).
3. API lấy dữ liệu
| Đường dẫn | Dữ liệu | date_field (lọc theo ngày nào) |
|---|---|---|
GEThttps://demov4.fastercrm.com/api/v2/customers | Khách hàng | created_at (khách mới, mặc định), updated_at (khách có cập nhật), generated_at (Ngày phát sinh — nhân viên sửa được) |
GEThttps://demov4.fastercrm.com/api/v2/appointments | Lịch hẹn | created_at (mặc định), updated_at, start_at (giờ hẹn) |
GEThttps://demov4.fastercrm.com/api/v2/calls | Cuộc gọi (kèm link ghi âm) | created_at |
GEThttps://demov4.fastercrm.com/api/v2/fields | Danh sách trường đang xuất (không trừ lượt) | — |
Tham số
| Tham số | Ý nghĩa |
|---|---|
from | Từ ngày: YYYY-MM-DD hoặc YYYY-MM-DD HH:MM:SS. Bỏ trống = hôm nay 00:00. |
to | Đến ngày (cùng định dạng; chỉ ghi ngày thì tính đến 23:59:59). Bỏ trống = cuối ngày from, hoặc bây giờ nếu cũng bỏ trống from. |
date_field | Lọc theo ngày nào (bảng trên). |
order | Sắp xếp theo ngày đang lọc: asc (cũ → mới, mặc định) hoặc desc (mới → cũ). |
page | Trang, bắt đầu từ 1. Còn dữ liệu thì meta.has_more = true và meta.next_page là trang tiếp. |
limit | Số dòng / trang, tối đa 100. |
phone | (customers, calls) Lọc theo số điện thoại. |
customer_id | (appointments, calls) Lọc theo mã khách hàng. |
Ví dụ: khách hàng mới hôm nay
curl -H "Authorization: Bearer <TOKEN_API_V2>" \
"https://demov4.fastercrm.com/api/v2/customers?date_field=created_at&from=2026-11-09"
Ví dụ: cuộc gọi trong 7 ngày, trang 2
curl -H "Authorization: Bearer <TOKEN_API_V2>" \
"https://demov4.fastercrm.com/api/v2/calls?from=2026-11-03&to=2026-11-09&page=2"
Kết quả
{
"data": [
{ "id": 1024, "name": "Nguyễn Văn A", "phone": "0901234567", "status": "Đã chốt", "source": "Facebook", "created_at": "2026-11-09 09:15:00", ... }
],
"meta": { "page": 1, "limit": 100, "count": 1, "has_more": false, "next_page": null,
"date_field": "created_at", "from": "2026-11-09 00:00:00", "to": "2026-11-09 23:59:59" },
"quota": { "daily_limit": 300, "remaining": 299 }
}
Lỗi
| HTTP | error.code | Ý nghĩa |
|---|---|---|
| 401 | UNAUTHORIZED | Token sai hoặc đã đổi. |
| 403 | API_DISABLED | CRM chưa bật API. |
| 422 | INVALID_DATE, INVALID_RANGE, RANGE_TOO_LARGE, INVALID_DATE_FIELD, PAGE_TOO_DEEP | Tham số sai (vẫn trừ 1 lượt). |
| 429 | DAILY_LIMIT, RATE_LIMIT | Hết lượt trong ngày / gọi quá nhanh. |
4. Danh sách trường
Tên trường đang dùng ở CRM này (đã áp tên Admin đặt). Khách hàng chỉ gồm các cột đang bật trong Sắp xếp cột KH (Mã KH, Ngày tạo, Ngày cập nhật luôn có). Trường trống trả về null hoặc chuỗi rỗng.
Khách hàng
| Trường | Ý nghĩa |
|---|---|
id | Mã KH |
name | Tên KH |
phone | SĐT |
phone_2 | SDT2 |
gender | Giới tính (male / female / other) |
age | Tuổi |
address | Địa chỉ |
city | Tỉnh/TP |
branch | Chi nhánh |
customer_group | Nhóm KH |
status | Trạng thái KH |
services | Dịch vụ |
source | Nguồn |
campaign | Chiến dịch |
ad_content | Nội dung |
note | Ghi chú |
next_follow_up_at | TG CS tiếp theo |
booking_date | Ngày đặt lịch |
generated_at | Ngày phát sinh |
transferred_at | Ngày chuyển |
last_call_at | Ngày gọi mới nhất |
last_interaction_at | Ngày tương tác gần nhất |
created_by | Người tạo |
created_at | Ngày tạo |
updated_at | Ngày cập nhật |
staff_telesales | Nhân viên Telesales |
staff_tvol | Nhân viên TVOL |
ghi_chu_2 | Ghi chú 2 |
sinh_nhat | Sinh nhật |
link | Link |
text | text |
Lịch hẹn
| Trường | Ý nghĩa |
|---|---|
id | Mã lịch hẹn |
customer_id | Mã KH |
customer_name | Tên khách hàng |
customer_phone | SĐT khách hàng |
title | Tiêu đề |
description | Mô tả |
note | Ghi chú |
status | Trạng thái |
start_at | Bắt đầu |
end_at | Kết thúc |
branch | Chi nhánh |
service | Dịch vụ |
price | Giá |
deposit | Đặt cọc |
paid | Đã thanh toán |
debt | Còn nợ |
customer_source | Nguồn khách hàng |
created_by | Người tạo |
created_at | Ngày tạo |
updated_at | Ngày cập nhật |
Cuộc gọi
| Trường | Ý nghĩa |
|---|---|
id | Mã cuộc gọi |
customer_id | Mã KH |
customer_name | Tên khách hàng |
phone | Số điện thoại |
staff | Nhân viên |
extension | Máy nhánh |
direction | Chiều gọi (inbound / outbound / missed) |
start_at | Bắt đầu |
end_at | Kết thúc |
duration | Tổng thời gian (giây) |
talk_seconds | Thời gian đàm thoại (giây) |
recording_url | Link file ghi âm |
provider | Tổng đài |
disposition | Kết quả (tổng đài) |
note | Ghi chú |
created_at | Ngày ghi nhận |
5. Webhook
Admin nhập URL nhận dữ liệu (khách hàng, lịch hẹn, cuộc gọi) và chọn sự kiện trong Cài đặt → API & Webhook. CRM gửi POST JSON tới URL đó ngay trên server, không phụ thuộc trình duyệt của nhân viên.
event | Khi nào | URL |
|---|---|---|
customer.created | Khách hàng mới | Khách hàng |
customer.updated | Cập nhật thông tin khách hàng | Khách hàng |
customer.note_created | Ghi chú mới | Khách hàng |
appointment.created | Tạo lịch hẹn | Lịch hẹn |
appointment.updated | Cập nhật lịch hẹn | Lịch hẹn |
call.ended | Kết thúc cuộc gọi | Cuộc gọi |
call.recording_ready | Có file ghi âm (gửi sau khi tổng đài trả file) | Cuộc gọi |
Header
Content-Type: application/json; charset=utf-8
X-FasterCRM-Event: customer.updated
X-FasterCRM-Delivery: 6f1c2a9e-… (mã lần gửi, dùng để bỏ qua bản gửi trùng)
X-FasterCRM-Signature: sha256=<HMAC-SHA256(body, secret)>
X-API-Key: <secret>
Nội dung
{
"id": "6f1c2a9e-…",
"event": "customer.updated",
"created_at": "2026-11-09 10:20:00",
"data": { "id": 1024, "name": "Nguyễn Văn A", "phone": "0901234567", "status": "Đã chốt", ... },
"changes": { "status": { "old": "Mới", "new": "Đã chốt" } }
}
customer.created,appointment.created,call.ended,call.recording_ready:datalà toàn bộ trường (như API).customer.updated,appointment.updated: thêmchanges(trường nào đổi, giá trị cũ / mới). Thay đổi do hệ thống tự cập nhật (số lần gọi, ngày gọi gần nhất…) không gửi.customer.note_created:data.note(id,content,status,created_by,created_at) vàdata.customer.call.endedcórecording_urlnếu tổng đài đã trả file; tổng đài trả file sau thì CRM gửi thêmcall.recording_ready.
Trả lời và gửi lại
- Bên nhận trả HTTP 2xx trong vòng 6 giây là thành công. Nên lưu dữ liệu rồi trả lời ngay, xử lý sau.
- Lỗi hoặc quá giờ: CRM gửi lại sau 1, 5, 15, 60, 180 phút (tối đa 6 lần), cùng
id. Admin xem nhật ký và gửi lại bằng tay trong Cài đặt.
Kiểm tra chữ ký (PHP)
$body = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $body, 'SECRET_CUA_BAN');
if (!hash_equals($expected, $_SERVER['HTTP_X_FASTERCRM_SIGNATURE'] ?? '')) { http_response_code(401); exit; }
$event = json_decode($body, true);
// lưu $event['id'] để bỏ qua bản gửi trùng
http_response_code(200);
6. Import khách hàng (đưa dữ liệu vào CRM)
Dùng POST https://demov4.fastercrm.com/api/import_from_json — xem mục Import khách hàng. Khách mới được chia cho các phòng ban giống form thêm khách:
| Phòng ban | Tham số ghi nhân viên | Chia tự động |
|---|---|---|
| Telesales | depart_59 | Có |
| TVOL | depart_61 | Không |