Saltar al contenido principal
Iniciar sesión
English (United States) Português do Brasil

¿Qué datos y operaciones están disponibles en la API de Oitchau?

Sucesso do Cliente
  • Actualización

La API de Oitchau permite integrar sistemas externos con la plataforma para consultar, crear y actualizar información relacionada con empleados, fichajes, Solicitudes, Horarios y la estructura organizacional de la empresa.

Entre los principales recursos disponibles se encuentran:

  • Empleados;
  • Fichajes;
  • Solicitudes;
  • Puestos;
  • Departamentos;
  • Centros de costos;
  • Subsidiaries;
  • Clientes;
  • Equipos;
  • Ubicaciones;
  • Grupos de Días Festivos;
  • Grupos de Pago;
  • Políticas de pago;
  • Horarios.

Cada operación está disponible mediante un endpoint. Antes de desarrollar la integración, consulta la documentación técnica para verificar los campos obligatorios, los formatos aceptados y los ejemplos actualizados.

Importante: la API permite consultar los fichajes y los datos de las Solicitudes. Sin embargo, no genera los archivos listos disponibles en Reportes, como Reporte de nómina, Resumen, Reporte de registros o reportes consolidados de Solicitudes.

¿Cómo acceder a las credenciales de la API?

Para utilizar la API:

  1. Accede al entorno Administrador;
  2. Abre Integraciones y Aplicaciones;
  3. Selecciona Conoce nuestra API;
  4. Consulta las credenciales de la aplicación;
  5. Copia el identificador y el secreto únicamente cuando sea necesario.

Las credenciales deben estar restringidas a las personas responsables del desarrollo y mantenimiento de la integración.

¿Cómo funciona la autenticación?

La API utiliza un token para autenticar las operaciones.

Método Endpoint Finalidad
POST /token Genera el token de acceso utilizando las credenciales de la aplicación.

Después de generar el token, envíalo en las solicitudes protegidas mediante el encabezado:

Authorization: Bearer TOKEN

El secreto de la aplicación debe tratarse como una contraseña. No lo incluyas en aplicaciones públicas, hojas de cálculo compartidas, repositorios o registros de errores.

¿Cómo interpretar los métodos?

Método Uso
GET Consulta información existente.
POST Crea registros, agrega asignaciones o ejecuta una acción.
PATCH Actualiza registros existentes.
DELETE Elimina un registro cuando la operación está disponible.

La misma ruta puede tener funciones diferentes según el método utilizado.

Endpoints de empleados

Los endpoints de empleados permiten crear, actualizar, buscar, desactivar y reactivar registros.

Método Endpoint Finalidad
POST /employees Crea uno o más empleados.
PATCH /employees Actualiza empleados existentes.
POST /deactivate_employees Desactiva empleados.
POST /activate_employees Reactiva empleados.
GET /employees Devuelve la lista de empleados.
GET /employees/find Localiza a un empleado mediante un identificador.
POST /employees/search Busca varios empleados mediante una lista de identificadores.

La búsqueda puede utilizar identificadores como:

  • UUID;
  • Matrícula;
  • CPF;
  • Correo electrónico;
  • externalId;
  • PIS;
  • Teléfono.

En la búsqueda masiva, utiliza únicamente un tipo de identificador en cada solicitud.

Según los campos aceptados por el endpoint, el registro también puede recibir asignaciones relacionadas con la estructura del empleado, como:

  • Puesto;
  • Departamento;
  • Centro de costos;
  • Supervisor;
  • Grupo de Pago;
  • Política de pago;
  • Grupo de Días Festivos;
  • Subsidiary;
  • Horario;
  • Ubicaciones.

Consulta primero los endpoints de las estructuras necesarias para obtener los identificadores correctos.

Endpoints de fichajes

Método Endpoint Finalidad
GET /punches Consulta los fichajes de la empresa.

La consulta puede utilizar filtros como:

  • Fecha de inicio;
  • Fecha final;
  • Fecha de actualización;
  • Empleado;
  • Estatus;
  • Solo fichajes clasificados;
  • Página;
  • Cantidad de resultados por página.

Los estatus disponibles en la documentación incluyen:

  • approved;
  • pending;
  • declined.

Utiliza filtros de periodo y paginación para evitar consultas demasiado extensas.

Consultar fichajes no es generar un reporte

El endpoint /punches devuelve los datos estructurados de los fichajes. No genera un archivo listo con los cálculos y la presentación de reportes como:

  • Reporte de nómina;
  • Resumen;
  • Reporte de registros;
  • Banco de horas;
  • Horas extras;
  • Entradas tardías;
  • Otros archivos disponibles en Reportes.

