Correções de Reconciliação de Folha de Ponto

A API de Reconciliação de Folha de Ponto permite que usuários autorizados criem ou corrijam lançamentos de tempo em massa. Você pode enviar uma única correção ou um lote de correções em uma única solicitação.

Este artigo explica quem pode usar a API, quais informações cada correção precisa, as regras que são aplicadas e como interpretar os resultados.

Para enviar correções de reconciliação de folha de ponto, você deve:

• Ser um Administrador Financeiro, e

• Ser um Administrador de Folha de Ponto, e

• Ter o recurso Correções de Folha de Ponto habilitado para sua organização, e

• Ter o recurso Correção de Reconciliação de Folha de Ponto habilitado para sua organização.

Se qualquer uma dessas condições não for atendida, a solicitação será rejeitada com a resposta 403 Forbidden e nenhuma correção será salva.

• Enviar uma única correção – envie uma entrada de correção e receba o resultado para essa entrada.

• Enviar um lote de correções – envie várias entradas de correção de uma vez e receba um resultado por linha, além de um resumo geral.

Cada entrada cria uma nova correção ou atualiza uma existente. Para atualizar uma correção existente, inclua seu Id de Registro. Para criar uma nova correção, deixe o Id de Registro vazio (ou defina-o como 0).

Cada entrada de correção é composta pelos seguintes campos.

Toda entrada deve incluir todos os seguintes campos:

• Data – a data à qual o tempo se refere.

• Horas – o número de horas registradas para a correção.

• Uma forma de identificar o recurso – forneça uma Referência de Recurso ou uma Referência Externa.

• Uma forma de identificar o trabalho – forneça pelo menos um entre Referência de Projeto, Referência Alternativa de Projeto ou Projeto (nome) para trabalhos não relacionados a projetos, como 'Licença' etc.

Estes campos podem ser fornecidos para adicionar mais detalhes ou para suportar cenários específicos:

• Id de Registro – o identificador de uma correção existente que você deseja atualizar. Para obter o Id de Registro de correções existentes, use o endpoint 'Find' para buscar correções em um intervalo de datas. Omita o Id de Registro para criar uma nova correção.

• Recurso – o nome do recurso (pessoa).

• Referência Financeira – uma referência financeira associada ao trabalho.

• Tarefa – a flex-task à qual o tempo se refere.

• Sub Atividade – uma atividade mais granular dentro da tarefa.

• Valor Local – um valor monetário para a entrada, na moeda local.

• Código de Moeda Local – a moeda para o Valor Local.

• Notas – notas em texto livre sobre a correção.

As correções são verificadas em duas etapas.

Estas são aplicadas primeiro a cada entrada:

• Uma Data deve ser fornecida.

• Horas devem ser fornecidas.

• O recurso deve ser identificável por uma Referência de Recurso ou uma Referência Externa.

• O trabalho deve ser identificável por uma Referência de Projeto, uma Referência Alternativa de Projeto ou um nome de Projeto.

• RecordId deve ser maior ou igual a 0.

Uma entrada que falhar em qualquer uma dessas verificações é marcada como inválida e não é processada adiante. O motivo é retornado para essa entrada.

As entradas que passam nas verificações básicas são então validadas em relação aos dados e regras da sua organização, por exemplo:

• O RecordId deve existir no sistema.

• O recurso referenciado deve existir.

• O projeto ou item de trabalho referenciado deve existir e ser válido para correções de folha de ponto.

• A data deve estar dentro de um período aberto para correção (períodos que foram bloqueados ou anteriores à Data de Bloqueio de Capitalização não podem ser corrigidos).

• O Projeto deve ser de um tipo ou status que a Configuração de Folha de Ponto marque como excluído das correções.

• Qualquer moeda fornecida deve ser válida.

Entradas que falham em uma verificação de negócio são marcadas como inválidas e o motivo específico é retornado para a linha correspondente. Entradas que passam em todas as verificações são submetidas.

Sucesso parcial é suportado. Quando você envia um lote, as entradas válidas são aplicadas mesmo que outras entradas no mesmo lote sejam inválidas. Você não precisa reenviar o lote inteiro para corrigir uma única linha com erro.

A resposta informa se a entrada foi válida ou inválida, e inclui quaisquer mensagens de validação explicando por que uma entrada foi rejeitada.

A resposta inclui um resumo geral e um detalhamento por linha:

• Status – o resultado geral do lote:

  • success – todas as entradas foram válidas e aplicadas.

  • partial – algumas entradas foram válidas e aplicadas; outras foram inválidas.

  • failed – nenhuma entrada foi válida; nada foi aplicado.

• Contagem total – o número de entradas enviadas.

• Contagem válida – o número de entradas que passaram na validação e foram aplicadas.

• Contagem inválida – o número de entradas que falharam na validação.

• Resultados por linha – para cada entrada, se foi válida e quaisquer mensagens de validação.

• Id de Correlação – uma referência para o lote, útil ao revisar ou acompanhar um envio.

• Sempre inclua Data e Horas em cada entrada.

• Forneça uma Referência de Recurso ou Referência Externa para que o recurso possa ser identificado sem ambiguidade.

