Avalúos

Cada ficha trae los parámetros, un ejemplo de petición en curl y JavaScript, la respuesta esperada y los errores posibles. Los ejemplos usan las variables API_URL y API_KEY descritas en convenciones.

POST/v1/avaluosavaluos:write

Crea un avalúo por referencia y dispara su procesamiento

POST/v1/avaluos/procesaravaluos:write

Crea un avalúo subiendo el PDF en base64

POST/v1/avaluos/estadosavaluos:read

Estados ligeros de varios folios

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

Estado completo del avalúo

DELETE/v1/avaluos/{folio}avaluos:delete

Elimina el avalúo y todo lo relacionado

GET/v1/avaluos/{folio}/previewavaluos:delete

Previsualiza la eliminación (dry-run)

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

Inicia la evaluación de 5 etapas

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

Justifica un hallazgo de la evaluación

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

Quita la justificación de un hallazgo

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

Guarda los comparables de mercado

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

Guarda las georreferencias TVO (histórico Tasvalúo)

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

Emite el certificado XML firmado del avalúo

POST/v1/avaluos/verifyavaluos:verify

Verifica un avalúo contra su certificado

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

Sube un PDF corregido (nueva versión)

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

Flujo SSE del estado del avalúo (tiempo real)

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

Job de procesamiento más reciente

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

Progreso de los jobs de etapa

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

Historial de versiones del documento

Crear y actualizar

Crear desde un PDF en base64

POST/v1/avaluos/procesaravaluos:write

Crea un avalúo subiendo el PDF en base64

Crea un avalúo enviando el PDF en base64. La API extrae del documento el folio, la institución (campo 1.16) y el tipo de inmueble (campo 1.10); no se envían. Responde en cuanto el avalúo existe y el procesamiento queda encolado; sigue el avance con GET /v1/avaluos/{folio} o por SSE (document.estado).

Si no se detecta la institución, o su clave no está en el catálogo, se usa BBVA. El tipo de inmueble, en cambio, es obligatorio.

Cuerpo application/json

Campo	Tipo	Descripción
`document`requerido	object	—
`document.type`requerido	binary_file	—
`document.base64`requerido	string	PDF en base64 estándar, en una sola línea y sin prefijo `data:`.
`document.filename`	string	Nombre original del archivo.
`metadata`	object	Datos del avalúo que se guardan tal cual. `perito_id` (texto) identifica al perito en la bandeja de control y en las métricas.

Petición

curl -X POST "$API_URL/v1/avaluos/procesar" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "document": {
    "type": "binary_file",
    "base64": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c+Pg==",
    "filename": "avaluo.pdf"
  },
  "metadata": {
    "perito_id": "usr_7"
  }
}'

Respuesta

201 — Avalúo creado; procesamiento encolado.

{
  "folio": "AVL-2026-000123",
  "avaluo_id": "8f14e45f-ceea-467a-9575-6e6b7c1a2f01",
  "estado": "processing",
  "institution": "BBVA",
  "property_type": "CASA_HABITACION"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). Si `document.base64` no es base64 estándar en una sola línea: `document.base64 must be base64 encoded`. Si decodifica a vacío: `El documento (base64) está vacío o es inválido`. Si los bytes no son un PDF: `PDF_INVALIDO` (`El documento no es un PDF válido`); si el PDF está cifrado: `PDF_PROTEGIDO`.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`409`	Ya existe un avalúo con el folio detectado en el PDF (`FOLIO_YA_EXISTE`). Para subir una corrección usa `POST /v1/avaluos/{folio}/documento`.
`413`	El cuerpo supera el tamaño máximo de 50 MB: `El cuerpo de la petición supera el tamaño máximo permitido`.
`422`	No se pudo clasificar el documento: no se halló el folio (`FOLIO_NO_DETECTADO`), falta la clave del tipo de inmueble del campo 1.10 (`TIPO_INMUEBLE_NO_DETECTADO`) o esa clave no está en el catálogo (`TIPO_INMUEBLE_NO_VALIDO`).
`429`	Se superó el límite de peticiones (rate limit).

Crear desde un archivo subido

POST/v1/avaluosavaluos:write

Crea un avalúo por referencia y dispara su procesamiento

Crea un avalúo a partir de la URL del PDF (document_url) o del file_id devuelto por POST /v1/files o POST /v1/files/presign, y dispara el procesamiento sin esperarlo.

El folio debe ser nuevo: si ya existe responde 409 FOLIO_YA_EXISTE y no modifica el avalúo existente. Para subir una corrección usa POST /v1/avaluos/{folio}/documento.

institution y property_type se comparan sin distinguir mayúsculas contra GET /v1/instituciones y GET /v1/tipos-inmueble.

Cuerpo application/json

Campo	Tipo	Descripción
`folio`requerido	string	Identificador único global. Si ya existe, se registra una versión nueva del documento.
`institution`requerido	string	Código de `GET /v1/instituciones`.
`property_type`requerido	string	Código de `GET /v1/tipos-inmueble`.
`document`requerido	object	—
`document.type`requerido	document_url \| binary_file	—
`document.document_url`	uri	URL del PDF. Requerido si `type` es `document_url`.
`document.file_id`	string	Requerido si `type` es `binary_file`: el `file_id` de `POST /v1/files` o `POST /v1/files/presign`.
`canal`	frontend \| whatsapp \| api \| ideas	Canal de origen del avalúo. (por defecto `"api"`)
`payload`	object	Reservado. Actualmente no se guarda.

Petición

curl -X POST "$API_URL/v1/avaluos" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "folio": "AVL-2026-000123",
  "institution": "BBVA",
  "property_type": "CASA_HABITACION",
  "document": {
    "type": "binary_file",
    "file_id": "uploads/3f6c2a4e-8b1d-4c7a-9e2f-5d8b7a1c0e94.pdf"
  },
  "canal": "api"
}'

Respuesta

202 — Avalúo creado; procesamiento disparado.

