REST API

Setiap tindakan di antarmuka Celerp adalah endpoint REST - API yang sama yang digunakan UI secara internal. Otomatiskan alur kerja, hubungkan sistem lain, atau bangun alat Anda sendiri. API berjalan secara lokal dengan data Anda; tidak ada yang dikirim ke cloud.

Autentikasi

Celerp menggunakan JSON Web Token berumur pendek. Masuk dengan email dan kata sandi Celerp Anda untuk mendapatkan access token, lalu kirimkan sebagai header Bearer pada setiap permintaan.

1. Masuk

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

Respons berisi dua token:

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

2. Panggil API dengan token

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

• Token mengidentifikasi pengguna, peran, dan perusahaan Anda, sehingga permintaan secara otomatis dibatasi ke perusahaan tersebut - tidak perlu header tambahan.
• Access token berlaku hingga 24 jam. Saat kedaluwarsa, dapatkan pasangan baru dengan melakukan POST refresh_token ke /auth/token/refresh.
• Tergabung di lebih dari satu perusahaan? Tampilkan daftarnya dengan GET /auth/my-companies, lalu ambil token untuk perusahaan lain dengan POST /auth/switch-company/{company_id}.

Membuat permintaan

Semua endpoint berada di bawah alamat server API Anda (http://localhost:8000 pada instalasi pip, seperti pada contoh di bawah) dan mengembalikan JSON. Endpoint daftar mengembalikan array items dan jumlah 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
}

Paginasi: kirim ?limit= (default 50) dan ?offset=. Sebagian besar endpoint daftar juga menerima kata kunci pencarian q= dan filter kolom (mis. ?status=available).

Membuat data

Kirim POST berisi JSON untuk membuat data. Operasi tulis mengembalikan id entitas baru (dan event_id yang mendasarinya - setiap perubahan di Celerp adalah sebuah event).

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"
  }'

Konvensi

• Kesalahan respons non-2xx mengembalikan {"detail": "..."} dengan kode status HTTP standar.
• Batas laju permintaan 60 permintaan/menit per IP secara default; login dibatasi 10/menit. Melebihi batas mengembalikan 429.
• Izin endpoint dikontrol oleh peran Anda: viewer → operator → manager → admin → owner.
• Cakupan perusahaan setiap permintaan bertindak pada perusahaan dalam token Anda; ganti perusahaan untuk bertindak pada yang lain.

Endpoint umum

Sebagian kecil untuk memulai. Setiap modul menambahkan miliknya sendiri - daftar lengkap ada di skema OpenAPI di bawah.

Referensi lengkap per area

Setiap endpoint yang disediakan API yang sedang berjalan, dikelompokkan per area. Setiap halaman mencantumkan method, path, parameter, bentuk request dan response, serta contoh pemanggilan.

Jelajahi API lengkap

Referensi lengkap dan selalu terkini adalah skema OpenAPI 3.1 yang dihasilkan oleh instance Anda sendiri:

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

Muat ke alat OpenAPI apa pun - Postman, Insomnia, Swagger UI, atau generator client - untuk menelusuri setiap endpoint dan model, mencoba permintaan, dan menghasilkan client bertipe dalam bahasa Anda. Celerp memberikan skemanya sendiri, bukan halaman dokumentasi yang dihosting, sehingga cakupan API Anda tetap privat di instance Anda.