Interpretar resultados

Todo el resultado de un avalúo está en GET /v1/avaluos/{folio}. Esta guía explica cada parte de esa respuesta.

GET/v1/avaluos/{folio}avaluos:read

Estado completo del avalúo

curl "$API_URL/v1/avaluos/AVL-2026-000123" -H "x-api-key: $API_KEY"

1 · El documento

document describe la versión vigente del PDF y si se pudo leer.

"document": {
  "version": 1,
  "estado": "completed",
  "nombre_archivo": "avaluo.pdf",
  "paginas": 58,
  "tamano_bytes": 482133,
  "created_at": "2026-06-24T18:30:01.000Z",
  "errores": [],
  "puede_evaluar": false
}

`document.estado`	Qué significa
`pending`	El PDF espera a leerse.
`processing`	Se está leyendo y validando.
`completed`	Terminó. Revisa `errores`.
`error`	No se pudo procesar. Vuelve a subirlo o reporta el folio.

Si el PDF no sirve para evaluarse —ilegible, incompleto o de otro avalúo—, errores trae un elemento por problema. En ese caso la evaluación no se ejecuta y el avalúo queda en requires_correction: hay que subir un PDF corregido (ver cómo).

"errores": [
  {
    "titulo": "Escritura ilegible",
    "codigo_regla": "DOC-002",
    "severidad": "critico",
    "descripcion": "Las páginas de la escritura no tienen texto legible.",
    "seccion_avaluo": "Escritura",
    "valor_encontrado": null,
    "valor_esperado": "Escritura legible",
    "sugerencia": "Escanea de nuevo la escritura con mejor resolución y vuelve a subir el documento."
  }
]

2 · La evaluación

Cuando el documento queda limpio, la evaluación empieza sola y aparece latest_evaluation. Mientras no existe, vale null.

"latest_evaluation": {
  "id": "e1a2b3c4-0000-4000-8000-000000000001",
  "estado": "processing",
  "result": null,
  "stages": [
    { "name": "documental", "status": "completed" },
    { "name": "datos", "status": "completed" },
    { "name": "calculos", "status": "processing" },
    { "name": "mercado", "status": "processing" },
    { "name": "reglas", "status": "pending" }
  ],
  "errors": [ … ],
  "comparables_web": null,
  "antecedentes": []
}

`latest_evaluation.estado`	Qué significa
`pending`	Creada, aún sin empezar.
`processing`	Alguna etapa sigue en curso.
`completed`	Terminaron las cinco etapas: los hallazgos son definitivos.
`error`	La evaluación falló.
`cancelled`	Se canceló.

Las cinco etapas

`name`	Qué revisa
`documental`	Que el expediente esté completo: anexos, firmas, vigencias.
`datos`	Que los datos capturados coincidan con la escritura y la carátula: superficies, colindancias, régimen.
`calculos`	La aritmética del avalúo: valores unitarios, factores, totales.
`mercado`	Que el valor sea coherente con comparables de mercado y el histórico de avalúos cercanos.
`reglas`	El cumplimiento de la normativa SHF y CNBV.

Cada etapa tiene status: pending, processing, completed, error o skipped.

Las etapas no terminan en orden

Las etapas corren en paralelo. stages viene ordenado para mostrarlo, pero una etapa puede terminar antes que la anterior. No des nada por terminado hasta que latest_evaluation.estado sea completed.

3 · Los hallazgos

Cada elemento de latest_evaluation.errors es un hallazgo: algo que el motor considera incorrecto o dudoso.

{
  "id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
  "codigo_regla": "MER-005",
  "severidad": "tecnico",
  "titulo": "Valor del avalúo >20% por debajo del mercado web",
  "descripcion": "El valor unitario del avalúo está 27% por debajo del promedio de comparables.",
  "seccion_avaluo": "Enfoque de mercado",
  "valor_encontrado": "Unitario avalúo $26,113/m²",
  "valor_esperado": "Dentro de ±20% del promedio de mercado",
  "sugerencia": "Revisa la selección de comparables o justifica la diferencia.",
  "estado": "pending",
  "justificacion": null,
  "justificado_at": null,
  "justificacion_heredada": false,
  "justificacion_origen": null,
  "sujeto_url": null
}

