1. Home
  2. Docs
  3. Hướng dẫn sử dụng FasterC...
  4. API
  5. API v2 & Webhook

API v2 & Webhook

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ày300 lần (tính lại từ 00:00)
Số lần gọi / phút20 lần
Số dòng tối đa / lần gọi100 dòng (dùng page để lấy tiếp)
Khoảng ngày tối đa / lần gọi31 ngày
Số khách tối đa / lần import200 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ẫnDữ liệudate_field (lọc theo ngày nào)
GEThttps://demov4.fastercrm.com/api/v2/customersKhách hàngcreated_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/appointmentsLịch hẹncreated_at (mặc định), updated_at, start_at (giờ hẹn)
GEThttps://demov4.fastercrm.com/api/v2/callsCuộc gọi (kèm link ghi âm)created_at
GEThttps://demov4.fastercrm.com/api/v2/fieldsDanh sách trường đang xuất (không trừ lượt)—

Tham số

Tham sốÝ nghĩa
fromTừ 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_fieldLọc theo ngày nào (bảng trên).
orderSắp xếp theo ngày đang lọc: asc (cũ → mới, mặc định) hoặc desc (mới → cũ).
pageTrang, bắt đầu từ 1. Còn dữ liệu thì meta.has_more = true và meta.next_page là trang tiếp.
limitSố 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

HTTPerror.codeÝ nghĩa
401UNAUTHORIZEDToken sai hoặc đã đổi.
403API_DISABLEDCRM chưa bật API.
422INVALID_DATE, INVALID_RANGE, RANGE_TOO_LARGE, INVALID_DATE_FIELD, PAGE_TOO_DEEPTham số sai (vẫn trừ 1 lượt).
429DAILY_LIMIT, RATE_LIMITHế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
idMã KH
nameTên KH
phoneSĐT
phone_2SDT2
genderGiới tính (male / female / other)
ageTuổi
addressĐịa chỉ
cityTỉnh/TP
branchChi nhánh
customer_groupNhóm KH
statusTrạng thái KH
servicesDịch vụ
sourceNguồn
campaignChiến dịch
ad_contentNội dung
noteGhi chú
next_follow_up_atTG CS tiếp theo
booking_dateNgày đặt lịch
generated_atNgày phát sinh
transferred_atNgày chuyển
last_call_atNgày gọi mới nhất
last_interaction_atNgày tương tác gần nhất
created_byNgười tạo
created_atNgày tạo
updated_atNgày cập nhật
staff_telesalesNhân viên Telesales
staff_tvolNhân viên TVOL
ghi_chu_2Ghi chú 2
sinh_nhatSinh nhật
linkLink
texttext

Lịch hẹn

TrườngÝ nghĩa
idMã lịch hẹn
customer_idMã KH
customer_nameTên khách hàng
customer_phoneSĐT khách hàng
titleTiêu đề
descriptionMô tả
noteGhi chú
statusTrạng thái
start_atBắt đầu
end_atKết thúc
branchChi nhánh
serviceDịch vụ
priceGiá
depositĐặt cọc
paidĐã thanh toán
debtCòn nợ
customer_sourceNguồn khách hàng
created_byNgười tạo
created_atNgày tạo
updated_atNgày cập nhật

Cuộc gọi

TrườngÝ nghĩa
idMã cuộc gọi
customer_idMã KH
customer_nameTên khách hàng
phoneSố điện thoại
staffNhân viên
extensionMáy nhánh
directionChiều gọi (inbound / outbound / missed)
start_atBắt đầu
end_atKết thúc
durationTổng thời gian (giây)
talk_secondsThời gian đàm thoại (giây)
recording_urlLink file ghi âm
providerTổng đài
dispositionKết quả (tổng đài)
noteGhi chú
created_atNgà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.

eventKhi nàoURL
customer.createdKhách hàng mớiKhách hàng
customer.updatedCập nhật thông tin khách hàngKhách hàng
customer.note_createdGhi chú mớiKhách hàng
appointment.createdTạo lịch hẹnLịch hẹn
appointment.updatedCập nhật lịch hẹnLịch hẹn
call.endedKết thúc cuộc gọiCuộc gọi
call.recording_readyCó 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: data là toàn bộ trường (như API).
  • customer.updated, appointment.updated: thêm changes (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.ended có recording_url nếu tổng đài đã trả file; tổng đài trả file sau thì CRM gửi thêm call.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 banTham số ghi nhân viênChia tự động
Telesalesdepart_59Có
TVOLdepart_61Không