# API HTTP (/es-ES/ontwikkelaars/http)

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 [#api-referentie-en-openapi]

- **[Referencia de la API](/api-referentie)** - Cada endpoint con parámetros y ejemplos; prueba requests directamente en el navegador
- **[Especificación OpenAPI](https://tillor.eu/api/openapi.json)** - Documentación completa de la API en formato JSON para generar código o importarla en Postman/Insomnia

---

## Claves de API [#api-sleutels]

### Crear [#aanmaken]

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](https://tillor.eu/api/openapi.json) bajo la etiqueta `api-keys` para las rutas y los esquemas de request y response.

<DocScreenshot src="/screenshots/http/api-keys-nav.png" alt="Claves API en los ajustes de la cuenta" />

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 [#rechten-beperken]

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 [#gebruik]

Envía la clave de API en la cabecera `x-api-key`:

```http
x-api-key: tkn_xxx
```

Las 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 [#rate-limits]

- **Predeterminado:** 5000 requests por 60 segundos por clave
- Al superarlo: `429 Too Many Requests` con `Retry-After`
- Cada respuesta con clave de API contiene cabeceras IETF `RateLimit-*`:

```http
RateLimit-Limit: 5000
RateLimit-Remaining: 4999
RateLimit-Reset: 58
RateLimit-Policy: 5000;w=60
```

`RateLimit-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 [#beveiliging]

<Callout type="warn" title="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`
</Callout>

---

## Base URL y contexto de la organización [#base-url-en-organisatie-context]

**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/customers
```

**Cabecera obligatoria para los endpoints de organización:** `x-api-key: tkn_xxx`. El ID de la organización va en la ruta.

---

## Ejemplo: cURL [#voorbeeld-curl]

```bash
curl -X GET "https://tillor.eu/api/orgs/org_abc123/customers" \
  -H "x-api-key: tkn_xxx" \
  -H "Content-Type: application/json"
```

---

## Integraciones (marketplace) [#integraties-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](https://tillor.eu/api/openapi.json) (etiqueta `integrations`) para los esquemas exactos.

---

## Relacionado [#gerelateerd]

- [Referencia de la API](/api-referentie) - Cada endpoint, para probar en el navegador
- [OpenAPI](https://tillor.eu/api/openapi.json) - Especificación de la API (JSON)
- [MCP](/ontwikkelaars/mcp) - Conectar Cursor, Claude, ChatGPT o Gemini mediante OAuth
- [Notificaciones externas](/ontwikkelaars/externe-notificaties) - Registra los correos que envió tu propio sistema
- [Webhooks](/ontwikkelaars/webhooks) - Recibe eventos mediante HTTP POST
- [Webhook entrante de una automatización](/ontwikkelaars/automatiseringen#een-automatisering-starten-met-een-webhook) - Inicia una automatización con un POST, sin clave de API
- [SSE](/ontwikkelaars/sse) - Transmite eventos mediante Server-Sent Events
- [Ejemplos](/ontwikkelaars/voorbeelden) - Ejemplos de código y de carga útil