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.
🔗 URL cơ sở
http://localhost:8000 khi cài bằng pip. Ứng dụng máy tính tự chọn cổng: xem celerp-data/api-port.
🔑 Xác thực
Bearer JWT từ /auth/login
📦 Định dạng
JSON vào, JSON ra
📖 Đặc tả
GET /openapi.json (OpenAPI 3.1)
Dùng cổng nào? Khi cài bằng pip install celerp, máy chủ API chạy trên localhost:8000 (thay đổi bằng --api-port) và cổng 8080 là giao diện web cho người dùng, không phải API. Ứng dụng máy tính chọn cổng trống mỗi lần khởi động và ghi cổng API vào tệp api-port trong thư mục celerp-data. Để cố định cổng, hãy đặt CELERP_API_PORT trước khi khởi chạ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ằngPOST /auth/switch-company/{company_id}.
Token mang theo quyền của bạn. Token viewer chỉ đọc được, không ghi được; dữ liệu chi phí cần vai trò manager trở lên. Xử lý token như mật khẩu - bất kỳ ai giữ token đều có thể hành động như bạn.
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"
}'
Idempotency: bao gồm idempotency_key trong bất kỳ thao tác ghi nào. Yêu cầu thử lại với cùng khóa sẽ không tạo bản ghi trùng lặp - an toàn cho mạng không ổn định và tác vụ hàng loạt.
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.
| Phương thức | Đường dẫn | Mô tả |
|---|---|---|
POST | /auth/login | Lấy access token (không cần xác thực) |
GET | /health | Trạng thái dịch vụ (không cần xác thực) |
GET | /items | Liệt kê mặt hàng tồn kho |
POST | /items | Tạo một mặt hàng |
GET | /docs | Liệt kê chứng từ (hóa đơn bán, PO, hóa đơn mua, …) |
POST | /docs | Tạo một tài liệu |
GET | /crm/contacts | Liệt kê khách hàng và nhà cung cấp |
POST | /crm/contacts | Tạo một danh bạ |
GET | /dashboard/kpis | KPI kinh doanh |
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.
Auth
API xác thực người dùng Celerp, đăng nhập, đăng xuất, khôi phục mật khẩu, chuyển đổi công ty và truy cập API. (16 endpoints)
Tiếng AnhCompanies
API cấu hình và quản trị công ty dành cho người dùng, vai trò, địa điểm, thuế, điều khoản thanh toán, bảng giá, mô-đun và tùy chọn công ty. (75 endpoints)
Tiếng AnhItems
API hàng tồn kho dành cho sản phẩm và mặt hàng tồn, số lượng, giá, vị trí, mã vạch, định giá, nhập khẩu, giữ hàng, chuyển kho, chuyển đổi và tình trạng tồn kho. (38 endpoints)
Tiếng AnhDocs
API tài liệu kinh doanh cho hóa đơn bán hàng, hóa đơn mua hàng, đơn mua hàng, báo giá, giấy báo có, chứng từ vận chuyển, thanh toán, thực hiện đơn hàng, xuất PDF và các thao tác trong vòng đời tài liệu. (56 endpoints)
Tiếng AnhLists
API danh sách tồn kho dành cho kiểm kê, chuyển kho, xóa sổ, bảng kê, quét mã, giữ hàng, ghi chú, xuất dữ liệu và các thao tác trong vòng đời danh sách. (41 endpoints)
Tiếng AnhAccounting
REST API kế toán của Celerp dành cho hệ thống tài khoản, bút toán nhật ký, sổ cái, đối chiếu ngân hàng, báo cáo tài chính, chuyển khoản và kiểm soát kỳ kế toán. (73 endpoints)
Tiếng AnhLedger
API sổ ghi sự kiện để đọc các sự kiện nghiệp vụ Celerp và tái tạo dữ liệu ứng dụng được suy ra từ sự kiện. (3 endpoints)
Tiếng AnhReports
API báo cáo ERP về tuổi nợ phải thu, phải trả, doanh số, mua hàng và hàng tồn kho sắp hết hạn. (5 endpoints)
Tiếng AnhManufacturing
API sản xuất cho lệnh sản xuất, công thức, trung tâm làm việc, quy trình, nhu cầu nguyên vật liệu, tính giá thành, lập lịch, xuất linh kiện và nhập kho thành phẩm. (32 endpoints)
Tiếng AnhLabels
API nhãn kho và mã vạch dành cho mẫu nhãn, nhãn từng mặt hàng, trang nhãn hàng loạt và PDF có thể in. (10 endpoints)
Tiếng AnhCrm
REST API CRM dành cho khách hàng, nhà cung cấp, liên hệ, địa chỉ, cá nhân, ghi chú, thẻ, tệp, nhập, xuất và quản lý liên hệ. (25 endpoints)
Tiếng AnhSubscriptions
API tài liệu định kỳ và đăng ký dành cho mẫu hóa đơn và đơn mua hàng, lập lịch, kích hoạt, tạm dừng, tiếp tục, hủy và tạo theo yêu cầu. (22 endpoints)
Tiếng AnhConnectors
API tích hợp để kết nối Celerp ERP với các nền tảng thương mại và kinh doanh bên ngoài, quản lý thông tin xác thực của trình kết nối và đồng bộ dữ liệu. (18 endpoints)
Tiếng AnhPayments
API tích hợp thanh toán để kết nối hệ thống xử lý thanh toán, kiểm tra khả năng thanh toán và xem trạng thái kết nối. (7 endpoints)
Tiếng AnhBackup
API sao lưu và khôi phục để xuất, nhập, liệt kê, tạo và khôi phục các bản sao lưu Celerp ERP. (8 endpoints)
Tiếng AnhNotifications
API thông báo người dùng để liệt kê thông báo và đánh dấu từng thông báo hoặc tất cả là đã đọc. (3 endpoints)
Tiếng AnhEvents
API sự kiện do máy chủ gửi (SSE) theo thời gian thực dành cho thông báo Celerp và các sự kiện trực tiếp trong ứng dụng. (1 endpoint)
Tiếng AnhSystem
Các điểm cuối kiểm tra tình trạng, mức sẵn sàng, khởi động lại và khôi phục cài đặt gốc của bản cài đặt Celerp ERP. (10 endpoints)
Tiếng AnhAdmin
Các điểm cuối chẩn đoán quản trị và trạng thái hệ thống để bảo trì bản cài đặt Celerp ERP. (2 endpoints)
Tiếng AnhAi
API AI của Celerp dành cho hội thoại với trợ lý ERP, trích xuất tài liệu, tác vụ hàng loạt, bộ nhớ, mức sử dụng và các thao tác nghiệp vụ được người dùng xác nhận. (26 endpoints)
Tiếng AnhAttachments
API tệp đính kèm hàng tồn kho để tải lên, tải xuống, gắn thẻ, xem trước và xóa tệp mặt hàng cùng hình ảnh sản phẩm. (12 endpoints)
Tiếng AnhDashboard
API bảng điều khiển cho các chỉ số hiệu suất ERP, hoạt động kinh doanh gần đây và lịch sử hoạt động có thể tìm kiếm. (3 endpoints)
Tiếng AnhPayments Public
Các điểm cuối thanh toán công khai dành cho liên kết thanh toán của khách hàng và xử lý lượt quay lại từ nhà cung cấp thanh toán. (2 endpoints)
Tiếng AnhReceived
API tài liệu đã nhận từ người dùng Celerp khác: liệt kê và xem xét tài liệu, ghi nhận một tài liệu thành bản nháp của riêng bạn, rồi cập nhật bản nháp đã ghi nhận theo bản sửa đổi mới nhất của người gửi. (5 endpoints)
Tiếng AnhSearch
API tìm kiếm toàn cục Celerp ERP để tìm các bản ghi được phép truy cập trong nhiều mô-đun chỉ bằng một truy vấn. (1 endpoint)
Tiếng AnhSettings
API cài đặt hệ thống và Celerp Connect để thiết lập tài khoản, xem trạng thái kết nối đám mây, thanh toán dịch vụ, sao lưu, trình kết nối và cấu hình đối tác. (18 endpoints)
Tiếng AnhShare
API chia sẻ tài liệu để tạo, xem, cập nhật và thu hồi các liên kết chia sẻ công khai của tài liệu và danh sách Celerp. (4 endpoints)
Tiếng AnhShare Public
Các điểm cuối công khai để chia sẻ và nhập tài liệu, xem tài liệu Celerp đã chia sẻ, tải xuống hoặc nhập các gói tài liệu có thể chuyển giao. (4 endpoints)
Tiếng AnhStars
API huy hiệu người ủng hộ và ghi nhận đóng góp cộng đồng Celerp để xác minh, hiển thị, từ chối tham gia và quản lý lời nhắc. (6 endpoints)
Tiếng AnhVerticals
API cấu hình ngành và lược đồ danh mục để thiết lập các trường và giá trị mặc định của Celerp ERP theo lĩnh vực kinh doanh. (5 endpoints)
Tiếng AnhCompany Backups
27 endpoints
Tiếng AnhCompany Peers
5 endpoints
Tiếng AnhFixed Assets
117 endpoints
Tiếng AnhHelp
3 endpoints
Tiếng AnhMigrations
39 endpoints
Tiếng AnhKhá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.
Muốn dùng ngôn ngữ tự nhiên? Trợ lý AI (Connect) gọi chính API này thay bạn - chỉ cần yêu cầu nó lấy báo cáo hay tạo chứng từ bằng ngôn ngữ tự nhiên. Và nhớ rằng: mọi thứ API làm được đều không cần quyền đặc biệt nào - đúng bằng những gì một người dùng đã đăng nhập có thể làm.