Tài liệu API

Tham chiếu API đầy đủ cho NotiBoost. Bao gồm authentication, event ingestion, flow management, và webhooks.

Xác thực

Tất cả API requests yêu cầu authentication thông qua API key.

API Key

Sử dụng Bearer token trong Authorization header:

Authorization: Bearer YOUR_API_KEY

Event Ingestion

Gửi events từ hệ thống sản phẩm của bạn đến NotiBoost.

Endpoint

POST /api/v1/events

Request Body

{
  "event_name": "order_created",
  "event_id": "evt_001",
  "occurred_at": "2025-12-01T10:00:00Z",
  "user_id": "u_123",
  "properties": {
    "order_id": "A001",
    "amount": 350000,
    "currency": "VND"
  }
}

Response

{
  "success": true,
  "trace_id": "trc_abc123",
  "event_id": "evt_001",
  "message": "Event ingested successfully"
}

Event Fields

Tên trường	Kiểu	Bắt buộc	Mô tả
event_name	string	Yes	Tên của event (ví dụ: order_created, payment_success)
event_id	string	Yes	ID duy nhất cho event này
occurred_at	ISO 8601	Yes	Thời điểm event xảy ra (ISO 8601 format)
user_id	string	Yes	ID của user liên quan đến event
properties	object	No	Các thuộc tính bổ sung của event (tùy chọn)

Users API

Quản lý users trong NotiBoost. Users là recipients của notifications.

Tạo User

POST /api/v1/users

{
  "user_id": "u_123",
  "name": "Nguyễn Văn A",
  "email": "user@example.com",
  "phone": "+84901234567",
  "properties": {
    "segment": "vip",
    "preferred_channel": "zns"
  }
}

Lấy User

GET /api/v1/users/{user_id}

{
  "user_id": "u_123",
  "name": "Nguyễn Văn A",
  "email": "user@example.com",
  "phone": "+84901234567",
  "channel_data": {
    "email": "user@example.com",
    "phone": "+84901234567",
    "push_token": "fcm_token_abc123",
    "push_platform": "android",
    "zns_oa_id": "123456789"
  },
  "properties": {
    "segment": "vip",
    "preferred_channel": "zns"
  },
  "created_at": "2025-12-01T10:00:00Z",
  "updated_at": "2025-12-01T10:00:00Z"
}

Cập nhật User

PUT /api/v1/users/{user_id}

Xóa User

DELETE /api/v1/users/{user_id}

Quản lý Channel Data

Cập nhật channel data cho user. Hỗ trợ tất cả channels: ZNS, Email, SMS, và Push.

PUT /api/v1/users/{user_id}/channel_data

{
  "email": "user@example.com",
  "phone": "+84901234567",
  "push_token": "fcm_token_abc123",
  "push_platform": "android",
  "zns_oa_id": "123456789"
}

Các fields có sẵn:

email - Địa chỉ email cho Email channel
phone - Số điện thoại cho SMS và ZNS channels (định dạng: +84901234567)
push_token - Push notification token (FCM hoặc APNS token)
push_platform - Push platform: "android" hoặc "ios"
zns_oa_id - Zalo OA ID cho ZNS channel (tùy chọn, dùng để nhận diện user)

User Preferences

Quản lý notification preferences của user (channels và categories).

PUT /api/v1/users/{user_id}/preferences

{
  "channels": {
    "zns": { "enabled": true },
    "email": { "enabled": true },
    "sms": { "enabled": true },
    "push": { "enabled": true }
  },
  "categories": {
    "order": { "enabled": true },
    "marketing": { "enabled": false }
  }
}

Audiences API

Quản lý audiences (nhóm users) dựa trên filters. Audiences được dùng để target notifications.

Tạo Audience

POST /api/v1/audiences

{
  "name": "VIP Customers",
  "description": "Customers with high order value",
  "filter": {
    "properties.order_count": { "gte": 10 },
    "properties.total_spent": { "gte": 1000000 }
  }
}

Danh sách Audiences

GET /api/v1/audiences

Lấy Audience

GET /api/v1/audiences/{audience_id}

Cập nhật Audience

PUT /api/v1/audiences/{audience_id}

Xóa Audience

DELETE /api/v1/audiences/{audience_id}

Lấy Users trong Audience

GET /api/v1/audiences/{audience_id}/users

Lấy danh sách users thuộc audience này.

Flow Management

Tạo và quản lý notification flows.

Tạo Flow

POST /api/v1/flows

Ví dụ

