# Introducción a la API REST

Qué es la API REST de plnnrly, dónde está, cómo te autenticas y cómo consigues un token.

La API REST permite que tu propio código lea y cambie tus datos de plnnrly: proyectos, elementos de trabajo, horas, documentos de Drive, clientes, facturas, ausencias, planificación y más. Funciona con JSON por HTTPS, en la propia dirección de plnnrly de tu organización.

Las guías de la API y la referencia están en inglés. Esta página resume lo esencial en español y enlaza con ellas.

## Datos de conexión

| Ajuste            | Valor                                                                     |
| ----------------- | ------------------------------------------------------------------------- |
| **URL base**      | `https://<tu-url>/api/v2`                                                 |
| **Autenticación** | `Authorization: Bearer <token>`                                           |
| **Formato**       | JSON. Envía `Content-Type: application/json` con cada cuerpo de petición. |
| **Contrato**      | [Documento OpenAPI 3.1](https://developers.plnnrly.com/openapi.json)      |

Sustituye `<tu-url>` por la dirección con la que inicias sesión en plnnrly, por ejemplo `acme.plnnrly.com`. Si tu organización usa su propio dominio, usa ese dominio: la API solo responde en esa dirección exacta y nunca redirige. No existe un `api.plnnrly.com` compartido.

En plnnrly, **Acceso a la API** en el menú de usuario abre la página **Tokens de API**, que muestra tu URL base lista para copiar.

## Dos formas de autenticarte

| Lo que creas                                                          | Qué usar                                                                                                                                                                                                                                                                                                                        |
| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Scripts e integraciones para ti o para tu organización                | Un token de acceso personal que creas en plnnrly. Consulta [Tokens de API (en inglés)](https://developers.plnnrly.com/en/docs/api/v2/guides/tokens/).                                                                                                                                                                           |
| Una aplicación que otras personas instalan y en la que inician sesión | Inicio de sesión OAuth: código de autorización con PKCE, y la aplicación se registra sola. Para aplicaciones de escritorio y de línea de comandos; quien inicia sesión necesita **Gestionar tokens de API**. Consulta [Iniciar sesión con OAuth (en inglés)](https://developers.plnnrly.com/en/docs/api/v2/guides/oauth-apps/). |

En ambos casos, cada petición actúa en nombre de una persona, con sus permisos y nada más. Las aplicaciones que usan el inicio de sesión OAuth no pueden eliminar a través de la API REST.

## Conseguir un token

1. En plnnrly, abre **Acceso a la API** en el menú de usuario (arriba a la derecha, bajo tu nombre) y elige **Crear token**.
2. Dale al token un **Nombre**.
3. En **Permisos**, elige **Lectura**, **Escritura** o **Eliminación**; la lista solo ofrece lo que te permite tu rol. La escritura incluye la lectura, y la eliminación incluye la escritura y la lectura. El token los guarda como `api:read`, `api:write` y `api:destroy`, o por recurso, como `api:read:projects`, cuando rellenas **Recursos**.
4. Deja **Recursos** vacío para conceder los permisos en todos los recursos, o elige las partes de plnnrly a las que se limita el token. La lista solo ofrece las partes para las que tienes permisos.
5. Elige una fecha en **Caduca el**. Es obligatoria, viene rellenada con la fecha de dentro de 90 días y puede estar como máximo a 12 meses vista.
6. Copia el token. Solo se muestra una vez.

**Acceso a la API** solo aparece en el menú de usuario mientras la API REST está activada y tienes el permiso **Gestionar tokens de API**. Consulta [quién puede crear tokens](https://developers.plnnrly.com/es/docs/administration/#permissions). Puedes tener diez tokens activos a la vez.

El campo **Permisos** del formulario fija los permisos del token, es decir, lo que el token puede hacer. No son lo mismo que los permisos que te da tu rol. Se aplican los dos, así que un token nunca hace más de lo que puedes hacer tú en plnnrly. [Tokens de API (en inglés)](https://developers.plnnrly.com/en/docs/api/v2/guides/tokens/) explica cómo renovar y revocar un token y describe el formulario completo.

## Cada operación indica lo que necesita

Cada página de operación de la [referencia (en inglés)](https://developers.plnnrly.com/en/docs/api/v2/) indica qué permisos del token y qué permiso de plnnrly necesita, y cuánto cuenta para el límite de peticiones. Los permisos del token y el permiso de tu rol se comprueban en cada petición, y el tipo de un `403` te dice qué lo rechazó:

- [insufficient-token-scope](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#insufficient-token-scope): los permisos del token no cubren la operación. Usa un token con permisos más amplios.
- [insufficient-permission](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#insufficient-permission): tu rol no tiene el permiso. Pide a un administrador que cambie tu rol.
- [forbidden-by-policy](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#forbidden-by-policy): no puedes hacer esto con este registro concreto.

## Ver lo que expone tu organización

La petición de [descubrimiento (en inglés)](https://developers.plnnrly.com/en/docs/api/v2/discovery/) enumera lo que expone tu organización: cada recurso con sus URL y sus operaciones. Cualquier token personal de API puede llamarla; no necesita ningún permiso.

```bash
curl https://<tu-url>/api/v2/ \
  -H "Authorization: Bearer <token>" \
  -H "Accept: application/json"
```

La cabecera `Accept` es opcional: omítela o envía `application/json`.

El descubrimiento omite las áreas que tu organización no usa, como la facturación. No comprueba qué recursos cubren los permisos de tu token o de tu rol, así que un recurso que aparece en la lista aún puede responder `403`.

## Cuando la API está desactivada

Un administrador puede desactivar la API REST en **Configuración › Administración › MCP & API**. Mientras está desactivada, todas las peticiones reciben `404` [endpoint-not-found](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/#endpoint-not-found), incluidas las que usan un token que antes funcionaba. Consulta [qué ocurre cuando un interruptor está desactivado](https://developers.plnnrly.com/es/docs/administration/#when-switched-off).

## Siguientes pasos

- [Primeros pasos (en inglés)](https://developers.plnnrly.com/en/docs/api/v2/guides/getting-started/): de un token a tu primera escritura.
- [Introducción a la referencia (en inglés)](https://developers.plnnrly.com/en/docs/api/v2/): cómo está organizada la referencia, y todas las guías.
- [Errores y reintentos (en inglés)](https://developers.plnnrly.com/en/docs/api/v2/guides/errors/): cada tipo de problema y qué hacer.
- [/openapi.json](https://developers.plnnrly.com/openapi.json): el contrato completo, para generadores de código y otras herramientas.

## Para asistentes de IA

Si quieres que un asistente de IA trabaje con tus datos de plnnrly, usa el [servidor MCP](https://developers.plnnrly.com/es/docs/mcp/). Llega a las mismas operaciones que tú, salvo la subida de archivos, sin que tengas que programar ningún cliente.