API REST

Chaque action de l'interface Celerp correspond à un endpoint REST : la même API que l'interface utilise en interne. Automatisez vos processus, connectez d'autres systèmes ou créez vos propres outils. L'API s'exécute localement, sur vos données ; rien n'est envoyé dans le cloud.

Authentification

Celerp utilise des JSON Web Tokens de courte durée de vie. Connectez-vous avec votre adresse e-mail et votre mot de passe Celerp pour obtenir un token d'accès, puis transmettez-le dans un en-tête Bearer à chaque requête.

1. Se connecter

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

La réponse contient deux tokens :

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

2. Appeler l'API avec le token

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

• Le token identifie votre utilisateur, votre rôle et votre entreprise : les requêtes sont automatiquement limitées à cette entreprise, sans en-tête supplémentaire.
• Les tokens d'accès sont valables jusqu'à 24 heures. À expiration, obtenez une nouvelle paire en envoyant votre refresh_token en POST sur /auth/token/refresh.
• Vous appartenez à plusieurs entreprises ? Listez-les avec GET /auth/my-companies, puis obtenez un token limité à une autre avec POST /auth/switch-company/{company_id}.

Effectuer des requêtes

Tous les endpoints se trouvent sous l'adresse de votre serveur d'API (http://localhost:8000 pour une installation pip, comme dans les exemples ci-dessous) et renvoient du JSON. Les endpoints de liste renvoient un tableau items et un décompte 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
}

Pagination : passez ?limit= (50 par défaut) et ?offset=. La plupart des endpoints de liste acceptent également un terme de recherche q= et des filtres de colonne (ex. ?status=available).

Créer des données

Envoyez du JSON en POST pour créer des enregistrements. Les écritures renvoient l'id de la nouvelle entité (et l'event_id sous-jacent : chaque modification dans Celerp est un événement).

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

Conventions

• Erreurs les réponses non 2xx renvoient {"detail": "..."} avec un code de statut HTTP standard.
• Limites de débit 60 requêtes/minute par IP par défaut ; la connexion est plafonnée à 10/minute. Dépasser une limite renvoie 429.
• Permissions l'accès aux endpoints dépend de votre rôle : viewer → operator → manager → admin → owner.
• Périmètre d'entreprise chaque requête agit sur l'entreprise de votre token ; changez d'entreprise pour agir sur une autre.

Endpoints courants

Un petit aperçu pour démarrer. Chaque module ajoute les siens : la liste complète se trouve dans le schéma OpenAPI ci-dessous.

Référence complète par domaine

Tous les endpoints servis par l’API en cours d’exécution, regroupés par domaine. Chaque page indique la méthode, le chemin, les paramètres, les structures de requête et de réponse ainsi qu’un exemple d’appel.

Explorer l'API complète

La référence complète et toujours à jour est le schéma OpenAPI 3.1 généré par votre propre instance :

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

Chargez-le dans n'importe quel outil OpenAPI (Postman, Insomnia, Swagger UI ou un générateur de clients) pour parcourir tous les endpoints et modèles, tester des requêtes et générer un client typé dans votre langage. Celerp livre le schéma lui-même plutôt qu'une page de documentation hébergée : votre surface d'API reste interne à votre instance.