# API del Agente de IA — VL Siniestros

**Base URL:** `https://ledesma.ngunilla.com/api/public/agent/v1`

## Autenticación

Todas las llamadas requieren un header:

```
Authorization: Bearer agt_live_...
Content-Type: application/json
```

El token se genera desde **Configuración → Agente IA** y se muestra una única vez al crearlo o rotarlo.

## Convenciones

- Todas las respuestas son JSON.
- Los errores siguen el formato `{ "error": { "code": string, "message": string } }`.
- Los timestamps están en ISO 8601 UTC.
- Paginación: `page` (>=1) y `pageSize` (máx 100).

## Códigos de error

| Código HTTP | Significado |
| --- | --- |
| 400 | Request mal formado |
| 401 | Token faltante o inválido |
| 403 | Scope insuficiente |
| 404 | Recurso no encontrado |
| 422 | Validación fallida |
| 500 | Error interno |

## Scopes disponibles

- `*` — acceso total
- `siniestros:read`, `siniestros:write`
- `documentos:read`, `documentos:write`
- `notas:read`, `notas:write`
- `ofertas:write`, `cierre:write`
- `catalogos:read`, `catalogos:write`
- `eventos:write`

## Endpoints

### `GET /me`

**Scope:** `cualquiera`  
Información del agente autenticado

**Response ejemplo:**

```json
{
  "id": "uuid",
  "nombre": "Asistente principal",
  "scopes": [
    "*"
  ],
  "user_id": "uuid"
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/me"
```

### `GET /siniestros`

**Scope:** `siniestros:read`  
Listar siniestros

**Query params:**

- `estado` (string) — Filtro por estado (ej. reclamo_presentado)
- `q` (string) — Búsqueda por código, N° siniestro o patente
- `page` (number) — Página (default 1)
- `pageSize` (number) — Tamaño de página (default 20, máx 100)

**Response ejemplo:**

```json
{
  "rows": [
    {
      "id": "uuid",
      "codigo": "VL-2025-0001",
      "estado": "reclamo_presentado",
      "cliente": {
        "nombre": "Juan Pérez"
      },
      "fecha_hecho": "2025-01-10"
    }
  ],
  "total": 1
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros"
```

### `GET /siniestros/:id`

**Scope:** `siniestros:read`  
Detalle de un siniestro

**Response ejemplo:**

```json
{
  "id": "uuid",
  "codigo": "VL-2025-0001",
  "estado": "reclamo_presentado"
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID"
```

### `POST /siniestros`

**Scope:** `siniestros:write`  
Crear un siniestro nuevo

**Body:**

Datos mínimos del cliente y del siniestro.

```json
{
  "cliente": {
    "nombre": "Juan Pérez",
    "dni_cuit": "20-12345678-9",
    "telefono": "+54..."
  },
  "siniestro": {
    "fecha_hecho": "2025-01-10",
    "descripcion_hecho": "Colisión en Av. Cabildo",
    "proximo_paso": "Presentar denuncia"
  }
}
```

**Response ejemplo:**

```json
{
  "id": "uuid",
  "codigo": "VL-2025-0001"
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"cliente":{"nombre":"Juan Pérez","dni_cuit":"20-12345678-9","telefono":"+54..."},"siniestro":{"fecha_hecho":"2025-01-10","descripcion_hecho":"Colisión en Av. Cabildo","proximo_paso":"Presentar denuncia"}}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros"
```

### `POST /siniestros/:id/estado`

**Scope:** `siniestros:write`  
Cambiar el estado de un siniestro

**Body:**

