Tài liệu API

1. Thêm SDK

Chèn thẻ script này vào phần head của trang. Nó tải bất đồng bộ và không bao giờ chặn quá trình hiển thị.

<!-- Add to your site's <head> -->
<script src="https://cdn.thepulseapi.com/pulse-sdk.min.js" async></script>

2. Khởi tạo

Khởi tạo Pulse bằng merchant ID và khóa công khai (pk_live_…) của bạn. Việc thu thập tín hiệu tự động bắt đầu ngay lập tức.

<script>
  window.addEventListener('DOMContentLoaded', () => {
    Pulse.init({
      merchantId: 'your_merchant_id',
      apiKey: 'pk_live_xxx'
    });
  });
</script>

3. Gắn thẻ các phần tử chính (tùy chọn)

Thêm thuộc tính data-pulse-track vào các menu sắp xếp, bộ lọc và nút CTA để tự động ghi nhận các tương tác có ý định cao.

<select data-pulse-track="sort_preference">
  <option value="price_low_high">Price: Low to High</option>
  <option value="price_high_low">Price: High to Low</option>
</select>

Trước tiên bạn cần một tài khoản Pulse. Đăng ký để tạo tổ chức của bạn, sau đó tạo và quản lý các khóa API từ bảng điều khiển. Đăng ký để nhận khóa API →

Tất cả các yêu cầu API đều cần xác thực bằng khóa API. Đưa khóa của bạn vào header Authorization.

Nhận suy luận persona thời gian thực cho một phiên truy cập. Trả về các thuộc tính persona, điểm tin cậy và thứ hạng sản phẩm được đề xuất.

Đẩy sản phẩm và danh mục của bạn lên Pulse để công cụ biết những gì có thể cá nhân hóa. Gửi toàn bộ danh mục một lần, sau đó giữ đồng bộ bằng cách gửi từng thao tác tạo, cập nhật hoặc xóa ngay khi nó xảy ra trong cửa hàng của bạn.

Làm giàu dữ liệu và gắn thẻ Digital Twin chạy bất đồng bộ trong pipeline nạp dữ liệu, lệnh upsert trả về 202 Accepted ngay lập tức và webhook products.tagged kích hoạt khi sản phẩm sẵn sàng cho suy luận. Bản thân suy luận vẫn nằm trên đường request.

Tạo hoặc cập nhật sản phẩm. Lệnh này có tính bất biến (idempotent) theo id, gửi lại cùng một sản phẩm với các trường mới để cập nhật nó. Chấp nhận một sản phẩm hoặc một lô.

{
  "products": [
    {
      "id": "prod_123",
      "name": "Performance Running Shoe",
      "description": "Lightweight cushioned trainer for daily runs",
      "price": 129.99,
      "category_id": "cat_running_shoes",
      "image_url": "https://...",
      "in_stock": true
    }
  ]
}

Đồng bộ cây danh mục của bạn để Pulse hiểu mối quan hệ giữa các sản phẩm. Đặt parent_id để phản ánh cấu trúc phân cấp của cửa hàng. Được upsert giống như sản phẩm.

{
  "categories": [
    { "id": "cat_footwear", "name": "Footwear", "parent_id": null },
    { "id": "cat_running_shoes", "name": "Running Shoes", "parent_id": "cat_footwear" }
  ]
}

Xóa một sản phẩm khi nó bị xóa hoặc hết hàng vĩnh viễn. Nó sẽ ngừng xuất hiện trong các đề xuất ngay lập tức. Sử dụng cùng mẫu để xóa danh mục.

Khi SDK đã thu thập tín hiệu và danh mục của bạn đã được đồng bộ, hãy gọi các endpoint này để sắp xếp lại cửa hàng theo thời gian thực cho khách hiện tại. Gọi chúng từ backend của bạn bằng Bearer token, truyền session_id mà SDK đã tạo trong trình duyệt.

Trả về danh sách sản phẩm được xếp hạng và cá nhân hóa theo persona trực tiếp của khách, dùng cho lưới "Dành cho bạn", sản phẩm liên quan và các dải trên trang chủ.

{
  "session_id": "sess_abc123",
  "type": "for_you",
  "limit": 12
}

{
  "recommendations": {
    "product_ids": ["prod_789", "prod_012"],
    "rerank_scores": [0.94, 0.91]
  },
  "persona": {
    "primary": "value_conscious_runner",
    "confidence": 0.89
  },
  "metadata": { "inference_time_ms": 28 }
}

Pulse sử dụng các mã trạng thái HTTP tiêu chuẩn và trả về lỗi theo định dạng RFC 7807 Problem Details, vì vậy mỗi lỗi đều bao gồm một type mà máy đọc được và một detail mà người đọc được.

{
  "type": "https://thepulseapi.com/errors/validation",
  "title": "Validation Error",
  "status": 400,
  "detail": "session_id is required",
  "instance": "/v1/recommend"
}