> 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/transferencias-pagamento-global.md).

# Transferências de Pagamento Global

Lista, com paginação, as transferências de pagamento Dataprev do originador: os repasses do valor descontado em folha. Filtro opcional por período de inclusão (`includedFrom`/`includedTo`, ISO-8601, ex.: `2024-01-01T00:00:00Z`).

## Request

`GET /api/v1/originator/dataprev/payment-transfers`

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

### Parâmetros

| Parâmetro      | Local | Tipo       | Obrigatório | Descrição                                           |
| -------------- | ----- | ---------- | ----------- | --------------------------------------------------- |
| `includedFrom` | query | `datetime` | Não         | Data/hora mínima de inclusão na Dataprev (ISO-8601) |
| `includedTo`   | query | `datetime` | 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 da transferência na plataforma                                                      |
| `dataprevId`                 | `integer`       | Identificador da transferência na Dataprev                                                                |
| `contractNumber`             | `string`        | Número do contrato (8 dígitos com zero à esquerda)                                                        |
| `amountPaid`                 | `number`        | Valor pago em reais (decimal com 2 casas)                                                                 |
| `guidePaymentAt`             | `datetime`      | Data de pagamento da guia                                                                                 |
| `transferAt`                 | `datetime`      | Data/hora da transferência                                                                                |
| `guideNumber`                | `integer`       | Número da guia                                                                                            |
| `trfCode`                    | `integer`       | Código da transferência                                                                                   |
| `competence`                 | `integer`       | Competência (AAAAMM)                                                                                      |
| `nsu`                        | `integer`       | NSU da transferência                                                                                      |
| `lateInterestAmount`         | `number`        | Juros de mora em reais (decimal com 2 casas)                                                              |
| `penaltyAmount`              | `number`        | Multa em reais (decimal com 2 casas)                                                                      |
| `monetaryAdjustmentAmount`   | `number`        | Ajuste monetário em reais (decimal com 2 casas)                                                           |
| `includedAtDataprev`         | `datetime`      | Data/hora de inclusão na Dataprev                                                                         |
| `institutionCode`            | `integer`       | Código da instituição                                                                                     |
| `cpf`                        | `string`        | CPF do trabalhador                                                                                        |
| `registrationNumber`         | `string`        | Matrícula do trabalhador                                                                                  |
| `operatorTaxId`              | `integer`       | Identificador fiscal do operador                                                                          |
| `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)       |

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

## Exemplo

```http
GET /api/v1/originator/dataprev/payment-transfers?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",
      "amountPaid": 593.78,
      "guidePaymentAt": "2024-04-25T00:00:00Z",
      "transferAt": "2024-04-28T14:30:00Z",
      "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 transferências de pagamento (paginado)

> Retorna as transferências de pagamento Dataprev do originador autenticado, com paginação e filtro\
> opcional por data de inclusão.\
> \
> 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/payment-transfers":{"get":{"summary":"Listar transferências de pagamento (paginado)","description":"Retorna as transferências de pagamento Dataprev do originador autenticado, com paginação e filtro\nopcional por data de inclusão.\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":"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 transferências 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"},"amountPaid":{"type":"number","format":"decimal","description":"Valor pago em reais (decimal com 2 casas decimais)."},"guidePaymentAt":{"type":"string","format":"date-time"},"transferAt":{"type":"string","format":"date-time"},"guideNumber":{"type":"integer","format":"int64"},"trfCode":{"type":"integer","format":"int64"},"competence":{"type":"integer"},"nsu":{"type":"integer","format":"int64"},"lateInterestAmount":{"type":"number","format":"decimal","description":"Juros de mora em reais (decimal com 2 casas decimais)."},"penaltyAmount":{"type":"number","format":"decimal","description":"Multa em reais (decimal com 2 casas decimais)."},"monetaryAdjustmentAmount":{"type":"number","format":"decimal","description":"Ajuste monetário em reais (decimal com 2 casas decimais)."},"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"},"institutionCode":{"type":"integer"},"cpf":{"type":"string"},"registrationNumber":{"type":"string"},"operatorTaxId":{"type":"integer","format":"int64"},"employerTaxIdType":{"type":"string","enum":["CNPJ","CPF"],"nullable":true,"description":"Tipo do documento do empregador em `employerRegistrationNumber`."},"employerRegistrationNumber":{"type":"string","maxLength":14},"fromSeverancePay":{"type":"boolean","nullable":true,"description":"A Dataprev marca o repasse como proveniente de verbas rescisórias. Não documentado no Manual\n005 v1.9 — vem no payload real.\n"},"errorReasonCode":{"type":"integer","nullable":true,"description":"Código do `motivoErro` da Dataprev para o repasse que não casou com um contrato."},"errorReasonDescription":{"type":"string","nullable":true,"maxLength":255,"description":"Descrição do `motivoErro` dada pela própria Dataprev, por exemplo\n`Empréstimo não cadastrado`. Não confundir com o `reason` de `unknown_contract_records`,\nque é a nossa conclusão sobre o formato do número do contrato.\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/>" %}