{
  "id": "8f14e45f-ceea-467a-9575-6e6b7c1a2f01",
  "folio": "AVL-2026-000123",
  "status": "processing",
  "created_at": "2026-09-10T15:00:00.000Z"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). `document.document_url` debe ser una URL cuando `type` es `document_url`; `document.file_id` es obligatorio cuando `type` es `binary_file`.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`409`	Ya existe un avalúo con ese folio (`FOLIO_YA_EXISTE`). Para subir una corrección usa `POST /v1/avaluos/{folio}/documento`.
`422`	El código no está en el catálogo activo: `institution 'X' no existe en el catálogo` o `property_type 'X' no existe en el catálogo`.
`429`	Se superó el límite de peticiones (rate limit).

Subir una versión corregida

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

Sube un PDF corregido (nueva versión)

Sube un PDF corregido (base64) como versión N+1 del documento y vuelve a procesarlo. El folio del PDF debe coincidir con el de la ruta y su contenido debe ser distinto al de las versiones ya subidas.

Al crear la versión nueva se revoca el certificado vigente y se cierra el dictamen vigente del controlador. Las justificaciones de hallazgos se conservan y se heredan en la siguiente evaluación. La institución y el tipo de inmueble se vuelven a leer del PDF.

Sólo la API Key que creó el avalúo puede subir una versión nueva.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Cuerpo application/json

Campo	Tipo	Descripción
`document`requerido	object	—
`document.type`requerido	binary_file	—
`document.base64`requerido	string	PDF en base64 estándar, en una sola línea y sin prefijo `data:`.
`document.filename`	string	Nombre original del archivo.

Petición

curl -X POST "$API_URL/v1/avaluos/AVL-2026-000123/documento" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "document": {
    "type": "binary_file",
    "base64": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c+Pg==",
    "filename": "avaluo-v2.pdf"
  }
}'

Respuesta

202 — Nueva versión creada; procesamiento disparado.

{
  "folio": "AVL-2026-000123",
  "status": "processing",
  "document_version": 2
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). Si `document.base64` no es base64 estándar en una sola línea: `document.base64 must be base64 encoded`. Si decodifica a vacío: `El documento (base64) está vacío o es inválido`. Si los bytes no son un PDF: `PDF_INVALIDO` (`El documento no es un PDF válido`); si el PDF está cifrado: `PDF_PROTEGIDO`.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	Faltan permisos (`Faltan scopes: avaluos:write`) o la API Key no es la que creó el avalúo: `Solo la API Key que creó el avalúo puede subir una versión nueva.`
`404`	El folio no existe: `Avalúo '<folio>' no encontrado`.
`409`	El PDF tiene el mismo contenido que una versión ya subida de este avalúo (`DOCUMENTO_DUPLICADO`). Sube un documento distinto.
`413`	El cuerpo supera el tamaño máximo de 50 MB: `El cuerpo de la petición supera el tamaño máximo permitido`.
`422`	No se halló el folio en el PDF (`FOLIO_NO_DETECTADO`), el PDF es de otro folio (`FOLIO_NO_COINCIDE`), falta la clave del tipo de inmueble del campo 1.10 (`TIPO_INMUEBLE_NO_DETECTADO`) o esa clave no está en el catálogo (`TIPO_INMUEBLE_NO_VALIDO`).
`429`	Se superó el límite de peticiones (rate limit).

Lanzar la evaluación

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

Inicia la evaluación de 5 etapas

Inicia manualmente la evaluación del documento vigente. Sin cuerpo. Úsalo cuando document.puede_evaluar es true.

Si el documento vigente ya tiene una evaluación en curso o completada, no crea otra y devuelve el avalúo tal cual: para volver a evaluar hay que subir una versión nueva del documento.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Petición

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

Respuesta

202 — Evaluación iniciada (o ya existente); devuelve el avalúo completo.

{
  "folio": "AVL-2026-000123",
  "status": "approved",
  "canal": "api",
  "created_at": "2026-09-10T15:00:00.000Z",
  "updated_at": "2026-09-10T15:06:12.000Z",
  "puede_certificar": false,
  "hallazgos_pendientes": 1,
  "dictamen_control": null,
  "certificado": null,
  "document": {
    "version": 1,
    "estado": "completed",
    "nombre_archivo": "avaluo.pdf",
    "paginas": 12,
    "tamano_bytes": 482133,
    "created_at": "2026-09-10T15:00:01.000Z",
    "errores": [],
    "puede_evaluar": false
  },
  "latest_evaluation": {
    "id": "c9a1e2b3-4d5f-4a6b-8c7d-9e0f1a2b3c4d",
    "estado": "completed",
    "result": "aprobado_con_observaciones",
    "stages": [
      {
        "name": "documental",
        "status": "completed"
      },
      {
        "name": "datos",
        "status": "completed"
      },
      {
        "name": "calculos",
        "status": "completed"
      },
      {
        "name": "mercado",
        "status": "completed"
      },
      {
        "name": "reglas",
        "status": "completed"
      }
    ],
    "errors": [
      {
        "titulo": "Valor del avalúo >20% por DEBAJO del mercado web",
        "codigo_regla": "MER-005",
        "severidad": "tecnico",
        "descripcion": "El valor unitario del avalúo queda por debajo del promedio de los comparables.",
        "seccion_avaluo": "Enfoque Mercado",
        "valor_encontrado": "Unitario avalúo $26,113/m²",
        "valor_esperado": "Dentro de ±20% del promedio de mercado",
        "sugerencia": "Revisa los comparables o justifica la diferencia.",
        "id": "b1e7c0de-5a4f-4c3b-9d2e-1f0a9b8c7d6e",
        "estado": "pending",
        "justificacion": null,
        "justificado_at": null,
        "justificacion_heredada": false,
        "justificacion_origen": null,
        "sujeto_url": null
      },
      {
        "titulo": "Superficie construida distinta a la de la escritura",
        "codigo_regla": "DAT-012",
        "severidad": "forma",
        "descripcion": null,
        "seccion_avaluo": "Cuadro de áreas",
        "valor_encontrado": "78 m²",
        "valor_esperado": "80 m²",
        "sugerencia": null,
        "id": "e2d3c4b5-a697-4887-9695-a4b3c2d1e0f9",
        "estado": "dismissed",
        "justificacion": "La superficie proviene de la escritura pública anexa (pág. 4).",
        "justificado_at": "2026-09-10T15:05:40.000Z",
        "justificacion_heredada": false,
        "justificacion_origen": "directa",
        "sujeto_url": null
      }
    ],
    "comparables_web": null,
    "antecedentes": []
  }
}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe (`Avalúo '<folio>' no encontrado`) o aún no tiene documento (`El avalúo '<folio>' no tiene documento que evaluar`).
`409`	El documento vigente aún se está procesando (`DOCUMENTO_NO_LISTO`) o tiene errores (`DOCUMENTO_CON_ERRORES`); corrígelo y súbelo de nuevo antes de evaluar.
`429`	Se superó el límite de peticiones (rate limit).

