Este artículo explica cómo integrarse con la API de Plain para:

El objetivo es que puedas entender el flujo completo antes de empezar a programar.

Antes de utilizar cualquier endpoint de Plain, es necesario autenticarse y obtener un token JWT.

Este token identifica a tu aplicación y autoriza las peticiones que hagas a la API.

El proceso tiene dos pasos:

Paso 1: Enviar credenciales al endpoint de autenticación

POST /saas/api/auth/token/

Este endpoint requiere un header Authorization con un token dummy estático:

Authorization: Bearer 9cb029da-b5a6-429e-8184-4ebfb89a732c

Body de la petición:

{

"grant_type": "password",

"username": "<usuario>",

"password": "<password>"

}

Notas importantes:

Paso 2: Usar el token devuelto

La respuesta incluirá:

{
"access_token": "<token jwt>",
"token_type": "BEARER",
"expires_in": 43199,
"company_name": "<company name>"
}

El access_token es el token JWT que deberás incluir en todas las llamadas posteriores:

Authorization: Bearer <token jwt>

El token es válido durante 12 horas. No es necesario solicitar uno nuevo en cada llamada: puedes almacenarlo y reutilizarlo hasta que expire.

Si trabajas en un entorno multivenue:

La exportación de datos (fichajes o ausencias) sigue siempre el mismo patrón:

Este sistema desacopla la generación del archivo de su descarga.

Paso 1: Obtener token de descarga

GET /saas/api/time-registrations/export?page_size=1000&start_from=2026-01-01&start_to=2026-02-28

Respuesta:

{
"access_token": "<token descarga documentos>",
"token_type": "EXPORT",
"expires_in": 31535999,
"company_name": "Nombre de empresa"
}

Este token no es el JWT de autenticación. Es un token específico para descargar el archivo generado.

Paso 2: Descargar el Excel

GET /saas/api/store/download/<token descarga documentos>

Este endpoint devuelve directamente el archivo Excel como un stream.

El proceso es exactamente el mismo, pero usando otro endpoint:

GET /saas/api/workflows/export?page_size=1000&workflow_type=Ausencias&sort=-requested&workflow_status=Pendiente&start_from=2026-01-01&start_to=2026-01-31

Después se descarga el archivo usando:

GET /saas/api/store/download/<token descarga documentos>

Multivenue en exportaciones

Si trabajas con multivenue:

Plain no expone directamente las vacaciones disponibles o disfrutadas mediante un endpoint aislado. Las cuentas se obtienen a través de una vista de planificación. Esto permite controlar qué columnas quieres exponer en la API.

Desde la aplicación:

Planificación → Configurar vistas → Crear nueva vista

Añade las columnas:

Guarda la vista con un nombre identificable (por ejemplo: "Vista integración").

GET /saas/api/plan-views

Este endpoint devuelve un listado de vistas con su id y name. Busca la vista creada y guarda su id.

Con el id de la vista:

GET /api/accounts/assignments?page_size=1000&start=2026-01-01&end=2026-01-31&group_id=566&plan_view_id=<id obtenido>

La respuesta contiene un array data. Para cada empleado:

Cada elemento de counters contiene:

Los valores devueltos corresponden exactamente a las columnas configuradas en la vista.

Además de exportar y consultar datos, la API de Plain permite importar empleados y workflows de forma masiva. Estos endpoints aceptan un array de elementos en una sola petición y devuelven el resultado individual de cada uno.

Aplican a todos los endpoints de importación:

POST /api/employees/imports/bulk

El identificador del empleado es el email. Si ya existe un empleado con ese email, se actualizan sus datos; en caso contrario, se crea uno nuevo.

Campos de cada elemento (EmployeeBulkDTO):

Ejemplo de body:

[
{
"name": "María",
"surname": "García López",
"email": "[email protected]",
"code": "EMP-001",
"enabled": true,
"with_access": true,
"start_day": "2024-01-15",
"position": "Camarera",
"group": "Sala"
},
{
"name": "Juan",
"surname": "Pérez Ruiz",
"email": "[email protected]",
"code": "EMP-002",
"enabled": true,
"with_access": false,
"start_day": "2023-06-01"
}
]

POST /api/workflows/imports/bulk

Un workflow representa una asignación planificada para un empleado durante un periodo, con un turno asociado. El identificador es la combinación de employee_code, la fecha start y el shift. Si ya existe un workflow con esa combinación, se actualiza; en caso contrario, se crea uno nuevo.

Campos de cada elemento (WorkflowBulkDTO):

Ejemplo de body:

[
{
"employee_code": "EMP-001",
"start": "2026-03-01"
"shift": "V",
"comments": "Asignación de Vacaciones de un día creada por integración"
},

{
"employee_code": "EMP-001",
"start": "2026-05-01",
"end": "2026-05-05",
"shift": "V",
"comments": "Asignación de vacaciones de varios días para anular"

"status": "Anulado"
​ },

{
"employee_code": "EMP-001",
"start": "2026-03-01",
"shift": "V",
"comments": "Asignación de vacaciones de ausencia por horas",

"workflow_hourly_requested": true,

"start_hour": "2026-08-10T10:30:00Z",

"duration": 4.5
}
​]

POST /api/time-registrations/imports/bulk

Un fichaje (time registration) representa un registro de tiempo de un empleado en un día concreto, con una hora de inicio, una hora de fin opcional y un tipo de tiempo asociado. El identificador de un fichaje es la combinación de empleado (employee_code) , día (day) y hora de inicio (start).