El sistema integrado puede utilizar los datos devueltos para construir una visualización propia, pero esa visualización no corresponde automáticamente al reporte oficial generado por Oitchau.

Endpoints de Solicitudes — Requests

Los endpoints de Requests permiten crear Solicitudes, actualizar sus estatus, enviar archivos adjuntos y consultar solicitudes.

Método Endpoint Finalidad
POST /v2/public/integrations_api/requests Crea una o más Solicitudes.
POST /v2/public/integrations_api/requests/status Actualiza el estatus de las Solicitudes.
POST /v2/public/integrations_api/requests/attachments Envía un archivo adjunto a una Solicitud.
GET /v2/public/integrations_api/requests/employees/:employeeUuid Lista las Solicitudes de un empleado.
GET /v2/public/integrations_api/requests Lista las Solicitudes de la empresa.
GET /v2/public/integrations_api/requests/employees/:employeeUuid/inbox Consulta la bandeja de entrada de Solicitudes de un empleado.

Crear Solicitudes

Utiliza:

POST /v2/public/integrations_api/requests

La operación recibe una lista de Solicitudes en el campo requests.

Entre la información presentada en la documentación se encuentra:

  • externalId: identificador personalizado de la Solicitud en el sistema externo;
  • employeeUuid: UUID del empleado;
  • employeeExternalId: identificador externo del empleado;
  • employeeMatricula: matrícula del empleado;
  • requestType: tipo de Solicitud;
  • Información sobre el periodo y si la solicitud abarca el día completo;
  • Comentario;
  • Identificación de quién está creando la Solicitud.

Es obligatorio utilizar al menos uno de los siguientes identificadores del empleado:

  • employeeUuid;
  • employeeExternalId;
  • employeeMatricula.

Si se envía más de uno, employeeUuid tendrá prioridad.

Para identificar quién está creando la Solicitud, utiliza uno de los siguientes campos:

  • createdByEmployeeUuid;
  • createdByEmployeeExternalId.

Si se envían ambos, createdByEmployeeUuid tendrá prioridad.

El campo requestType debe utilizar un tipo de Solicitud activo. La documentación presenta como ejemplos:

  • medical;
  • vacation;
  • custom.

Antes de crear la Solicitud, confirma que el tipo esté disponible para la empresa y que las fechas representen correctamente el periodo solicitado.

Actualizar los estatus de las Solicitudes

Utiliza:

POST /v2/public/integrations_api/requests/status

La operación permite actualizar las Solicitudes con los siguientes resultados:

  • Aprobada;
  • Ignorada o cancelada;
  • Rechazada.

Las Solicitudes pueden identificarse mediante UUID:

  • approvedUuids;
  • ignoredUuids;
  • declinedUuids.

También pueden identificarse mediante el ID del sistema externo:

  • approvedExternalIds;
  • ignoredExternalIds;
  • declinedExternalIds.

También es necesario identificar quién realiza la actualización mediante uno de los siguientes campos:

  • updatedByEmployeeUuid;
  • updatedByEmployeeExternalId.

En un mismo objeto de estatus, utiliza los UUID o los IDs externos. No envíes ambos formatos al mismo tiempo, ya que la documentación indica que esta combinación genera un error.

Enviar un archivo adjunto a una Solicitud

Utiliza:

POST /v2/public/integrations_api/requests/attachments

El envío se realiza como multipart/form-data.

Entre los campos presentados se encuentran:

Campo Finalidad
attachment Archivo que será adjuntado.
mimeType Tipo de archivo.
title Título del archivo adjunto.
requestUuid UUID de la Solicitud.
requestExternalId Identificador de la Solicitud en el sistema externo.
createdByEmployeeUuid UUID de quien envía el archivo.
createdByEmployeeExternalId Identificador externo de quien envía el archivo.

Para identificar la Solicitud, envía:

  • requestUuid; o
  • requestExternalId.

Si se informan ambos, requestUuid tendrá prioridad.

Para identificar quién envía el archivo, utiliza:

  • createdByEmployeeUuid; o
  • createdByEmployeeExternalId.

Si se informan ambos, createdByEmployeeUuid tendrá prioridad.

Listar las Solicitudes de un empleado

Utiliza:

GET /v2/public/integrations_api/requests/employees/:employeeUuid

El employeeUuid debe informarse en la ruta de la solicitud.

La consulta acepta filtros como:

Parámetro Finalidad
from Inicio del periodo.
to Fin del periodo.
status Filtra por estatus de la Solicitud.
since Considera Solicitudes actualizadas a partir de la fecha indicada.
side Define el papel del empleado en la Solicitud.
page Página consultada.
per_page Cantidad de resultados por página.

