REST API

Celerp の画面で行える操作は、すべて REST エンドポイントとして用意されています。UI が内部で使っているのと同じ API です。業務フローを自動化したり、他のシステムとつないだり、独自のツールを作ったりできます。API はお客様のデータとともにローカルで動き、クラウドには何も送信されません。

認証

Celerp は有効期限の短い JSON Web Token を使います。Celerp のメールアドレスとパスワードでログインしてアクセストークンを取得し、すべてのリクエストに Bearer ヘッダーとして付けて送信してください。

1. ログイン

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

レスポンスには 2つのトークンが含まれます。

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

2. トークンを使って API を呼び出す

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

• トークンにはユーザー、役割、会社の情報が含まれるため、リクエストは自動的にその会社の範囲に限定されます。追加のヘッダーは要りません。
• アクセストークンの有効期間は最長24時間です。期限が切れたら、refresh_token を /auth/token/refresh に POST して新しいトークンの組を取得してください。
• 複数の会社に所属している場合は、GET /auth/my-companies で一覧を取得し、POST /auth/switch-company/{company_id} で別の会社に紐づくトークンを取得できます。

リクエストを送る

すべてのエンドポイントは API サーバーのアドレス（pip でインストールした場合は http://localhost:8000。以下の例もこのアドレスを使います）以下にあり、JSON を返します。一覧系のエンドポイントは items 配列と件数 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
}

ページ送り: ?limit=（既定値50）と ?offset= を指定します。ほとんどの一覧エンドポイントは、検索語 q= と列ごとの絞り込み（例:?status=available）も受け付けます。

データの作成

レコードを作成するには JSON を POST します。書き込みに成功すると、新しいエンティティの id が返ります。あわせて元になった event_id も返ります。Celerp では、あらゆる変更がイベントとして記録されます。

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

共通の決まりごと

• エラー 2xx 以外のレスポンスは、標準の HTTP ステータスコードとともに {"detail": "..."} を返します。
• レート制限 既定では IP あたり毎分60リクエスト、ログインは毎分10回までです。上限を超えると 429 が返ります。
• 権限 エンドポイントは役割によって制限されます:viewer → operator → manager → admin → owner。
• 会社スコープ リクエストはすべて、トークンに紐づく会社に対して実行されます。別の会社を操作するには会社を切り替えてください。

主なエンドポイント

まず使いはじめるための、ごく一部です。モジュールごとに独自のエンドポイントが追加されます。全体は下の OpenAPI スキーマで確認できます。

分野別の完全なリファレンス

稼働中の API が提供するすべてのエンドポイントを分野別に整理しています。各ページには メソッド、パス、パラメーター、リクエストとレスポンスの形式、呼び出し例を掲載しています。

API の全体像を見る

完全で常に最新のリファレンスは、お客様自身のインスタンスが生成する OpenAPI 3.1 スキーマです。

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

OpenAPI に対応したツール（Postman、Insomnia、Swagger UI、クライアント生成ツールなど）に読み込めば、すべてのエンドポイントとモデルを確認し、リクエストを試し、お使いのプログラミング言語で型付きのクライアントを生成できます。Celerp はホスト型のドキュメントページではなくスキーマそのものを提供するため、API の内容が外部に出ることはありません。