---
title: 11.3. Arquivos Lidos do Bucket
url: https://docs.vehub.com.br/API/Integra%C3%A7%C3%A3o%20FIDC/11.%20Leitura%20do%20Bucket%20da%20Administradora/11.3.%20Arquivos%20Lidos%20do%20Bucket/
---
Acompanha os arquivos lidos das pastas do bucket da administradora e libera para uma nova leitura o arquivo que falhou.

## Consultar arquivos lidos

| Método | URL |
|--------|-----|
| ![GET](https://img.shields.io/badge/GET-blue) | `https://BASE_URL/public/api/v1/operacoes/{idOperacao}/arquivos-lidos-bucket` |

Lista, **paginado**, os arquivos lidos das pastas da operação, do mais recente para o mais antigo.

### Query Params

Todos são opcionais.

| Parâmetro | Tipo | Descrição |
|-----------|------|-----------|
| `idConfiguracaoLeitura` | Número | Filtra pela pasta (id de [Pastas de Leitura do Bucket](11.2.%20Pastas%20de%20Leitura%20do%20Bucket.md)). |
| `status` | Texto | Filtra pelo resultado da leitura: `Processado`, `Falha` ou `Ignorado`. |
| `indicePagina` | Número | Página (base 1). Padrão `1`. |
| `tamanhoDaPagina` | Número | Tamanho da página. Padrão `20`, máximo `200` (valor maior é reduzido a `200`, e o `paginaQuantidadeRegistro` da resposta mostra o tamanho usado). |

```` bash title="Exemplo de cURL — falhas de uma pasta"
curl -X GET "https://BASE_URL/public/api/v1/operacoes/23/arquivos-lidos-bucket?idConfiguracaoLeitura=7&status=Falha" \
  -H "Authorization: Bearer {token}" \
  -H "GrupoEconomico: {grupo}"
````

```` json title="Response Body — 200 OK"
{
  "registros": [
    {
      "id": 1502,
      "idConfiguracaoLeitura": 7,
      "nomeConfiguracaoLeitura": "Retornos de cessão",
      "chaveObjeto": "retornos/cessao/retorno_cessao_20260928_002.csv",
      "hashConteudo": "9f2c1e...",
      "tamanho": 18240,
      "dataLeitura": "2026-09-29T18:10:02.771Z",
      "status": "Falha",
      "mensagemErro": "Não foi possível baixar o arquivo do bucket (objeto não encontrado)."
    }
  ],
  "paginacao": {
    "paginaAtual": 1,
    "paginaTotal": 1,
    "paginaQuantidadeRegistro": 20,
    "quantidadeRegistros": 1,
    "temPaginaAnterior": false,
    "temProximaPagina": false
  },
  "mensagem": null
}
````

## Reprocessar arquivo lido

| Método | URL |
|--------|-----|
| ![POST](https://img.shields.io/badge/POST-green) | `https://BASE_URL/public/api/v1/operacoes/{idOperacao}/arquivos-lidos-bucket/{id}/reprocessar` |

Libera um arquivo lido com **falha** (ou **ignorado** por falta de processador) para ser lido de novo na próxima leitura do bucket — por exemplo, depois de corrigir a configuração que causou a falha. Esta rota não possui `Request Body`.

```` bash title="Exemplo de cURL"
curl -X POST "https://BASE_URL/public/api/v1/operacoes/23/arquivos-lidos-bucket/1502/reprocessar" \
  -H "Authorization: Bearer {token}" \
  -H "GrupoEconomico: {grupo}"
````

```` json title="Response Body — 200 OK"
{
  "status": "sucesso",
  "mensagem": "O arquivo será lido de novo na próxima leitura do bucket."
}
````

## Erros

Erros retornam o envelope `RetornoPadrao`.

| HTTP | Quando |
|------|--------|
| `404 Not Found` | Operação inexistente ou inativa; no reprocessamento, arquivo que não é da operação. |
| `400 Bad Request` | Reprocessamento de arquivo já **processado** com sucesso. |

# Modelo de dados

## Arquivo lido

| Campo | Tipo | Descrição |
|-------|------|-----------|
| `id` | Número | Identificador do registro do arquivo lido. É o `id` do reprocessamento. |
| `idConfiguracaoLeitura` | Número | Pasta de onde o arquivo foi lido. |
| `nomeConfiguracaoLeitura` | Texto | Nome da pasta. |
| `chaveObjeto` | Texto | Caminho do arquivo no bucket da administradora. |
| `hashConteudo` | Texto | Hash do conteúdo lido. |
| `tamanho` | Número | Tamanho do arquivo, em bytes. |
| `dataLeitura` | Data e hora | Quando o arquivo foi lido. |
| `status` | Texto | `Processado`, `Falha` ou `Ignorado`. |
| `mensagemErro` | Texto | Motivo da falha ou do descarte, quando houver: a recusa do processamento (por exemplo, o lote do retorno não encontrado), o arquivo que sumiu do bucket, a falta de processador para o tipo da pasta. Uma falha inesperada (fora dessas regras) aparece com a mensagem genérica `Falha inesperada ao ler ou processar o arquivo...` — o detalhe fica só no log da plataforma; acione o suporte se ela se repetir depois do reprocessamento. |

O envelope de paginação (`registros`, `paginacao`, `mensagem`) é o mesmo de [Listar Lotes (Paginado)](../4.%20Consultas/4.6.%20Listar%20Lotes%20%28Paginado%29.md#envelope-de-paginacao).

# Observações

- **Processado não reprocessa:** o arquivo lido com sucesso já produziu o efeito dele (lote atualizado, estoque importado); reprocessá-lo é recusado para não aplicar o mesmo retorno duas vezes.
- **Escopo por operação:** o `id` do reprocessamento e o `idConfiguracaoLeitura` do filtro valem só dentro da operação da rota — o de outra operação devolve `404` no reprocessamento e lista vazia na consulta.
- **O arquivo continua no bucket:** reprocessar não baixa nem move nada na hora; a próxima leitura agendada encontra o arquivo de novo e o processa.