Los estatus presentados en la documentación son:

  • approved;
  • ignored;
  • declined.

El parámetro side acepta:

  • subject: empleado al que se refiere la Solicitud;
  • approver: empleado responsable de la aprobación.

Listar las Solicitudes de la empresa

Utiliza:

GET /v2/public/integrations_api/requests

La consulta acepta filtros como:

Parámetro Finalidad
from Inicio del periodo.
to Fin del periodo.
status Filtra por estatus de la Solicitud.
since Considera Solicitudes actualizadas a partir de la fecha indicada.
page Página consultada.
per_page Cantidad de resultados por página.
uuids Restringe la consulta a determinados UUID.
external_ids Restringe la consulta a determinados identificadores externos.

Utiliza la paginación para recorrer todos los resultados cuando la empresa tenga muchas Solicitudes.

El filtro since puede utilizarse en sincronizaciones incrementales para consultar únicamente las solicitudes actualizadas después de una fecha determinada.

Consultar la bandeja de entrada de Solicitudes

Utiliza:

GET /v2/public/integrations_api/requests/employees/:employeeUuid/inbox

Esta operación consulta la bandeja de entrada de Solicitudes del empleado indicado en employeeUuid.

La consulta acepta:

Parámetro Finalidad
status Filtra las Solicitudes por estatus.
since Considera Solicitudes actualizadas a partir de la fecha indicada.
side Define si el empleado es el solicitante o el aprobador.

El parámetro side acepta:

  • subject;
  • approver.

Esta operación puede utilizarse para consultar solicitudes relacionadas con el empleado o Solicitudes que esperan su actuación como aprobador.

Consultar Solicitudes no es exportar un reporte

Los endpoints de Requests devuelven datos estructurados para uso de la integración.

No generan automáticamente:

  • PDF de Solicitudes;
  • Hoja de cálculo consolidada de Solicitudes;
  • Reporte con la misma presentación de la plataforma;
  • Archivo listo del área de Reportes.

Por lo tanto, es posible consultar y procesar las Solicitudes mediante la API, pero no solicitar que la API genere el mismo archivo disponible en la interfaz.

Endpoints de puestos

Método Endpoint Finalidad
POST /positions Crea puestos.
PATCH /positions Actualiza puestos.
POST /deactivate_positions Desactiva puestos.
GET /positions Devuelve la lista de puestos.

Los puestos pueden identificarse mediante el UUID de Oitchau o el externalId utilizado en el sistema integrado.

Endpoints de departamentos

Método Endpoint Finalidad
POST /departments Crea departamentos.
PATCH /departments Actualiza departamentos.
GET /departments Devuelve la lista de departamentos.
GET /departments/:departmentUuid Consulta un departamento específico.
POST /departments/add_employees Agrega empleados a un departamento.
POST /departments/remove_employees Elimina empleados de un departamento.

En las operaciones de asignación, confirma el departamento, los empleados y el tipo de identificador utilizado.

Endpoints de centros de costos

Método Endpoint Finalidad
POST /cost_centers Crea centros de costos.
PATCH /cost_centers Actualiza centros de costos.
GET /cost_centers Devuelve la lista de centros de costos.
GET /cost_centers/:costCenterUuid Consulta un centro de costos específico.
POST /cost_centers/add_employees Agrega empleados a un centro de costos.
POST /cost_centers/remove_employees Elimina empleados de un centro de costos.

Estos endpoints pueden utilizarse para sincronizar la estructura organizacional con el sistema de origen.

Endpoints de Subsidiaries

Método Endpoint Finalidad
POST /subsidiaries Crea Subsidiaries.
PATCH /subsidiaries Actualiza Subsidiaries.
POST /deactivate_subsidiaries Desactiva Subsidiaries.
GET /subsidiaries Devuelve la lista de Subsidiaries.
POST /subsidiaries/:subsidiaryUuid/add_employees Agrega empleados a la Subsidiary.
POST /subsidiaries/:subsidiaryUuid/remove_employees Elimina empleados de la Subsidiary.
POST /subsidiaries/:subsidiaryUuid/add_locations Asigna Ubicaciones a la Subsidiary.
POST /subsidiaries/:subsidiaryUuid/remove_locations Elimina Ubicaciones de la Subsidiary.

Una Subsidiary puede tener empleados y Ubicaciones asignados.

Endpoints de clientes

En este contexto, Clientes representa las empresas atendidas por la empresa registrada en Oitchau.