```json
{
  "estado": "reclamo_presentado",
  "nota": "Enviado por plataforma X"
}
```

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"estado":"reclamo_presentado","nota":"Enviado por plataforma X"}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/estado"
```

### `POST /siniestros/:id/eventos`

**Scope:** `eventos:write`  
Agregar un evento/nota al timeline

**Body:**

```json
{
  "titulo": "Llamado con la compañía",
  "descripcion": "Informa demora",
  "tipo": "nota"
}
```

**Response ejemplo:**

```json
{
  "id": "uuid"
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"titulo":"Llamado con la compañía","descripcion":"Informa demora","tipo":"nota"}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/eventos"
```

### `GET /siniestros/:id/timeline`

**Scope:** `siniestros:read`  
Timeline de eventos del siniestro

**Response ejemplo:**

```json
{
  "rows": [
    {
      "id": "uuid",
      "tipo": "cambio_estado",
      "titulo": "Cambio de estado"
    }
  ]
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/timeline"
```

### `GET /siniestros/:id/checklist`

**Scope:** `documentos:read`  
Checklist de documentos del siniestro

**Response ejemplo:**

```json
{
  "rows": [
    {
      "id": "uuid",
      "document_type": "DNI",
      "estado": "faltante"
    }
  ]
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/checklist"
```

### `GET /clientes`

**Scope:** `catalogos:read`  
Listar clientes

**Response ejemplo:**

```json
{
  "rows": [
    {
      "id": "uuid",
      "nombre": "Juan Pérez"
    }
  ]
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/clientes"
```

### `GET /companias`

**Scope:** `catalogos:read`  
Listar compañías

**Response ejemplo:**

```json
{
  "rows": [
    {
      "id": "uuid",
      "nombre": "La Segunda"
    }
  ]
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/companias"
```

### `GET /productores`

**Scope:** `catalogos:read`  
Listar productores

**Response ejemplo:**

```json
{
  "rows": [
    {
      "id": "uuid",
      "nombre": "Broker X"
    }
  ]
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/productores"
```

### `GET /tramitadores`

**Scope:** `catalogos:read`  
Listar tramitadores

**Response ejemplo:**

```json
{
  "rows": [
    {
      "id": "uuid",
      "nombre": "Estudio Y"
    }
  ]
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/tramitadores"
```

### `GET /plantillas`

**Scope:** `catalogos:read`  
Listar plantillas de mensajes

**Response ejemplo:**

```json
{
  "rows": [
    {
      "id": "uuid",
      "nombre": "Aviso presentación"
    }
  ]
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/plantillas"
```

### `GET /search`

**Scope:** `siniestros:read`  
Búsqueda global

**Query params:**

- `q` (string, requerido) — Texto a buscar

**Response ejemplo:**

```json
{
  "siniestros": [],
  "clientes": []
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/search"
```

### `PATCH /siniestros/:id`

**Scope:** `siniestros:write`  
Actualizar campos del siniestro. Permite modificar cualquier campo editable (montos, fechas, IDs de catálogo, observaciones, etc). No permite tocar id, codigo, timestamps ni is_test.

**Body:**

```json
{
  "proximo_paso": "Reunión con perito",
  "monto_reclamado": 500000,
  "compania_propia_id": "uuid"
}
```

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"proximo_paso":"Reunión con perito","monto_reclamado":500000,"compania_propia_id":"uuid"}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID"
```

### `POST /siniestros/:id/archivar`

**Scope:** `siniestros:write`  
Archivar un siniestro

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/archivar"
```

### `POST /siniestros/:id/reabrir`

**Scope:** `siniestros:write`  
Reabrir un siniestro archivado

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/reabrir"
```

### `GET /siniestros/:id/notas`

**Scope:** `notas:read`  
Listar notas del siniestro (por audiencia)

**Response ejemplo:**

```json
{
  "rows": [
    {
      "id": "uuid",
      "audiencia": "interna",
      "contenido": "..."
    }
  ]
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/notas"
```

### `POST /siniestros/:id/notas`

**Scope:** `notas:write`  
Crear nota con audiencia (interna/productor/cliente/todos)

**Body:**

```json
{
  "contenido": "Cliente confirmó documentación",
  "audiencia": "interna"
}
```

**Response ejemplo:**

```json
{
  "id": "uuid"
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"contenido":"Cliente confirmó documentación","audiencia":"interna"}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/notas"
```

### `POST /siniestros/:id/documentos`

**Scope:** `documentos:write`  
Agregar requisito al checklist

**Body:**

Especificar por UUID o por código (`document_type_codigo`).

```json
{
  "document_type_codigo": "dni_titular",
  "estado": "faltante"
}
```

**Response ejemplo:**

```json
{
  "id": "uuid"
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"document_type_codigo":"dni_titular","estado":"faltante"}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/documentos"
```

### `PATCH /siniestros/:id/documentos/:docId`

**Scope:** `documentos:write`  
Actualizar estado/comentario de un ítem del checklist

**Body:**

```json
{
  "estado": "recibido",
  "comentario": "OK",
  "fecha_recepcion": "2025-02-01"
}
```

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"estado":"recibido","comentario":"OK","fecha_recepcion":"2025-02-01"}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/documentos/:docId"
```

### `POST /siniestros/:id/documentos/:docId/archivos`

**Scope:** `documentos:write`  
Subir archivo (base64) o adjuntar link externo (Dropbox/Drive). Enviar `content_base64` para subir directo al bucket, o `external_url` para guardar solo el link. Máximo 25MB por archivo. Marca el requisito como recibido.

**Body:**

```json
{
  "nombre": "dni-frente.jpg",
  "mime_type": "image/jpeg",
  "content_base64": "iVBORw0KGgo..."
}
```

**Response ejemplo:**

```json
{
  "id": "uuid",
  "storage_path": "uuid/dni_titular/agent-..."
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"dni-frente.jpg","mime_type":"image/jpeg","content_base64":"iVBORw0KGgo..."}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/documentos/:docId/archivos"
```

### `GET /siniestros/:id/adjuntos`

**Scope:** `documentos:read`  
Listar adjuntos libres (fotos DNI, póliza, etc.)

**Response ejemplo:**

```json
{
  "rows": []
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/adjuntos"
```

### `POST /siniestros/:id/adjuntos`

**Scope:** `documentos:write`  
Subir un adjunto libre (foto DNI, póliza, etc.)

**Body:**

```json
{
  "nombre": "poliza.pdf",
  "kind": "poliza",
  "mime_type": "application/pdf",
  "content_base64": "JVBERi0xLjQK..."
}
```

**Response ejemplo:**

```json
{
  "id": "uuid",
  "storage_path": "..."
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"poliza.pdf","kind":"poliza","mime_type":"application/pdf","content_base64":"JVBERi0xLjQK..."}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/adjuntos"
```

### `GET /siniestros/:id/ofertas`

**Scope:** `siniestros:read`  
Listar ofertas de negociación

**Response ejemplo:**

```json
{
  "rows": []
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/ofertas"
```

### `POST /siniestros/:id/ofertas`

**Scope:** `ofertas:write`  
Registrar oferta / contraoferta / aceptación / rechazo

**Body:**

```json
{
  "origen": "compania",
  "tipo": "oferta",
  "monto": 450000,
  "canal": "email",
  "comentario": "Primera propuesta"
}
```

**Response ejemplo:**

```json
{
  "id": "uuid",
  "secuencia": 1
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"origen":"compania","tipo":"oferta","monto":450000,"canal":"email","comentario":"Primera propuesta"}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/ofertas"
```

### `GET /siniestros/:id/cierre`

**Scope:** `siniestros:read`  
Checklist de cierre del siniestro

**Response ejemplo:**

```json
{
  "rows": []
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/cierre"
```

### `PATCH /siniestros/:id/cierre/:taskId`

**Scope:** `cierre:write`  
Actualizar una tarea del checklist de cierre

**Body:**

```json
{
  "estado": "hecho",
  "comentario": "Confirmado"
}
```

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"estado":"hecho","comentario":"Confirmado"}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/siniestros/SINIESTRO_ID/cierre/:taskId"
```

### `POST /clientes`

**Scope:** `catalogos:write`  
Crear cliente

**Body:**

```json
{
  "nombre": "Juan Pérez",
  "dni_cuit": "20-...",
  "telefono": "+54...",
  "email": "j@e.com"
}
```

**Response ejemplo:**

```json
{
  "id": "uuid"
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Juan Pérez","dni_cuit":"20-...","telefono":"+54...","email":"j@e.com"}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/clientes"
```

### `PATCH /clientes/:id`

**Scope:** `catalogos:write`  
Actualizar cliente

**Body:**

```json
{
  "telefono": "+54..."
}
```

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"telefono":"+54..."}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/clientes/SINIESTRO_ID"
```

### `POST /companias`

**Scope:** `catalogos:write`  
Crear compañía

**Body:**

```json
{
  "nombre": "La Segunda",
  "email_reclamos": "reclamos@..."
}
```

**Response ejemplo:**

```json
{
  "id": "uuid"
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"La Segunda","email_reclamos":"reclamos@..."}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/companias"
```

### `PATCH /companias/:id`

**Scope:** `catalogos:write`  
Actualizar compañía

**Body:**

```json
{
  "activa": false
}
```

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activa":false}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/companias/SINIESTRO_ID"
```

### `POST /productores`

**Scope:** `catalogos:write`  
Crear productor/broker

**Body:**

```json
{
  "nombre": "Broker X",
  "email": "..."
}
```

**Response ejemplo:**

```json
{
  "id": "uuid"
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Broker X","email":"..."}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/productores"
```

### `PATCH /productores/:id`

**Scope:** `catalogos:write`  
Actualizar productor

**Body:**

```json
{
  "activo": false
}
```

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activo":false}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/productores/SINIESTRO_ID"
```

### `POST /tramitadores`

**Scope:** `catalogos:write`  
Crear tramitador

**Body:**

```json
{
  "nombre": "Estudio Y"
}
```

**Response ejemplo:**

```json
{
  "id": "uuid"
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Estudio Y"}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/tramitadores"
```

### `PATCH /tramitadores/:id`

**Scope:** `catalogos:write`  
Actualizar tramitador

**Body:**

```json
{
  "email": "..."
}
```

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email":"..."}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/tramitadores/SINIESTRO_ID"
```

### `POST /plantillas`

**Scope:** `catalogos:write`  
Crear plantilla

**Body:**

```json
{
  "nombre": "Recordatorio",
  "canal": "email",
  "cuerpo": "Hola {{cliente}}..."
}
```

**Response ejemplo:**

```json
{
  "id": "uuid"
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nombre":"Recordatorio","canal":"email","cuerpo":"Hola {{cliente}}..."}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/plantillas"
```

### `PATCH /plantillas/:id`

**Scope:** `catalogos:write`  
Actualizar plantilla

**Body:**

```json
{
  "activa": false
}
```

**Response ejemplo:**

```json
{
  "ok": true
}
```

**Ejemplo curl:**

```bash
curl -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"activa":false}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/plantillas/SINIESTRO_ID"
```

### `GET /document-types`

**Scope:** `catalogos:read`  
Tipos de documento disponibles para el checklist

**Response ejemplo:**

```json
{
  "rows": [
    {
      "id": "uuid",
      "codigo": "dni_titular",
      "nombre": "DNI titular"
    }
  ]
}
```

**Ejemplo curl:**

```bash
curl -H "Authorization: Bearer $TOKEN" "https://ledesma.ngunilla.com/api/public/agent/v1/document-types"
```

### `POST /storage/signed-url`

**Scope:** `documentos:read`  
Obtener URL firmada temporal para descargar un archivo del bucket

**Body:**

```json
{
  "storage_path": "uuid/dni_titular/agent-...",
  "expires_in": 600
}
```

**Response ejemplo:**

```json
{
  "url": "https://..."
}
```

**Ejemplo curl:**

```bash
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"storage_path":"uuid/dni_titular/agent-...","expires_in":600}' \
  "https://ledesma.ngunilla.com/api/public/agent/v1/storage/signed-url"
```