REST API

Mọi thao tác trong giao diện Celerp đều là một REST endpoint - đúng API mà giao diện dùng bên trong. Tự động hóa quy trình, kết nối hệ thống khác, hoặc tự xây công cụ của riêng bạn. API chạy cục bộ trên dữ liệu của bạn; không có gì được gửi lên đám mây.

Xác thực

Celerp sử dụng JSON Web Tokens có thời hạn ngắn. Đăng nhập bằng email và mật khẩu Celerp của bạn để nhận access token, sau đó gửi nó dưới dạng tiêu đề Bearer trong mỗi yêu cầu.

1. Đăng nhập

curl -X POST http://localhost:8000/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "[email protected]", "password": "your-password"}'

Phản hồi chứa hai token:

{
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJhbGciOiJI..."
}

2. Gọi API với token

curl http://localhost:8000/items \
  -H "Authorization: Bearer eyJhbGciOiJI..."

• Token xác định người dùng, vai trò và công ty của bạn, vì vậy các yêu cầu tự động được giới hạn trong công ty đó - không cần tiêu đề thêm.
• Access token có hiệu lực tối đa 24 giờ. Khi hết hạn, nhận cặp mới bằng cách POST refresh_token đến /auth/token/refresh.
• Thuộc nhiều hơn một công ty? Liệt kê chúng bằng GET /auth/my-companies, sau đó nhận token cho công ty khác bằng POST /auth/switch-company/{company_id}.

Thực hiện yêu cầu

Tất cả endpoint nằm dưới địa chỉ máy chủ API của bạn (http://localhost:8000 với bản cài bằng pip, như trong các ví dụ bên dưới) và trả về JSON. Endpoint danh sách trả về mảng items và số đếm total:

curl "http://localhost:8000/items?limit=20&offset=0" \
  -H "Authorization: Bearer $TOKEN"

{
  "items": [
    { "id": "item:...", "sku": "WIDGET-001", "name": "Widget", "quantity": 42 }
  ],
  "total": 142
}

Phân trang: truyền ?limit= (mặc định 50) và ?offset=. Hầu hết endpoint danh sách cũng chấp nhận từ khóa tìm kiếm q= và bộ lọc cột (ví dụ: ?status=available).

Tạo dữ liệu

POST JSON để tạo bản ghi. Thao tác ghi trả về id của thực thể mới (và event_id bên dưới - mọi thay đổi trong Celerp đều là một sự kiện).

curl -X POST http://localhost:8000/crm/contacts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "email": "[email protected]",
    "contact_type": "customer",
    "idempotency_key": "acme-2026-06-21"
  }'

Quy ước

• Lỗi phản hồi không phải 2xx trả về {"detail": "..."} kèm mã trạng thái HTTP chuẩn.
• Giới hạn tốc độ 60 yêu cầu/phút mỗi IP theo mặc định; đăng nhập bị giới hạn ở 10/phút. Vượt giới hạn trả về 429.
• Quyền hạn endpoint được kiểm soát bởi vai trò của bạn: viewer → operator → manager → admin → owner.
• Phạm vi công ty mọi yêu cầu đều tác động đến công ty trong token của bạn; chuyển công ty để tác động đến công ty khác.

Endpoints phổ biến

Một mẫu nhỏ để bắt đầu. Mỗi module thêm endpoint của riêng nó - danh sách đầy đủ trong lược đồ OpenAPI bên dưới.

Tài liệu tham chiếu đầy đủ theo từng khu vực

Mọi endpoint mà API đang chạy cung cấp, được nhóm theo khu vực. Mỗi trang liệt kê method, path, tham số, cấu trúc request và response, cùng một ví dụ gọi.

Khám phá toàn bộ API

Tài liệu tham chiếu đầy đủ và luôn cập nhật là lược đồ OpenAPI 3.1 do chính instance của bạn tạo ra:

GET http://localhost:8000/openapi.json

Nạp nó vào bất kỳ công cụ OpenAPI nào - Postman, Insomnia, Swagger UI hay một trình sinh client - để duyệt mọi endpoint và model, thử gửi yêu cầu và sinh client có kiểu trong ngôn ngữ của bạn. Celerp cung cấp thẳng lược đồ thay vì một trang tài liệu đặt trên máy chủ của chúng tôi, nên bề mặt API của bạn vẫn riêng tư trong instance của bạn.