Método Endpoint Finalidad
GET /clients Devuelve la lista de clientes.
POST /clients Crea clientes.
PATCH /clients Actualiza clientes.
POST /deactivate_clients Desactiva clientes.
POST /clients/:clientUuid/add_locations Asigna Ubicaciones al cliente.

Consulta los tipos de Ubicación aceptados antes de crear la asignación.

Endpoints de equipos

Método Endpoint Finalidad
POST /teams Crea Equipos y define su Supervisor.
PATCH /teams Actualiza Equipos.
POST /deactivate_teams Desactiva Equipos.
GET /teams Devuelve la lista de Equipos.
POST /teams/:teamUuid/add_employees Agrega empleados al Equipo.
POST /teams/:teamUuid/remove_employees Elimina empleados del Equipo.

Cuando la integración cree Supervisores y sus subordinados, registra primero al Supervisor para que pueda realizarse la asignación.

Endpoints de Ubicaciones

Método Endpoint Finalidad
POST /locations Crea Ubicaciones.
PATCH /locations Actualiza Ubicaciones.
POST /deactivate_locations Desactiva Ubicaciones.
GET /locations Devuelve la lista de Ubicaciones.
POST /locations/:locationUuid/add_employees Autoriza empleados en la Ubicación.
POST /locations/:locationUuid/remove_employees Elimina empleados de la Ubicación.

Las Ubicaciones pueden utilizar información como:

  • Nombre;
  • Código;
  • Tipo;
  • Dirección;
  • Latitud;
  • Longitud;
  • Radio.

Consulta los formatos aceptados por la operación antes de crear o actualizar una Ubicación.

Endpoints de Grupos de Días Festivos

Método Endpoint Finalidad
GET /holidays-groups Devuelve los Grupos de Días Festivos.
POST /holidays-groups Crea un Grupo de Días Festivos.
GET /holidays-groups/:holidaysGroupUuid Consulta un grupo específico.
POST /deactivate_holidays_groups Desactiva Grupos de Días Festivos.
POST /activate_holidays_groups Reactiva Grupos de Días Festivos.
POST /holidays-groups/:holidaysGroupUuid/add_employees Agrega empleados al grupo.
POST /holidays-groups/:holidaysGroupUuid/remove_employees Elimina empleados del grupo.
POST /holidays-groups/:holidaysGroupUuid/add_holidays Agrega días festivos al grupo.
POST /holidays-groups/:holidaysGroupUuid/delete_holidays Elimina días festivos del grupo.
GET /holidays-groups/holidays/employees/:employeeUuid Consulta los días festivos aplicables a un empleado.

En las operaciones de asignación, revisa la fecha en la que debe comenzar la inclusión o eliminación.

Endpoints de consulta de la empresa y de los grupos

Método Endpoint Finalidad
GET /company Devuelve los datos de la empresa asociada con las credenciales.
GET /payroll_groups_list Devuelve los Grupos de Pago.
GET /business_rules_groups Devuelve las Políticas de pago.

Estas consultas pueden utilizarse para obtener los identificadores necesarios antes de crear o actualizar empleados.

Endpoints de Horarios

Método Endpoint Finalidad
GET /schedules/list Devuelve la lista de Horarios.
POST /companies/:companyUuid/schedules/:scheduleUuid/user_profiles Asigna empleados a un Horario mediante UUID.
POST /companies/:companyUuid/external_id_schedule_assignments Asigna empleados a un Horario mediante el identificador externo.
GET /companies/:companyUuid/user_profiles/:userProfileUuid/shifts Consulta los turnos de un empleado en una fecha.

En las asignaciones, verifica:

  • La empresa;
  • El Horario;
  • Los empleados;
  • La Fecha de inicio;
  • Los identificadores utilizados.

Ejemplo de flujo para sincronizar Solicitudes

Una integración puede seguir esta secuencia:

  1. Generar el token de autenticación;
  2. Localizar al empleado;
  3. Confirmar el tipo de Solicitud que se utilizará;
  4. Crear la Solicitud con un externalId;
  5. Registrar el identificador devuelto por la operación;
  6. Enviar el archivo adjunto, cuando sea necesario;
  7. Consultar las Solicitudes del empleado o de la empresa;
  8. Actualizar el estatus cuando la integración sea responsable de esa operación;
  9. Utilizar since en las siguientes consultas para buscar únicamente cambios recientes.