Consultar

Obtener un avalúo

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

Estado completo del avalúo

Objeto canónico del avalúo: estado, documento (última versión), última evaluación (etapas y hallazgos), certificado y dictamen vigente del controlador. Es el mismo objeto que emite el stream SSE.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Petición

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

Respuesta

200 — Estado completo del avalúo.

{
  "folio": "AVL-2026-000123",
  "status": "approved",
  "canal": "api",
  "created_at": "2026-09-10T15:00:00.000Z",
  "updated_at": "2026-09-10T15:06:12.000Z",
  "puede_certificar": false,
  "hallazgos_pendientes": 1,
  "dictamen_control": null,
  "certificado": null,
  "document": {
    "version": 1,
    "estado": "completed",
    "nombre_archivo": "avaluo.pdf",
    "paginas": 12,
    "tamano_bytes": 482133,
    "created_at": "2026-09-10T15:00:01.000Z",
    "errores": [],
    "puede_evaluar": false
  },
  "latest_evaluation": {
    "id": "c9a1e2b3-4d5f-4a6b-8c7d-9e0f1a2b3c4d",
    "estado": "completed",
    "result": "aprobado_con_observaciones",
    "stages": [
      {
        "name": "documental",
        "status": "completed"
      },
      {
        "name": "datos",
        "status": "completed"
      },
      {
        "name": "calculos",
        "status": "completed"
      },
      {
        "name": "mercado",
        "status": "completed"
      },
      {
        "name": "reglas",
        "status": "completed"
      }
    ],
    "errors": [
      {
        "titulo": "Valor del avalúo >20% por DEBAJO del mercado web",
        "codigo_regla": "MER-005",
        "severidad": "tecnico",
        "descripcion": "El valor unitario del avalúo queda por debajo del promedio de los comparables.",
        "seccion_avaluo": "Enfoque Mercado",
        "valor_encontrado": "Unitario avalúo $26,113/m²",
        "valor_esperado": "Dentro de ±20% del promedio de mercado",
        "sugerencia": "Revisa los comparables o justifica la diferencia.",
        "id": "b1e7c0de-5a4f-4c3b-9d2e-1f0a9b8c7d6e",
        "estado": "pending",
        "justificacion": null,
        "justificado_at": null,
        "justificacion_heredada": false,
        "justificacion_origen": null,
        "sujeto_url": null
      },
      {
        "titulo": "Superficie construida distinta a la de la escritura",
        "codigo_regla": "DAT-012",
        "severidad": "forma",
        "descripcion": null,
        "seccion_avaluo": "Cuadro de áreas",
        "valor_encontrado": "78 m²",
        "valor_esperado": "80 m²",
        "sugerencia": null,
        "id": "e2d3c4b5-a697-4887-9695-a4b3c2d1e0f9",
        "estado": "dismissed",
        "justificacion": "La superficie proviene de la escritura pública anexa (pág. 4).",
        "justificado_at": "2026-09-10T15:05:40.000Z",
        "justificacion_heredada": false,
        "justificacion_origen": "directa",
        "sujeto_url": null
      }
    ],
    "comparables_web": null,
    "antecedentes": []
  }
}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe: `Avalúo '<folio>' no encontrado`.
`429`	Se superó el límite de peticiones (rate limit).

Estados de varios avalúos

POST/v1/avaluos/estadosavaluos:read

Estados ligeros de varios folios

Devuelve el estado de muchos folios en una sola llamada (para listas). Cada ítem trae además la última versión del documento y la última evaluación con sus fechas de inicio y fin, para saber si hay un proceso en curso y cuándo terminó el último.

Los folios que no existen se omiten de la respuesta, sin error.
El orden de estados no está garantizado: relaciona cada ítem por folio.

Cuerpo application/json

Campo	Tipo	Descripción
`folios`requerido	string[]	Folios a consultar (al menos uno).

Petición

curl -X POST "$API_URL/v1/avaluos/estados" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "folios": [
    "AVL-2026-000123",
    "AVL-2026-000124"
  ]
}'

Respuesta

200 — Estados de los folios encontrados.

{
  "estados": [
    {
      "folio": "AVL-2026-000123",
      "status": "approved",
      "document": {
        "version": 2,
        "estado": "completed",
        "created_at": "2026-09-10T14:00:00.000Z",
        "procesado_at": "2026-09-10T14:01:12.000Z"
      },
      "latest_evaluation": {
        "id": "c9a1e2b3-4d5f-4a6b-8c7d-9e0f1a2b3c4d",
        "estado": "completed",
        "result": "aprobado",
        "created_at": "2026-09-10T14:02:00.000Z",
        "started_at": "2026-09-10T14:02:01.000Z",
        "completed_at": "2026-09-10T14:05:40.000Z"
      }
    },
    {
      "folio": "AVL-2026-000124",
      "status": "processing",
      "document": {
        "version": 1,
        "estado": "processing",
        "created_at": "2026-09-11T09:00:00.000Z",
        "procesado_at": null
      },
      "latest_evaluation": null
    }
  ]
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). `folios` debe ser un arreglo de textos no vacío.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`429`	Se superó el límite de peticiones (rate limit).

