Este artículo explica cómo integrarse con la API de Plain para:
Autenticarse correctamente
Exportar fichajes y ausencias
Obtener vacaciones y otras cuentas de empleados
Trabajar en entornos multivenue
El objetivo es que puedas entender el flujo completo antes de empezar a programar.
1. Autenticación
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.
1.1 Cómo obtener el token JWT
El proceso tiene dos pasos:
Paso 1: Enviar credenciales al endpoint de autenticación
Endpoint:
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:
El username en Plain siempre es un email.
El usuario debe tener rol administrador.
Es recomendable crear un usuario específico para la integración.
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.
1.2 Entornos multivenue
Si trabajas en un entorno multivenue:
La respuesta incluirá
other_company_tokens.Cada venue tiene su propio token JWT.
Debes crear el usuario administrador en cada venue.
El username debe ser exactamente el mismo en todas las venues.
Para operar en cada venue, debes usar el token correspondiente.
2. Exportación de datos a Excel
La exportación de datos (fichajes o ausencias) sigue siempre el mismo patrón:
Obtener un token de descarga.
Usar ese token para descargar el archivo.
Este sistema desacopla la generación del archivo de su descarga.
2.1 Exportación de fichajes
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.
2.2 Exportación de ausencias
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:
Debes repetir el proceso completo para cada venue.
Cada venue requiere su propio JWT.
Cada exportación genera su propio token de descarga.
3. Obtener vacaciones y otras cuentas de empleados
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.
3.1 Crear una vista de planificación
Desde la aplicación:
Planificación → Configurar vistas → Crear nueva vista
Añade las columnas:
Vacaciones pendientes periodo
Vacaciones disfrutadas periodo
Guarda la vista con un nombre identificable (por ejemplo: “Vista integración”).
3.2 Obtener el ID de la vista
Endpoint:
GET /saas/api/plan-views
Este endpoint devuelve un listado de vistas con su:
id
name
Busca la vista creada y guarda su id.
3.3 Obtener las cuentas mediante API
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:
El email está en:
data[i].employee.emailLas cuentas están en:
data[i].counters
Cada elemento de counters contiene:
label→ nombre de la cuentavalue→ valor de la cuenta
Los valores devueltos corresponden exactamente a las columnas configuradas en la vista.