> For the complete documentation index, see [llms.txt](https://docs.giro.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/consulta-de-escrituracoes/lancamentos-contabeis-global.md).

# Lançamentos Contábeis Global

Lista, com paginação, os lançamentos contábeis Dataprev do originador: os descontos em folha declarados pelo empregador. Filtro opcional por período de inclusão.

## Request

`GET /api/v1/originator/dataprev/bookkeeping-entries`

Requer autenticação: `Authorization: Bearer {originatorToken}`.

### Parâmetros

| Parâmetro      | Local | Tipo                 | Obrigatório | Descrição                                           |
| -------------- | ----- | -------------------- | ----------- | --------------------------------------------------- |
| `includedFrom` | query | `string` (date-time) | Não         | Data/hora mínima de inclusão na Dataprev (ISO-8601) |
| `includedTo`   | query | `string` (date-time) | Não         | Data/hora máxima de inclusão na Dataprev (ISO-8601) |
| `page`         | query | `integer`            | Não         | Número da página, começando em `0`. Padrão `0`      |
| `size`         | query | `integer`            | Não         | Tamanho da página. Padrão `20`                      |

## Response

Página (`content` + metadados de paginação).

### Item (`content[]`)

| Campo                             | Tipo                 | Descrição                                                                                                                                                                                              |
| --------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `publicId`                        | `string (uuid)`      | Identificador público do lançamento na plataforma                                                                                                                                                      |
| `dataprevId`                      | `integer`            | Identificador do lançamento na Dataprev                                                                                                                                                                |
| `contractNumber`                  | `string`             | Número do contrato (8 dígitos com zero à esquerda)                                                                                                                                                     |
| `referencePeriod`                 | `integer`            | Período de referência (AAAAMM)                                                                                                                                                                         |
| `deductionAmount`                 | `number`             | Valor da dedução em reais (decimal com 2 casas)                                                                                                                                                        |
| `eventDeductionAmount`            | `number`             | Soma de `deductionAmount` dos lançamentos com o mesmo `eSocialEventId`, contrato e competência — o desconto efetivo da folha no evento. Igual a `deductionAmount` quando o evento tem um lançamento só |
| `eventEntryCount`                 | `integer`            | Quantidade de lançamentos que compõem o evento (`1` quando o desconto não foi dividido)                                                                                                                |
| `eventEntries`                    | `array`              | Os lançamentos que compõem o evento, inclusive este, ordenados por `dataprevId`. Cada item: `publicId`, `dataprevId` e `deductionAmount` da rubrica                                                    |
| `includedAtDataprev`              | `string` (date-time) | Data/hora de inclusão na Dataprev                                                                                                                                                                      |
| `eSocialEventId`                  | `string`             | Identificador do evento eSocial (string numérica; pode exceder 64 bits)                                                                                                                                |
| `dataMatch`                       | `boolean`            | Indica se os dados conferem                                                                                                                                                                            |
| `eventTypeCode`                   | `integer`            | Código do tipo de evento                                                                                                                                                                               |
| `institutionCode`                 | `integer`            | Código da instituição                                                                                                                                                                                  |
| `cpf`                             | `string`             | CPF do trabalhador                                                                                                                                                                                     |
| `registrationNumber`              | `string`             | Matrícula do trabalhador                                                                                                                                                                               |
| `employerTaxIdType`               | `string`             | Tipo do documento em `employerRegistrationNumber`: `CNPJ` ou `CPF` (`null` quando a Dataprev não informa)                                                                                              |
| `employerRegistrationNumber`      | `string`             | Número de inscrição do empregador (preserva zeros à esquerda; radical do CNPJ com 8 dígitos ou CPF)                                                                                                    |
| `loanInstitutionCode`             | `integer`            | Código da instituição do empréstimo                                                                                                                                                                    |
| `loanInstallmentValue`            | `number`             | Valor da parcela do empréstimo                                                                                                                                                                         |
| `analysisContractBooked`          | `boolean`            | Análise: contrato escriturado                                                                                                                                                                          |
| `analysisWorkerBooked`            | `boolean`            | Análise: trabalhador escriturado                                                                                                                                                                       |
| `analysisInstitutionCorrect`      | `boolean`            | Análise: instituição correta                                                                                                                                                                           |
| `analysisInstallmentValueCorrect` | `boolean`            | Análise: valor da parcela correto                                                                                                                                                                      |
| `analysisLinkCorrect`             | `boolean`            | Análise: vínculo correto                                                                                                                                                                               |
| `exclusionEventDatetime`          | `string`             | Data/hora do evento de exclusão                                                                                                                                                                        |
| `correctionEventDatetime`         | `string`             | Data/hora do evento de correção                                                                                                                                                                        |
| `exclusionEventId`                | `string`             | Identificador do evento de exclusão (string numérica; pode exceder 64 bits)                                                                                                                            |
| `correctionEventId`               | `string`             | Identificador do evento de correção (string numérica; pode exceder 64 bits)                                                                                                                            |

* **200 OK** — página retornada (`content` vazio quando nada corresponde ao filtro).

### Desconto dividido em mais de um lançamento

O empregador pode dividir o desconto de uma parcela em mais de uma rubrica do mesmo evento de remuneração (S-1200). Cada rubrica vira um lançamento, com o mesmo `eSocialEventId`.

* A Dataprev compara **cada lançamento** com a parcela inteira: `analysisInstallmentValueCorrect` vem `false` em todas as partes, mesmo quando a soma bate. Para saber se a parcela foi descontada inteira, compare `eventDeductionAmount` com `loanInstallmentValue`.
* Todo lançamento do evento traz a lista completa em `eventEntries`, mesmo que as partes caiam em páginas diferentes.

| `dataprevId` | `deductionAmount` | `loanInstallmentValue` | `analysisInstallmentValueCorrect` | `eventDeductionAmount` | `eventEntryCount` |
| ------------ | ----------------- | ---------------------- | --------------------------------- | ---------------------- | ----------------- |
| 456790       | 158.35            | 179.27                 | `false`                           | 179.27                 | 2                 |
| 456791       | 20.92             | 179.27                 | `false`                           | 179.27                 | 2                 |

Nos dois lançamentos, `eventEntries` é:

```json
[
  { "publicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02", "dataprevId": 456790, "deductionAmount": 158.35 },
  { "publicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b03", "dataprevId": 456791, "deductionAmount": 20.92 }
]
```

Neste exemplo a parcela de R$ 179,27 foi descontada inteira, em duas rubricas: R$ 158,35 + R$ 20,92.

{% hint style="info" %}
Estes são **lançamentos** da folha (o que o empregador declarou ter descontado), não repasses. O dinheiro que efetivamente chegou aparece nas [transferências de pagamento](https://docs.giro.tech/desenvolvedores/api-gtpayroll/api-reference/consulta-de-escrituracoes/transferencias-pagamento-global.md).
{% endhint %}

## Exemplo

```http
GET /api/v1/originator/dataprev/bookkeeping-entries?includedFrom=2024-04-01T00:00:00Z&includedTo=2024-04-30T23:59:59Z&page=0&size=20 HTTP/1.1
Host: api.giro.tech
Authorization: Bearer {originatorToken}
```

Resposta `200`:

```json
{
  "content": [
    {
      "dataprevId": 456789,
      "contractNumber": "00345678",
      "referencePeriod": 202404,
      "deductionAmount": 593.78,
      "eventDeductionAmount": 593.78,
      "eventEntryCount": 1,
      "eventEntries": [
        { "publicId": "0198f2a1-7c3e-7b2d-9f14-3a5c8e6d1b02", "dataprevId": 456789, "deductionAmount": 593.78 }
      ],
      "eSocialEventId": "1065346190000002026070811274100003",
      "employerRegistrationNumber": "06534619"
    }
  ],
  "totalElements": 1,
  "totalPages": 1,
  "size": 20,
  "number": 0,
  "numberOfElements": 1,
  "first": true,
  "last": true,
  "empty": false
}
```

## Erros

| Código | Situação                                     |
| ------ | -------------------------------------------- |
| 401    | Token ausente, expirado ou inválido          |
| 403    | Token válido sem permissão para este recurso |

Formato dos erros: [Erros da API](https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.md).

## Listar lançamentos contábeis (paginado)

> Retorna os lançamentos contábeis Dataprev do originador autenticado, com paginação e filtros\
> opcionais por data de inclusão e por vigência (\`status\`).\
> \
> A listagem devolve o histórico completo: um lançamento por evento do eSocial. Para obter só o\
> que vale hoje, use \`status=ACTIVE\`.\
> \
> O filtro por inclusão é um \*\*intervalo fechado\*\*: \`includedFrom\` e \`includedTo\` precisam vir juntos.\
> Informar só uma das pontas responde \`400\` (\`errorCode: INCOMPLETE\_DATE\_RANGE\`) — antes, a ponta\
> isolada era ignorada em silêncio e a listagem inteira voltava com \`200\`.\
> \
> Sem \`sort\`, a ordem é \`id\` crescente. Com \`sort\`, o \`id\` é acrescentado como desempate, então a\
> paginação não repete nem pula linhas quando várias têm o mesmo valor no campo ordenado.<br>

```json
{"openapi":"3.0.0","info":{"title":"GT Payroll Originator API","version":"1.1.0"},"tags":[{"name":"Dataprev","description":"Dados Dataprev (transferências de pagamento e lançamentos contábeis)"}],"servers":[{"url":"https://ingress.gtpayroll.staging.giro.tech","description":"Ambiente de Staging"},{"url":"https://ingress.gtpayroll.giro.tech","description":"Ambiente de Produção"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token fornecido pelo administrador"}}},"paths":{"/api/v1/originator/dataprev/bookkeeping-entries":{"get":{"summary":"Listar lançamentos contábeis (paginado)","description":"Retorna os lançamentos contábeis Dataprev do originador autenticado, com paginação e filtros\nopcionais por data de inclusão e por vigência (`status`).\n\nA listagem devolve o histórico completo: um lançamento por evento do eSocial. Para obter só o\nque vale hoje, use `status=ACTIVE`.\n\nO filtro por inclusão é um **intervalo fechado**: `includedFrom` e `includedTo` precisam vir juntos.\nInformar só uma das pontas responde `400` (`errorCode: INCOMPLETE_DATE_RANGE`) — antes, a ponta\nisolada era ignorada em silêncio e a listagem inteira voltava com `200`.\n\nSem `sort`, a ordem é `id` crescente. Com `sort`, o `id` é acrescentado como desempate, então a\npaginação não repete nem pula linhas quando várias têm o mesmo valor no campo ordenado.\n","tags":["Dataprev"],"parameters":[{"name":"includedFrom","in":"query","required":false,"description":"Data/hora mínima de inclusão na Dataprev (ISO-8601). Exige `includedTo`.","schema":{"type":"string","format":"date-time"}},{"name":"includedTo","in":"query","required":false,"description":"Data/hora máxima de inclusão na Dataprev (ISO-8601). Exige `includedFrom`.","schema":{"type":"string","format":"date-time"}},{"name":"ingestedFrom","in":"query","required":false,"description":"Data/hora mínima (inclusive, ISO-8601) em que a plataforma gravou a linha (`ingestedAt`) — o cursor\nda sincronização incremental. Guarde o maior `ingestedAt` recebido e passe-o na chamada seguinte;\ncomo a comparação é `>=`, a última linha volta de novo, então deduplique por `publicId`.\n\nDiferente de `includedFrom`/`includedTo`, que filtram pela data da Dataprev e perdem linhas que ela\npublica com carimbo antigo, `ingestedFrom` acompanha a ordem em que a plataforma recebeu os dados.\nVale para linhas gravadas depois de o carimbo existir (`ingestedAt: null` não aparece aqui); para o\nhistórico anterior use o intervalo de inclusão. A plataforma recebe os dados em ciclos (hoje 06h e 18h, horário de\nBrasília): uma linha só aparece depois do ciclo que a traz. Não exige `includedTo`.\n","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","required":false,"description":"Filtra por vigência do lançamento. Sem o parâmetro, a listagem traz o histórico completo.\n`ACTIVE` devolve apenas os lançamentos que não foram excluídos nem retificados.\n","schema":{"type":"string","enum":["ACTIVE","CORRECTED","EXCLUDED"]}},{"name":"page","in":"query","required":false,"description":"Número da página (0-based)","schema":{"type":"integer","default":0}},{"name":"size","in":"query","required":false,"description":"Tamanho da página","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Página de lançamentos retornada com sucesso","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer","format":"int64","deprecated":true,"description":"**Deprecated.** Chave interna da plataforma (auto-incremento), exposta na resposta sem garantia\nde contrato: não use como identificador nem grave na sua base. Será removido em uma versão\nfutura; use `publicId`.\n"},"publicId":{"type":"string","maxLength":36,"description":"Identificador publico opaco. Presente nos registros novos; omitido (ausente no JSON) enquanto\no registro é antigo. Trate como string opaca.\n"},"dataprevId":{"type":"integer","format":"int64"},"contractNumber":{"type":"string","description":"Número do contrato (8 dígitos com zero à esquerda).\nPor padrão (estratégia GIRO), gerado pela plataforma; na estratégia ORIGINATOR_MANAGED, pode ser informado pelo originador.\n"},"referencePeriod":{"type":"integer"},"deductionAmount":{"type":"number","format":"decimal","description":"Valor da dedução em reais (decimal com 2 casas decimais)."},"eventDeductionAmount":{"type":"number","format":"decimal","description":"Soma de `deductionAmount` das linhas com o mesmo `eSocialEventId`, contrato e competência —\no desconto efetivo da folha naquele evento. O empregador pode dividir o desconto da parcela\nem mais de uma rubrica do mesmo S-1200, e cada rubrica chega como um lançamento separado.\n\nCompare `eventDeductionAmount` com `loanInstallmentValue` para saber se a parcela foi\ndescontada inteira. `analysisInstallmentValueCorrect` é o veredito da Dataprev **por\nlançamento** e fica `false` em cada parte de um desconto dividido, mesmo quando a soma bate.\n\nIgual a `deductionAmount` quando o evento tem um lançamento só.\n"},"eventEntryCount":{"type":"integer","format":"int64","description":"Quantos lançamentos compõem o evento. `1` quando o desconto não foi dividido."},"eventEntries":{"type":"array","description":"Os lançamentos que compõem o evento, inclusive este, ordenados por `dataprevId`. Cada item\ndo evento traz a mesma lista, então as partes ficam visíveis mesmo quando caem em páginas\ndiferentes da consulta global. Um item só quando o desconto não foi dividido.\n","items":{"type":"object","description":"Um lançamento que compõe o desconto de um evento eSocial.","properties":{"publicId":{"type":"string","maxLength":36,"description":"Identificador público do lançamento. Pode vir ausente em registros antigos."},"dataprevId":{"type":"integer","format":"int64"},"deductionAmount":{"type":"number","format":"decimal","description":"Valor descontado nesta rubrica."}}}},"includedAtDataprev":{"type":"string","format":"date-time"},"ingestedAt":{"type":"string","format":"date-time","nullable":true,"description":"Instante em que a plataforma gravou a linha (UTC). Não confundir com `includedAtDataprev`, o\ncarimbo da própria Dataprev, que pode chegar com dias de atraso: para sincronização incremental\nuse este campo, via o filtro `ingestedFrom`.\n\nVem `null` nas linhas gravadas antes de o carimbo existir — elas não aparecem no filtro\n`ingestedFrom`. É carimbo de inserção: uma correção feita depois na linha não muda o valor.\n"},"eSocialEventId":{"type":"string","maxLength":50},"dataMatch":{"type":"boolean"},"eventTypeCode":{"type":"integer"},"institutionCode":{"type":"integer"},"cpf":{"type":"string"},"registrationNumber":{"type":"string"},"employerTaxIdType":{"type":"string","enum":["CNPJ","CPF"],"nullable":true,"description":"Tipo do documento do empregador em `employerRegistrationNumber`."},"employerRegistrationNumber":{"type":"string","maxLength":14},"loanInstitutionCode":{"type":"integer"},"loanInstallmentValue":{"type":"number","format":"decimal"},"analysisContractBooked":{"type":"boolean"},"analysisWorkerBooked":{"type":"boolean"},"analysisInstitutionCorrect":{"type":"boolean"},"analysisInstallmentValueCorrect":{"type":"boolean"},"analysisLinkCorrect":{"type":"boolean"},"exclusionEventDatetime":{"type":"string"},"correctionEventDatetime":{"type":"string"},"exclusionEventId":{"type":"string","maxLength":50},"correctionEventId":{"type":"string","maxLength":50},"eventTypeDescription":{"type":"string","nullable":true,"maxLength":255,"description":"Descrição de `tipoEventoESocial` dada pela Dataprev, ao lado do código já existente."},"employerRegistrationTypeDescription":{"type":"string","nullable":true,"maxLength":255,"description":"Descrição de `inscricaoEmpregador`, ao lado do código já existente."},"status":{"type":"string","enum":["ACTIVE","CORRECTED","EXCLUDED"],"description":"Vigência do lançamento, derivada de `exclusionEventId` e `correctionEventId`. A Dataprev não\nmarca qual linha vale: cada reenvio do S-1200 para a mesma competência entra como lançamento\nnovo, e o anterior passa a apontar o evento que o substituiu.\n\n- `ACTIVE`: lançamento vigente — é o que deve ser considerado.\n- `CORRECTED`: retificado; `correctionEventId` traz o `eSocialEventId` do sucessor, que está\n  na mesma listagem.\n- `EXCLUDED`: excluído pelo evento S-3000 em `exclusionEventId`. Pode não haver substituto —\n  nesse caso a competência fica sem lançamento vigente.\n\nNão use recência (`dataprevId` ou `includedAtDataprev`) para escolher o lançamento vigente:\na ordem de chegada não acompanha a ordem dos eventos, e `includedAtDataprev` empata entre\nlançamentos da mesma carga diária. Duas linhas `ACTIVE` com o mesmo `eSocialEventId` são\ndescontos parciais da mesma competência e **somam** — não são versões.\n"}}}},"totalElements":{"type":"integer","format":"int64"},"totalPages":{"type":"integer"},"size":{"type":"integer"},"number":{"type":"integer"},"numberOfElements":{"type":"integer"},"first":{"type":"boolean"},"last":{"type":"boolean"},"empty":{"type":"boolean"}}}}}},"400":{"description":"Só uma das datas do intervalo informada, ou parâmetro com tipo errado.","content":{"application/problem+json":{"schema":{"type":"object","description":"Resposta de erro no formato RFC 7807 (Problem Details). Os campos extras **não** vêm na raiz:\nficam dentro de `properties` (`message`, `errorCode`, `errors`, `retryAfter`…).\n\nIdentifique o erro por `status` + `properties.errorCode`. O `type` agrupa famílias e sozinho não\nidentifica o erro: `#business-rule-violation` aparece com 400, 403, 404, 409, 413, 422 e 503.\nCatálogo completo em https://docs.giro.tech/desenvolvedores/api-gtpayroll/guias/erros.\n","required":["type","title","status"],"properties":{"type":{"type":"string","description":"URL do guia de erros com o fragmento da família: `validation-error`, `not-authenticated`,\n`forbidden`, `resource-not-found`, `conflict`, `business-rule-violation`,\n`dataprev-suspension-window`, `rate-limit-exceeded`, `internal-error`, `upstream-error`,\n`service-unavailable`. Corpo ilegível, parâmetro de tipo errado, rota inexistente, `405` e\n`415` vêm como `about:blank`, sem `properties`.\n"},"title":{"type":"string","description":"Resumo curto. Na maioria dos casos é a frase padrão do status HTTP."},"status":{"type":"integer","description":"Código HTTP do erro"},"detail":{"type":"string","description":"Mensagem legível desta ocorrência. Pode mudar de texto; use `properties.errorCode` para automação."},"instance":{"type":"string","description":"Path da requisição que falhou"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"401":{"description":"Não autenticado","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autenticação (HTTP 401). Token ausente, com prefixo diferente de `Bearer `, expirado, revogado ou inválido.","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}},"403":{"description":"Permissão insuficiente","content":{"application/problem+json":{"schema":{"type":"object","description":"Erro de autorização (HTTP 403). Token válido de outro perfil, sem permissão de originador.\nRecusas de permissão por regra de negócio (ex.: `ORIGINATOR_OPT_IN_NOT_ENABLED`) usam\n`#business-rule-violation` com `properties.errorCode`.\n","required":["type","title","status"],"properties":{"type":{"type":"string"},"title":{"type":"string"},"status":{"type":"integer"},"detail":{"type":"string"},"instance":{"type":"string"},"properties":{"type":"object","nullable":true,"description":"Extensões do ProblemDetail. Ausente (`null`) nas respostas `about:blank`.","additionalProperties":true,"properties":{"message":{"type":"string","description":"Repete o `detail`."},"errorCode":{"type":"string","description":"Código estável da regra violada. Opcional: só parte dos erros de regra de negócio tem.\nLista por status no guia de erros.\n"},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"(Apenas 400 `validation-error`) Mapa campo → mensagem."},"retryAfter":{"type":"integer","description":"(429 e 503) Segundos a aguardar antes de nova requisição."},"limit":{"type":"integer","description":"(Apenas 429) Limite de requisições da janela."},"resetAt":{"type":"integer","format":"int64","description":"(Apenas 429) Fim da janela, em epoch **milissegundos**."}}}}}}}}}}}}}
```

{% embed url="<https://giro.tech/central-de-atendimento/>" %}