Versiones del documento

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

Historial de versiones del documento

Todas las versiones del documento (metadatos + URL prefirmada para verlo), de la más reciente a la más antigua.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Petición

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

Respuesta

200 — Versiones del documento.

{
  "folio": "AVL-2026-000123",
  "documentos": [
    {
      "version": 2,
      "nombre_archivo": "avaluo-v2.pdf",
      "paginas": 12,
      "tamano_bytes": 491200,
      "estado": "completed",
      "created_at": "2026-09-11T19:00:00.000Z",
      "url": "https://storage.example.com/avaluos/AVL-2026-000123/v2.pdf?X-Amz-Signature=…"
    },
    {
      "version": 1,
      "nombre_archivo": "avaluo.pdf",
      "paginas": 12,
      "tamano_bytes": 482133,
      "estado": "completed",
      "created_at": "2026-09-10T15:00:01.000Z",
      "url": "https://storage.example.com/avaluos/AVL-2026-000123/v1.pdf?X-Amz-Signature=…"
    }
  ]
}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe: `Avalúo '<folio>' no encontrado`.
`429`	Se superó el límite de peticiones (rate limit).

Seguimiento

Stream en tiempo real

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

Flujo SSE del estado del avalúo (tiempo real)

Server-Sent Events con el mismo objeto que GET /v1/avaluos/{folio}. Envía un snapshot al conectar, en cada cambio del procesamiento y en un sondeo cada 30 s; no reenvía snapshots idénticos al anterior.

Formato:

Snapshot: data: <json> (evento por defecto message).
Keepalive cada 20 s: event: ping con data: keepalive.

La autenticación va en la cabecera x-api-key, que el EventSource nativo del navegador no puede enviar: consúmelo desde tu servidor o a través de un proxy.

Si el folio no existe responde 404 como JSON, sin abrir el stream.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Petición

curl

curl -N "$API_URL/v1/avaluos/AVL-2026-000123/stream" \
  -H "x-api-key: $API_KEY" \
  -H "Accept: text/event-stream"

Respuesta

200 — Stream de eventos text/event-stream.

text/event-stream

data: {"folio":"AVL-2026-000123","status":"processing","canal":"api",…}

event: ping
data: keepalive

data: {"folio":"AVL-2026-000123","status":"approved","canal":"api",…}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe: `Avalúo '<folio>' no encontrado`. Se responde antes de abrir el stream.
`429`	Se superó el límite de peticiones (rate limit).

Último trabajo

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

Job de procesamiento más reciente

Estado del job más reciente del avalúo, de cualquier tipo (procesamiento del documento o evaluación). Para el progreso de cada etapa usa GET /v1/avaluos/{folio}/jobs. job es null si el avalúo aún no tiene ninguno.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Petición

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

Respuesta

200 — Job más reciente (o null).

{
  "folio": "AVL-2026-000123",
  "job": {
    "job_id": "0f9e8d7c-6b5a-4493-8271-605f4e3d2c1b",
    "target": "process",
    "status": "running",
    "progress": 40,
    "stage": "procesamiento",
    "source_url": null,
    "avaluo_id": "8f14e45f-ceea-467a-9575-6e6b7c1a2f01",
    "documento_id": "2c3d4e5f-6a7b-4c8d-9e0f-1a2b3c4d5e6f",
    "pdf_hash": null,
    "response_status": null,
    "error": null,
    "latency_ms": null,
    "created_at": "2026-09-10T15:00:02.000Z",
    "updated_at": "2026-09-10T15:00:14.000Z",
    "completed_at": null
  }
}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe: `Avalúo '<folio>' no encontrado`.
`429`	Se superó el límite de peticiones (rate limit).

Trabajos por etapa

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

Progreso de los jobs de etapa

Progreso de cada etapa de la última evaluación, con el job más reciente de cada una.

A diferencia de GET /v1/avaluos/{folio}, aquí estado y resultado usan los valores en español. Si el avalúo aún no tiene evaluación responde evaluacion_id: null, estado: null, resultado: null y etapas: [].

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Petición

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

Respuesta

200 — Progreso por etapa.

{
  "folio": "AVL-2026-000123",
  "evaluacion_id": "c9a1e2b3-4d5f-4a6b-8c7d-9e0f1a2b3c4d",
  "estado": "en_progreso",
  "resultado": null,
  "etapas": [
    {
      "tipo": "documental",
      "orden": 1,
      "estado": "completed",
      "job": {
        "job_id": "4b3a2f1e-0d9c-4b8a-9766-5e4d3c2b1a09",
        "status": "completed",
        "progress": 100,
        "error": null,
        "started_at": "2026-09-10T15:02:01.000Z",
        "completed_at": "2026-09-10T15:03:10.000Z"
      }
    },
    {
      "tipo": "datos",
      "orden": 2,
      "estado": "processing",
      "job": {
        "job_id": "5c4b3a2f-1e0d-4c9b-8a77-6f5e4d3c2b1a",
        "status": "running",
        "progress": 35,
        "error": null,
        "started_at": "2026-09-10T15:03:11.000Z",
        "completed_at": null
      }
    },
    {
      "tipo": "calculos",
      "orden": 3,
      "estado": "pending",
      "job": null
    }
  ]
}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe: `Avalúo '<folio>' no encontrado`.
`429`	Se superó el límite de peticiones (rate limit).

Hallazgos

Justificar un hallazgo

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

Justifica un hallazgo de la evaluación

Registra la justificación de un hallazgo. El hallazgo pasa a dismissed y guarda el texto y la fecha.

La justificación se recuerda por código de regla + sección + sujeto:

se aplica también a los demás hallazgos iguales de la misma evaluación (justificacion_origen: propagada);
y a las evaluaciones siguientes del mismo avalúo (justificacion_origen: heredada, justificacion_heredada: true).

Volver a enviar el POST sobre un hallazgo heredado lo convierte en justificación directa y actualiza el texto.

