Introducción a la API REST

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

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).
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).

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

En plnnrly, abre Acceso a la API en el menú de usuario (arriba a la derecha, bajo tu nombre) y elige Crear token.
Dale al token un Nombre.
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.
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.
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.
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. 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) 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) 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: los permisos del token no cubren la operación. Usa un token con permisos más amplios.
insufficient-permission: tu rol no tiene el permiso. Pide a un administrador que cambie tu rol.
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) 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.

Terminal

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, incluidas las que usan un token que antes funcionaba. Consulta qué ocurre cuando un interruptor está desactivado.

Siguientes pasos

Primeros pasos (en inglés): de un token a tu primera escritura.
Introducción a la referencia (en inglés): cómo está organizada la referencia, y todas las guías.
Errores y reintentos (en inglés): cada tipo de problema y qué hacer.
/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. Llega a las mismas operaciones que tú, salvo la subida de archivos, sin que tengas que programar ningún cliente.