• Forneça uma Referência de Projeto, Referência Alternativa de Projeto ou nome de Projeto para que o trabalho possa ser identificado.

• Certifique-se de que a Data esteja dentro de um período ainda aberto para reconciliação.

• Para atualizar uma correção existente em vez de criar uma nova, inclua seu Id de Registro.

• Ao enviar um lote, revise os resultados por linha para que você possa corrigir e reenviar apenas as linhas que falharam.

/rest/api/timesheetreconciliation

O status do limite de taxa é retornado nos cabeçalhos da resposta:

Recupera registros de correção de reconciliação de folha de ponto para o intervalo de datas especificado. Tanto startDate quanto endDate são obrigatórios.

Exemplo HTTP

Endpoint: GET /rest/api/timesheetreconciliation/find

Exemplo cURL

curl -X GET "https://organisation.fluid.work/rest/api/timesheetreconciliation/find?startDate=2026-07-01&endDate=2026-07-31&version=3.0" \
  -H "Authorization: Bearer {your_api_token}" \
  -H "Accept: application/json"

Parâmetros de Consulta:

Cabeçalhos de Resposta:

Resposta:

[
  {
    "fields": {
      "recordId": 1042,
      "date": "2026-07-01T00:00:00",
      "resource": "Henry Rogers",
      "resourceRef": "Henry.rogers",
      "externalRef": "EMP-001",
      "project": "Project Solara",
      "projectRef": "ED-EN-1000",
      "alternateProjectRef": null,
      "financialRef": "FR-JC-01",
      "task": null,
      "subActivity": null,
      "hours": 8.0,
      "localValue": 0.0,
      "localCurrencyCode": null,
      "notes": null
    }
  }
]

Resposta (400 Bad Request) — parâmetros de data ausentes ou inválidos:

{
  "message": "startDate and endDate are required and must be valid dates."
}

Resposta (403 Forbidden):

{
  "message": "You do not have the required permission to fetch timesheet reconciliation corrections."
}

Cria ou atualiza uma única entrada de correção de reconciliação de folha de ponto.

Exemplo HTTP

Endpoint: POST /rest/api/timesheetreconciliation

Corpo da Requisição:

{
  "fields": {
    "recordId": 0,
    "date": "2026-07-01T00:00:00Z",
    "resourceRef": "Henry.rogers",
    "projectRef": "ED-EN-1000",
    "financialRef": "FR-JC-01",
    "subActivity": "Application Support",
    "hours": 8.0,
    "localValue": 350.00,
    "localCurrencyCode": "GBP",
    "notes": "July correction"
  }
}

Exemplo cURL

curl -X POST "https://organisation.fluid.work/rest/api/timesheetreconciliation?version=3.0" \
  -H "Authorization: Bearer {your_api_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "recordId": 0,
      "date": "2026-07-01T00:00:00Z",
      "resourceRef": "Henry.rogers",
      "projectRef": "ED-EN-1000",
      "financialRef": "FR-JC-01",
      "subActivity": "Application Support",
      "hours": 8.0,
      "localValue": 350.00,
      "localCurrencyCode": "GBP",
      "notes": "July correction"
    }
  }'

Resposta — Entrada válida:

{
    "fields": {
        "rowIndex": 1,
        "isValid": true,
        "status": "valid",
        "validationMessages": []
    }
}

Resposta — Erro de validação:

{
    "fields": {
        "rowIndex": 1,
        "isValid": false,
        "status": "invalid",
        "validationMessages": [
            "This row was skipped as Project 'Vacations' is not a valid Miscellaneous Task as configured in Timesheet Configuration."
        ]
    }
}

Resposta (403 Forbidden):

{
  "message": "You do not have the required permission to create timesheet reconciliation corrections."
}

Envia múltiplas entradas de correção de reconciliação de folha de ponto em uma única requisição. Cada entrada é validada e processada de forma independente. Linhas inválidas não impedem que linhas válidas sejam salvas.

Exemplo HTTP
Endpoint: POST /rest/api/timesheetreconciliation/bulk

Corpo da Requisição:

[
  {
    "fields": {
      "recordId": 0,
      "date": "2026-07-01T00:00:00Z",
      "resourceRef": "Henry.rogers",
      "projectRef": "ED-EN-1000",
      "hours": 8.0
    }
  },
  {
    "fields": {
      "recordId": 1042,
      "date": "2026-07-02T00:00:00Z",
      "resourceRef": "Henry.rogers",
      "projectRef": "ED-EN-1000",
      "financialRef": "FR-JC-01",
      "hours": 10.5
    }
  },
  {
    "fields": {
      "recordId": 0,
      "date": "2026-07-03T00:00:00Z",
      "resourceRef": "unknown.user",
      "projectRef": "ED-EN-1000",
      "hours": 8.0
    }
  }
]

Exemplo cURL