El status del avalúo no cambia, pero latest_evaluation.result se recalcula.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.
`errorId`requerido	uuid	En la ruta. UUID del hallazgo (`latest_evaluation.errors[].id`).

Cuerpo application/json

Campo	Tipo	Descripción
`justificacion`requerido	string	Por qué el hallazgo es aceptable o un falso positivo. (mín. 3 caracteres, máx. 2000 caracteres)

Petición

curl -X POST "$API_URL/v1/avaluos/AVL-2026-000123/errores/b1e7c0de-5a4f-4c3b-9d2e-1f0a9b8c7d6e/justificar" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "justificacion": "El valor de superficie proviene de la escritura pública anexa (pág. 4), es correcto."
}'

Respuesta

200 — Justificación guardada; devuelve el avalúo completo.

{
  "folio": "AVL-2026-000123",
  "status": "approved",
  "canal": "api",
  "created_at": "2026-09-10T15:00:00.000Z",
  "updated_at": "2026-09-10T15:06:12.000Z",
  "puede_certificar": false,
  "hallazgos_pendientes": 1,
  "dictamen_control": null,
  "certificado": null,
  "document": {
    "version": 1,
    "estado": "completed",
    "nombre_archivo": "avaluo.pdf",
    "paginas": 12,
    "tamano_bytes": 482133,
    "created_at": "2026-09-10T15:00:01.000Z",
    "errores": [],
    "puede_evaluar": false
  },
  "latest_evaluation": {
    "id": "c9a1e2b3-4d5f-4a6b-8c7d-9e0f1a2b3c4d",
    "estado": "completed",
    "result": "aprobado_con_observaciones",
    "stages": [
      {
        "name": "documental",
        "status": "completed"
      },
      {
        "name": "datos",
        "status": "completed"
      },
      {
        "name": "calculos",
        "status": "completed"
      },
      {
        "name": "mercado",
        "status": "completed"
      },
      {
        "name": "reglas",
        "status": "completed"
      }
    ],
    "errors": [
      {
        "titulo": "Valor del avalúo >20% por DEBAJO del mercado web",
        "codigo_regla": "MER-005",
        "severidad": "tecnico",
        "descripcion": "El valor unitario del avalúo queda por debajo del promedio de los comparables.",
        "seccion_avaluo": "Enfoque Mercado",
        "valor_encontrado": "Unitario avalúo $26,113/m²",
        "valor_esperado": "Dentro de ±20% del promedio de mercado",
        "sugerencia": "Revisa los comparables o justifica la diferencia.",
        "id": "b1e7c0de-5a4f-4c3b-9d2e-1f0a9b8c7d6e",
        "estado": "pending",
        "justificacion": null,
        "justificado_at": null,
        "justificacion_heredada": false,
        "justificacion_origen": null,
        "sujeto_url": null
      },
      {
        "titulo": "Superficie construida distinta a la de la escritura",
        "codigo_regla": "DAT-012",
        "severidad": "forma",
        "descripcion": null,
        "seccion_avaluo": "Cuadro de áreas",
        "valor_encontrado": "78 m²",
        "valor_esperado": "80 m²",
        "sugerencia": null,
        "id": "e2d3c4b5-a697-4887-9695-a4b3c2d1e0f9",
        "estado": "dismissed",
        "justificacion": "La superficie proviene de la escritura pública anexa (pág. 4).",
        "justificado_at": "2026-09-10T15:05:40.000Z",
        "justificacion_heredada": false,
        "justificacion_origen": "directa",
        "sujeto_url": null
      }
    ],
    "comparables_web": null,
    "antecedentes": []
  }
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). `justificacion` debe tener entre 3 y 2000 caracteres. También si `errorId` no es un UUID (`Validation failed (uuid is expected)`).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe (`Avalúo '<folio>' no encontrado`) o el hallazgo no pertenece a ese avalúo (`Error '<errorId>' no encontrado en el avalúo '<folio>'`).
`429`	Se superó el límite de peticiones (rate limit).

Quitar una justificación

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

Quita la justificación de un hallazgo

Revierte la justificación: el hallazgo vuelve a pending (sin texto ni fecha) y la justificación deja de heredarse en las evaluaciones siguientes. Justificar de nuevo el mismo hallazgo la reactiva.

El status del avalúo no cambia, pero latest_evaluation.result se recalcula.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.
`errorId`requerido	uuid	En la ruta. UUID del hallazgo (`latest_evaluation.errors[].id`).

Petición

curl -X DELETE "$API_URL/v1/avaluos/AVL-2026-000123/errores/b1e7c0de-5a4f-4c3b-9d2e-1f0a9b8c7d6e/justificar" \
  -H "x-api-key: $API_KEY"

Respuesta

200 — Justificación retirada; devuelve el avalúo completo.

