> ## Documentation Index
> Fetch the complete documentation index at: https://docs.judit.io/llms.txt
> Use this file to discover all available pages before exploring further.

# API de Transferência de Arquivos

> Liste, consulte e faça download de arquivos disponíveis para transferência na Judit API. Atualize o status de cada arquivo após o consumo para fluxos auditáveis.

A **File Transfer API** entrega para você arquivos grandes geradas pela Judit — exportações em CSV/JSON de consultas customizadas, relatórios sob demanda, agregações volumosas — de forma assíncrona, com controle de status (`pending`, `available`, `consumed`) auditável por arquivo.

> 🤖 **Base URL:** `https://lawsuits.production.judit.io/`. Após gerar um relatório (ex.: [Consulta Customizada](/requests/custom-search.md)), use esta API para listar arquivos pendentes, baixar via URL pré-assinada e marcar como consumidos para evitar reprocessamento.

## Quando usar

> **Relatórios sob demanda**
>
> Consumir resultados de Consultas Customizadas que entregam arquivo (CSV/JSON) em vez de webhook.

> **Exportação batch**
>
> Receber dumps periódicos de carteira inteira (centenas de milhares de processos).

> **Auditoria**
>
> Trilha auditável de quem baixou cada arquivo e quando — perfeito para SOX/LGPD.

> **Pipelines de dados**
>
> Integrar Judit ao seu data lake/data warehouse via consumo de arquivos em batch.

***

## 🔐 Autenticação

Todas as requisições devem conter um cabeçalho com a chave de API da empresa:

```http theme={null}
api-key: SUA_CHAVE_DE_API
```

⚠️ Um usuário só pode acessar arquivos pertencentes ao tenant da sua própria empresa.

***

## 📂 Listar arquivos disponíveis

### `GET /transfer-file`

Retorna uma lista paginada de arquivos disponíveis para a empresa do usuário autenticado.

### Query Params suportados:

* `description`: string (filtra por descrição)
* `file_type`: `csv`, `json`, `parquet`
* `name`: string (filtra por nome do arquivo)
* `status`: string ou array (ex: `status=completed` ou `status=["completed","error"]`)
* Datas: filtros de intervalo para os campos abaixo:
  * `created_at`, `updated_at`, `completed_at`, `downloaded_at`, `error_at`, `failed_at`, `started_at`
  * Exemplo: `created_at_gte=2025-04-01T00:00:00.000Z`
* Paginação e ordenação:
  * `page`: número da página (default: 1)
  * `page_size`: tamanho da página (máx: 100, default: 10)
  * `order_by`: campo de ordenação (default: `created_at`)
  * `order`: `asc` ou `desc` (default: `desc`)

### Exemplo de chamada com `curl`:

```bash theme={null}
curl -H "api-key: SUA_CHAVE_DE_API" \
  "https://lawsuits.production.judit.io/transfer-file?page=1&page_size=20&status=[\"completed\"]"
```

### Exemplo de resposta:

```json theme={null}
{
  "page": 1,
  "page_data": [
    {
      "transfer_file_id": "be4ed52a-a96b-4782-a181-b7ed75cb2f21",
      "description": "ARQUIVO INICIAL - CARGA 0",
      "file_type": "parquet",
      "name": "be4ed52a-a96b-4782-a181-b7ed75cb2f21-part-00001.parquet",
      "status": "downloaded",
      "created_at": "2025-04-22T11:50:00.000Z",
      "updated_at": "2025-04-22T09:21:06.343Z",
      "completed_at": "2025-04-22T11:51:00.000Z",
      "started_at": "2025-04-22T11:50:01.000Z",
      "downloaded_at": "2025-04-22T09:21:06.343Z",
      "error_at": "2025-04-22T09:20:31.460Z",
      "error_message": "teste de erro",
      "file_size": 0.038,
      "lawsuits_count": 19
    }
  ],
  "page_count": 1,
  "all_count": 1,
  "all_pages_count": 1
}
```

#### Explicação dos campos de retorno:

* `page`: número da página atual
* `page_data`: lista de arquivos retornados nesta página
* `page_count`: quantidade de registros nesta página
* `all_count`: total de arquivos encontrados no filtro
* `all_pages_count`: total de páginas disponíveis

***

## 📥 Obter URL para download

### `GET /transfer-file/:transfer_file_id`

Retorna os metadados do arquivo e uma URL pré-assinada da AWS para download (válida por 5 minutos).

### Exemplo de chamada com `curl`:

```bash theme={null}
curl -H "api-key: SUA_CHAVE_DE_API" \
  "https://lawsuits.production.judit.io/transfer-file/be4ed52a-a96b-4782-a181-b7ed75cb2f21"
```

### Exemplo de resposta:

```json theme={null}
{
  "transfer_file_id": "be4ed52a-a96b-4782-a181-b7ed75cb2f21",
  "description": "ARQUIVO INICIAL - CARGA 0",
  "file_type": "parquet",
  "name": "be4ed52a-a96b-4782-a181-b7ed75cb2f21-part-00001.parquet",
  "status": "completed",
  "created_at": "2025-04-22T11:50:00.000Z",
  "updated_at": "2025-04-22T09:21:06.343Z",
  "completed_at": "2025-04-22T11:51:00.000Z",
  "started_at": "2025-04-22T11:50:01.000Z",
  "file_size": 0.038,
  "lawsuits_count": 19,
  "pre_signed_url": "https://s3.amazonaws.com/..."
}
```

***

## 🛠 Atualizar status de um arquivo

### `PATCH /transfer-file/:transfer_file_id`

Permite marcar o arquivo como `downloaded` ou `error` após a tentativa de uso.

### Exemplo de chamada com `curl`:

```bash theme={null}
curl -X PATCH -H "api-key: SUA_CHAVE_DE_API" \
     -H "Content-Type: application/json" \
     -d '{"status": "downloaded"}' \
     "https://lawsuits.production.judit.io/transfer-file/be4ed52a-a96b-4782-a181-b7ed75cb2f21"
```

### Corpo da requisição:

Para marcar como baixado:

```json theme={null}
{
  "status": "downloaded"
}
```

Para reportar erro:

```json theme={null}
{
  "status": "error",
  "error_message": "Descrição do erro, stack trace ou contexto do problema."
}
```

### Exemplo de resposta - status `downloaded`:

```json theme={null}
{
  "transfer_file_id": "be4ed52a-a96b-4782-a181-b7ed75cb2f21",
  "description": "ARQUIVO INICIAL - CARGA 0",
  "file_type": "parquet",
  "name": "be4ed52a-a96b-4782-a181-b7ed75cb2f21-part-00001.parque
t",
  "created_at": "2025-04-22T11:50:00.000Z",
  "updated_at": "2025-04-22T11:50:00.000Z"
}
```

## Erros comuns

| HTTP | Motivo | Como tratar |
| :- | :- | :- |
| `400` | Filtro ou status inválido. | Validar query params antes de enviar. |
| `401` | API Key ausente ou inválida. | Conferir o header `api-key`. |
| `404` | Arquivo não encontrado. | O `transfer_file_id` pode pertencer a outro tenant. |
| `429` | Rate limit excedido. | Backoff exponencial. |

## Próximos passos

* [Consulta Customizada](/requests/custom-search.md) — gerar relatórios grandes.
* [Webhooks](/webhook/callbacks.md) — ser notificado quando um arquivo estiver pronto.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.