Quais dados e operações estão disponíveis na API Oitchau? – Oitchau

A API Oitchau permite integrar sistemas externos à plataforma para consultar, criar e atualizar informações relacionadas aos colaboradores, registros de ponto, Pedidos, Jornadas e à estrutura organizacional da empresa.

Entre os principais recursos disponíveis estão:

Colaboradores;
Registros de ponto;
Pedidos;
Cargos;
Departamentos;
Centros de custo;
Filiais;
Clientes;
Times;
Localizações;
Grupos de Feriados;
Grupos de Pagamento;
Grupos de Regras;
Jornadas;

Cada operação é disponibilizada por meio de um endpoint. Antes de desenvolver a integração, consulte a documentação técnica para conferir os campos obrigatórios, os formatos aceitos e os exemplos atualizados.

Importante: a API permite consultar os registros de ponto e os dados dos Pedidos. No entanto, ela não gera os arquivos prontos disponíveis em Relatórios, como Folha de Frequência, Resumo, Espelho de Ponto ou relatórios consolidados de Pedidos.

Como acessar as credenciais da API?

Para utilizar a API:

Acesse o ambiente Administrador;
Abra Integrações e Aplicativos;
Selecione Conheça nossa API;
Consulte as credenciais da aplicação;
Copie o identificador e o segredo somente quando necessário.

As credenciais devem ficar restritas às pessoas responsáveis pelo desenvolvimento e pela manutenção da integração.

Como funciona a autenticação?

A API utiliza um token para autenticar as operações.

Método	Endpoint	Finalidade
`POST`	`/token`	Gera o token de acesso utilizando as credenciais da aplicação.

Depois de gerar o token, envie-o nas requisições protegidas pelo cabeçalho:

Authorization: Bearer TOKEN

O segredo da aplicação deve ser tratado como uma senha. Não o inclua em aplicativos públicos, planilhas compartilhadas, repositórios ou registros de erro.

Como interpretar os métodos?

Método	Utilização
`GET`	Consulta informações existentes.
`POST`	Cria registros, adiciona vínculos ou executa uma ação.
`PATCH`	Atualiza registros existentes.
`DELETE`	Exclui um registro quando a operação estiver disponível.

O mesmo caminho pode possuir funções diferentes de acordo com o método utilizado.

Endpoints de colaboradores

Os endpoints de colaboradores permitem criar, atualizar, pesquisar, desativar e reativar cadastros.

Método	Endpoint	Finalidade
`POST`	`/employees`	Cria um ou mais colaboradores.
`PATCH`	`/employees`	Atualiza colaboradores existentes.
`POST`	`/deactivate_employees`	Desativa colaboradores.
`POST`	`/activate_employees`	Reativa colaboradores.
`GET`	`/employees`	Retorna a lista de colaboradores.
`GET`	`/employees/find`	Localiza um colaborador por um identificador.
`POST`	`/employees/search`	Pesquisa vários colaboradores por uma lista de identificadores.

A busca pode utilizar identificadores como:

UUID;
Matrícula;
CPF;
E-mail;
externalId;
PIS;
Telefone.

Na pesquisa em lote, utilize somente um tipo de identificador em cada requisição.

Conforme os campos aceitos pelo endpoint, o cadastro também pode receber vínculos relacionados à estrutura do colaborador, como:

Cargo;
Departamento;
Centro de custo;
Supervisor;
Grupo de Pagamento;
Grupo de Regras;
Grupo de Feriados;
Filial;
Jornada;
Localizações.

Consulte primeiro os endpoints das estruturas necessárias para obter os identificadores corretos.

Endpoints de registros de ponto

Método	Endpoint	Finalidade
`GET`	`/punches`	Consulta os registros de ponto da empresa.

A consulta pode utilizar filtros como:

Data inicial;
Data final;
Data de atualização;
Colaborador;
Status;
Apenas pontos classificados;
Página;
Quantidade de resultados por página.

Os status disponíveis na documentação incluem:

approved;
pending;
declined.

Utilize filtros de período e paginação para evitar consultas muito extensas.

Consulta de pontos não é geração de relatório

O endpoint /punches retorna os dados estruturados dos registros de ponto. Ele não gera um arquivo pronto com os cálculos e a apresentação de relatórios como:

Folha de Frequência;
Resumo;
Espelho de Ponto;
Banco de Horas;
Horas Extras;
Atrasos;
Outros arquivos disponíveis em Relatórios.

