Developer API

Kết nối ứng dụng với Co-Space Core

Gateway phiên bản 1 là ranh giới tích hợp cho Lucy, hệ thống Business và các tool nội bộ. Ứng dụng gọi API qua HTTPS; không kết nối trực tiếp tới database Core.

Credential riêng từng app

Secret được băm khi lưu, chỉ trả về một lần lúc tạo hoặc rotate. Có thể thu hồi độc lập từng ứng dụng.

Quyền tối thiểu theo scope

Mỗi credential chỉ gọi được operation được cấp. Credential Business được ràng buộc với tài khoản và dữ liệu sở hữu.

State có kiểm soát

Ghi state cần xác nhận trạng thái hiện tại; conflict trả HTTP 409 thay vì ghi đè âm thầm.

Base URL và xác thực

Base URL

https://<cospace-host>/api/v1/integrations/v1

Request header

Authorization: Bearer csp_<key-id>.<secret>

Không ghi credential vào source control, frontend bundle hoặc log. HTTPS là bắt buộc ngoài môi trường loopback local. Response được đánh dấu no-store.

Scopes Business

Business quản lý key trong khu vực Business. API giới hạn truy cập Opportunity/Temporal State vào tài sản do Business sở hữu.

  • core:ghost-zone:read

    Đọc nguồn cung tương lai từ Ghost Zone.

  • core:opportunities:read

    Đọc Opportunity gắn với Property thuộc Business.

  • core:temporal-states:read

    Đọc trạng thái và lịch sử state của tài sản Business.

  • core:temporal-states:write

    Ghi state transition cho tài sản Business hiện có.

Mở Business API Console

Scopes tool nội bộ

Credential nội bộ được Super Admin cấp riêng cho từng stack. Chỉ cấp quyền dữ liệu rộng khi thực sự cần.

  • core:health:read

    Kiểm tra khả dụng của Core API.

  • core:capabilities:read

    Khám phá capability mà credential được cấp.

  • core:ghost-zone:read

    Đọc nguồn cung tương lai từ Ghost Zone.

  • core:opportunities:read

    Đọc Opportunity gắn với Property thuộc Business.

  • core:temporal-states:read

    Đọc trạng thái và lịch sử state của tài sản Business.

  • core:temporal-states:write

    Ghi state transition cho tài sản Business hiện có.

Endpoint hiện có

MethodPathScope
GET/healthcore:health:read
GET/capabilitiescore:capabilities:read
GET/ghost-zone/opportunitiescore:ghost-zone:read
GET/opportunitiescore:opportunities:read
GET/opportunities/{opportunity_id}core:opportunities:read
GET/temporal-states/{entity_type}/{entity_id}core:temporal-states:read
GET/temporal-states/{entity_type}/{entity_id}/historycore:temporal-states:read
POST/temporal-states/transitionscore:temporal-states:write

Ghi Temporal State và xử lý xung đột

POST transition phải kèm `expected_current_state` (dùng `null` nếu entity chưa có current state), `to_state` và `effective_at` có timezone. Mỗi event được lưu lịch sử; nếu nhận HTTP 409, đọc state/history mới nhất rồi quyết định gửi lại. Confidence `VERIFIED` chỉ dành cho quy trình xác minh đáng tin cậy, không cấp cho Business self-service.

{
  "entity_type": "property",
  "entity_id": 123,
  "expected_current_state": "NOTICE_GIVEN",
  "to_state": "VACATING",
  "effective_at": "2026-10-07T10:00:00+00:00",
  "expected_at": "2026-11-01T10:00:00+00:00",
  "confidence": "LIKELY"
}