{
  "folio": "AVL-2026-000123",
  "status": "approved",
  "canal": "api",
  "created_at": "2026-09-10T15:00:00.000Z",
  "updated_at": "2026-09-10T15:06:12.000Z",
  "puede_certificar": false,
  "hallazgos_pendientes": 1,
  "dictamen_control": null,
  "certificado": null,
  "document": {
    "version": 1,
    "estado": "completed",
    "nombre_archivo": "avaluo.pdf",
    "paginas": 12,
    "tamano_bytes": 482133,
    "created_at": "2026-09-10T15:00:01.000Z",
    "errores": [],
    "puede_evaluar": false
  },
  "latest_evaluation": {
    "id": "c9a1e2b3-4d5f-4a6b-8c7d-9e0f1a2b3c4d",
    "estado": "completed",
    "result": "aprobado_con_observaciones",
    "stages": [
      {
        "name": "documental",
        "status": "completed"
      },
      {
        "name": "datos",
        "status": "completed"
      },
      {
        "name": "calculos",
        "status": "completed"
      },
      {
        "name": "mercado",
        "status": "completed"
      },
      {
        "name": "reglas",
        "status": "completed"
      }
    ],
    "errors": [
      {
        "titulo": "Valor del avalúo >20% por DEBAJO del mercado web",
        "codigo_regla": "MER-005",
        "severidad": "tecnico",
        "descripcion": "El valor unitario del avalúo queda por debajo del promedio de los comparables.",
        "seccion_avaluo": "Enfoque Mercado",
        "valor_encontrado": "Unitario avalúo $26,113/m²",
        "valor_esperado": "Dentro de ±20% del promedio de mercado",
        "sugerencia": "Revisa los comparables o justifica la diferencia.",
        "id": "b1e7c0de-5a4f-4c3b-9d2e-1f0a9b8c7d6e",
        "estado": "pending",
        "justificacion": null,
        "justificado_at": null,
        "justificacion_heredada": false,
        "justificacion_origen": null,
        "sujeto_url": null
      },
      {
        "titulo": "Superficie construida distinta a la de la escritura",
        "codigo_regla": "DAT-012",
        "severidad": "forma",
        "descripcion": null,
        "seccion_avaluo": "Cuadro de áreas",
        "valor_encontrado": "78 m²",
        "valor_esperado": "80 m²",
        "sugerencia": null,
        "id": "e2d3c4b5-a697-4887-9695-a4b3c2d1e0f9",
        "estado": "dismissed",
        "justificacion": "La superficie proviene de la escritura pública anexa (pág. 4).",
        "justificado_at": "2026-09-10T15:05:40.000Z",
        "justificacion_heredada": false,
        "justificacion_origen": "directa",
        "sujeto_url": null
      }
    ],
    "comparables_web": null,
    "antecedentes": []
  }
}

Errores

HTTP	Cuándo ocurre
`400`	`errorId` no es un UUID (`Validation failed (uuid is expected)`).
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe (`Avalúo '<folio>' no encontrado`) o el hallazgo no pertenece a ese avalúo (`Error '<errorId>' no encontrado en el avalúo '<folio>'`).
`429`	Se superó el límite de peticiones (rate limit).

Certificado

Emitir el certificado

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

Emite el certificado XML firmado del avalúo

Emite el certificado de integridad del avalúo (XML firmado) para su última evaluación y marca el avalúo approved. Sin cuerpo.

Requisitos: documento procesado y sin errores, evaluación completada y todo hallazgo justificado (de cualquier severidad, no sólo los críticos). Los máximos de hallazgos sin justificar que aún permiten certificar son configurables con evaluacion.max_criticos_certificacion y evaluacion.max_pendientes_certificacion (ambos 0 por defecto).

Idempotente: si la última evaluación ya tiene certificado, lo devuelve con una URL de descarga nueva.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Petición

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

Respuesta

200 — Certificado emitido (o el ya existente).

{
  "folio": "AVL-2026-000123",
  "status": "approved",
  "certificado": {
    "estado": "vigente",
    "emitido_at": "2026-09-12T16:45:00.000Z",
    "hash_avaluo": "b70a14ee1e15d7aa94bd810ec06f4cb77a346e8f33aef6bfeae3d7c4442d7a93",
    "sha256_certificado": "ec31682fde561917952ff78a7a8adeffd0febc372dd26871916c46c630381b45",
    "url": "https://storage.example.com/certificados/AVL-2026-000123-20260912-164500.xml?X-Amz-Signature=…"
  }
}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe (`Avalúo '<folio>' no encontrado`) o no tiene documento (`El avalúo '<folio>' no tiene documento que certificar`).
`409`	El avalúo no es elegible; se comprueba en este orden: sin evaluación (`SIN_EVALUACION`), documento aún en proceso (`DOCUMENTO_NO_LISTO`), documento con errores (`DOCUMENTO_CON_ERRORES`), documento sin huella de contenido (`SIN_HASH`), evaluación sin terminar (`EVALUACION_NO_COMPLETADA`), hallazgos críticos sin justificar (`CRITICOS_PENDIENTES`) y hallazgos de cualquier severidad sin justificar (`HALLAZGOS_PENDIENTES`).
`429`	Se superó el límite de peticiones (rate limit).

Verificar un certificado

POST/v1/avaluos/verifyavaluos:verify

Verifica un avalúo contra su certificado

Recibe el PDF del avalúo (base64) y el certificado XML, y responde si son auténticos e íntegros:

Firma: el certificado lo emitió este sistema.
Hash: el texto del PDF es el mismo que se certificó.
Estado: el certificado no ha sido revocado.

Siempre responde 200 con el veredicto. Si el XML no se puede leer, valido es false, motivo es certificado_ilegible y folio y los hashes vienen null. No deja constancia; para eso usa POST /v1/control/verificaciones.

Cuerpo application/json

Campo	Tipo	Descripción
`avaluo_base64`requerido	string	PDF del avalúo en base64 estándar, en una sola línea y sin prefijo `data:`.
`certificado_xml`requerido	string	Contenido del certificado XML, como texto. (mín. 1 caracteres)

Petición

curl -X POST "$API_URL/v1/avaluos/verify" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "avaluo_base64": "JVBERi0xLjcKJeLjz9MKMSAwIG9iago8PC9UeXBlL0NhdGFsb2c+Pg==",
  "certificado_xml": "<?xml version=\"1.0\" encoding=\"UTF-8\"?><certificado>…</certificado>"
}'

Respuesta

200 — Veredicto de la verificación. El ejemplo es un certificado válido; si el PDF se hubiera modificado vendría valido: false, coincide_hash: false, un hash_calculado distinto y motivo: hash_no_coincide.

{
  "valido": true,
  "folio": "AVL-2026-000123",
  "firma_valida": true,
  "coincide_hash": true,
  "certificado_estado": "vigente",
  "hash_esperado": "b70a14ee1e15d7aa94bd810ec06f4cb77a346e8f33aef6bfeae3d7c4442d7a93",
  "hash_calculado": "b70a14ee1e15d7aa94bd810ec06f4cb77a346e8f33aef6bfeae3d7c4442d7a93"
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). Si `avaluo_base64` no es base64 válido o decodifica a vacío (`El avalúo (base64) está vacío o es inválido`), o si `certificado_xml` está vacío. Si los bytes no son un PDF: `PDF_INVALIDO` (`El documento no es un PDF válido`); si el PDF está cifrado: `PDF_PROTEGIDO`.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`413`	El cuerpo supera el tamaño máximo de 50 MB: `El cuerpo de la petición supera el tamaño máximo permitido`.
`429`	Se superó el límite de peticiones (rate limit).

