Tasvalúo SAI

Avalúos

Crear, consultar, seguir, justificar, certificar y eliminar 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/avaluosObsoletoavaluos:write

Crea un avalúo por referencia (obsoleto)

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}/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). La evaluación no arranca sola: cuando document.puede_evaluar sea true, lánzala con POST /v1/avaluos/{folio}/evaluar.

Los tres datos son obligatorios: sin folio en el formato SHF («Folio:» y 11 dígitos), sin clave de entidad otorgante del catálogo o sin tipo de inmueble del catálogo, el avalúo no se crea (422). Otros formatos de avalúo, como el «Avalúo Inmobiliario» con «Folio UV», no son compatibles.

Cuerpo application/json
CampoTipoDescripción
documentrequeridoobject—
document.typerequeridobinary_file—
document.base64requeridostringPDF en base64 estándar, en una sola línea y sin prefijo data:.
document.filenamestringNombre original del archivo.
metadataobjectDatos 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": "26091000123",
  "avaluo_id": "8f14e45f-ceea-467a-9575-6e6b7c1a2f01",
  "estado": "processing",
  "status": "processing",
  "institution": "BBVA",
  "property_type": "CASA_HABITACION"
}
Errores
HTTPCuándo ocurre
400Cuerpo 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. document es obligatorio: ausente, null, {} o un cuerpo que no es JSON responde 400 (document should not be null or undefined / document must be a non-empty object).
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
409Ya 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.
413El cuerpo supera el tamaño máximo de 50 MB de las rutas que llevan el PDF: El cuerpo de la petición supera el tamaño máximo permitido.
422No se pudo clasificar el documento: no se halló el folio en el formato SHF (FOLIO_NO_DETECTADO), falta la clave de entidad otorgante del campo 1.16 (INSTITUCION_NO_DETECTADA) o no está en el catálogo (INSTITUCION_NO_VALIDA), o falta la clave del tipo de inmueble del campo 1.10 (TIPO_INMUEBLE_NO_DETECTADO) o no está en el catálogo (TIPO_INMUEBLE_NO_VALIDO). Con una clave del catálogo que está inactiva (1 Terreno, 5 Otro, 7 Terreno más vivienda proyectada) el mensaje de TIPO_INMUEBLE_NO_VALIDO dice qué se admite.
429Se 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. La evaluación de la versión nueva no arranca sola: cuando document.puede_evaluar sea true, lánzala con POST /v1/avaluos/{folio}/evaluar.

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; para cualquier otra el folio responde 404 (en la 1.0, 403).

Parámetros
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
Cuerpo application/json
CampoTipoDescripción
documentrequeridoobject—
document.typerequeridobinary_file—
document.base64requeridostringPDF en base64 estándar, en una sola línea y sin prefijo data:.
document.filenamestringNombre original del archivo.
Petición
curl -X POST "$API_URL/v1/avaluos/26091000123/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": "26091000123",
  "status": "processing",
  "document_version": 2
}
Errores
HTTPCuándo ocurre
400Cuerpo 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. document es obligatorio: ausente, null, {} o un cuerpo que no es JSON responde 400 (document should not be null or undefined / document must be a non-empty object).
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
404El folio no existe o lo creó otra API Key (sólo la llave que creó el avalúo puede modificarlo): Avalúo '<folio>' no encontrado.
409El PDF tiene el mismo contenido que una versión ya subida de este avalúo (DOCUMENTO_DUPLICADO). Sube un documento distinto.
413El cuerpo supera el tamaño máximo de 50 MB de las rutas que llevan el PDF: El cuerpo de la petición supera el tamaño máximo permitido.
422No se halló el folio en el PDF (FOLIO_NO_DETECTADO), el PDF es de otro folio (FOLIO_NO_COINCIDE), falta la clave de entidad otorgante del campo 1.16 (INSTITUCION_NO_DETECTADA) o no está en el catálogo (INSTITUCION_NO_VALIDA), o falta la clave del tipo de inmueble del campo 1.10 (TIPO_INMUEBLE_NO_DETECTADO) o no está en el catálogo o está inactiva (TIPO_INMUEBLE_NO_VALIDO).
429Se 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
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
Petición
curl -X POST "$API_URL/v1/avaluos/26091000123/evaluar" \
  -H "x-api-key: $API_KEY"
