Tài liệu API

Mọi thứ bạn cần để tích hợp công cụ suy luận thời gian thực của Pulse vào nền tảng thương mại điện tử.

Bắt đầu nhanh

Thêm Pulse vào trang web của bạn trong 3 bước

Xác thực

Tìm hiểu cách xác thực các yêu cầu API của bạn

API Cá nhân hóa

Sắp xếp lại cửa hàng của bạn theo thời gian thực

Đồng bộ Danh mục

Đồng bộ sản phẩm & danh mục theo thời gian thực

URL cơ sở

https://thepulseapi.com/v1

Cách hoạt động

Pulse cá nhân hóa cửa hàng của bạn qua ba bước: thu thập tín hiệu ẩn danh trong phiên, cho chúng tôi biết bạn bán gì, rồi hỏi chúng tôi cách sắp xếp sản phẩm cho khách đang truy cập. SDK trình duyệt xử lý bước đầu; backend của bạn xử lý hai bước còn lại qua một REST API đơn giản.

1. Thu thập tín hiệu

Chèn SDK vào. Nó lặng lẽ truyền hành vi ẩn danh đến Pulse ở chế độ nền. Không cookie, không gì riêng tư.

2. Đồng bộ danh mục

Đẩy sản phẩm và danh mục của bạn để Pulse biết những gì có thể đề xuất và xếp hạng.

3. Lấy dữ liệu cá nhân hóa

Gọi API Cá nhân hóa để sắp xếp lại lưới sản phẩm và kết quả tìm kiếm cho khách đang truy cập.

Bắt đầu nhanh

Thêm Pulse vào trang web của bạn trong ba bước. SDK tải ngầm nên không bao giờ làm chậm trang, và chỉ đọc tín hiệu ẩn danh trong phiên. Không cookie, không lưu gì riêng tư.

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ị.

index.html

<!-- 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.

index.html

<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.

product-list.html

<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>

Vậy là xong, bạn đã hoạt động: SDK truyền các tín hiệu ẩn danh (thiết bị, nguồn giới thiệu, cuộn trang, nhấp chuột) đến POST /v1/track và Pulse suy luận persona của khách truy cập trong dưới 50ms. Gọi Inference API bên dưới từ backend của bạn để cá nhân hóa tìm kiếm, đề xuất và bố cục.

Xác thực

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.

# Example request with authentication

curl -X GET "https://thepulseapi.com/v1/infer" \

-H "Authorization: Bearer YOUR_API_KEY"

Lưu ý bảo mật: Không bao giờ để lộ khóa API bí mật của bạn trong mã phía client. Mọi yêu cầu suy luận và danh mục nên được thực hiện từ máy chủ backend của bạn. SDK trình duyệt sử dụng khóa công khai (pk_live_…) chỉ giới hạn cho việc thu thập sự kiện.

API Suy luận

POST/v1/infer

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.

Độ trễ mục tiêu: <50ms (p95)

Nội dung yêu cầu

request.json

{
  "session_id": "sess_abc123",
  "context": {
    "device": "mobile",
    "browser": "safari",
    "referrer": "instagram.com",
    "geo": { "country": "US", "region": "CA" },
    "time": "2025-01-14T23:30:00Z"
  },
  "behavior": {
    "search_query": "running shoes under 100",
    "filters": ["price:0-100", "rating:4+"],
    "viewed_products": ["prod_123", "prod_456"],
    "dwell_time_ms": 45000
  }
}

Phản hồi

200 OK

{
  "persona": {
    "primary": "value_conscious_runner",
    "confidence": 0.89,
    "attributes": {
      "price_sensitivity": "high",
      "brand_loyalty": "low",
      "social_proof_reliance": "high",
      "purchase_intent": "active"
    }
  },
  "recommendations": {
    "product_ids": ["prod_789", "prod_012", "prod_345"],
    "rerank_scores": [0.94, 0.91, 0.87]
  },
  "metadata": {
    "inference_time_ms": 32,
    "model_version": "v2.3.1"
  }
}