Campo	Qué es
`id`	Identificador del hallazgo. Lo usas para justificarlo.
`codigo_regla`	La regla que lo produjo. Ver el catálogo de reglas.
`severidad`	Qué tan grave es (ver abajo).
`titulo`, `descripcion`	Qué se encontró, para mostrar al perito.
`seccion_avaluo`	La sección del avalúo donde está.
`valor_encontrado`, `valor_esperado`	El dato del PDF y lo que se esperaba.
`sugerencia`	Cómo resolverlo.
`estado`	`pending` (sin atender), `dismissed` (justificado) o `resolved`.
`justificacion`, `justificado_at`	El texto de la justificación y cuándo se escribió.
`justificacion_origen`	`directa`, `heredada` o `propagada`. Ver justificaciones.
`sujeto_url`	Enlace al anuncio o fuente concreta, cuando el hallazgo se refiere a uno.

Severidades

`severidad`	Significado
`critico`	Afecta la validez del avalúo. Mientras haya uno sin justificar, el veredicto es `no_aprobado`.
`tecnico`	Error o inconsistencia técnica que hay que corregir o explicar.
`forma`	Detalle de presentación.

Todos los hallazgos, sea cual sea su severidad, deben corregirse o justificarse antes de emitir el certificado.

4 · El veredicto

latest_evaluation.result resume el resultado. Es null mientras la evaluación no termina.

`result`	Cuándo
`aprobado`	No hay hallazgos.
`aprobado_con_observaciones`	Hay hallazgos, pero ningún crítico sin justificar.
`no_aprobado`	Hay al menos un hallazgo crítico sin justificar.

El veredicto se recalcula cada vez que justificas o quitas una justificación: al justificar el último crítico pasa de no_aprobado a aprobado_con_observaciones.

5 · Material de mercado

Dos bloques de apoyo para revisar la etapa mercado:

comparables_web — null o un objeto con resumen (número de comparables, radio de búsqueda, unitario promedio frente al del avalúo…) y comparables, la lista de anuncios usados, cada uno con titulo, fuente, ubicacion, precio, unitario, superficie_m2, recamaras, banos, operacion y url.
antecedentes — avalúos históricos cercanos, con dirección, coordenadas, distancia_m, superficies y valor_avaluo. Son material de consulta: no generan hallazgos que bloqueen el avalúo.

6 · Estado general y siguientes pasos

Campo	Qué te dice
`status`	Estado del avalúo. Ver ciclo de vida.
`hallazgos_pendientes`	Cuántos hallazgos faltan por atender.
`puede_certificar`	`true` cuando se puede emitir el certificado.
`certificado`	El certificado vigente, o `null`.
`dictamen_control`	El dictamen del controlador, o `null`.

Lanzar la evaluación a mano

Normalmente no hace falta: la evaluación empieza sola. Si document.puede_evaluar es true y quieres forzarla:

POST/v1/avaluos/{folio}/evaluaravaluos:write

Inicia la evaluación de 5 etapas

curl -X POST "$API_URL/v1/avaluos/AVL-2026-000123/evaluar" -H "x-api-key: $API_KEY"

Responde 202 con el avalúo completo. Si el documento ya tiene una evaluación en curso o terminada no crea otra: para re-evaluar hay que subir una versión nueva del PDF.

HTTP	`code`	Causa
`404`	—	El folio no existe o no tiene documento.
`409`	`DOCUMENTO_NO_LISTO`	El PDF todavía se está leyendo. Espera y reintenta.
`409`	`DOCUMENTO_CON_ERRORES`	El PDF tiene errores: sube una versión corregida.