Respuesta

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

{
  "folio": "26091000123",
  "status": "approved",
  "canal": "api",
  "created_at": "2026-09-10T15:00:00.000Z",
  "updated_at": "2026-09-10T15:06:12.000Z",
  "puede_certificar": false,
  "certificacion_bloqueo": "HALLAZGOS_PENDIENTES",
  "hallazgos_pendientes": 1,
  "dictamen_control": null,
  "ultimo_dictamen_cerrado": 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",
    "documento_version": 1,
    "estado": "completed",
    "result": "aprobado_con_observaciones",
    "error": null,
    "stages": [
      {
        "name": "documental",
        "status": "completed",
        "error": null
      },
      {
        "name": "datos",
        "status": "completed",
        "error": null
      },
      {
        "name": "calculos",
        "status": "completed",
        "error": null
      },
      {
        "name": "mercado",
        "status": "completed",
        "error": null
      },
      {
        "name": "reglas",
        "status": "completed",
        "error": null
      }
    ],
    "errors": [
      {
        "titulo": "Valor del avalúo 79.5% por ENCIMA del mercado web",
        "codigo_regla": "MER-005",
        "severidad": "tecnico",
        "descripcion": "El unitario del avalúo se desvía 79.5% respecto al promedio de comparables de mercado web (umbral TVO ±20%).",
        "seccion_avaluo": "Enfoque Mercado",
        "valor_encontrado": "Unitario avalúo $20,747/m² (79.5% vs mercado)",
        "valor_esperado": "Entre $9,248.81 y $13,873.21/m² (±20% del promedio de mercado $11,561.01/m²)",
        "sugerencia": "Posible sobrevaluación: revisar la homologación, los factores aplicados y los comparables, o justificar el valor.",
        "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
HTTPCuándo ocurre
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
404El folio no existe o lo creó otra API Key (sólo la llave que creó el avalúo puede modificarlo): Avalúo '<folio>' no encontrado. También si aún no tiene documento (El avalúo '<folio>' no tiene documento que evaluar).
409El 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.
429Se 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, dictamen vigente del controlador y el último dictamen cerrado. Es el mismo objeto que emite el stream SSE.

  • puede_certificar + certificacion_bloqueo dicen si se puede llamar a POST /v1/avaluos/{folio}/certificado y, si no, por qué. Salen de la misma regla que aplica esa ruta.
  • Si latest_evaluation.documento_version no es document.version, la versión vigente del documento aún no tiene evaluación: el veredicto y los hallazgos a la vista son de la anterior y no se pueden justificar (409 EVALUACION_SUSTITUIDA).
  • ultimo_dictamen_cerrado conserva el motivo de un rechazo después de subir la versión corregida (que cierra el dictamen vigente).

Lo puede leer la llave que creó el avalúo o una llave con control:read.

Parámetros
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
Petición
curl "$API_URL/v1/avaluos/26091000123" \
  -H "x-api-key: $API_KEY"
Respuesta

200 — Estado completo del avalúo.

{
  "folio": "26091000123",
  "status": "approved",
  "canal": "api",
  "created_at": "2026-09-10T15:00:00.000Z",
  "updated_at": "2026-09-10T15:06:12.000Z",
  "puede_certificar": false,
  "certificacion_bloqueo": "HALLAZGOS_PENDIENTES",
  "hallazgos_pendientes": 1,
  "dictamen_control": null,
  "ultimo_dictamen_cerrado": 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",
    "documento_version": 1,
    "estado": "completed",
    "result": "aprobado_con_observaciones",
    "error": null,
    "stages": [
      {
        "name": "documental",
        "status": "completed",
        "error": null
      },
      {
        "name": "datos",
        "status": "completed",
        "error": null
      },
      {
        "name": "calculos",
        "status": "completed",
        "error": null
      },
      {
        "name": "mercado",
        "status": "completed",
        "error": null
      },
      {
        "name": "reglas",
        "status": "completed",
        "error": null
      }
    ],
    "errors": [
      {
        "titulo": "Valor del avalúo 79.5% por ENCIMA del mercado web",
        "codigo_regla": "MER-005",
        "severidad": "tecnico",
        "descripcion": "El unitario del avalúo se desvía 79.5% respecto al promedio de comparables de mercado web (umbral TVO ±20%).",
        "seccion_avaluo": "Enfoque Mercado",
        "valor_encontrado": "Unitario avalúo $20,747/m² (79.5% vs mercado)",
        "valor_esperado": "Entre $9,248.81 y $13,873.21/m² (±20% del promedio de mercado $11,561.01/m²)",
        "sugerencia": "Posible sobrevaluación: revisar la homologación, los factores aplicados y los comparables, o justificar el valor.",
        "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
HTTPCuándo ocurre
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
404El folio no existe, o lo creó otra API Key y la tuya no tiene control:read: Avalúo '<folio>' no encontrado.
429Se 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.

  • Hasta 200 folios por llamada, cada uno de 11 dígitos; para más, parte la lista en lotes.
  • Los folios que no existen se omiten de la respuesta, sin error. También los que creó otra API Key, salvo que la tuya tenga control:read.
  • El orden de estados no está garantizado: relaciona cada ítem por folio.
Cuerpo application/json
CampoTipoDescripción
foliosrequeridostring[]Folios a consultar: entre 1 y 200, cada uno de 11 dígitos (límite de la v1.1).
Petición
curl -X POST "$API_URL/v1/avaluos/estados" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "folios": [
    "26091000123",
    "26091000124"
  ]
}'
Respuesta

200 — Estados de los folios encontrados.

{
  "estados": [
    {
      "folio": "26091000123",
      "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",
        "error": null,
        "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": "26091000124",
      "status": "processing",
      "document": {
        "version": 1,
        "estado": "processing",
        "created_at": "2026-09-11T09:00:00.000Z",
        "procesado_at": null
      },
      "latest_evaluation": null
    }
  ]
}
Errores
HTTPCuándo ocurre
400Cuerpo 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 no vacío de hasta 200 folios de 11 dígitos (folios must contain no more than 200 elements, cada folio debe tener 11 dígitos).
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
429Se 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
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
Petición
curl "$API_URL/v1/avaluos/26091000123/documentos" \
  -H "x-api-key: $API_KEY"
Respuesta

200 — Versiones del documento.

{
  "folio": "26091000123",
  "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/26091000123/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/26091000123/v1.pdf?X-Amz-Signature=…"
    }
  ]
}
Errores
HTTPCuándo ocurre
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
404El folio no existe, o lo creó otra API Key y la tuya no tiene control:read: Avalúo '<folio>' no encontrado.
429Se 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, o lo creó otra API Key y la tuya no tiene control:read, responde 404 como JSON (application/json) antes de abrir el stream; en la 1.0 podía llegar un 200 con event: error.

Parámetros
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
Petición
curl
curl -N "$API_URL/v1/avaluos/26091000123/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":"26091000123","status":"processing","canal":"api",…}

event: ping
data: keepalive

data: {"folio":"26091000123","status":"approved","canal":"api",…}
Errores
HTTPCuándo ocurre
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
404El folio no existe, o lo creó otra API Key y la tuya no tiene control:read: Avalúo '<folio>' no encontrado. Se responde antes de abrir el stream.
429Se 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.

El job process de una re-subida se cierra (completed o failed) en cuanto el documento termina de procesarse; ya no se queda en running. La URL del PDF (source_url) ya no se expone.

Parámetros
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
Petición
curl "$API_URL/v1/avaluos/26091000123/job" \
  -H "x-api-key: $API_KEY"
Respuesta

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

{
  "folio": "26091000123",
  "job": {
    "job_id": "0f9e8d7c-6b5a-4493-8271-605f4e3d2c1b",
    "target": "process",
    "status": "running",
    "progress": 40,
    "stage": "procesamiento",
    "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
HTTPCuándo ocurre
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
404El folio no existe, o lo creó otra API Key y la tuya no tiene control:read: Avalúo '<folio>' no encontrado.
429Se 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.

estado y resultado usan el mismo vocabulario que latest_evaluation de GET /v1/avaluos/{folio} (en la 1.0 salían los valores internos en español: en_progreso, completada, rechazado…). etapas[].job.status sigue en el vocabulario de los jobs (dispatched, running, completed, failed). Si el avalúo aún no tiene evaluación responde evaluacion_id: null, estado: null, resultado: null y etapas: []. Si la evaluación falló, error y etapas[].error dicen por qué.

Parámetros
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
Petición
curl "$API_URL/v1/avaluos/26091000123/jobs" \
  -H "x-api-key: $API_KEY"
Respuesta

200 — Progreso por etapa.

{
  "folio": "26091000123",
  "evaluacion_id": "c9a1e2b3-4d5f-4a6b-8c7d-9e0f1a2b3c4d",
  "estado": "processing",
  "resultado": null,
  "error": null,
  "etapas": [
    {
      "tipo": "documental",
      "orden": 1,
      "estado": "completed",
      "error": null,
      "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",
      "error": null,
      "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",
      "error": null,
      "job": null
    }
  ]
}
Errores
HTTPCuándo ocurre
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
404El folio no existe, o lo creó otra API Key y la tuya no tiene control:read: Avalúo '<folio>' no encontrado.
429Se 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).

En DAT-001, DAT-007, DAT-015 y DAT-018 sin sujeto explícito, el sujeto es el título del hallazgo normalizado: justificar un motivo no desestima otro de la misma sección. En la URL de un comparable sólo el dominio se compara sin mayúsculas; la ruta las distingue.

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

Sólo se justifican hallazgos de la evaluación vigente: la última del avalúo y hecha sobre la versión vigente del documento (si no, 409 EVALUACION_SUSTITUIDA). Con un dictamen aprobado vigente las justificaciones ya no se editan (409 YA_DICTAMINADO). Con el certificado vigente el texto sí se puede editar mientras no haya dictamen o el vigente sea un rechazo: es como el perito responde a un rechazo.

latest_evaluation.result se recalcula y el status del avalúo también: sin hallazgos pendientes pasa a approved y con alguno a requires_correction. Esto sólo ocurre con la evaluación vigente completada, sin certificado ni dictamen vigentes, y nunca desde processing ni error.

Parámetros
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
errorIdrequeridouuidEn la ruta. UUID del hallazgo (latest_evaluation.errors[].id).
Cuerpo application/json
CampoTipoDescripción
justificacionrequeridostringPor 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/26091000123/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": "26091000123",
  "status": "approved",
  "canal": "api",
  "created_at": "2026-09-10T15:00:00.000Z",
  "updated_at": "2026-09-10T15:06:12.000Z",
  "puede_certificar": false,
  "certificacion_bloqueo": "HALLAZGOS_PENDIENTES",
  "hallazgos_pendientes": 1,
  "dictamen_control": null,
  "ultimo_dictamen_cerrado": 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",
    "documento_version": 1,
    "estado": "completed",
    "result": "aprobado_con_observaciones",
    "error": null,
    "stages": [
      {
        "name": "documental",
        "status": "completed",
        "error": null
      },
      {
        "name": "datos",
        "status": "completed",
        "error": null
      },
      {
        "name": "calculos",
        "status": "completed",
        "error": null
      },
      {
        "name": "mercado",
        "status": "completed",
        "error": null
      },
      {
        "name": "reglas",
        "status": "completed",
        "error": null
      }
    ],
    "errors": [
      {
        "titulo": "Valor del avalúo 79.5% por ENCIMA del mercado web",
        "codigo_regla": "MER-005",
        "severidad": "tecnico",
        "descripcion": "El unitario del avalúo se desvía 79.5% respecto al promedio de comparables de mercado web (umbral TVO ±20%).",
        "seccion_avaluo": "Enfoque Mercado",
        "valor_encontrado": "Unitario avalúo $20,747/m² (79.5% vs mercado)",
        "valor_esperado": "Entre $9,248.81 y $13,873.21/m² (±20% del promedio de mercado $11,561.01/m²)",
        "sugerencia": "Posible sobrevaluación: revisar la homologación, los factores aplicados y los comparables, o justificar el valor.",
        "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
HTTPCuándo ocurre
400Cuerpo 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)).
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
404El folio no existe o lo creó otra API Key (sólo la llave que creó el avalúo puede modificarlo): Avalúo '<folio>' no encontrado. También si el hallazgo no pertenece a ese avalúo (Error '<errorId>' no encontrado en el avalúo '<folio>').
409El hallazgo no es de la evaluación vigente (EVALUACION_SUSTITUIDA: hay una evaluación o una versión del documento más reciente; recarga el avalúo) o el avalúo tiene un dictamen aprobado vigente (YA_DICTAMINADO).
429Se 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; los hallazgos de la misma evaluación que la heredaban vuelven también a pending. Justificar de nuevo el mismo hallazgo la reactiva.

No se puede quitar con el certificado vigente (409 CERTIFICADO_VIGENTE: el certificado cuenta ese hallazgo como justificado; sube una versión corregida), con un dictamen aprobado vigente (409 YA_DICTAMINADO), sobre una evaluación que ya no es la vigente (409 EVALUACION_SUSTITUIDA) ni si otro hallazgo de la evaluación justificado a mano comparte su llave (409 JUSTIFICACION_COMPARTIDA, p. ej. dos comparables con la misma URL): la justificación de ese lo volvería a cubrir. Edita el texto de este hallazgo o quita primero la del otro.

latest_evaluation.result y el status del avalúo se recalculan como al justificar.

Parámetros
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
errorIdrequeridouuidEn la ruta. UUID del hallazgo (latest_evaluation.errors[].id).
Petición
curl -X DELETE "$API_URL/v1/avaluos/26091000123/errores/b1e7c0de-5a4f-4c3b-9d2e-1f0a9b8c7d6e/justificar" \
  -H "x-api-key: $API_KEY"
Respuesta

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

{
  "folio": "26091000123",
  "status": "approved",
  "canal": "api",
  "created_at": "2026-09-10T15:00:00.000Z",
  "updated_at": "2026-09-10T15:06:12.000Z",
  "puede_certificar": false,
  "certificacion_bloqueo": "HALLAZGOS_PENDIENTES",
  "hallazgos_pendientes": 1,
  "dictamen_control": null,
  "ultimo_dictamen_cerrado": 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",
    "documento_version": 1,
    "estado": "completed",
    "result": "aprobado_con_observaciones",
    "error": null,
    "stages": [
      {
        "name": "documental",
        "status": "completed",
        "error": null
      },
      {
        "name": "datos",
        "status": "completed",
        "error": null
      },
      {
        "name": "calculos",
        "status": "completed",
        "error": null
      },
      {
        "name": "mercado",
        "status": "completed",
        "error": null
      },
      {
        "name": "reglas",
        "status": "completed",
        "error": null
      }
    ],
    "errors": [
      {
        "titulo": "Valor del avalúo 79.5% por ENCIMA del mercado web",
        "codigo_regla": "MER-005",
        "severidad": "tecnico",
        "descripcion": "El unitario del avalúo se desvía 79.5% respecto al promedio de comparables de mercado web (umbral TVO ±20%).",
        "seccion_avaluo": "Enfoque Mercado",
        "valor_encontrado": "Unitario avalúo $20,747/m² (79.5% vs mercado)",
        "valor_esperado": "Entre $9,248.81 y $13,873.21/m² (±20% del promedio de mercado $11,561.01/m²)",
        "sugerencia": "Posible sobrevaluación: revisar la homologación, los factores aplicados y los comparables, o justificar el valor.",
        "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
HTTPCuándo ocurre
400errorId no es un UUID (Validation failed (uuid is expected)).
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
404El folio no existe o lo creó otra API Key (sólo la llave que creó el avalúo puede modificarlo): Avalúo '<folio>' no encontrado. También si el hallazgo no pertenece a ese avalúo (Error '<errorId>' no encontrado en el avalúo '<folio>').
409La evaluación tiene certificado vigente (CERTIFICADO_VIGENTE), hay un dictamen aprobado vigente (YA_DICTAMINADO), el hallazgo no es de la evaluación vigente (EVALUACION_SUSTITUIDA) u otro hallazgo justificado a mano comparte su llave (JUSTIFICACION_COMPARTIDA: «La justificación de este hallazgo comparte llave con «<título>»; edita el texto de este hallazgo o quita primero la de ese.»).
429Se 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 la evaluación de la versión vigente del documento y marca el avalúo approved. Sin cuerpo.

Requisitos: la versión vigente del documento evaluada (una evaluación de una versión anterior no sirve), documento procesado, sin errores y con huella de contenido, 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). puede_certificar y certificacion_bloqueo de GET /v1/avaluos/{folio} lo anticipan con la misma regla.

Idempotente: si esa evaluación ya tiene certificado vigente, lo devuelve con una URL de descarga nueva; dos llamadas simultáneas reciben el mismo certificado. Un certificado revocado no se reemite: hay que subir una versión corregida.

status es el estado real del avalúo en ese momento: approved al emitir, pero en la respuesta idempotente puede ser otro (p. ej. requires_correction tras un rechazo del controlador).

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

Parámetros
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
Petición
curl -X POST "$API_URL/v1/avaluos/26091000123/certificado" \
  -H "x-api-key: $API_KEY"
Respuesta

200 — Certificado emitido (o el ya existente).

{
  "folio": "26091000123",
  "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/26091000123-20260912-164500.xml?X-Amz-Signature=…"
  }
}
Errores
HTTPCuándo ocurre
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
404El folio no existe o lo creó otra API Key (sólo la llave que creó el avalúo puede modificarlo): Avalúo '<folio>' no encontrado. También si no tiene documento (El avalúo '<folio>' no tiene documento que certificar).
409El avalúo no es elegible; se comprueba en este orden: la versión vigente del documento no tiene evaluación (DOCUMENTO_SIN_EVALUAR si hubo evaluaciones de versiones anteriores, SIN_EVALUACION si no hubo ninguna), el certificado de esa evaluación fue revocado (CERTIFICADO_REVOCADO), la evaluación no terminó o falló (EVALUACION_NO_COMPLETADA), documento aún en proceso (DOCUMENTO_NO_LISTO), documento con errores (DOCUMENTO_CON_ERRORES), hallazgos críticos sin justificar (CRITICOS_PENDIENTES), hallazgos de cualquier severidad sin justificar (HALLAZGOS_PENDIENTES) y documento sin huella de contenido (SIN_HASH: sube una versión corregida; el mismo PDF se rechaza como duplicado).
429Se 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 está registrado en el sistema y vigente.

valido es true sólo si se cumplen las tres. Un certificado con firma y hash correctos que no está en el sistema (el avalúo se eliminó, o viene de otro entorno) no es válido: certificado_estado: desconocido y motivo: certificado_desconocido.

Siempre responde 200 con el veredicto. Si el XML no se puede leer, o sus identificadores no son de este sistema (no son UUID), 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
CampoTipoDescripción
avaluo_base64requeridostringPDF del avalúo en base64 estándar, en una sola línea y sin prefijo data:.
certificado_xmlrequeridostringContenido 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": "26091000123",
  "firma_valida": true,
  "coincide_hash": true,
  "certificado_estado": "vigente",
  "hash_esperado": "b70a14ee1e15d7aa94bd810ec06f4cb77a346e8f33aef6bfeae3d7c4442d7a93",
  "hash_calculado": "b70a14ee1e15d7aa94bd810ec06f4cb77a346e8f33aef6bfeae3d7c4442d7a93"
}
Errores
HTTPCuándo ocurre
400Cuerpo 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.
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
413El cuerpo supera el tamaño máximo de 50 MB de las rutas que llevan el PDF: El cuerpo de la petición supera el tamaño máximo permitido.
429Se 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
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
Petición
curl "$API_URL/v1/avaluos/26091000123/preview" \
  -H "x-api-key: $API_KEY"
Respuesta

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

{
  "folio": "26091000123",
  "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
HTTPCuándo ocurre
401API Key ausente, inválida, revocada o expirada.
403Falta 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.).
404El folio no existe: Avalúo '<folio>' no encontrado. Se comprueba antes que la propiedad del avalúo.
429Se 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
CampoTipoDescripción
foliorequeridostringEn la ruta. Identificador único global del avalúo.
Petición
curl -X DELETE "$API_URL/v1/avaluos/26091000123" \
  -H "x-api-key: $API_KEY"
Respuesta

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

{
  "folio": "26091000123",
  "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
HTTPCuándo ocurre
401API Key ausente, inválida, revocada o expirada.
403Falta 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.).
404El folio no existe: Avalúo '<folio>' no encontrado. Se comprueba antes que la propiedad del avalúo.
429Se superó el límite de peticiones (rate limit).

Obsoletos

Siguen respondiendo, pero no los uses: el documento no llega a procesarse. Para crear un avalúo, envía el PDF con POST /v1/avaluos/procesar.

Crear desde un archivo subido

POST/v1/avaluosObsoletoavaluos:write

Crea un avalúo por referencia (obsoleto)

Obsoleto. Da de alta desde un PDF en base64 con POST /v1/avaluos/procesar: el API extrae del documento el folio, la institución y el tipo de inmueble. La entrega por URL (document_url) queda para una versión posterior del contrato.

Heredado de la v1, donde el perito capturaba folio, institución y tipo en un formulario: aquí esos datos los declara el cliente y el API no abre el PDF, así que el documento no llega a procesarse. 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
CampoTipoDescripción
foliorequeridostringIdentificador único global. Debe ser nuevo: si ya existe responde 409 FOLIO_YA_EXISTE.
institutionrequeridostringCódigo de GET /v1/instituciones.
property_typerequeridostringCódigo de GET /v1/tipos-inmueble.
documentrequeridoobject—
document.typerequeridodocument_url | binary_file—
document.document_urluriURL del PDF. Requerido si type es document_url.
document.file_idstringRequerido si type es binary_file: el file_id de POST /v1/files o POST /v1/files/presign.
canalfrontend | whatsapp | api | ideasCanal de origen del avalúo. (por defecto "api")
payloadobjectReservado. 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": "26091000123",
  "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": "26091000123",
  "status": "processing",
  "created_at": "2026-09-10T15:00:00.000Z"
}
Errores
HTTPCuándo ocurre
400Cuerpo 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. document es obligatorio: ausente, null, {} o un cuerpo que no es JSON responde 400 (document should not be null or undefined / document must be a non-empty object).
401API Key ausente, inválida, revocada o expirada.
403La API Key es válida pero le faltan permisos: Faltan scopes: <scope>.
409Ya existe un avalúo con ese folio (FOLIO_YA_EXISTE). Para subir una corrección usa POST /v1/avaluos/{folio}/documento.
422El 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.
429Se superó el límite de peticiones (rate limit).

Secciones

Las partes en que se divide un avalúo.

Control

Bandejas, verificación de integridad y dictamen del controlador.

On this page

Crear y actualizarCrear desde un PDF en base64Subir una versión corregidaLanzar la evaluaciónConsultarObtener un avalúoEstados de varios avalúosVersiones del documentoSeguimientoStream en tiempo realÚltimo trabajoTrabajos por etapaHallazgosJustificar un hallazgoQuitar una justificaciónCertificadoEmitir el certificadoVerificar un certificadoEliminarVista previa de la eliminaciónEliminar un avalúoObsoletosCrear desde un archivo subido