Partner API Reference

Danh sách các API endpoints dành cho partner web systems tích hợp với Sense Sphere. Các endpoints này cho phép partner query thông tin user, system branding và bot details.

Authentication

Partner APIs sử dụng Partner Auth Token được cấp qua OAuth flow. Gửi token qua query parameter:

GET /api/partner/user-info/?token={partner_token}&user_uuid={user_uuid}

Token có hiệu lực trong khoảng thời gian cấu hình (PARTNER_AUTH_TOKEN_EXPIRY_DAYS). Old tokens tự động bị revoke khi tạo token mới (rotation policy).

Xem chi tiết cơ chế auth tại: OAuth Integration.

---

User Info

GET /api/partner/user-info/?token=xxx&user_uuid=<uuid>

Trả về thông tin profile của user cho partner systems. Yêu cầu xác thực qua PartnerAuthToken.

Query Parameters

Response (200 OK)

{
  "user": {
    "id": 42,
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "username": "john.doe",
    "first_name": "John",
    "last_name": "Doe",
    "full_name": "John Doe",
    "email": "[email protected]",
    "avatar": "https://sensesphere.ai/media/avatars/user42.jpg"
  }
}

Error Responses

Implementation Notes

• Avatar URL được convert thành absolute URL qua request.build_absolute_uri()
• Nếu user không có avatar, field avatar sẽ là null
• Token expiry check: partner_token.expires_at < now() → return 401

---

System Info

GET /api/partner/system-info/

Trả về thông tin cơ bản của hệ thống Sense Sphere để partner hiển thị lên trang web của họ. Public endpoint — không yêu cầu xác thực.

Response (200 OK)

{
  "name": "Sense Sphere",
  "url": "https://sensesphere.ai",
  "logo": "https://sensesphere.ai/static/img/sensesphere-logo.png",
  "favicon": "https://sensesphere.ai/static/img/sensesphere-icon.png",
  "support_email": "[email protected]",
  "description": "AI Agent Platform"
}

Usage Example

Partner có thể dùng thông tin này để:

• Hiển thị logo Sense Sphere trên trang tích hợp
• Set favicon cho iframe embed
• Hiển thị link support email cho user
• Show platform name và description trong UI

---

Bot Info

GET /api/partner/bot/<uuid:bot_uuid>/

Trả về thông tin cơ bản của bot qua UUID. Public endpoint — không yêu cầu xác thực.

URL Parameters

Response (200 OK)

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Customer Support Bot",
  "avatar": "https://sensesphere.ai/media/bots/avatar_42.png",
  "description": "Bot hỗ trợ khách hàng 24/7 cho dự án XYZ",
  "is_active": true
}

Error Responses

Avatar URL Handling

• Nếu avatar là URL (http/https/data:) → trả về nguyên bản
• Nếu avatar là local path → convert thành absolute URL qua request.build_absolute_uri()

---

Integration Example

Full OAuth + API Flow

// 1. Redirect user to Sense Sphere OAuth
const oauthUrl = new URL('https://sensesphere.ai/auth/sensesphere-auth/');
oauthUrl.searchParams.set('partner_key', 'my-partner-key');
oauthUrl.searchParams.set('redirect_uri', encodeURIComponent('https://myapp.com/auth/callback'));
window.location.href = oauthUrl.toString();

// 2. Partner callback receives token
// GET https://myapp.com/auth/callback?token=xxx&user_id=yyy&created=false

const partnerToken = new URLSearchParams(window.location.search).get('token');
const userUuid = new URLSearchParams(window.location.search).get('user_id');

// 3. Fetch user info
const userInfo = await fetch(
  `https://sensesphere.ai/api/partner/user-info/?token=${partnerToken}&user_uuid=${userUuid}`
).then(r => r.json());

console.log(userInfo.user.full_name); // "John Doe"

// 4. Fetch bot info (public, no auth needed)
const botInfo = await fetch(
  'https://sensesphere.ai/api/partner/bot/550e8400-e29b-41d4-a716-446655440000/'
).then(r => r.json());

console.log(botInfo.name); // "Customer Support Bot"

Embed Chatbot in Partner Website

<!-- Load system info for branding -->
<script>
fetch('https://sensesphere.ai/api/partner/system-info/')
  .then(r => r.json())
  .then(data => {
    document.title = `Chat with ${data.name}`;
    // Set favicon
    const link = document.querySelector("link[rel~='icon']") || document.createElement('link');
    link.type = 'image/x-icon';
    link.rel = 'icon';
    link.href = data.favicon;
    document.head.appendChild(link);
  });
</script>

<!-- Embed chatbot iframe -->
<iframe 
  src="https://sensesphere.ai/chatbot/{bot_uuid}/" 
  width="375" 
  height="600"
  style="border:none;border-radius:12px;">
</iframe>

---

Rate Limiting

Các partner API endpoints không có explicit rate limit decorator, nhưng chịu chung rate limiting của Django middleware và server infrastructure.

OAuth callback endpoints có rate limit riêng:

• /auth/sensesphere-auth/callback/: 10/m per IP
• /login/: 5/m per IP

---

Error Handling Best Practices

1. Always check HTTP status codes — 401 cho auth errors, 404 cho not found
2. Handle expired tokens gracefully — redirect user quay lại OAuth flow để refresh token
3. Cache system-info — endpoint này không đổi thường xuyên, có thể cache lâu dài
4. Validate bot_uuid format — UUID validation trước khi gọi API

---

Trang liên quan

• OAuth Integration — Hướng dẫn tích hợp OAuth