REST API

Ogni azione dell'interfaccia di Celerp è un endpoint REST: la stessa API che l'interfaccia usa internamente. Automatizza i flussi di lavoro, collega altri sistemi o costruisci i tuoi strumenti. L'API gira in locale sui tuoi dati; nulla viene inviato al cloud.

Autenticazione

Celerp usa JSON Web Token di breve durata. Accedi con e-mail e password Celerp per ottenere un token di accesso, poi invialo come header Bearer in ogni richiesta.

1. Accedi

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

La risposta contiene due token:

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

2. Chiama l'API con il token

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

• Il token identifica utente, ruolo e azienda, quindi le richieste sono automaticamente circoscritte a quell'azienda: non serve alcun header aggiuntivo.
• I token di accesso durano fino a 24 ore. Quando uno scade, ottieni una coppia nuova inviando il tuo refresh_token con una POST a /auth/token/refresh.
• Appartieni a più di un'azienda? Elencale con GET /auth/my-companies, poi ottieni un token circoscritto a un'altra con POST /auth/switch-company/{company_id}.

Effettuare le richieste

Tutti gli endpoint stanno sotto l'indirizzo del tuo server API (http://localhost:8000 con un'installazione pip, come negli esempi qui sotto) e restituiscono JSON. Gli endpoint di elenco restituiscono un array items e un conteggio 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
}

Paginazione: passa ?limit= (predefinito 50) e ?offset=. Quasi tutti gli endpoint di elenco accettano anche un termine di ricerca q= e filtri di colonna (es. ?status=available).

Creare dati

Invia JSON in POST per creare record. Le scritture restituiscono l'id della nuova entità (e l'event_id sottostante: in Celerp ogni modifica è un evento).

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

Convenzioni

• Errori le risposte non 2xx restituiscono {"detail": "..."} con un codice di stato HTTP standard.
• Limiti di frequenza 60 richieste al minuto per IP per impostazione predefinita; il login è limitato a 10 al minuto. Superare un limite restituisce 429.
• Permessi l'accesso agli endpoint dipende dal tuo ruolo: viewer → operator → manager → admin → owner.
• Ambito aziendale ogni richiesta agisce sull'azienda nel tuo token; cambia azienda per agire su un'altra.

Endpoint comuni

Una piccola selezione per iniziare. Ogni modulo aggiunge i propri: l'elenco completo è nello schema OpenAPI qui sotto.

Riferimento completo per area

Tutti gli endpoint esposti dall’API in esecuzione, raggruppati per area. Ogni pagina elenca metodo, path, parametri, strutture di request e response e una chiamata di esempio.

Esplora l'API completa

Il riferimento completo e sempre aggiornato è lo schema OpenAPI 3.1 che genera la tua istanza:

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

Caricalo in un qualsiasi strumento OpenAPI – Postman, Insomnia, Swagger UI o un generatore di client – per sfogliare ogni endpoint e ogni modello, provare le richieste e generare un client tipizzato nel tuo linguaggio. Celerp distribuisce lo schema anziché una pagina di documentazione ospitata, così la superficie della tua API resta privata alla tua istanza.