Consejos y solución de problemas

  • La autenticación falló: genera un nuevo token y revisa las credenciales y el encabezado Authorization;
  • No se encontró al empleado: revisa el UUID, externalId o matrícula utilizada;
  • La Solicitud se creó para la persona incorrecta: revisa la prioridad entre los identificadores enviados;
  • La actualización de estatus devolvió un error: no combines UUID e IDs externos en el mismo objeto de estatus;
  • No se envió el archivo adjunto: verifica que la solicitud utilice multipart/form-data y que la Solicitud y el responsable estén identificados;
  • La consulta no devolvió todas las Solicitudes: revisa page y per_page;
  • Necesito buscar únicamente cambios recientes: utiliza el parámetro since;
  • Necesito consultar las Solicitudes de una persona: utiliza el endpoint con employeeUuid;
  • Necesito consultar todas las Solicitudes de la empresa: utiliza GET /v2/public/integrations_api/requests;
  • Necesito consultar Solicitudes que dependen de un aprobador: utiliza el endpoint de inbox con side=approver;
  • Necesito descargar una hoja de cálculo de Solicitudes: la API permite consultar los datos, pero no genera el archivo;
  • Necesito descargar un Reporte de nómina: utiliza el área de Reportes de la plataforma.

Mejores prácticas

  • Utiliza externalId para mantener el vínculo entre los sistemas;
  • Verifica si el empleado ya existe antes de crearlo;
  • No utilices únicamente nombre, teléfono o correo electrónico como identificador permanente;
  • Registra el externalId de cada Solicitud creada por la integración;
  • No combines UUID e IDs externos en las actualizaciones de estatus;
  • Utiliza paginación en las consultas de listas;
  • Utiliza since para realizar sincronizaciones incrementales;
  • Limita las consultas de fichajes y Solicitudes a los periodos necesarios;
  • No registres el secreto de la aplicación en los logs;
  • Protege los archivos adjuntos y los datos personales devueltos;
  • Prueba la integración con pocos registros antes de realizar operaciones masivas;
  • Consulta la documentación antes de agregar nuevos campos u operaciones.

Preguntas frecuentes

  1. ¿Es posible generar reportes de asistencia mediante la API?

    No. La API no genera archivos como Reporte de nómina, Resumen o Reporte de registros.

  2. ¿Es posible consultar los fichajes mediante la API?

    Sí. Utiliza GET /punches. La respuesta contiene los datos de los fichajes, no un reporte listo.

  3. ¿Es posible crear Solicitudes mediante la API?

    Sí. Utiliza:

    POST /v2/public/integrations_api/requests

  4. ¿Es posible consultar las Solicitudes de un empleado?

    Sí. Utiliza:

    GET /v2/public/integrations_api/requests/employees/:employeeUuid

  5. ¿Es posible consultar las Solicitudes de toda la empresa?

    Sí. Utiliza:

    GET /v2/public/integrations_api/requests

  6. ¿Es posible consultar la bandeja de entrada de Solicitudes de un aprobador?

    Sí. Utiliza el endpoint de inbox e indica al empleado:

    GET /v2/public/integrations_api/requests/employees/:employeeUuid/inbox

  7. ¿Es posible aprobar, cancelar o rechazar Solicitudes mediante la API?

    Sí. Utiliza el endpoint de actualización de estatus:

    POST /v2/public/integrations_api/requests/status

  8. ¿Es posible enviar archivos adjuntos a una Solicitud?

    Sí. Utiliza:

    POST /v2/public/integrations_api/requests/attachments

  9. ¿Puedo identificar al empleado mediante la matrícula?

    Al crear la Solicitud, la documentación permite utilizar employeeUuid, employeeExternalId o employeeMatricula.

  10. ¿Qué sucede si envío más de un identificador del empleado?

    employeeUuid tendrá prioridad sobre el identificador externo y la matrícula.

  11. ¿Puedo utilizar UUID e IDs externos al actualizar el estatus?

    Utiliza únicamente uno de los formatos en el mismo objeto de estatus. Enviar ambos genera un error.

  12. ¿Es posible descargar un reporte de Solicitudes mediante la API?

    No. La API devuelve datos estructurados, pero no genera un PDF ni una hoja de cálculo consolidada.

  13. ¿Cómo puedo consultar únicamente Solicitudes actualizadas recientemente?

    Utiliza el parámetro since en los endpoints de consulta.

  14. ¿La API devuelve todos los resultados en una sola solicitud?

    No siempre. Utiliza page y per_page para recorrer los resultados.

  15. ¿Para qué sirve externalId?

    Mantiene el vínculo entre el registro creado en Oitchau y el registro correspondiente en el sistema externo.

  16. ¿Dónde encuentro los campos completos de cada operación?

    Consulta la documentación técnica de la API para verificar los campos, ejemplos y reglas actuales.

Artículos relacionados

Comentarios

0 comentarios

Inicie sesión para dejar un comentario.