API de Transferência de Arquivos

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), 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:

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`:

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:

{
  "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`:

curl -H "api-key: SUA_CHAVE_DE_API" \
  "https://lawsuits.production.judit.io/transfer-file/be4ed52a-a96b-4782-a181-b7ed75cb2f21"

Exemplo de resposta:

{
  "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`:

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:

{
  "status": "downloaded"
}

Para reportar erro:

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

Exemplo de resposta - status `downloaded`:

{
  "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 — gerar relatórios grandes.
Webhooks — ser notificado quando um arquivo estiver pronto.

Primeiros Passos

Conceitos Fundamentais

Modelo de Dados (Schemas)

Consultas Assíncronas

Consultas Síncronas

Monitoramento

Dados Cadastrais

Consultas Penais

Transferência de Arquivos

Cofre de Credenciais

Webhook

Recursos

Quando usar

Relatórios sob demanda

Exportação batch

Auditoria

Pipelines de dados

🔐 Autenticação

📂 Listar arquivos disponíveis

`GET /transfer-file`

Query Params suportados:

Exemplo de chamada com `curl`:

Exemplo de resposta:

Explicação dos campos de retorno:

📥 Obter URL para download

`GET /transfer-file/:transfer_file_id`

Exemplo de chamada com `curl`:

Exemplo de resposta:

🛠 Atualizar status de um arquivo

`PATCH /transfer-file/:transfer_file_id`

Exemplo de chamada com `curl`:

Corpo da requisição:

Exemplo de resposta - status `downloaded`:

Erros comuns

Próximos passos

​Quando usar

Relatórios sob demanda

Exportação batch

Auditoria

Pipelines de dados

​🔐 Autenticação

​📂 Listar arquivos disponíveis

​GET /transfer-file

​Query Params suportados:

​Exemplo de chamada com curl:

​Exemplo de resposta:

​Explicação dos campos de retorno:

​📥 Obter URL para download

​GET /transfer-file/:transfer_file_id

​Exemplo de chamada com curl:

​Exemplo de resposta:

​🛠 Atualizar status de um arquivo

​PATCH /transfer-file/:transfer_file_id

​Exemplo de chamada com curl:

​Corpo da requisição:

​Exemplo de resposta - status downloaded:

​Erros comuns

​Próximos passos

Quando usar

🔐 Autenticação

📂 Listar arquivos disponíveis

`GET /transfer-file`

Query Params suportados:

Exemplo de chamada com `curl`:

Exemplo de resposta:

Explicação dos campos de retorno:

📥 Obter URL para download

`GET /transfer-file/:transfer_file_id`

Exemplo de chamada com `curl`:

Exemplo de resposta:

🛠 Atualizar status de um arquivo

`PATCH /transfer-file/:transfer_file_id`

Exemplo de chamada com `curl`:

Corpo da requisição:

Exemplo de resposta - status `downloaded`:

Erros comuns

Próximos passos