Este artículo proporciona toda la información que necesitan los clientes de Personio que participan en la prueba beta de la API de informes personalizados. Gracias por participar en esta prueba beta.
Consejo
Haz clic en el botón Seguir que se encuentra en la esquina superior derecha para recibir por correo electrónico información actualizada sobre los diferentes avances y fases beta.
Fases de la prueba beta
El calendario previsto para esta prueba beta es el siguiente:
|
Fecha |
Descripción |
|
Semana 34 |
Inicio de la fase beta: Las funcionalidades enumeradas a continuación están activadas en tu cuenta de Personio. |
|
Semana 38 |
Publicación global: las funcionalidades mencionadas anteriormente están disponibles para todos los clientes |
Análisis de las pruebas beta
Las siguientes funcionalidades están disponibles en la actual fase beta:
-
Endpoint para obtener una lista de los informes personalizados existentes:
Este endpoint te proporciona metadatos sobre los informes personalizados existentes en tu cuenta de Personio, como el nombre del informe, el tipo de informe, la fecha / el período del informe. -
Endpoint para obtener una lista de columnas/definiciones de atributos:
Este endpoint proporciona etiquetas legibles para las columnas de la tabla del informe.Es especialmente importante si obtienes un informe con atributos personalizados o datos de ausencia, ya que tendrás que hacer coincidir los ID de las columnas con la traducción. -
Endpoint para obtener los datos de un informe personalizado existente:
Este endpoint te proporciona los datos de un informe personalizado existente en formato JSON.
Para utilizar el endpoint de informes personalizados, genera credenciales o activa el endpoint de lectura para un par de credenciales existentes. Actualmente no hay un endpoint de escritura implementado.
Nota
Todos los informes existentes se pueden recuperar si el endpoint de lectura está habilitado. Además, la sección Atributos legibles del empleado para la API de datos del empleado no se tendrá en cuenta para el endpoint de los informes personalizados. Todos los atributos añadidos a un informe personalizado se podrán recuperar a través del endpoint si está habilitado para las credenciales correspondientes, sin importar si el atributo se ha incluido en la lista blanca o no.
Acceso y autorización de la API
Puede encontrar información detallada sobre el acceso general y la autorización en el Centro de desarrolladores de Personio.
Endpoints de los informes personalizados
Para utilizar los endpoints de informes personalizados, deberás generar credenciales de API (client_id y client_secret). Para ello, sigue estos pasos:
- Haz clic en Generar nueva credencial.
- Marca Leer para Informes personalizados. También es posible activar el endpoint de lectura de informes personalizados para un par de credenciales existentes.
La API de informes personalizados permite recuperar todas las filas y campos de un informe personalizado formateado en JSON y listo para su posterior análisis o consumo. Actualmente, la API no permite crear o actualizar un informe existente.
Un caso de uso común para la API de informes personalizados es exportar los datos contenidos en un informe personalizado de Personio a otros sistemas, como una herramienta de inteligencia empresarial o un almacén de datos.
Cuando utilices la API de informes personalizados, ten en cuenta los siguientes puntos:
Grandes conjuntos de datos o rangos de tiempo
Para los informes que incluyen un gran número de empleados o que abarcan amplios intervalos de fechas, se recomienda consultar primero el endpoint de GetReports para recuperar la marca de tiempo data_refreshed_at para el informe de interés. Esto debe hacerse antes de recuperar el contenido del informe utilizando el endpoint GetReportData para asegurarse de que haya transcurrido un período de tiempo suficiente desde la anterior actualización de datos.
Atributos personalizados
Los atributos personalizados de los empleados tienen un ID de atributo que comienza con el prefijo dynamic_, que se proporciona cuando se recupera el contenido del informe utilizando el endpoint GetReport. Para recuperar el nombre legible para las personas del atributo, es necesario utilizar primero el endpoint GetColumns, que permite hacer referencia cruzada del ID del atributo con su nombre legible para las personas. Los nombres de otras configuraciones regionales pueden obtenerse añadiendo al endpoint de GetColumns ?locale=<un código de configuración regional de 2 caracteres>, por ejemplo .../columns?locale=EN
Obtén el endpoint de los informes
Método HTTP - GET
https://api.personio.de/v1/company/custom-reports/reportsEl propósito de este endpoint es recuperar la lista de los informes personalizados existentes en tu cuenta. Ten en cuenta que solo puedes recuperar los informes que ya hayan sido creados dentro de la plataforma Personio.
Ejemplo de respuesta{
"success": true,
"metadata": {
"total_elements": 92,
"current_page": 1,
"total_pages": 1
},
"offset": 0,
"limit": 0,
"data": [
{
"type": "Report",
"attributes": {
"id": "9f1edbf3-f68e-4f13-83e3-9b1400bacw313",
"name": "Test Report",
"description": "This is a description",
"author_first_name": "Robert",
"author_last_name": "Wilson",
"type": "point_in_time",
"status": "UP_TO_DATE",
"start_date": "2022-07-13",
"end_date": "2022-07-13",
"created_at": "2022-07-11T12:39:05Z",
"updated_at": "2022-07-12T09:45:13Z",
"data_refreshed_at": "2022-07-12T09:45:13Z",
"columns": [
"first_name",
"last_name",
"position",
"team_id",
"department_id",
"fix_salary",
"dynamic_1945114"
],
"filters": [
{
"column": "subcompany_id",
"comparison": "neq",
"value": "7996"
},
{
"column": "subcompany_id",
"comparison": "neq",
"value": "21963"
},
],
"period_type": "today",
"items": null
}
}
]
}Endpoint de Get columns
Método HTTP - GET
https://api.personio.de/v1/company/custom-reports/columns?locale=de
El propósito de este endpoint es recuperar una lista de todas las columnas disponibles para permitir a los usuarios asignar column_id a la traducción legible para el ser humano.
Ejemplo de respuesta{
"success": true,
"metadata": {
"total_elements": 232,
"current_page": 1,
"total_pages": 1
},
"offset": 0,
"limit": 0,
"data": [
{
"type": "Column",
"attributes": {
"id": "id",
"human_readable": "ID",
"data_type": "INTEGER"
}
},
{
"type": "Column",
"attributes": {
"id": "first_name",
"human_readable": "First name",
"data_type": "TEXT"
}
},
{
"type": "Column",
"attributes": {
"id": "last_name",
"human_readable": "Last name",
"data_type": "TEXT"
}
},
{
"type": "Column",
"attributes": {
"id": "email",
"human_readable": "Email",
"data_type": "TEXT"
}
},
{
"type": "Column",
"attributes": {
"id": "dynamic_47589",
"human_readable": "Birthday",
"data_type": "DATE"
}
}
]
}Consejo
Para ofrecer datos más relevantes para la elaboración de informes, los tipos de datos de la columna del endpoint de los informes personalizados pueden ser diferentes de data_types en el endpoint de los empleados.
Obtener endpoint de datos del informeMétodo HTTP - GET
https://api.personio.de/v1/company/custom-reports/reports/{report_id}El objetivo de este endpoint es recuperar los datos de un informe personalizado existente en tu cuenta.
Ejemplo de respuesta{
"success": true,
"metadata": {
"total_elements": 114,
"current_page": 1,
"total_pages": 1
},
"offset": 0,
"limit": 0,
"data": [
{
"type": "Report",
"attributes": {
"id": "9f1edbf3-f65e-4f13-83e9-9b1400bace13",
"name": "Report Name",
"description": "This is a description",
"author_first_name": "Robert",
"author_last_name": "Wilson",
"type": "point_in_time",
"status": "UP_TO_DATE",
"start_date": "2022-07-12",
"end_date": "2022-07-12",
"created_at": "2022-07-11T12:39:05Z",
"updated_at": "2022-07-12T09:45:13Z",
"data_refreshed_at": "2022-07-12T09:45:13Z",
"columns": [
"first_name",
"last_name",
"position",
"team_id",
"department_id",
"fix_salary",
"dynamic_1945114"
],
"filters": [],
"period_type": "today",
"items": [
{
"employee_id": 1314107,
"attributes": [
{
"attribute_id": "first_name",
"data_type": "TEXT",
"value": "Adella Lena"
},
{
"attribute_id": "last_name",
"data_type": "TEXT",
"value": "Broose-Maier"
},
{
"attribute_id": "position",
"data_type": "TEXT",
"value": "Director Engineering"
},
{
"attribute_id": "team_id",
"data_type": "ENTITY",
"entity_id": "64728",
"value": "Executive Team"
},
{
"attribute_id": "department_id",
"data_type": "ENTITY",
"entity_id": "412781",
"value": "Product & Engineering"
},
{
"attribute_id": "fix_salary",
"data_type": "SALARY",
"amount": "100000.00",
"currency_symbol": "$"
},
{
"attribute_id": "fix_salary_interval",
"data_type": "TEXT",
"value": "yearly"
},
{
"attribute_id": "dynamic_1945114",
"data_type": "OPTION",
"value": "Festanstellung/Permanent position"
}
]
},
{
"employee_id": 2610586,
"attributes": [
{
"attribute_id": "first_name",
"data_type": "TEXT",
"value": "Joline"
},
{
"attribute_id": "last_name",
"data_type": "TEXT",
"value": "Sicha"
},
{
"attribute_id": "position",
"data_type": "TEXT",
"value": "Engineering Manager"
},
{
"attribute_id": "team_id",
"data_type": "ENTITY",
"entity_id": "64938",
"value": "A Team"
},
{
"attribute_id": "department_id",
"data_type": "ENTITY",
"entity_id": "346001",
"value": "Research & Development"
},
{
"attribute_id": "fix_salary",
"data_type": "SALARY",
"amount": "70000.00",
"currency_symbol": "$"
},
{
"attribute_id": "fix_salary_interval",
"data_type": "TEXT",
"value": "yearly"
},
{
"attribute_id": "dynamic_1945114",
"data_type": "OPTION",
"value": "Festanstellung/Permanent position"
}
]
}
]
}
}
]
}Nota
Para el tipo de informe Datos históricos, la respuesta de los valores históricos se coteja solo con el employee_id. El nombre y los apellidos no se incluirán. Para emparejar el employee_id con el nombre, se puede recuperar el endpoint del empleado.Consejo
Si necesitas más información, encontrarás un archivo openapi.yaml en la sección Descargas de este artículo.Feedback
Como cliente de la versión beta, tienes la oportunidad de dar forma activamente a la experiencia de la evaluación por parte de un compañero para la API de informes personalizados. La función que estás probando se encuentra en una fase inicial de desarrollo, y nos encantaría conocer tu opinión sobre ella. Cuanto antes recibamos tu feedback, mejor, ya que así podremos analizarlo y tenerlo en cuenta para futuras mejoras.
Para ello utiliza el siguiente formulario:
Nota
Todos los evaluadores de la versión beta deben enviar sus comentarios al menos una vez durante la fase de prueba mediante el formulario Typeform que aparece a continuación.