Justificar hallazgos

Explicar un hallazgo con un motivo, quitar la justificación y cómo se reutiliza entre versiones.

Un hallazgo que no es un error real se justifica: se deja por escrito por qué el valor es correcto. El hallazgo no se borra; queda como dismissed con su justificación, fecha y llave que la escribió, y deja de bloquear el certificado.

Si el hallazgo sí es un error, no lo justifiques: corrige el PDF y sube una versión nueva.

Justificar

POST/v1/avaluos/{folio}/errores/{errorId}/justificaravaluos:justify

Justifica un hallazgo de la evaluación

errorId es el id del hallazgo en latest_evaluation.errors.

curl -X POST "$API_URL/v1/avaluos/AVL-2026-000123/errores/7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f/justificar" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"justificacion":"La diferencia corresponde a la ampliación regularizada en 2021; se anexa licencia de construcción."}'

const res = await fetch(
  `${API_URL}/v1/avaluos/${folio}/errores/${hallazgo.id}/justificar`,
  {
    method: 'POST',
    headers: { 'x-api-key': API_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ justificacion: texto }),
  },
);
const avaluo = await res.json(); // el avalúo completo, ya actualizado

Campo	Regla
`justificacion`	Texto de 3 a 2000 caracteres.

Respuesta 200: el avalúo completo, con la misma forma que GET /v1/avaluos/{folio}. Así puedes refrescar tu pantalla sin otra llamada:

Lo que cambia (resumido)

{
  "hallazgos_pendientes": 0,
  "puede_certificar": true,
  "latest_evaluation": {
    "result": "aprobado_con_observaciones",
    "errors": [
      {
        "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
        "codigo_regla": "DAT-011",
        "estado": "dismissed",
        "justificacion": "La diferencia corresponde a la ampliación regularizada en 2021; …",
        "justificado_at": "2026-06-24T18:40:02.000Z",
        "justificacion_heredada": false,
        "justificacion_origen": "directa"
      }
    ]
  }
}

Justificar no cambia status del avalúo, pero sí recalcula hallazgos_pendientes, puede_certificar y el veredicto result. Volver a enviar la justificación sobre el mismo hallazgo reemplaza el texto.

Errores

HTTP	Causa	Solución
`400`	`errorId` no es un UUID (`Validation failed (uuid is expected)`).	Usa el `id` tal cual viene en `errors`.
`400`	`justificacion` falta, tiene menos de 3 o más de 2000 caracteres.	Ajusta el texto.
`404`	`Avalúo '…' no encontrado`.	Revisa el folio.
`404`	`Error '…' no encontrado en el avalúo '…'`.	El hallazgo es de otro avalúo.

Quitar una justificación

DELETE/v1/avaluos/{folio}/errores/{errorId}/justificaravaluos:justify

Quita la justificación de un hallazgo

curl -X DELETE "$API_URL/v1/avaluos/AVL-2026-000123/errores/7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f/justificar" \
  -H "x-api-key: $API_KEY"

Sin cuerpo. El hallazgo vuelve a pending, la justificación deja de reutilizarse y la respuesta es de nuevo el avalúo completo. Mismos errores 400 y 404 que al justificar.

Las justificaciones se reutilizan

Una justificación se recuerda por regla + sección + sujeto del hallazgo, no por su id. Por eso se aplica sola en dos casos, y justificacion_origen te dice cuál:

`justificacion_origen`	Cuándo
`directa`	La escribiste sobre ese hallazgo.
`heredada`	Viene de una evaluación anterior del mismo avalúo. Pasa al subir una versión nueva del PDF: los hallazgos que se repiten llegan ya justificados.
`propagada`	Viene de otro hallazgo igual en la misma evaluación que justificaste.

Los hallazgos heredada y propagada traen además justificacion_heredada: true.

Por qué

Corregir un dato del PDF no debería obligar a escribir de nuevo veinte justificaciones que siguen siendo válidas. Si una justificación heredada ya no aplica, quítala con DELETE; si quieres cambiar su texto, envía un POST nuevo sobre ese hallazgo.

El sujeto distingue hallazgos de la misma regla y sección que hablan de cosas distintas —por ejemplo, dos anuncios de mercado diferentes—, para que justificar uno no justifique el otro.

Qué desbloquea

El certificado sólo se emite cuando ningún hallazgo está pendiente, sea crítico, técnico o de forma. Mientras falte alguno, POST …/certificado responde 409 HALLAZGOS_PENDIENTES.

Atajo para tu interfaz: deshabilita el botón de certificar mientras puede_certificar sea false, y muestra hallazgos_pendientes como contador.