Evidence

Conjunto de notas administrativas (con adjuntos e historial de cambios) asociado de forma polimórfica a otro modelo. Sirve para dejar constancia y justificación de acciones sensibles; hoy el único owner soportado es BalanceMovement (alias de ruta balance-movements), normalmente para respaldar ajustes de saldo.

Ciclo de vida

  • Se crea junto con su primera nota (AdminNote con id 1) sobre el modelo indicado en la ruta {modelType}/{modelId}/evidence, opcionalmente con un adjunto.
  • Al actualizar se añade una nota nueva (petición sin id) o se edita una existente (con id); cambiar el texto de una nota guarda una copia del texto anterior en previous_versions.
  • Se pueden añadir más adjuntos a una nota concreta con el endpoint de adjuntos.
  • Un BalanceMovement sólo admite una Evidence, que queda enlazada en su relación related.

list (array de AdminNote)

Clave Descripción
id Identificador de la nota dentro de la evidencia.
text Texto de la nota.
author_id Cuenta que creó la nota.
created_at / updated_at Fechas de la nota.
attachments Lista de adjuntos ({url}).
previous_versions Versiones anteriores del texto ({text, updated_at}).
author Datos del autor añadidos en la respuesta (id, name, email).

Estructura de Datos

Atributo Tipo Descripción
id int
owner_type string Clase del modelo al que pertenece la evidencia (relación polimórfica owner).
owner_id int ID del modelo al que pertenece la evidencia.
list Collection Colección de notas administrativas (AdminNote); ver la tabla de arriba.
created_at datetime\|null Fecha de creación.
updated_at datetime\|null Fecha de última modificación.
allLogs ApiLog> Registros de auditoría de la API, incluidos los internos.
logs ApiLog> Registros de auditoría de la API visibles.
owner Model\|Eloquent Modelo dueño de la evidencia (por ahora siempre {@link BalanceMovement}). 
{
    "id": 5,
    "owner_type": "App\BalanceMovement",
    "owner_id": 75868,
    "list": [
        {
            "id": 1,
            "text": "IVA y otras pruebas con documento 123-4321-00",
            "created_at": "2025-07-15 18:43:25",
            "updated_at": "2025-07-15 18:43:25",
            "author_id": 1,
            "attachments": [],
            "previous_versions": [],
            "author": {
                "id": 1,
                "name": "Simgulary",
                "email": "superadmin@ondemand.io"
            }
        }
    ],
    "created_at": "2025-07-15 18:40:35",
    "updated_at": "2025-07-15 18:43:40"
}

Endpoints

Insertar Evidence

Crear una evidencia

Crea una Evidence sobre el modelo {modelType}/{modelId} con una primera nota (text) y, si se envía, un attachment. Si el owner es un BalanceMovement, éste queda enlazado a la evidencia por su relación related.

Método URI Cabeceras
POST /companies/{companyId}/{modelType}/{modelId}/evidence Authorization 
{
    "text": "required|string|max:512",
    "attachment": "nullable|image|mimes:jpeg,png,bmp|max:8192"
}

Errores de negocio

Código HTTP Cuándo ocurre
ER409 409 El movimiento de saldo ya tiene una evidencia asociada o no admite evidencias.

Listar Evidence

{info} Soporta: Paginación Filters Carga dinámica

Listar evidencias de un modelo

Devuelve las Evidence asociadas al modelo {modelType}/{modelId} (por ejemplo balance-movements/{id}), paginadas.

Método URI Cabeceras
GET /companies/{companyId}/{modelType}/{modelId}/evidence Authorization

Mostrar Evidence

{info} Soporta: Carga dinámica

Ver una evidencia

Devuelve la Evidence indicada con todas sus notas.

Método URI Cabeceras
GET /companies/{companyId}/evidence/{evidenceId} Authorization

Actualizar Evidence

Añadir o editar una nota

Con id edita el texto de esa nota (guardando el texto anterior en previous_versions); sin id agrega una nota nueva a la Evidence.

Método URI Cabeceras
PATCH /companies/{companyId}/evidence/{evidenceId} Authorization 
{
    "id": "nullable|integer|min:1",
    "text": "required|string|max:512"
}

Errores de negocio

Código HTTP Cuándo ocurre
ER422 422 Se envió un id que no corresponde a ninguna nota de la evidencia.

Eliminar Evidence

Eliminar una evidencia

Borra la Evidence indicada con todas sus notas.

Método URI Cabeceras
DELETE /companies/{companyId}/evidence/{evidenceId} Authorization

Acciones de Evidence

Añadir un adjunto a una nota

Sube un attachment y lo agrega a la nota id de la Evidence indicada.

Método URI Cabeceras
POST /companies/{companyId}/evidence/{evidenceId}/add-attachment Authorization 
{
    "id": "required|integer|min:1",
    "attachment": "required|image|mimes:jpeg,png,bmp|max:8192"
}

Errores de negocio

Código HTTP Cuándo ocurre
ER422 422 No existe una nota con ese id en la evidencia.

Relaciones