API HTTP
Claves de API, base URL y autenticación de la REST API de Tillor
Última actualización el
La API de Tillor es una REST API. Autentícate con una clave de API y envía las cabeceras correctas en cada request. Las claves de API son por cuenta: una clave funciona para todas las organizaciones a las que tienes acceso.
Referencia de la API y OpenAPI
- Referencia de la API - Cada endpoint con parámetros y ejemplos; prueba requests directamente en el navegador
- Especificación OpenAPI - Documentación completa de la API en formato JSON para generar código o importarla en Postman/Insomnia
Claves de API
Crear
Las claves de API las creas en la aplicación de Tillor mediante el menú de usuario, en Cuenta > Claves API (marca 1 = menú, marca 2 = Claves API en la captura). También puedes crearlas mediante la API con una sesión iniciada (sin clave de API). Consulta la especificación OpenAPI bajo la etiqueta api-keys para las rutas y los esquemas de request y response.
La clave en bruto se devuelve una sola vez al crearla o regenerarla. Guárdala de forma segura; después ya no se puede recuperar.
Limitar los permisos
De forma predeterminada, una clave puede todo lo que puedes tú, en cada organización de la que eres miembro. En la ventana de la clave activa Limitar a los permisos seleccionados y elige los permisos que necesita la integración, por ejemplo solo leer facturas. Una clave limitada obtiene en cada organización la intersección de sus permisos y tu pertenencia allí: una clave nunca puede más que tú. Una llamada fuera de los permisos elegidos recibe 403 Forbidden, igual que un usuario sin ese permiso. Un cambio de los permisos vale en un minuto. Mediante la API: scopes (lista de ids de permisos como invoices:read, o null para todo) al crear y actualizar una clave.
Uso
Envía la clave de API en la cabecera x-api-key:
x-api-key: tkn_xxxLas claves usan el prefijo tkn_. En los endpoints de organización, el ID de la organización va en la ruta (/orgs/org_abc123/...); no hace falta una cabecera aparte.
Rate limits
- Predeterminado: 5000 requests por 60 segundos por clave
- Al superarlo:
429 Too Many RequestsconRetry-After - Cada respuesta con clave de API contiene cabeceras IETF
RateLimit-*:
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60RateLimit-Reset es el número de segundos hasta que empieza de nuevo la ventana actual. Los clientes de navegador pueden leer estas cabeceras mediante CORS (Access-Control-Expose-Headers).
Seguridad
Atención
- Nunca expongas claves de API en código del lado del cliente ni en repositorios públicos
- Regenera las claves periódicamente con Regenerar en la aplicación (OpenAPI:
POST /api/api-keys/:id/renew) - Elimina las claves sin uso con
DELETE /api/api-keys/:id
Base URL y contexto de la organización
Base URL: https://tillor.eu (o la URL de tu despliegue; OpenAPI menciona {APP_URL}/api)
Rutas de organización: añade el ID de la organización en la ruta:
/api/orgs/:orgId/...Ejemplo:
GET https://tillor.eu/api/orgs/org_abc123/customersCabecera obligatoria para los endpoints de organización: x-api-key: tkn_xxx. El ID de la organización va en la ruta.
Ejemplo: cURL
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
-H "x-api-key: tkn_xxx" \
-H "Content-Type: application/json"Integraciones (marketplace)
Las integraciones de la organización (antes "apps" en la API) usan un recurso por tipo bajo /api/orgs/:orgId/integrations/{integrationType}. Los permisos necesarios son organization:integrations:read y organization:integrations:write (sustituye a organization:apps:*).
| Method | Ruta | Descripción |
|---|---|---|
| GET | /integrations/{integrationType} | Estado (installed, available) y settings censurados |
| POST | /integrations/{integrationType} | Instalar (settings opcional en el cuerpo; OAuth puede devolver redirectUrl) |
| PUT | /integrations/{integrationType} | Actualizar ajustes (settings en el cuerpo) |
| DELETE | /integrations/{integrationType} | Desinstalar |
Con GET y tras PUT, settings contiene solo campos públicos más, por cada campo secreto, { configured: true }. Las contraseñas, claves de API y tokens OAuth no se devuelven. Deja vacíos los campos secretos en PUT para conservar el valor existente.
Consulta la especificación OpenAPI (etiqueta integrations) para los esquemas exactos.
Relacionado
- Referencia de la API - Cada endpoint, para probar en el navegador
- OpenAPI - Especificación de la API (JSON)
- MCP - Conectar Cursor, Claude, ChatGPT o Gemini mediante OAuth
- Notificaciones externas - Registra los correos que envió tu propio sistema
- Webhooks - Recibe eventos mediante HTTP POST
- Webhook entrante de una automatización - Inicia una automatización con un POST, sin clave de API
- SSE - Transmite eventos mediante Server-Sent Events
- Ejemplos - Ejemplos de código y de carga útil