Lịch sử tương tác

Tổng quan

Open API đọc và ghi ghi chú nội bộ trên dòng thời gian của khách — VD ghi chú của nhân viên kho, lịch sử chăm sóc từ hệ thống khác.

Method + path	Scope	Dùng để
GET /interactions	customers_detail	Liệt kê ghi chú để đồng bộ (keyset)
POST /customers/:id/interactions	customers_update	Thêm ghi chú vào hồ sơ một khách

Đối tượng ghi chú

{
  "id": 48213,
  "customerId": "1f0c6a7e-5d1b-4a8e-9a63-2c1f0f6b9d10",
  "externalId": "erp-note-9912",
  "content": "<p>Khách hẹn lấy hàng thứ 6.</p>",
  "authorName": "Kho Hà Nội",
  "source": "api:ERP Kho",
  "createdAt": "2026-10-08T03:12:45.123Z",
  "updatedAt": "2026-10-08T03:12:45.123Z"
}

content là HTML. source = ui với ghi chú nhân viên tạo trên giao diện, api:<tên key> với ghi chú tạo qua Open API.

---

Liệt kê ghi chú

GET /api/open/v1/interactions?updatedSince=2026-10-01T00:00:00Z&updatedUntil=2026-10-08T00:00:00Z&limit=50&excludeSource=api:ERP%20Kho

Trả { "data": [ghi chú…], "nextCursor": "…" | null, "window": {…} } (tối đa 50 / lần, cửa sổ tối đa 30 ngày), chỉ gồm ghi chú của những khách mà người tạo key được thấy. Tham số: xem Phân trang keyset.

---

Thêm ghi chú

POST /api/open/v1/customers/1f0c6a7e-5d1b-4a8e-9a63-2c1f0f6b9d10/interactions

{
  "externalId": "erp-note-9912",
  "content": "Khách hẹn lấy hàng thứ 6.\nĐã gọi xác nhận.",
  "authorName": "Kho Hà Nội"
}

Trường	Kiểu	Ghi chú
externalId	chuỗi ≤ 100, bắt buộc	Id ghi chú bên hệ thống của bạn — khoá chống trùng
content	chuỗi ≤ 10.000, bắt buộc	Văn bản thuần; mỗi dòng thành một đoạn, ký tự HTML được mã hoá an toàn
authorName	chuỗi ≤ 255	Tên người viết hiển thị trên dòng thời gian

Trả { "data": ghi chú, "created": true } với 201.

Gửi lại an toàn

Gửi lại cùng externalId cho cùng khách ⇒ trả về ghi chú đã có (200, "created": false), không tạo trùng. Cứ retry thoải mái khi mạng lỗi.