O sistema integrado pode utilizar os dados retornados para construir uma visualização própria, mas essa visualização não corresponde automaticamente ao relatório oficial gerado pela Oitchau.

Endpoints de Pedidos — Requests

Os endpoints de Requests permitem criar Pedidos, atualizar seus status, enviar anexos e consultar solicitações.

Método	Endpoint	Finalidade
`POST`	`/v2/public/integrations_api/requests`	Cria um ou mais Pedidos.
`POST`	`/v2/public/integrations_api/requests/status`	Atualiza o status de Pedidos.
`POST`	`/v2/public/integrations_api/requests/attachments`	Envia um anexo para um Pedido.
`GET`	`/v2/public/integrations_api/requests/employees/:employeeUuid`	Lista os Pedidos de um colaborador.
`GET`	`/v2/public/integrations_api/requests`	Lista os Pedidos da empresa.
`GET`	`/v2/public/integrations_api/requests/employees/:employeeUuid/inbox`	Consulta a caixa de entrada de Pedidos de um colaborador.

Criar Pedidos

Utilize:

POST /v2/public/integrations_api/requests

A operação recebe uma lista de Pedidos no campo requests.

Entre as informações apresentadas pela documentação estão:

externalId: identificador personalizado do Pedido no sistema externo;
employeeUuid: UUID do colaborador;
employeeExternalId: identificador externo do colaborador;
employeeMatricula: matrícula do colaborador;
requestType: tipo do Pedido;
Informações sobre o período e se a solicitação abrange o dia inteiro;
Comentário;
Identificação de quem está criando o Pedido.

É obrigatório utilizar pelo menos um dos seguintes identificadores do colaborador:

employeeUuid;
employeeExternalId;
employeeMatricula.

Caso mais de um seja enviado, o employeeUuid terá prioridade.

Para identificar quem está criando a solicitação, utilize um dos seguintes campos:

createdByEmployeeUuid;
createdByEmployeeExternalId.

Caso os dois sejam enviados, o createdByEmployeeUuid terá prioridade.

O campo requestType deve utilizar um tipo de Pedido ativo. A documentação apresenta como exemplos:

medical;
vacation;
custom.

Antes de criar o Pedido, confirme se o tipo está disponível para a empresa e se as datas representam corretamente o período solicitado.

Atualizar os status dos Pedidos

Utilize:

POST /v2/public/integrations_api/requests/status

A operação permite atualizar Pedidos para os seguintes resultados:

Aprovado;
Ignorado ou cancelado;
Recusado.

Os Pedidos podem ser identificados por UUID:

approvedUuids;
ignoredUuids;
declinedUuids.

Também podem ser identificados pelo ID do sistema externo:

approvedExternalIds;
ignoredExternalIds;
declinedExternalIds.

É necessário informar também quem está realizando a atualização por meio de um dos seguintes campos:

updatedByEmployeeUuid;
updatedByEmployeeExternalId.

Em um mesmo objeto de status, utilize os UUIDs ou os IDs externos. Não envie os dois formatos ao mesmo tempo, pois a documentação informa que essa combinação gera erro.

Enviar um anexo para um Pedido

Utilize:

POST /v2/public/integrations_api/requests/attachments

O envio é realizado como multipart/form-data.

Entre os campos apresentados estão:

Campo	Finalidade
`attachment`	Arquivo que será anexado.
`mimeType`	Tipo do arquivo.
`title`	Título do anexo.
`requestUuid`	UUID do Pedido.
`requestExternalId`	Identificador do Pedido no sistema externo.
`createdByEmployeeUuid`	UUID de quem está enviando o anexo.
`createdByEmployeeExternalId`	Identificador externo de quem está enviando.

Para identificar o Pedido, envie:

requestUuid; ou
requestExternalId.

Caso os dois sejam informados, o requestUuid terá prioridade.

Para identificar quem está enviando o arquivo, envie:

createdByEmployeeUuid; ou
createdByEmployeeExternalId.

Caso os dois sejam informados, o createdByEmployeeUuid terá prioridade.

Listar os Pedidos de um colaborador

Utilize:

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

O employeeUuid deve ser informado no caminho da requisição.

A consulta aceita filtros como:

Parâmetro	Finalidade
`from`	Início do período.
`to`	Fim do período.
`status`	Filtra pelo status do Pedido.
`since`	Considera solicitações atualizadas a partir da data informada.
`side`	Define o lado do colaborador na solicitação.
`page`	Página consultada.
`per_page`	Quantidade de resultados por página.

