La API de Personio conecta con otros sistemas los datos de empleados, contratos, ausencias, asistencia, compensación, documentos, informes y reclutamiento, pero no es un mando a distancia universal para todos los flujos de trabajo de Personio. La pregunta práctica no es si existe un endpoint, sino si el objeto, la operación de escritura, el evento, el permiso y el modelo operativo encajan con tu caso de uso.
¿A qué puede acceder realmente la API de Personio?
Personio no tiene una única API monolítica. Su interfaz pública combina endpoints v1, endpoints v2, una API de Recruiting independiente y webhooks. La superficie disponible depende además de tu plan de Personio, de los scopes concedidos a la credencial y de los atributos que un administrador haya hecho legibles.
En agosto de 2026, la visión general oficial de las API públicas de Personio describe v1 y v2 como complementarias. También fija el 31 de julio de 2026 como fecha de retirada de ciertos endpoints v1 de asistencia (Attendance) y proyectos (Projects). Por eso, una integración nueva debería partir de la referencia v2 actual y usar v1 solo donde una operación necesaria no tenga un sustituto adecuado en v2.
| Ámbito | Operaciones públicas útiles | Límite importante | Uso típico |
|---|---|---|---|
| Personas y contratos | Listar, consultar, crear y actualizar los datos básicos de las personas; consultar y actualizar los datos del contrato | Los scopes y los atributos legibles determinan el contenido real de la respuesta | Aprovisionamiento de identidades, data warehouse de RR. HH., sincronización de directorios |
| Organización | Leer unidades organizativas, entidades jurídicas, centros de coste, centros de trabajo, puestos y bandas salariales cuando están activados | No todos los objetos de configuración se pueden escribir a través de la API pública | Mapeo contable, reglas de acceso, analítica de plantilla |
| Ausencias y asistencia | Leer y escribir periodos, sujeto al endpoint y a la validación de negocio | Los solapamientos, las reglas de fechas, las aprobaciones y la propiedad del dato de origen requieren un tratamiento explícito | Sistemas de control horario y de permisos |
| Compensación | Leer la compensación; crear registros y tipos de compensación compatibles | Los tipos compatibles y la semántica de escritura son más limitados que un modelo de nómina completo | Preparación de nóminas e importaciones controladas |
| Documentos de empleados | Listar metadatos, descargar, actualizar metadatos, eliminar y usar una vía de subida independiente | Los documentos de empleados no son lo mismo que los adjuntos de reclutamiento | Nóminas, contratos, archivos de documentos |
| Reclutamiento | Leer candidatos, candidaturas, cambios de fase, puestos y categorías; crear candidaturas mediante la vía de escritura de reclutamiento | Las respuestas de lectura actuales omiten los atributos personalizados y las etiquetas de candidatos y candidaturas | Páginas de empleo, analítica de ATS, traspasos de preselección |
| Informes y webhooks | Leer informes configurados; suscribirse a eventos de cambio compatibles | Los webhooks cubren un catálogo de eventos, no todas las acciones de la interfaz ni todos los cambios de campos | Sincronización incremental e informes posteriores |
Esto es un mapa de capacidades, no un sustituto de comprobar el esquema exacto de cada endpoint. La guía de inicio actual de Personio explica que los atributos de empleados deben estar en la lista de permitidos, que los atributos personalizados muestran su valor actual y no un historial completo, y que las credenciales deben usarse desde un servicio backend y no desde código de navegador.
¿Qué no puede hacer la API de Personio?
Los errores de integración más caros empiezan con una suposición: si un flujo de trabajo existe en la interfaz de Personio, debe haber un endpoint público para cada paso. No es una suposición segura.
La referencia pública actual no presenta una API de escritura general para cada acción de reclutamiento. No deberías diseñar sobre endpoints supuestos para mover una candidatura existente por todas las fases, programar entrevistas, completar scorecards, enviar mensajes a candidatos o activar todas las aprobaciones. Algunos de esos flujos pueden resolverse con el propio Personio, con una integración del Marketplace, con un módulo conectado o con un intercambio deliberadamente acotado.
El reclutamiento tiene otro límite sutil. Los endpoints de lectura v2 cubren candidatos, candidaturas, puestos, categorías y cambios de fase, pero los candidatos y las candidaturas no devuelven actualmente atributos personalizados ni etiquetas. El endpoint de candidaturas independiente sí puede recibir atributos del candidato, etiquetas y referencias a archivos subidos cuando se crea una candidatura nueva. Leer y crear, por tanto, no son operaciones simétricas.
Otras carencias habituales tienen que ver con la semántica más que con objetos que faltan:
- Sin historial automático: un atributo actual de un empleado no permite reconstruir sus valores anteriores.
- Sin flujo de eventos universal: los webhooks reducen el polling para los eventos compatibles, pero no avisan de todos los cambios posibles.
- Sin fuente única de verdad por defecto: dos sistemas pueden aceptar escrituras y, aun así, discrepar tras una edición manual.
- Sin contexto del flujo de trabajo: una respuesta de la API puede mostrar un estado sin la política, la aprobación o la decisión humana que hay detrás.
- Sin derecho garantizado a la función: un endpoint que figura en la documentación puede seguir exigiendo un plan, una función de producto o un scope que tu cuenta no tiene.
Haz una prueba con credenciales en un sandbox o con un empleado de prueba antes de dar por buena la arquitectura. Confirma con datos reales los campos, la paginación, los filtros, el comportamiento de escritura, las respuestas de error y los scopes activados en la cuenta.
¿Cómo afectan los límites de uso y la sincronización al diseño?
Los límites de uso no son una única cifra para toda la plataforma. Pueden variar según la generación de la API y el endpoint. Por ejemplo, Personio documenta un límite de 20 solicitudes en 60 segundos por empresa para los endpoints v1 de candidaturas y documentos de reclutamiento. Al superar el umbral, los envíos deben esperar el tiempo de enfriamiento indicado. La introducción oficial a la API de Recruiting es la fuente que conviene consultar antes de dimensionar una página de empleo o una importación de preselección.
Una integración en producción debe tratar el HTTP 429 como una condición de funcionamiento esperada. Usa un backoff exponencial con jitter. Respeta cualquier indicación de la respuesta. Pon las escrituras en cola en lugar de descartarlas. Mantén una estrategia de idempotencia para que un reintento no cree un candidato, una ausencia o un documento duplicados.
Consultar todo cada pocos minutos rara vez es el mejor diseño. Es preferible esta secuencia:
- Haz una sincronización inicial paginada y guarda los ID de Personio.
- Suscríbete a los eventos de webhook disponibles para los objetos relevantes.
- Usa el evento como señal para recuperar el registro de referencia.
- Ejecuta una tarea de conciliación más lenta para recuperar los cambios perdidos o no compatibles.
- Registra un cursor, una marca de tiempo de actualización, un hash de la carga y el resultado del procesamiento.
Define la propiedad a nivel de campo. Personio puede ser el origen del nombre, la situación laboral y el departamento. Un sistema de control horario puede serlo de los fichajes en bruto. Un módulo de preselección puede ser el origen de una puntuación y su evidencia, mientras Personio conserva la decisión final de reclutamiento. Sin ese contrato, una integración con Personio técnicamente correcta puede sobrescribir en silencio datos más fiables.
¿Cuándo usar la interfaz DATEV de Personio?
Una integración de Personio con DATEV no es simplemente un script a medida sobre la API genérica de empleados. Es una conexión diseñada para los flujos de nómina alemanes. La documentación de configuración de DATEV de Personio describe flujos separados para los datos de nómina de Personio a DATEV, los documentos de nómina de DATEV a Personio y la recuperación automática de eAU.
Usa la interfaz nativa de Personio con DATEV cuando el proceso compatible coincida con tu modelo operativo. Ya refleja conceptos como entidad jurídica, identificadores de asesor y de cliente, autorización, atributos de nómina y la colaboración con el gestor de nóminas. Reconstruir esa semántica con endpoints genéricos suele generar trabajo sin aportar diferenciación.
Una capa de API a medida puede seguir teniendo sentido en los márgenes. Algunos ejemplos son validar los datos maestros antes del cierre de nómina, combinar datos para el controlling interno o derivar excepciones a una cola de aprobación. Mantén el traspaso nativo a DATEV como vía de la nómina y trata la capa a medida como validación u orquestación.
Antes de elegir una u otra vía, mapea el proceso mensual con el responsable de nóminas:
- ¿Qué entidades jurídicas y qué programa de nóminas de DATEV entran en el alcance?
- ¿Qué sistema es el origen de cada campo de datos maestros y de compensación?
- ¿Quién resuelve un registro de nómina rechazado o incoherente?
- ¿Cómo se devuelven y se distribuyen los documentos?
- ¿Cuál es el procedimiento de contingencia antes del cierre de nómina?
¿Cómo encajan las integraciones de ATS, sourcing y preselección?
Hay tres patrones de reclutamiento distintos. Mezclarlos en una vaga “integración con el ATS” produce diseños frágiles.
Página de empleo hacia Personio
El endpoint de creación de candidaturas encaja con una página de empleo que recoge los datos y los documentos del candidato y luego crea una candidatura para un puesto publicado de Personio. Valida la correspondencia de puestos antes de aceptar el envío. Sube los documentos desde el backend. Guarda los identificadores devueltos. Diseña una cola de fallos visible, porque un formulario bien pulido no garantiza que la candidatura se haya creado en el sistema de destino.
Sourcing hacia Personio
El Sourcing activo empieza antes de que exista una candidatura. Un sistema de sourcing puede investigar personas, gestionar el consentimiento de contacto y el estado de la secuencia, y enviar al ATS solo los perfiles interesados o cualificados. Ese traspaso más acotado mantiene el ruido de la prospección fuera de Personio. Un flujo de People Search conectado o un complemento de Sourcing activo para Personio puede ser más útil que copiar toda una base de datos de sourcing en campos de empleados o de candidatos.
Preselección junto a Personio
La preselección necesita algo más que una puntuación. Necesita los criterios del puesto, el material del candidato, la evidencia, el estado de revisión y una vía de retorno controlada. Para una recepción con muchos documentos, compara un módulo de preselección de CV conectado con un pipeline a medida. Para preselecciones telefónicas estructuradas, un complemento de preselección por entrevista de voz puede encargarse de la experiencia de la entrevista mientras Personio sigue siendo el ATS de referencia. La preselección de CV de Sprad Atlas escribe la valoración y el resumen como nota en el candidato de Personio; los cambios de estado dependen de lo que permitan las interfaces de Personio, así que pruébalos en un piloto. Sprad es el proveedor de esta página.
No fuerces cada función intermedia dentro de campos personalizados de Personio. Devuelve el resultado útil más pequeño posible: una recomendación, evidencias estructuradas, un enlace al registro detallado y un punto de decisión humana claro. Si una operación de escritura necesaria en reclutamiento no está disponible, usa un traspaso documentado o una tarea, en lugar de una automatización del navegador disfrazada de integración.
¿Cuándo es mejor un módulo conectado que un desarrollo a medida?
Desarrolla cuando la propia integración encarna un proceso distintivo de tu empresa. Compra o conecta un módulo cuando la mayor parte del esfuerzo se iría en fontanería estándar, experiencia de usuario, monitorización y mantenimiento constante de la API.
| Criterio de decisión | La integración a medida es más sólida cuando | El módulo conectado es más sólido cuando |
|---|---|---|
| Singularidad del proceso | Tus reglas o tu modelo de datos son realmente propios de la empresa | El flujo de trabajo es común a los equipos de reclutamiento |
| Cobertura de la API | Las lecturas, escrituras y eventos necesarios están documentados y son estables | El módulo ya sortea las superficies de escritura limitadas con un traspaso compatible |
| Experiencia de usuario | Basta con una sincronización en segundo plano o un flujo de administración interno | Candidatos, reclutadores o Hiring Managers necesitan una interfaz cuidada |
| Operaciones | Tu equipo puede asumir colas, reintentos, alertas, migraciones y soporte | Quieres que un proveedor opere el conector y el flujo de trabajo |
| Ritmo de cambio | El proceso y los esquemas cambian pocas veces | Los prompts, las scorecards, los canales o los controles de cumplimiento evolucionan a menudo |
| Economía | El valor interno a largo plazo supera el esfuerzo de desarrollo y mantenimiento | Importan más el tiempo hasta obtener valor y una responsabilidad predecible que el control del código fuente |
Comprueba siempre la disponibilidad de planes y precios para tu cuenta concreta; situación a agosto de 2026. Personio indica que el acceso a la API pública a medida requiere el derecho correspondiente en el plan. Un módulo de terceros también puede requerir su propia suscripción e implantación. Compara el coste total de propiedad, no solo la primera factura: el descubrimiento, la revisión de seguridad, el desarrollo, la migración de datos, la observabilidad, el soporte y los futuros cambios de la API entran en el cálculo.
Un diseño híbrido suele ser sensato. Personio sigue siendo el sistema de referencia. Un módulo conectado se encarga de un flujo de trabajo acotado. Una capa de orquestación mueve solo los datos mínimos necesarios. Este es el modelo que hay detrás de un agente de IA conectado a Personio, pero la misma arquitectura puede implementarse con un iPaaS, un partner de integración o un servicio interno.
¿Qué debes verificar antes de la implantación?
- Define el resultado: nombra la tarea manual, el error o el retraso que la integración debe eliminar.
- Lista objetos y campos: separa los datos imprescindibles de los que solo son cómodos.
- Marca dirección y propiedad: lectura, creación, actualización, eliminación, evento y fuente de verdad.
- Prueba el acceso de la cuenta: confirma plan, función, scopes, atributos legibles y datos reales.
- Modela el fallo: cubre 401, 403, 422, 429, timeouts, duplicados y éxito parcial.
- Minimiza los datos personales: mueve solo lo que necesita el flujo de destino y define qué ocurre con la eliminación.
- Pilota un solo flujo: concilia los resultados a mano antes de ampliar el volumen o el acceso de escritura.
El mejor diseño de la API de Personio suele ser más pequeño que el primer diagrama. Un traspaso acotado y observable, con una propiedad clara, es más fiable que una sincronización bidireccional amplia cuyas reglas de conflicto nadie sabe explicar.
Preguntas frecuentes sobre la API de Personio
¿Tiene Personio una API abierta?
Personio ofrece API públicas y webhooks documentados, pero el acceso depende del plan de la cuenta, de los productos activados, de los scopes de la credencial y de los atributos legibles. “Pública” no significa que cada pantalla o flujo de trabajo de Personio se pueda controlar de forma remota.
¿Puede la API de Personio crear candidatos?
Sí. La API de Recruiting puede crear una candidatura para un puesto publicado que cumpla los requisitos y adjuntar documentos subidos previamente. Construye la llamada en un servicio backend y prevé errores de validación, gestión de duplicados y el límite de solicitudes específico de reclutamiento.
¿Puedo leer todos los campos y etiquetas de los candidatos?
No. Los endpoints de lectura v2 de candidatos y candidaturas indican actualmente que no devuelven atributos personalizados ni etiquetas. Verifica los campos exactos que necesita tu caso de uso de preselección o analítica antes de comprometerte con el diseño.
¿Es la interfaz DATEV de Personio lo mismo que la API pública?
No. Es una integración de nómina específica, con autorización, servicios de datos, atributos y flujos de documentos propios de DATEV. Usa la conexión nativa para el proceso de nómina compatible y añade validación a medida solo donde resuelva un requisito distinto.
¿Deberíamos desarrollar nosotros mismos una integración con Personio?
Desarrolla cuando el flujo de trabajo sea distintivo, existan las operaciones de API necesarias y tu equipo pueda operar el conector. Elige un módulo conectado cuando lo difícil sea el flujo de trabajo que lo rodea, la interfaz, la monitorización o el mantenimiento continuo, y no la transferencia de datos en sí.