Đồng bộ Danh mục — Sản phẩm & Danh mục

Đẩ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.

Việc làm giàu dữ liệu và gắn thẻ Digital Twin chạy bất đồng bộ trong pipeline thu thập — lệnh upsert trả về 202 Accepted ngay lập tức và webhook products.tagged được kích hoạt khi một sản phẩm sẵn sàng cho suy luận. Bản thân quá trình suy luận vẫn diễn ra theo thời gian thực (dưới 50ms).

POST/v1/products

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ô.

POST /v1/products

{
  "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
    }
  ]
}

POST/v1/categories

Đồ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.

POST /v1/categories

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

DELETE/v1/products/{id}

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.

Giữ đồng bộ: Hầu hết các nhà bán hàng kết nối các lệnh gọi này với sự kiện thay đổi sản phẩm/danh mục của cửa hàng (ví dụ: một webhook Shopify hoặc một save hook trong backend tùy chỉnh) để danh mục Pulse luôn phản ánh đúng những gì người mua nhìn thấy. Nên đồng bộ lại toàn bộ hằng đêm như một biện pháp dự phòng.

API Cá nhân hóa

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.

POST/v1/recommend

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ủ.

POST /v1/recommend

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

200 OK

{
  "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 }
}

POST/v1/search

Xếp hạng lại kết quả tìm kiếm theo ý định. Gửi truy vấn của người mua và Pulse sắp xếp các sản phẩm phù hợp theo persona được suy luận trong phiên này. Kết quả được phân trang bằng con trỏ (cursor).

POST /v1/search

{
  "session_id": "sess_abc123",
  "query": "running shoes under 100",
  "filters": ["price:0-100", "rating:4+"],
  "limit": 24
}

200 OK

{
  "results": [
    { "product_id": "prod_789", "score": 0.94 },
    { "product_id": "prod_012", "score": 0.91 }
  ],
  "pagination": {
    "cursor": "eyJpZCI6IjEyMyJ9",
    "has_more": true,
    "limit": 24
  }
}

Webhooks

Cấu hình webhooks để nhận thông báo thời gian thực cho các sự kiện như cập nhật persona, theo dõi chuyển đổi và cải tiến mô hình.

Sự kiện có sẵn

•session.converted — Chuyển đổi được ghi nhận cho Pulse
•products.tagged — Hoàn tất gắn thẻ sản phẩm
•model.updated — Mô hình suy luận được cải tiến

Lỗi

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.

400 Bad Request

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

Các mã trạng thái phổ biến

Mã	Ý nghĩa
400	Bad Request — payload không đúng định dạng hoặc thiếu trường bắt buộc.
401	Unauthorized — khóa API bị thiếu hoặc không hợp lệ.
403	Forbidden — khóa hợp lệ nhưng không được phép truy cập tài nguyên này.
404	Not Found — phiên, sản phẩm hoặc endpoint không tồn tại.
422	Unprocessable Entity — yêu cầu đúng định dạng nhưng không qua được kiểm tra hợp lệ.
429	Too Many Requests — bạn đã vượt quá giới hạn tần suất của gói.
500	Server Error — đã xảy ra lỗi từ phía chúng tôi; thử lại với backoff.

Giới hạn tần suất

Gói	API Suy luận	API Danh mục
Starter	100 req/sec	10 req/sec
Growth	500 req/sec	50 req/sec
Enterprise	Tùy chỉnh	Tùy chỉnh

SDK & Thư viện

JavaScript / Node.js

npm install @pulse-ai/sdk

Python

pip install pulse-ai

Ruby

gem install pulse-ai

Cần trợ giúp?

Đội ngũ kỹ sư giải pháp của chúng tôi sẵn sàng giúp bạn tích hợp Pulse thành công.

Nhận hỗ trợ tích hợp Liên hệ hỗ trợ