API REST

Cada acción en la interfaz de Celerp es un endpoint REST: la misma API que usa la interfaz internamente. Automatiza flujos de trabajo, conecta otros sistemas o construye tus propias herramientas. La API se ejecuta localmente con tus datos; nada se envía a la nube.

Autenticación

Celerp usa JSON Web Tokens de corta duración. Inicia sesión con tu correo y contraseña de Celerp para obtener un token de acceso y envíalo después como cabecera Bearer en cada solicitud.

1. Iniciar sesión

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

La respuesta contiene dos tokens:

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

2. Llamar a la API con el token

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

• El token identifica tu usuario, rol y empresa, por lo que las solicitudes se acotan automáticamente a esa empresa, sin cabeceras adicionales.
• Los tokens de acceso duran hasta 24 horas. Cuando uno expira, obtén un par nuevo enviando tu refresh_token por POST a /auth/token/refresh.
• ¿Perteneces a más de una empresa? Lístalas con GET /auth/my-companies y obtén un token para otra con POST /auth/switch-company/{company_id}.

Hacer solicitudes

Todos los endpoints están bajo la dirección de tu servidor de la API (http://localhost:8000 en una instalación con pip, como en los ejemplos de abajo) y devuelven JSON. Los endpoints de listado devuelven un array items y un recuento 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
}

Paginación: pasa ?limit= (50 por defecto) y ?offset=. La mayoría de los endpoints de listado admiten además un término de búsqueda q= y filtros por columna (p. ej. ?status=available).

Crear datos

Envía JSON por POST para crear registros. Las escrituras devuelven el id de la nueva entidad (y el event_id subyacente; cada cambio en Celerp es 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"
  }'

Convenciones

• Errores las respuestas no 2xx devuelven {"detail": "..."} con un código de estado HTTP estándar.
• Límites de frecuencia 60 solicitudes/minuto por IP por defecto; el inicio de sesión está limitado a 10/minuto. Superar un límite devuelve 429.
• Permisos los endpoints están controlados por tu rol: viewer → operator → manager → admin → owner.
• Ámbito de empresa cada solicitud actúa sobre la empresa de tu token; cambia de empresa para actuar sobre otra.

Endpoints comunes

Una pequeña muestra para empezar. Cada módulo añade los suyos; la lista completa está en el esquema OpenAPI de más abajo.

Referencia completa por área

Todos los endpoints que expone la API en ejecución, agrupados por área. Cada página enumera el método, la ruta, los parámetros, las estructuras de solicitud y respuesta y una llamada de ejemplo.

Explorar la API completa

La referencia completa y siempre actualizada es el esquema OpenAPI 3.1 que genera tu propia instancia:

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

Cárgalo en cualquier herramienta OpenAPI (Postman, Insomnia, Swagger UI o un generador de clientes) para explorar todos los endpoints y modelos, probar solicitudes y generar un cliente tipado en tu lenguaje. Celerp entrega el propio esquema en lugar de una página de documentación alojada, así que la superficie de tu API queda privada en tu instancia.