API de Trazo

Dirección y versión

Todo vive bajo /api/v1, en el mismo origen que la aplicación (en local, http://localhost:8088/api/v1). Las rutas de esta referencia se muestran sin ese prefijo. Los recursos van en plural, se identifican por su ULID público y los catálogos por su code. Las fechas viajan en ISO 8601 y en UTC, y los campos en snake_case.

Sesión

El ingreso (POST /auth/login) entrega un token de Sanctum con el prefijo trazo_. Si la cuenta tiene verificación en dos pasos, ese primer token solo sirve para enviar el código; el definitivo llega después. Cada petición lo manda en Authorization: Bearer …. La sesión dura como máximo 8 horas y se cierra tras 1 hora sin uso.

Cabeceras

Respuestas

Lo que sale bien viene en data y meta. Cada recurso trae actions: lo que la persona puede hacer con él, decidido por el backend. La interfaz solo muestra los botones que esa lista permite.

{
  "data": {
    "id": "01jbzk8m3q9w2e5r7t1y4u6i0p",
    "code": "TZ-26-0142",
    "title": "No llega el correo de recuperación",
    "actions": {
      "update": true,
      "change_status": true
    }
  },
  "meta": {}
}

{
  "data": [
    "…"
  ],
  "meta": {
    "page": 1,
    "per_page": 20,
    "total": 137,
    "last_page": 7
  }
}

Errores

Todos siguen el estándar RFC 9457 (application/problem+json) con un code estable que la interfaz traduce a un mensaje claro. Nunca incluyen trazas ni consultas. El catálogo completo está en Errores de la API.

{
  "type": "urn:trazo:error:validation-failed",
  "title": "Validation failed",
  "status": 422,
  "code": "VALIDATION_FAILED",
  "errors": {
    "title": [
      {
        "code": "TOO_LONG",
        "params": {
          "max": "80"
        }
      }
    ]
  },
  "trace_id": "01JB7Q3W0Z5K8R2M4N6P9T1V3X"
}

Límites

Módulos