# API REST — PES2B Agent 1.1.0

Base local padrão:

```text
http://127.0.0.1:3000
```

## Autenticação

Exceto `/health`, todas as rotas exigem:

```http
X-PES2B-API-KEY: <PES2B_API_KEY>
```

## Estados de job

Estados observados pelo Agent e runners:

- `QUEUED`;
- `RUNNING`;
- `SUCCEEDED`;
- `FAILED`;
- `TIMED_OUT`;
- `FAILED_TO_START` em resultado de runner.

## GET /health

Saúde do processo. Não exige autenticação.

```json
{
  "status": "UP",
  "service": "PES2B Agent",
  "version": "1.1.0",
  "executor": "RPA_LOCAL_01",
  "environment": "production",
  "automationsLoaded": 3,
  "startedAt": "2026-08-01T10:00:00.000Z",
  "uptimeSeconds": 120,
  "timestamp": "2026-08-01T10:02:00.000Z"
}
```

## GET /api/v1/automations

Lista os pacotes carregados.

```json
{
  "count": 1,
  "items": [
    {
      "schemaVersion": "1.0",
      "id": "teste-node",
      "name": "Teste Node",
      "version": "1.0.0",
      "enabled": true
    }
  ]
}
```

## GET /api/v1/automations/:id

Retorna um pacote carregado. Responde `404` se não existir.

## POST /api/v1/automations/reload

Limpa o registro e relê os diretórios em `AUTOMATIONS_ROOT`.

Resposta `200`:

```json
{
  "count": 3,
  "items": []
}
```

## POST /api/v1/automations/:id/run

Cria um job assíncrono.

```json
{
  "requestId": "operacao-idempotente-opcional",
  "input": {
    "campo": "valor"
  }
}
```

Resposta `202`:

```json
{
  "id": "uuid-do-job",
  "jobId": "uuid-do-job",
  "requestId": "request-id",
  "automationId": "teste-node",
  "status": "QUEUED",
  "createdAt": "2026-08-01T10:00:00.000Z",
  "startedAt": null,
  "finishedAt": null,
  "input": {
    "campo": "valor"
  },
  "result": null,
  "files": [],
  "error": null
}
```

Observação: `requestId` é pesquisável, mas a versão 1.1.0 não impede automaticamente a criação de duplicatas com o mesmo valor.

## GET /api/v1/jobs?limit=50

Lista os jobs mais recentes. `limit` aceita de 1 a 200.

## GET /api/v1/jobs/:id

Consulta um job específico.

Exemplo terminal:

```json
{
  "id": "uuid",
  "jobId": "uuid",
  "requestId": "request-id",
  "automationId": "dec-poa",
  "status": "SUCCEEDED",
  "result": {
    "success": true,
    "result": {
      "success": true,
      "state": "COMPLETED"
    }
  },
  "files": [],
  "error": null
}
```

## GET /api/v1/jobs/by-request/:requestId

Localiza a primeira execução em memória com o `requestId` informado. Responde `404` quando não encontrada.

## GET /api/v1/jobs/:jobId/files

Lista os arquivos registrados para o job.

```json
{
  "jobId": "uuid",
  "count": 1,
  "items": [
    {
      "fileId": "uuid-arquivo",
      "jobId": "uuid",
      "fileName": "relatorio.pdf",
      "mimeType": "application/pdf",
      "sizeBytes": 12345,
      "createdAt": "2026-08-01T10:00:00.000Z",
      "expiresAt": "2026-08-08T10:00:00.000Z",
      "downloadedAt": null,
      "downloadUrl": "/api/v1/jobs/uuid/files/uuid-arquivo"
    }
  ]
}
```

## GET /api/v1/jobs/:jobId/files/:fileId

Baixa o arquivo. O arquivo precisa:

- estar registrado no índice;
- pertencer ao `jobId` da URL;
- ainda existir no disco.

Respostas relevantes:

- `200`: download;
- `404`: registro não pertence ao job ou não existe;
- `410`: registro existe, mas o arquivo deixou de estar disponível.

## Erros comuns

```json
{
  "error": "Automation not found."
}
```

```json
{
  "error": "Invalid or missing API key."
}
```

```json
{
  "error": "Route not found."
}
```


# Configuração

O Agent usa variáveis de ambiente carregadas do processo e, complementarmente, do arquivo `.env`.

| Variável | Padrão | Descrição |
|---|---:|---|
| `NODE_ENV` | `development` | Ambiente. Em produção desativa o console formatado. |
| `HOST` | `127.0.0.1` | Interface de escuta. |
| `PORT` | `3000` | Porta HTTP. |
| `EXECUTOR_ID` | `RPA_LOCAL_01` | Identificador lógico da máquina/executor. |
| `PES2B_API_KEY` | vazio | Chave obrigatória para rotas `/api/v1`. |
| `JSON_LIMIT` | `1mb` | Limite do body JSON do Express. |
| `AUTOMATIONS_ROOT` | `C:\PES2B\Automacoes` | Raiz dos pacotes. |
| `MAX_CONCURRENT_JOBS` | `1` | Concorrência global da fila. |
| `DEFAULT_AUTOMATION_TIMEOUT_MS` | `300000` | Timeout padrão quando o pacote não define outro. |
| `FILE_STORAGE_ROOT` | `runtime/files` | Índice de metadados de arquivos. |
| `FILE_ALLOWED_ROOTS` | `AUTOMATIONS_ROOT` | Lista separada por `;` de raízes autorizadas. |
| `FILE_RETENTION_DAYS` | `7` | Retenção do registro no índice. |
| `LOG_DIR` | `logs` | Diretório dos logs. |
| `RUNTIME_DIR` | `runtime` | Diretório transitório do Agent. |
| `LOG_LEVEL` | `info` | Nível do Pino. |

## Produção segura

```dotenv
NODE_ENV=production
HOST=127.0.0.1
PORT=3000
EXECUTOR_ID=RPA_LOCAL_01
PES2B_API_KEY=<segredo-gerado>
AUTOMATIONS_ROOT=C:\PES2B\Automacoes
MAX_CONCURRENT_JOBS=1
DEFAULT_AUTOMATION_TIMEOUT_MS=600000
FILE_STORAGE_ROOT=C:\PES2B\Plataforma\PES2B-Agent\runtime\files
FILE_ALLOWED_ROOTS=C:\PES2B\Automacoes
FILE_RETENTION_DAYS=7
LOG_DIR=C:\PES2B\Plataforma\PES2B-Agent\logs
RUNTIME_DIR=C:\PES2B\Plataforma\PES2B-Agent\runtime
LOG_LEVEL=info
```

Não envolva valores com aspas sem necessidade. Em `FILE_ALLOWED_ROOTS`, separe múltiplos caminhos por ponto e vírgula.