Material de mercado

Cargan los comparables y antecedentes que se muestran en la etapa mercado. Reenviarlos reemplaza lo anterior.

Cargar comparables de mercado

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

Guarda los comparables de mercado

Registra los anuncios de portales web (mercadolibre, inmuebles24, …) hallados para la etapa mercado de la última evaluación del folio. Las métricas del resumen (totales, promedios, desviación) son opcionales: lo que no venga se deriva de comparables.

Reenviarlo reemplaza el resultado anterior de la etapa. El detalle del avalúo lo expone en latest_evaluation.comparables_web.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Cuerpo application/json

Campo	Tipo	Descripción
`municipio`	string	—
`estado_mx`	string	—
`colonia`	string	—
`cp`	string	—
`lat`	number	—
`lng`	number	—
`radio_m`	integer	Radio buscado, en metros. (mín. 0)
`tipo_inmueble`	string	—
`operacion`	string	(por defecto `"venta"`)
`superficie_sujeto`	number	—
`edad_anios_sujeto`	integer	—
`valor_avaluo`	number	—
`unitario_avaluo`	number	Valor unitario ($/m²) del avalúo.
`total_comparables`	integer	—
`total_descartados`	integer	—
`mercado_inactivo`	boolean	—
`unitario_promedio`	number	—
`superficie_promedio`	number	—
`ticket_maximo`	number	—
`desviacion_vs_avaluo`	number	Desviación % del avalúo vs el mercado.
`alerta_desviacion_20`	boolean	—
`portales`	object	Portales consultados y su conteo.
`descartados`	object[]	Anuncios descartados y el motivo.
`raw`	object	Resultado íntegro de la búsqueda, para auditoría.
`comparables`	object[]	—
`comparables[].portal`requerido	string	—
`comparables[].fuente_url`requerido	string	URL del anuncio.
`comparables[].titulo`	string	—
`comparables[].precio`	number	—
`comparables[].moneda`	string	(por defecto `"MXN"`)
`comparables[].tipo_operacion`	string	—
`comparables[].tipo_inmueble`	string	—
`comparables[].superficie_construida`	number	—
`comparables[].superficie_terreno`	number	—
`comparables[].superficie_referencia`	number	Superficie con la que se calcula el $/m². Si falta se usa construida o terreno.
`comparables[].recamaras`	integer	—
`comparables[].banos`	number	—
`comparables[].cp`	string	—
`comparables[].colonia`	string	—
`comparables[].municipio`	string	—
`comparables[].estado_mx`	string	—
`comparables[].lat`	number	—
`comparables[].lng`	number	—
`comparables[].distancia_m`	integer	Distancia al sujeto, en metros. (mín. 0)
`comparables[].tiene_contacto`	boolean	(por defecto `false`)

Petición

curl -X POST "$API_URL/v1/avaluos/AVL-2026-000123/scraping" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "municipio": "Benito Juárez",
  "estado_mx": "Quintana Roo",
  "lat": 21.1213,
  "lng": -86.8484,
  "radio_m": 3000,
  "tipo_inmueble": "departamento",
  "operacion": "venta",
  "superficie_sujeto": 68,
  "valor_avaluo": 2332264,
  "unitario_avaluo": 34298,
  "comparables": [
    {
      "portal": "mercadolibre",
      "fuente_url": "https://articulo.mercadolibre.com.mx/MLM-1234567890",
      "titulo": "Departamento En Venta En Cancún, See Towers",
      "precio": 2909850,
      "moneda": "MXN",
      "tipo_operacion": "Venta",
      "superficie_construida": 60,
      "recamaras": 1,
      "banos": 1,
      "colonia": "Alfredo Bonfil",
      "municipio": "Benito Juárez",
      "distancia_m": 1450,
      "tiene_contacto": true
    }
  ],
  "descartados": [
    {
      "fuente_url": "https://www.inmuebles24.com/propiedades/98765.html",
      "motivo": "sin superficie"
    }
  ]
}'

Respuesta

200 — Comparables guardados (resumen de lo registrado).

{
  "resultado_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "evaluacion_id": "c9a1e2b3-4d5f-4a6b-8c7d-9e0f1a2b3c4d",
  "etapa_id": "f0e1d2c3-b4a5-4968-8776-655443322110",
  "total_comparables": 1,
  "total_descartados": 1,
  "mercado_inactivo": false,
  "alerta_desviacion_20": true
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). `radio_m` y `comparables[].distancia_m` deben ser enteros mayores o iguales a 0.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe (`Avalúo '<folio>' no encontrado`), aún no tiene evaluación (`El avalúo '<folio>' aún no tiene evaluación`) o su evaluación no tiene etapa de mercado (`La evaluación de '<folio>' no tiene etapa de mercado`).
`429`	Se superó el límite de peticiones (rate limit).

Cargar antecedentes

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

Guarda las georreferencias TVO (histórico Tasvalúo)

Registra los inmuebles del histórico Tasvalúo cercanos al sujeto contra la última evaluación del folio (se enlazan a su etapa mercado si existe).

Reenviarlo reemplaza todos los antecedentes de la evaluación; un arreglo vacío los borra. El detalle del avalúo los expone en latest_evaluation.antecedentes.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Cuerpo application/json