Os status apresentados na documentação são:

approved;
ignored;
declined.

O parâmetro side aceita:

subject: colaborador ao qual o Pedido se refere;
approver: colaborador responsável pela aprovação.

Listar os Pedidos da empresa

Utilize:

GET /v2/public/integrations_api/requests

A consulta aceita filtros como:

Parâmetro	Finalidade
`from`	Início do período.
`to`	Fim do período.
`status`	Filtra pelo status do Pedido.
`since`	Considera solicitações atualizadas a partir da data informada.
`page`	Página consultada.
`per_page`	Quantidade de resultados por página.
`uuids`	Restringe a consulta a determinados UUIDs.
`external_ids`	Restringe a consulta a determinados identificadores externos.

Utilize a paginação para percorrer todos os resultados quando a empresa possuir muitos Pedidos.

O filtro since pode ser usado em sincronizações incrementais, buscando apenas solicitações atualizadas após determinada data.

Consultar a caixa de entrada de Pedidos

Utilize:

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

Essa operação consulta a caixa de entrada de Pedidos do colaborador informado no employeeUuid.

A consulta aceita:

Parâmetro	Finalidade
`status`	Filtra os Pedidos pelo status.
`since`	Considera solicitações atualizadas a partir da data informada.
`side`	Define se o colaborador é o solicitante ou o aprovador.

O parâmetro side aceita:

subject;
approver.

Essa operação pode ser utilizada para consultar solicitações relacionadas ao colaborador ou Pedidos que aguardam sua atuação como aprovador.

Consulta de Pedidos não é exportação de relatório

Os endpoints de Requests retornam dados estruturados para uso pela integração.

Eles não geram automaticamente:

PDF de Pedidos;
Planilha consolidada de Pedidos;
Relatório com a mesma apresentação da plataforma;
Arquivo pronto da área de Relatórios.

Portanto, é possível consultar e tratar os Pedidos pela API, mas não solicitar que a API gere o mesmo arquivo disponibilizado pela interface.

Endpoints de cargos

Método	Endpoint	Finalidade
`POST`	`/positions`	Cria cargos.
`PATCH`	`/positions`	Atualiza cargos.
`POST`	`/deactivate_positions`	Desativa cargos.
`GET`	`/positions`	Retorna a lista de cargos.

Os cargos podem ser identificados pelo UUID da Oitchau ou pelo externalId utilizado no sistema integrado.

Endpoints de departamentos

Método	Endpoint	Finalidade
`POST`	`/departments`	Cria departamentos.
`PATCH`	`/departments`	Atualiza departamentos.
`GET`	`/departments`	Retorna a lista de departamentos.
`GET`	`/departments/:departmentUuid`	Consulta um departamento específico.
`POST`	`/departments/add_employees`	Adiciona colaboradores a um departamento.
`POST`	`/departments/remove_employees`	Remove colaboradores de um departamento.

Nas operações de vínculo, confirme o departamento, os colaboradores e o tipo de identificador utilizado.

Endpoints de centros de custo

Método	Endpoint	Finalidade
`POST`	`/cost_centers`	Cria centros de custo.
`PATCH`	`/cost_centers`	Atualiza centros de custo.
`GET`	`/cost_centers`	Retorna a lista de centros de custo.
`GET`	`/cost_centers/:costCenterUuid`	Consulta um centro de custo específico.
`POST`	`/cost_centers/add_employees`	Adiciona colaboradores a um centro de custo.
`POST`	`/cost_centers/remove_employees`	Remove colaboradores de um centro de custo.

Esses endpoints podem ser utilizados para sincronizar a estrutura organizacional com o sistema de origem.

Endpoints de filiais

Método	Endpoint	Finalidade
`POST`	`/subsidiaries`	Cria filiais.
`PATCH`	`/subsidiaries`	Atualiza filiais.
`POST`	`/deactivate_subsidiaries`	Desativa filiais.
`GET`	`/subsidiaries`	Retorna a lista de filiais.
`POST`	`/subsidiaries/:subsidiaryUuid/add_employees`	Adiciona colaboradores à filial.
`POST`	`/subsidiaries/:subsidiaryUuid/remove_employees`	Remove colaboradores da filial.
`POST`	`/subsidiaries/:subsidiaryUuid/add_locations`	Vincula localizações à filial.
`POST`	`/subsidiaries/:subsidiaryUuid/remove_locations`	Remove localizações da filial.

Uma filial pode possuir colaboradores e localizações vinculadas.

Endpoints de clientes