{
  "name": "order_confirmation",
  "description": "Send order confirmation via ZNS",
  "rules": [
    {
      "condition": "event_name == 'order_created'",
      "action": "send_zns"
    }
  ],
  "channels": ["zns"],
  "template_id": "tpl_order_confirm"
}

Templates API

Quản lý message templates cho các channels.

Tạo Template

POST /api/v1/templates

{
  "name": "order_confirmation_zns",
  "channel": "zns",
  "content": {
    "header": "Xác nhận đơn hàng",
    "body": "Đơn hàng {{order_id}} đã được xác nhận. Tổng tiền: {{amount}} VNĐ",
    "footer": "Cảm ơn bạn đã mua sắm"
  },
  "variables": ["order_id", "amount"]
}

Danh sách Templates

GET /api/v1/templates?channel=zns

Lấy Template

GET /api/v1/templates/{template_id}

Cập nhật Template

PUT /api/v1/templates/{template_id}

Batch Operations

Gửi nhiều events hoặc tạo nhiều users cùng lúc để tối ưu performance.

Batch Events

POST /api/v1/events/batch

{
  "events": [
    {
      "event_name": "order_created",
      "event_id": "evt_001",
      "user_id": "u_123",
      "properties": { "order_id": "A001" }
    },
    {
      "event_name": "payment_success",
      "event_id": "evt_002",
      "user_id": "u_123",
      "properties": { "order_id": "A001" }
    }
  ]
}

Batch Users

POST /api/v1/users/batch

{
  "users": [
    {
      "user_id": "u_123",
      "name": "Nguyễn Văn A",
      "email": "user1@example.com",
      "phone": "+84901234567"
    },
    {
      "user_id": "u_124",
      "name": "Trần Thị B",
      "email": "user2@example.com",
      "phone": "+84901234568",
      "push_token": "fcm_token_xyz789",
      "push_platform": "ios"
    }
  ]
}

Lưu ý: Bạn có thể bao gồm channel data (email, phone, push_token, etc.) trong batch requests. Channel data cũng có thể được set riêng bằng channel_data endpoint.

Webhooks

Nhận thông báo về delivery status qua webhooks.

Setup Webhook

Cấu hình webhook endpoint để nhận notifications.

POST /api/v1/webhooks

{
  "url": "https://your-app.com/webhooks/notiboost",
  "events": ["message.sent", "message.delivered", "message.failed"],
  "secret": "your_webhook_secret"
}

Webhook Security

Verify webhook signatures để đảm bảo requests đến từ NotiBoost.

// Verify webhook signature
const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

Webhook Events

message.sent - Message đã được gửi
message.delivered - Message đã được giao thành công
message.failed - Message gửi thất bại
message.retried - Message đang được retry

Webhook Payload

{
  "event": "message.delivered",
  "trace_id": "trc_abc123",
  "message_id": "msg_xyz789",
  "channel": "zns",
  "delivered_at": "2025-12-01T10:00:05Z",
  "status": "success"
}

Xử lý Lỗi

NotiBoost API trả về standard HTTP status codes.

Error Codes

Code	Ý nghĩa
400	Bad Request - Request không hợp lệ
401	Unauthorized - API key không hợp lệ
404	Not Found - Resource không tồn tại
429	Too Many Requests - Vượt quá rate limit
500	Internal Server Error - Lỗi server

Rate Limits

API có rate limits để đảm bảo stability:

1000 requests per minute per API key
Burst limit: 100 requests per second
Vượt quá rate limit sẽ trả về 429 status code

Rate Limit Headers

Response headers chứa thông tin về rate limits:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1640995200

Pagination

Các API list endpoints hỗ trợ pagination.

Query Parameters

GET /api/v1/users?page=1&per_page=50

Response Format

{
  "data": [...],
  "pagination": {
    "page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3,
    "has_next": true,
    "has_prev": false
  }
}

Idempotency

Sử dụng Idempotency-Key header để đảm bảo requests không bị duplicate.

POST /api/v1/events
Idempotency-Key: unique-key-12345

NotiBoost sẽ trả về kết quả tương tự nếu cùng một idempotency key được sử dụng trong 24 giờ.

Ví dụ

Các ví dụ code để tích hợp NotiBoost.

cURL Example

curl -X POST https://api.notiboost.com/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_name": "order_created",
    "event_id": "evt_001",
    "occurred_at": "2025-12-01T10:00:00Z",
    "user_id": "u_123",
    "properties": {
      "order_id": "A001",
      "amount": 350000
      }
  }'