Campo	Tipo	Descripción
`antecedentes`requerido	object[]	—
`antecedentes[].folio_tasvaluo`requerido	string	—
`antecedentes[].folio_ut`	string	—
`antecedentes[].fuente`	string	(por defecto `"historico_tvo"`)
`antecedentes[].codigo_regla`	string	(por defecto `"TVO-000"`)
`antecedentes[].calle`	string	—
`antecedentes[].numero_exterior`	string	—
`antecedentes[].colonia`	string	—
`antecedentes[].municipio`	string	—
`antecedentes[].cp`	string	—
`antecedentes[].latitud`	number	(mín. -90, máx. 90)
`antecedentes[].longitud`	number	(mín. -180, máx. 180)
`antecedentes[].distancia_m`requerido	integer	Distancia al sujeto, en metros. (mín. 0, máx. 2147483647)
`antecedentes[].superficie_terreno`	number	(mín. 0, máx. 99999999.99)
`antecedentes[].superficie_construida`	number	(mín. 0, máx. 99999999.99)
`antecedentes[].superficie_vendible`	number	(mín. 0, máx. 99999999.99)
`antecedentes[].valor_avaluo`	number	(mín. 0, máx. 999999999999.99)
`antecedentes[].precio_m2`	integer	Valor unitario ($/m²), entero. (mín. 0, máx. 2147483647)
`antecedentes[].fecha_alta`	date	Fecha de alta en el histórico (ISO 8601, p. ej. `2026-07-12`).
`antecedentes[].valuador`	string	—
`antecedentes[].notas`	string	—
`antecedentes[].estatus_gys`	string	—

Petición

curl -X POST "$API_URL/v1/avaluos/AVL-2026-000123/antecedentes" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "antecedentes": [
    {
      "folio_tasvaluo": "26071017645",
      "folio_ut": "2601103000025298",
      "fuente": "historico_tvo",
      "codigo_regla": "TVO-001",
      "calle": "IGNACIO COMONFORT",
      "numero_exterior": "155",
      "colonia": "INSURGENTES",
      "municipio": "AHOME",
      "distancia_m": 0,
      "superficie_vendible": 127,
      "superficie_construida": 78,
      "valor_avaluo": 953000,
      "precio_m2": 7529,
      "fecha_alta": "2026-07-12"
    }
  ]
}'

Respuesta

200 — Antecedentes guardados.

{
  "evaluacion_id": "c9a1e2b3-4d5f-4a6b-8c7d-9e0f1a2b3c4d",
  "etapa_id": "f0e1d2c3-b4a5-4968-8776-655443322110",
  "total": 1
}

Errores

HTTP	Cuándo ocurre
`400`	Cuerpo o parámetros inválidos. `message` es un arreglo con un texto por problema (campo faltante, tipo incorrecto o campo no permitido). `antecedentes[].distancia_m` es obligatorio y debe ser un entero mayor o igual a 0. También si un número está fuera de su rango (ver cada campo) o `fecha_alta` no es una fecha ISO 8601 válida.
`401`	API Key ausente, inválida, revocada o expirada.
`403`	La API Key es válida pero le faltan permisos: `Faltan scopes: <scope>`.
`404`	El folio no existe (`Avalúo '<folio>' no encontrado`) o aún no tiene evaluación (`El avalúo '<folio>' aún no tiene evaluación`).
`429`	Se superó el límite de peticiones (rate limit).

Eliminar

Vista previa de la eliminación

GET/v1/avaluos/{folio}/previewavaluos:delete

Previsualiza la eliminación (dry-run)

Cuenta cuántos registros borraría DELETE /v1/avaluos/{folio}, sin borrar nada. Sólo la API Key que creó el avalúo puede consultarlo.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Petición

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

Respuesta

200 — Conteo de registros que se eliminarían, por tipo.

{
  "folio": "AVL-2026-000123",
  "avaluo_id": "8f14e45f-ceea-467a-9575-6e6b7c1a2f01",
  "estado": "requires_correction",
  "total": 22,
  "filas": {
    "processing_events": 5,
    "processing_jobs": 5,
    "evaluacion_antecedentes": 0,
    "evaluation_errors": 3,
    "evaluation_stages": 5,
    "certificates": 0,
    "evaluations": 1,
    "document_images": 0,
    "documents": 1,
    "justificaciones_avaluo": 1,
    "appraisals": 1
  }
}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	Falta el scope `avaluos:delete` (`Faltan scopes: avaluos:delete`) o la API Key no es la que creó el avalúo (`Solo la API Key que creó el avalúo puede eliminarlo.`).
`404`	El folio no existe: `Avalúo '<folio>' no encontrado`. Se comprueba antes que la propiedad del avalúo.
`429`	Se superó el límite de peticiones (rate limit).

Eliminar un avalúo

DELETE/v1/avaluos/{folio}avaluos:delete

Elimina el avalúo y todo lo relacionado

Elimina definitivamente el avalúo con sus documentos, evaluaciones, etapas, hallazgos, justificaciones, certificados y jobs de procesamiento. No se puede deshacer; usa GET /v1/avaluos/{folio}/preview antes para ver el alcance.

Sólo la API Key que creó el avalúo puede eliminarlo.

Parámetros

Campo	Tipo	Descripción
`folio`requerido	string	En la ruta. Identificador único global del avalúo.

Petición

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

Respuesta

200 — Avalúo eliminado; conteo de registros borrados por tipo.

{
  "folio": "AVL-2026-000123",
  "avaluo_id": "8f14e45f-ceea-467a-9575-6e6b7c1a2f01",
  "eliminado": true,
  "total": 22,
  "filas": {
    "processing_events": 5,
    "processing_jobs": 5,
    "evaluacion_antecedentes": 0,
    "evaluation_errors": 3,
    "evaluation_stages": 5,
    "certificates": 0,
    "evaluations": 1,
    "document_images": 0,
    "documents": 1,
    "justificaciones_avaluo": 1,
    "appraisals": 1
  }
}

Errores

HTTP	Cuándo ocurre
`401`	API Key ausente, inválida, revocada o expirada.
`403`	Falta el scope `avaluos:delete` (`Faltan scopes: avaluos:delete`) o la API Key no es la que creó el avalúo (`Solo la API Key que creó el avalúo puede eliminarlo.`).
`404`	El folio no existe: `Avalúo '<folio>' no encontrado`. Se comprueba antes que la propiedad del avalúo.
`429`	Se superó el límite de peticiones (rate limit).

Avalúos

On this page