Nesse contexto, Clientes representam empresas atendidas pela empresa cadastrada na Oitchau.

Método	Endpoint	Finalidade
`GET`	`/clients`	Retorna a lista de clientes.
`POST`	`/clients`	Cria clientes.
`PATCH`	`/clients`	Atualiza clientes.
`POST`	`/deactivate_clients`	Desativa clientes.
`POST`	`/clients/:clientUuid/add_locations`	Vincula localizações ao cliente.

Consulte os tipos de localização aceitos antes de criar o vínculo.

Endpoints de times

Método	Endpoint	Finalidade
`POST`	`/teams`	Cria times e define seu supervisor.
`PATCH`	`/teams`	Atualiza times.
`POST`	`/deactivate_teams`	Desativa times.
`GET`	`/teams`	Retorna a lista de times.
`POST`	`/teams/:teamUuid/add_employees`	Adiciona colaboradores ao time.
`POST`	`/teams/:teamUuid/remove_employees`	Remove colaboradores do time.

Quando a integração criar supervisores e seus subordinados, cadastre primeiro o supervisor para que o vínculo possa ser realizado.

Endpoints de localizações

Método	Endpoint	Finalidade
`POST`	`/locations`	Cria localizações.
`PATCH`	`/locations`	Atualiza localizações.
`POST`	`/deactivate_locations`	Desativa localizações.
`GET`	`/locations`	Retorna a lista de localizações.
`POST`	`/locations/:locationUuid/add_employees`	Autoriza colaboradores na localização.
`POST`	`/locations/:locationUuid/remove_employees`	Remove colaboradores da localização.

As localizações podem utilizar informações como:

Nome;
Código;
Tipo;
Endereço;
Latitude;
Longitude;
Raio.

Consulte os formatos aceitos pela operação antes de criar ou atualizar uma localização.

Endpoints de Grupos de Feriados

Método	Endpoint	Finalidade
`GET`	`/holidays-groups`	Retorna os Grupos de Feriados.
`POST`	`/holidays-groups`	Cria um Grupo de Feriados.
`GET`	`/holidays-groups/:holidaysGroupUuid`	Consulta um grupo específico.
`POST`	`/deactivate_holidays_groups`	Desativa Grupos de Feriados.
`POST`	`/activate_holidays_groups`	Reativa Grupos de Feriados.
`POST`	`/holidays-groups/:holidaysGroupUuid/add_employees`	Adiciona colaboradores ao grupo.
`POST`	`/holidays-groups/:holidaysGroupUuid/remove_employees`	Remove colaboradores do grupo.
`POST`	`/holidays-groups/:holidaysGroupUuid/add_holidays`	Adiciona feriados ao grupo.
`POST`	`/holidays-groups/:holidaysGroupUuid/delete_holidays`	Exclui feriados do grupo.
`GET`	`/holidays-groups/holidays/employees/:employeeUuid`	Consulta os feriados aplicáveis ao colaborador.

Nas operações de vínculo, confira a data em que a inclusão ou remoção deve começar.

Endpoints de consulta da empresa e dos grupos

Método	Endpoint	Finalidade
`GET`	`/company`	Retorna os dados da empresa associada às credenciais.
`GET`	`/payroll_groups_list`	Retorna os Grupos de Pagamento.
`GET`	`/business_rules_groups`	Retorna os Grupos de Regras.

Essas consultas podem ser utilizadas para obter os identificadores necessários antes de criar ou atualizar colaboradores.

Endpoints de Jornadas

Método	Endpoint	Finalidade
`GET`	`/schedules/list`	Retorna a lista de Jornadas.
`POST`	`/companies/:companyUuid/schedules/:scheduleUuid/user_profiles`	Atribui colaboradores a uma Jornada pelo UUID.
`POST`	`/companies/:companyUuid/external_id_schedule_assignments`	Atribui colaboradores a uma Jornada pelo identificador externo.
`GET`	`/companies/:companyUuid/user_profiles/:userProfileUuid/shifts`	Consulta os turnos de um colaborador em uma data.

Nas atribuições, confira:

A empresa;
A Jornada;
Os colaboradores;
A data de início;
Os identificadores utilizados.

Exemplo de fluxo para sincronizar Pedidos

Uma integração pode seguir esta sequência:

Gerar o token de autenticação;
Localizar o colaborador;
Confirmar o tipo de Pedido que será utilizado;
Criar o Pedido com um externalId;
Registrar o identificador retornado pela operação;
Enviar o anexo, quando necessário;
Consultar os Pedidos do colaborador ou da empresa;
Atualizar o status quando a integração for responsável por essa operação;
Utilizar since nas consultas seguintes para buscar somente alterações recentes.

Dicas ou solução de problemas

A autenticação falhou: gere um novo token e confira as credenciais e o cabeçalho Authorization;
O colaborador não foi encontrado: revise o UUID, o externalId ou a matrícula utilizada;
O Pedido foi criado para a pessoa errada: confira a prioridade entre os identificadores enviados;
A atualização de status retornou erro: não misture UUIDs e IDs externos no mesmo objeto de status;
O anexo não foi enviado: confira se a requisição utiliza multipart/form-data e se o Pedido e o responsável foram identificados;
A consulta não retornou todos os Pedidos: revise page e per_page;
Preciso buscar apenas alterações recentes: utilize o parâmetro since;
Preciso consultar os Pedidos de uma pessoa: utilize o endpoint com employeeUuid;
Preciso consultar todos os Pedidos da empresa: utilize GET /v2/public/integrations_api/requests;
Preciso consultar os Pedidos que dependem de um aprovador: utilize o endpoint de inbox e o parâmetro side=approver;
Preciso baixar uma planilha de Pedidos: a API permite consultar os dados, mas não gera o arquivo;
Preciso baixar uma Folha de Frequência: utilize a área de Relatórios da plataforma.

Melhores práticas

Utilize o externalId para manter o vínculo entre os sistemas;
Consulte se o colaborador já existe antes de criá-lo;
Não utilize somente nome, telefone ou e-mail como identificador permanente;
Registre o externalId de cada Pedido criado pela integração;
Não misture UUIDs e IDs externos nas atualizações de status;
Utilize paginação nas consultas de listas;
Utilize since para realizar sincronizações incrementais;
Restrinja consultas de ponto e Pedidos aos períodos necessários;
Não registre o segredo da aplicação nos logs;
Proteja os anexos e os dados pessoais retornados;
Teste a integração com poucos registros antes de realizar operações em massa;
Consulte a documentação antes de adicionar novos campos ou operações.

Perguntas frequentes

É possível gerar relatórios de ponto pela API?

Não. A API não gera arquivos como Folha de Frequência, Resumo ou Espelho de Ponto.
É possível consultar os registros de ponto pela API?

Sim. Utilize GET /punches. O retorno contém os dados dos registros, e não um relatório pronto.
É possível criar Pedidos pela API?

Sim. Utilize:
```
POST /v2/public/integrations_api/requests
```
É possível consultar os Pedidos de um colaborador?

Sim. Utilize:
```
GET /v2/public/integrations_api/requests/employees/:employeeUuid
```
É possível consultar os Pedidos de toda a empresa?

Sim. Utilize:
```
GET /v2/public/integrations_api/requests
```
É possível consultar a caixa de entrada de Pedidos de um aprovador?

Sim. Utilize o endpoint de inbox e informe o colaborador:
```
GET /v2/public/integrations_api/requests/employees/:employeeUuid/inbox
```
É possível aprovar, cancelar ou recusar Pedidos pela API?

Sim. Utilize o endpoint de atualização de status:
```
POST /v2/public/integrations_api/requests/status
```
É possível enviar anexos para um Pedido?

Sim. Utilize:
```
POST /v2/public/integrations_api/requests/attachments
```
Posso identificar o colaborador pela matrícula?

Na criação do Pedido, a documentação permite utilizar employeeUuid, employeeExternalId ou employeeMatricula.
O que acontece se eu enviar mais de um identificador do colaborador?

O employeeUuid terá prioridade sobre o identificador externo e a matrícula.
Posso utilizar UUIDs e IDs externos ao atualizar o status?

Utilize apenas um dos formatos no mesmo objeto de status. Enviar os dois gera erro.
É possível baixar um relatório de Pedidos pela API?

Não. A API retorna os dados estruturados, mas não gera um PDF ou uma planilha consolidada.
Como consultar somente Pedidos atualizados recentemente?

Utilize o parâmetro since nos endpoints de consulta.
A API retorna todos os resultados em uma única requisição?

Nem sempre. Utilize page e per_page para percorrer os resultados.
Para que serve o externalId?

Ele mantém o vínculo entre o registro criado na Oitchau e o registro correspondente no sistema externo.
Onde encontro os campos completos de cada operação?

Consulte a documentação técnica da API para verificar os campos, exemplos e regras atuais.