Este artículo explica cómo generar y gestionar credenciales para las API públicas de Personio. Las API permiten a Personio compartir datos con otros servicios o herramientas. Las credenciales de la API actúan como una clave que controla el flujo de información y decide qué se comparte.
Antes de empezar
- Para usar el Marketplace y configurar las integraciones, tienes que tener permisos de edición para Integración de Marketplace y la API.
- Para crear tu propia integración personalizada usando nuestra API pública, tienes que tener el plan Core Pro de Personio.
- Personio crea automáticamente credenciales de API para todas las integraciones, excepto para las personalizadas.
Más información sobre las credenciales de API
Las credenciales de la API crean conexiones y protegen la comunicación entre aplicaciones. En Personio, el sistema crea credenciales de API para lo siguiente:
- API de reclutamiento
- Integraciones de Personio
- Integraciones de socios de Personio
No puedes gestionar estas credenciales. Puedes actualizar estas integraciones a través del Marketplace de Personio. El sistema configura la mayoría de los permisos de acceso a la API en el nivel necesario para que la integración funcione. Por lo general, generas y administras las credenciales de API manualmente para las integraciones personalizadas.
Ten en cuenta que:
Cuando vayas a Ajustes > Credenciales de la API, Personio te redirigirá a Marketplace > Integraciones conectadas. Aquí es donde están todas las integraciones, tanto las integraciones de Marketplace como las integraciones personalizadas que hayas creado tú.
Cómo funciona el acceso API para Integraciones personalizadas
Cuando configuras una integración personalizada, defina sus permisos de acceso (por ejemplo, si puede leer o escribir datos en áreas como Empleados, Registros de jornada, Ausencias y Documentos). La integración utiliza entonces sus credenciales API (ID de cliente y secreto API) para autenticar solicitudes API.
El acceso API funciona de manera diferente al acceso basado en roles de empleados en Personio. Los permisos de los roles de empleado controlan lo que los usuarios pueden ver y hacer en la interfaz de Personio, pero no controlan lo que las integraciones personalizadas pueden obtener a través de la API. Esto significa que no puedes limitar el acceso a la API únicamente a los empleados con un rol específico usando los permisos de los roles de empleado.
Ten en cuenta que:
Cualquier persona con acceso a las credenciales de la API puede recuperar casi todos los datos de la cuenta de Personio a través de la API, independientemente de sus permisos en Personio. Los permisos del rol de empleado se aplican únicamente a la interfaz. No restringen lo que se puede recuperar a través de la API. Otorga acceso a las credenciales de la API únicamente a usuarios de confianza.
Genera credenciales de API para integraciones personalizadas
Para generar credenciales para integraciones personalizadas:
- Ve a Marketplace > Integraciones conectadas.
- Haz clic en Crear integración personalizada en la parte superior derecha de la pantalla. Este botón solo está disponible si tienes el plan Core Pro de Personio. Si no lo ves, comprueba el plan actual en Ajustes > Cuenta y ayuda > Suscripción y facturación para confirmar que tienes el plan Core Pro.
- Configura los ajustes.
Ten en cuenta que:
Los permisos de escritura no incluyen acceso de lectura. Si desea recuperar datos a través de nuestras API, también tiene que otorgar permisos de lectura.
La siguiente tabla muestra lo que cada permiso deja hacer a un sistema de terceros. Algunos permisos otorgan acceso de solo lectura. Para obtener detalles sobre los endpoint, visita el Centro de desarrolladores.
Permisos de integración |
Permisos de lectura | Permisos de escritura |
|---|---|---|
Empleados |
Permitir que los sistemas de terceros obtengan datos de Personio. Al activar el permiso de lectura para los empleados, aparece una lista de atributos de empleado legibles. Selecciona solo los atributos que quieras que la integración recupere. Cualquier atributo que no selecciones no será accesible a través de las solicitudes GET de esa credencial. |
Permitir que los sistemas de terceros creen y actualicen datos en Personio. |
Registros de jornada |
Permitir que los sistemas de terceros obtengan datos de Personio. | Permitir que los sistemas de terceros creen, actualicen y eliminen datos en Personio. |
Ausencia |
Permitir que los sistemas de terceros obtengan datos de Personio. | Permitir que los sistemas de terceros creen y actualicen datos en Personio. |
Documentos |
Permitir que los sistemas de terceros obtengan ID de categoría de documento de Personio. | Permitir que los sistemas de terceros creen documentos en Personio. |
Informes personalizados |
Permitir que los sistemas de terceros recuperen todos los informes personalizados ya creados de Personio. Marca esta casilla para que todos los atributos de un informe personalizado sean recuperables. Activar el permiso de acceso a Informes personalizados anula las selecciones de atributos de empleado legibles. La integración puede recuperar cualquier atributo incluido en esos informes, incluso atributos que no hayas seleccionado tú. |
No aplicable. |
| Remuneraciones | Permitir que sistemas de terceros extraigan datos de remuneración de Personio. | Permitir que sistemas de terceros creen y actualicen datos de remuneración en Personio. |
Reclutamiento |
Permitir que los sistemas de terceros obtengan datos de Personio. | Permitir que los sistemas de terceros creen y actualicen datos en Personio. |
Webhooks |
Recuperar metadatos del webhook. |
Crear, actualizar y eliminar webhooks. Los permisos de lectura y escritura no afectan al desencadenante de un webhook. Un webhook sigue funcionando después de que lo creas, sin importar la configuración de permisos. Obtén más información sobre los webhooks en nuestra documentación técnica. |
Unidades organizativas |
Permitir que los sistemas de terceros obtengan datos de Personio. | No aplicable. |
Entidades legales |
Permitir que los sistemas de terceros obtengan datos de Personio. | No aplicable. |
Centros de costes |
Permitir que los sistemas de terceros obtengan datos de Personio. | No aplicable. |
Centros de trabajo |
Permitir que los sistemas de terceros obtengan datos de Personio. | No aplicable. |
Informes |
Permitir que los sistemas de terceros obtengan datos de Personio. | No aplicable. |
Requisitos de permisos de la API y disponibilidad de datos
Activar el acceso a Registro de jornada también permite que su integración utilice el endpoint de la API de Proyectos (/v2/projects) para integraciones personalizadas. No existe un permiso de Proyectos independiente en los ajustes de las credenciales.
Para que la API de Remuneraciones devuelva datos del salario, los empleados tienen que estar asignados a una entidad legal en Personio. Los empleados sin una entidad legal asignada no aparecen en las respuestas de la API de remuneraciones.
Los nombres de los atributos en los selectores Atributos del empleado legibles y Entidades legales legibles aparecen en inglés, independientemente del idioma que hayas configurado en la cuenta de Personio. Si no encuentras un atributo, busca el equivalente en inglés.
Autenticar las solicitudes de la API
Tras generar las credenciales de la API, tienes que intercambiarlas por un código de portador antes de realizar cualquier llamada a la API. No puedes usar la clave del cliente directamente como código de portador.
Para obtener un código de portador:
- Envía una solicitud POST al endpoint de autenticación: POST https://api.personio.de/v2/auth/token con Content-Type: application/x-www-form-urlencoded y los siguientes parámetros: grant_type=client_credentials, client_id={your_client_id}, client_secret={your_client_secret}
- La respuesta devuelve un código de portador. Inclúyelo en el encabezado de autorización de cada solicitud de la API posterior: Autorización: Portador {código}
Los códigos de portador son válidos durante 24 horas. Genera otro código cuando venzan. Puedes encontrar el ID de cliente y la clave del cliente en Ajustes > Seguridad e integraciones > Credenciales de la API.
Actualice las credenciales de la API para las integraciones personalizadas
Para actualizar los permisos de las integraciones personalizadas:
- Ve a Marketplace > Integraciones conectadas.
- Haz clic en la integración para actualizarla.
- En la ventana que aparece, realiza los cambios.
- Guarda los ajustes configurados.
También puedes restablecer las credenciales de API desde aquí siguiendo las instrucciones.
Desconecte o deshabilite las credenciales de la API para las integraciones personalizadas
Para desconectar o deshabilitar las credenciales de la API para las integraciones personalizadas:
- Ve a Marketplace > Integraciones conectadas.
- En la columna Acción, haz clic en los tres puntos.
- Haz clic en Deshabilitar para deshabilitar temporalmente las credenciales.
- Haz clic en Desconectar para eliminar las credenciales de forma permanente.
Si no sabes si una integración sigue en uso, escoge Deshabilitar en lugar de Desconectar. “Deshabilitar” desactiva la integración, pero la mantiene visible en Marketplace > Integraciones conectadas. Si la integración está activa, puedes volver a activarla. La desconexión elimina permanentemente las credenciales y esta acción no se puede deshacer.
Generar las credenciales de la API
Para rotar las credenciales de una integración personalizada o de terceros en Marketplace sin interrupciones del servicio, crea un conjunto de credenciales antes de desactivar las antiguas. Pueden coexistir varias credenciales activas, así que la integración puede seguir funcionando con las credenciales antiguas mientras la actualizas para usar las nuevas.
Para restablecer las credenciales, haz lo siguiente:
- Ve a Marketplace > Integraciones conectadas.
- Selecciona la integración.
- Abre la pestaña Credenciales de la API y sigue las instrucciones para restablecerlas.
Personio no admite la rotación automatizada de credenciales. Tienes que rotar las credenciales manualmente.
Acceder a la documentación técnica
Encuentra toda la documentación de la API en nuestro Centro para desarrolladores. Esto incluye endpoints, webhooks, detalles de datos y tutoriales. El Centro para desarrolladores tiene dos versiones con contenido diferente. La información de los webhooks está en la versión 2.0. Para cambiar de versión, haz clic en el número de versión en la parte superior de la página de inicio.