Por este motivo, para un empleado y un día debes enviar siempre todos los fichajes de ese día, incluso los que no han cambiado. Si omites alguno, se interpretará como que se ha eliminado.

Esto no significa que tengas que enviar los fichajes de todos los días: solo debes incluir los días en los que haya fichajes añadidos, modificados o eliminados. Cada elemento del array representa el conjunto completo de fichajes de un empleado en un día.

Campos de cada elemento (TimeRegistrationBulkDTO):

Campos de cada fichaje dentro de items (TimeRegistrationItemBulkDTO):

Ejemplo de body:

[
{
"day": "2026-06-25",
"employee_code": "47",
"items": [
{
"start": "2026-06-25T07:30:12Z",
"end": "2026-06-25T11:45:15Z",
"time_type": "Trabajo"
},
{
"start": "2026-06-25T13:30:12Z",
"end": "",
"time_type": "Trabajo"
}
]
}
]

Los endpoints de importación devuelven un array con un resultado por cada elemento enviado, en el mismo orden.

Campos de ErrorItemDTO:

Ejemplo ilustrativo de respuesta (un elemento correcto y otro con error):

[
{ "status": 200 },
{
"status": 400,
"errors": [
{
"code": "...",
"key": "email",
"fields": ["email"],
"value": "juan.perez",
"availables": "...",
"description": "...",
"index": 1
}
]
}
]

Conviene recorrer siempre el array de respuesta y comprobar cada resultado: una petición puede importar correctamente unos elementos y fallar en otros. El campo index permite identificar exactamente qué elemento del array original ha fallado.

Al igual que en las exportaciones, en un entorno multivenue debes repetir el proceso completo para cada venue, usando el token JWT correspondiente a cada una.

Esta sección describe cómo sincronizar el balance de horas (bolsa de horas) de un sistema externo con Plain. El flujo consiste en consultar el balance actual de cada empleado en Plain, calcular la diferencia respecto al balance del sistema externo, y enviar una transacción de compensación que ajuste el balance al valor correcto.

Para evitar acumular transacciones de compensación en sincronizaciones sucesivas, se recomienda guardar el id de la transacción creada para cada empleado y, en las siguientes ejecuciones, actualizarla en vez de crear una nueva.

GET /saas/api/accounts/assignments?start=2020-01-01&end=2026-05-29&transaction_rule_system_id=5&page_size=50&page=0

Parámetros relevantes:

Paginación recomendada: pedir páginas de 50 en 50 y procesar cada lote (calcular la compensación y enviar/actualizar la transacción de cada empleado) antes de solicitar la siguiente página.

Estructura de la respuesta (AccountAssignmentSearchBeanDTO):

{
"data": [
{
"employee": {
"id": 12345,
"name": "María",
"surname": "García López",
"email": "[email protected]",
"code": "EMP-001"
},
"counters": [
{
"label": "Balance",
"value": 12.5
}
]
}
],
"pagination": {
"total_items": 245,
"page": 0,
"page_size": 50
}
}

Notas sobre la respuesta:

Para cada empleado de la página:

compensación = balance_externo − balance_plain

Donde:

Si la diferencia es 0, no es necesario crear ni actualizar ninguna transacción para ese empleado.

POST /saas/api/transactions/

Body de la petición (TransactionDTO):

{
"day": "2026-05-29",
"value": "12.5",
"account_id": 99474,
"employee_id": 12345,
"observations": "Compensación horas objetivo"
}

Campos relevantes:

La respuesta es un TransactionDTOResponse que incluye el id de la transacción creada:

{
"id": 7654321,
"day": "2026-05-29",
"value": "12.5",
"employee_id": 12345,
"observations": "Compensación horas objetivo",
"account": { "id": 99474, "name": "...", "type": "..." },
"employee": { "id": 12345, "name": "María", "surname": "García López" },
"created": "2026-05-29T08:00:00",
"updated": "2026-05-29T08:00:00",
"version": 1
}

Guarda este id en el sistema externo, asociado al empleado. Será necesario para actualizar la transacción en las siguientes sincronizaciones sin crear una nueva.

Si en el sistema externo ya está guardado el id de la transacción de compensación previa para ese empleado, se actualiza esa misma transacción en lugar de crear una nueva. Esto evita acumular transacciones de compensación a lo largo del tiempo:

PUT /saas/api/transactions/{transaction-id}

Donde {transaction-id} es el id guardado de la transacción previa.

Body de la petición (mismo TransactionDTO, con el nuevo valor calculado):

{
"day": "2026-05-29",
"value": "10.0",
"account_id": 99474,
"employee_id": 12345,
"observations": "Compensación horas objetivo"
}

El day y el value se actualizan al nuevo cálculo de compensación; el id de la transacción se mantiene.

Al igual que en el resto de operaciones, en un entorno multivenue debes repetir el proceso completo para cada venue, usando el token JWT correspondiente a cada una. Los id de empleado, de transacción y de cuenta son específicos de cada venue, por lo que deben guardarse asociados al venue correspondiente.

Resumen de las estructuras de datos utilizadas por la API.

AuthenticationDTO — body de la autenticación

TokenDTO — respuesta de la autenticación

StatusDTO — resultado correcto de una importación

ErrorDTO — resultado con error

Los esquemas EmployeeBulkDTO, WorkflowBulkDTO y ErrorItemDTO están detallados en la sección 4.