curl -X POST "https://organisation.fluid.work/rest/api/timesheetreconciliation/bulk?version=3.0" \
  -H "Authorization: Bearer {your_api_token}" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "fields": {
        "recordId": 0,
        "date": "2026-07-01T00:00:00Z",
        "resourceRef": "Henry.rogers",
        "projectRef": "ED-EN-1000",
        "hours": 8.0
      }
    },
    {
      "fields": {
        "recordId": 1042,
        "date": "2026-07-02T00:00:00Z",
        "resourceRef": "Henry.rogers",
        "projectRef": "ED-EN-1000",
        "financialRef": "FR-JC-01",
        "hours": 10.5
      }
    }
  ]'

Resposta — Sucesso parcial:

{
  "status": "partial",
  "totalCount": 3,
  "validCount": 2,
  "invalidCount": 1,
  "correlationId": "12345678-1234-1234-1234-123456789012",
  "results": [
    {
      "fields": {
        "rowIndex": 1,
        "isValid": true
        "status": "valid",
        "validationMessages": [],
      }
    },
    {
      "fields": {
        "rowIndex": 2,
        "isValid": true
        "status": "valid",
        "validationMessages": [],
      }
    },
    {
      "fields": {
        "rowIndex": 3,
        "isValid": false
        "status": "valid",
        "validationMessages": [
          "Row 3: no resource found matching the Resource Ref 'unknown.user'"
        ]
      }
    }
  ]
}

O objeto de requisição de nível superior encapsula um objeto fields.

{
  "fields": { ... }
}

* resourceRef ou externalRef é obrigatório.
** projectRef ou alternateProjectRef é obrigatório (ou project para entradas de tarefas diversas).

Retornado pelos endpoints de criação individual e criação em lote.

status valores

Retornado por registro pelo endpoint GET /find.

A validação é executada em duas fases: nível de requisição (pré-processador) e nível de processador.

Aplicada antes da execução do processador. Uma linha que falha em qualquer uma dessas verificações é marcada como inválida e excluída da execução do processador.

Aplicada para cada entrada que passa na Fase 1.

Quando recordId é maior que zero, o processador busca o registro de correção existente por esse ID e compara os seguintes campos com o que foi enviado:

Se algum campo não corresponder, a linha é rejeitada e o registro existente permanece inalterado. Somente hours, localValue, localCurrencyCode e notes podem diferir dos valores armazenados — todos os outros campos atuam como chave de identidade para confirmar que o registro correto está sendo atualizado.

1. Validação da solicitação: Cada linha é verificada em relação às regras de campos obrigatórios.

2. Remoção de duplicatas: Linhas que compartilham a mesma chave (resourceRef, projectRef, date, financialRef, subActivity) dentro de um único lote são desduplicadas. A linha que aparece por último na lista de combinações duplicadas é mantida; as duplicatas anteriores são rejeitadas sem processamento.

3. Execução do processador: Todas as entradas válidas são enviadas.

A API suporta versionamento por meio do parâmetro de consulta version:

• version=3 ou version=3.0 — API V3 (atual)

• Omitido — resolve para a versão estável mais recente (atualmente V3)

POST /rest/api/timesheetreconciliation?version=3.0

Use o parâmetro de consulta fields para limitar quais campos aparecem na resposta:

GET rest/api/timesheetreconciliation/find?startDate=2026-08-01&endDate=2026-08-30&fields=resourceRef,projectRef,recordid

1. Use o endpoint Find antes de atualizações em massa: Chame GET /rest/api/timesheetreconciliation/find primeiro para recuperar os valores atuais de recordId e os valores exatos dos campos armazenados no banco de dados. Isso garante que a verificação de combinação seja aprovada ao enviar atualizações.

2. Trate recordId como um identificador opaco: Obtenha-o a partir do endpoint 'Find'.

3. Para atualizações, altere apenas hours, localValue, localCurrencyCode ou notes: Qualquer alteração em date, resourceRef, projectRef, financialRef, subActivity ou task em uma linha com recordId > 0 fará a verificação de combinação falhar e a linha será rejeitada.

4. Use o endpoint em massa para envios de múltiplas linhas: O endpoint em massa processa todas as linhas em um único lote e retorna resultados por linha. Enviar linhas individualmente por meio de múltiplas chamadas POST únicas é menos eficiente.

5. Verifique isValid por linha: Itere sobre results e verifique isValid para identificar linhas rejeitadas e suas validationMessages.

6. Trate o sucesso parcial: O campo status indica "success", "partial" ou "failed".

7. Respeite a Data de Bloqueio de Capitalização: Entradas com uma date igual ou anterior à Data de Bloqueio de Capitalização são sempre rejeitadas. Verifique a data de bloqueio antes de enviar correções históricas.

8. Entradas de tarefas diversas: Para entradas direcionadas a uma tarefa diversa em vez de um projeto padrão, defina o campo project com o nome de exibição da tarefa e deixe projectRef e alternateProjectRef vazios. Não inclua subActivity em linhas de tarefas diversas.

9. Entradas de tarefas do quadro flex: Defina o campo task com o título exato da tarefa do quadro flex. Não combine task com financialRef.

10. Use a filtragem de campos: Use o parâmetro de consulta fields para reduzir o tamanho do payload da resposta quando apenas campos específicos são necessários.