# API REST de Logs de Error (Laravel)

Esta API permite que sistemas externos registren y administren logs de errores centralizados.

## 1. Objetivo

Con esta API puedes:
- Guardar logs de error desde aplicaciones externas.
- Listar logs con filtros y paginación.
- Ver el detalle de un log específico.
- Actualizar estado o datos de un log.
- Eliminar logs (soft delete).

## 2. Base URL

En entorno local:
- `http://127.0.0.1:8000/api/v1`

## 3. Autenticación

Todos los endpoints de logs requieren token Bearer con Sanctum:

- Header: `Authorization: Bearer {token}`
- Header: `Accept: application/json`

Puedes emitir token usando el endpoint existente:
- `POST /api/v1/auth/token`

## 4. Tabla creada

Migración: `database/migrations/2026_04_06_000000_create_error_logs_table.php`

Tabla: `error_logs`

Campos principales:
- `id` (uuid, PK)
- `source` (string 100, nullable): sistema que reporta
- `environment` (string 50, nullable): ambiente (`production`, `staging`, etc.)
- `level` (enum): `debug`, `info`, `notice`, `warning`, `error`, `critical`, `alert`, `emergency`
- `message` (text)
- `exception_class` (string, nullable)
- `file` (string 1024, nullable)
- `line` (unsigned integer, nullable)
- `context` (json, nullable)
- `trace` (longText, nullable)
- `fingerprint` (string 64, nullable)
- `is_resolved` (boolean, default `false`)
- `occurred_at` (timestamp)
- `resolved_at` (timestamp, nullable)
- `created_at`, `updated_at`, `deleted_at`

## 5. Endpoints

### 5.1 Crear log

`POST /api/v1/error-logs`

Request ejemplo:
```json
{
  "source": "erp-backend",
  "environment": "production",
  "level": "error",
  "message": "Error al procesar factura",
  "exception_class": "RuntimeException",
  "file": "app/Services/InvoiceService.php",
  "line": 128,
  "context": {
    "invoice_id": 1502,
    "tenant_id": 44
  },
  "trace": "Stacktrace ...",
  "fingerprint": "5fca8f53ce4f8f2b8d988b1a6f5f60f8",
  "occurred_at": "2026-04-06T16:20:00Z"
}
```

Respuesta `201`:
```json
{
  "data": {
    "id": "8ef7f07f-a754-4cc7-b77e-3ec0d890b44d",
    "source": "erp-backend",
    "environment": "production",
    "level": "error",
    "message": "Error al procesar factura",
    "exception_class": "RuntimeException",
    "file": "app/Services/InvoiceService.php",
    "line": 128,
    "context": {
      "invoice_id": 1502,
      "tenant_id": 44
    },
    "trace": "Stacktrace ...",
    "fingerprint": "5fca8f53ce4f8f2b8d988b1a6f5f60f8",
    "is_resolved": false,
    "occurred_at": "2026-04-06T16:20:00.000000Z",
    "resolved_at": null,
    "created_at": "2026-04-06T16:20:03.000000Z",
    "updated_at": "2026-04-06T16:20:03.000000Z"
  }
}
```

### 5.2 Listar logs

`GET /api/v1/error-logs`

Query params soportados:
- `source` (string)
- `environment` (string)
- `level` (enum)
- `is_resolved` (`true|false|1|0`)
- `search` (busca en message, exception_class, file, fingerprint)
- `from` (date/datetime)
- `to` (date/datetime)
- `per_page` (1 a 100)

Ejemplo:
`GET /api/v1/error-logs?level=error&is_resolved=0&search=factura&per_page=20`

Respuesta `200`:
```json
{
  "data": [],
  "meta": {
    "current_page": 1,
    "last_page": 1,
    "per_page": 20,
    "total": 0
  }
}
```

### 5.3 Ver detalle

`GET /api/v1/error-logs/{errorLogId}`

Respuesta `200`:
```json
{
  "data": {
    "id": "8ef7f07f-a754-4cc7-b77e-3ec0d890b44d",
    "level": "error",
    "message": "Error al procesar factura"
  }
}
```

### 5.4 Actualizar log

`PATCH /api/v1/error-logs/{errorLogId}`

Request ejemplo (marcar resuelto):
```json
{
  "is_resolved": true,
  "resolved_at": "2026-04-06T17:00:00Z"
}
```

Request ejemplo (reabrir):
```json
{
  "is_resolved": false
}
```

Respuesta `200`:
```json
{
  "data": {
    "id": "8ef7f07f-a754-4cc7-b77e-3ec0d890b44d",
    "is_resolved": true,
    "resolved_at": "2026-04-06T17:00:00.000000Z"
  }
}
```

### 5.5 Eliminar log

`DELETE /api/v1/error-logs/{errorLogId}`

Respuesta `204` sin cuerpo.

## 6. Errores de validación

Cuando el payload es inválido, la API responde `422`:

```json
{
  "message": "Los datos enviados no son válidos.",
  "errors": {
    "level": [
      "The selected level is invalid."
    ]
  }
}
```

## 7. Comandos de despliegue

Ejecutar migraciones:

```bash
php artisan migrate
```

Verificar rutas:

```bash
php artisan route:list --path=error-logs
```

## 8. Notas de integración

- Esta API administra solo información de logs, sin lógica de notificaciones ni procesamiento adicional.
- Si quieres deduplicar en tu sistema cliente, usa `fingerprint`.
- `context` acepta objetos JSON anidados.