Crear un avalúo

Cómo enviar el PDF, qué se lee del documento y cómo re-subir una versión corregida.

Un avalúo se crea enviando su PDF. El documento es la fuente de verdad: el API lee de él el folio, la institución y el tipo de inmueble, y con eso da de alta el avalúo. Esos datos no se envían por separado.

La respuesta llega en cuanto el avalúo existe; la lectura del documento sigue en segundo plano. La evaluación no arranca sola: cuando el documento termine de leerse sin errores (document.puede_evaluar es true), lánzala con POST /v1/avaluos/{folio}/evaluar (ver cómo). Después, sigue el avance.

El alta por referencia a un archivo está obsoleta

POST /v1/files, POST /v1/files/presign y POST /v1/avaluos (folio, institución y tipo enviados por el cliente junto a un file_id o un document_url) siguen respondiendo, pero el documento no llega a procesarse: no los uses. La entrega del PDF por URL llegará en una versión posterior del contrato.

Enviar el PDF en base64

POST/v1/avaluos/procesaravaluos:write

Crea un avalúo subiendo el PDF en base64

# El base64 de un PDF real (varios MB) no cabe en un argumento de curl:
# se arma el cuerpo en un archivo y curl lo lee de ahí.
{
  printf '{"document":{"type":"binary_file","filename":"avaluo.pdf","base64":"'
  base64 < avaluo.pdf | tr -d '\n'
  printf '"},"metadata":{"perito_id":"P-998"}}'
} > body.json

curl -X POST "$API_URL/v1/avaluos/procesar" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @body.json

import { readFile } from 'node:fs/promises';

const pdf = await readFile('avaluo.pdf');
const res = await fetch(`${API_URL}/v1/avaluos/procesar`, {
  method: 'POST',
  headers: { 'x-api-key': API_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    document: { type: 'binary_file', filename: 'avaluo.pdf', base64: pdf.toString('base64') },
    metadata: { perito_id: 'P-998' },
  }),
});
const avaluo = await res.json();

201 Created

{
  "folio": "26091000123",
  "avaluo_id": "5b2f7c1e-3a4d-4f6b-9e21-8c7d6a5b4f3e",
  "estado": "processing",
  "institution": "BBVA",
  "property_type": "CASA_HABITACION"
}

metadata es opcional: un objeto libre para tus propios datos.

Límite	Valor
Tamaño	Cuerpo JSON de hasta 50 MB: un PDF de hasta ~37 MB, porque el base64 ocupa un tercio más.
Formato	Solo PDF y sin contraseña.

Qué se lee del PDF

Los tres datos son obligatorios. Si falta alguno, el avalúo no se crea.

Dato	Campo del PDF (formato SHF)	Si no se encuentra
Folio	Carátula: `Folio:` seguido de 11 dígitos.	`422 FOLIO_NO_DETECTADO`. Otros formatos de avalúo, como el «Avalúo Inmobiliario» con «Folio UV», no son compatibles.
Institución	`1.16 Clave de entidad otorgante`	`422 INSTITUCION_NO_DETECTADA`, o `422 INSTITUCION_NO_VALIDA` si la clave no está activa en el catálogo.
Tipo de inmueble	`1.10 Tipo de Inmueble`	`422 TIPO_INMUEBLE_NO_DETECTADO`, o `422 TIPO_INMUEBLE_NO_VALIDO` si la clave no está activa en el catálogo.

Errores

HTTP	`code`	Causa	Solución
`400`	—	`document.base64 must be base64 encoded`	Envía el base64 en una sola línea y sin prefijo `data:`.
`400`	—	`El documento (base64) está vacío o es inválido`	Revisa que leíste el archivo antes de codificarlo.
`400`	`PDF_INVALIDO`	El base64 no contiene un PDF.	Envía el PDF original, no una imagen ni otro formato.
`400`	`PDF_PROTEGIDO`	El PDF tiene contraseña.	Quita la protección y vuelve a enviarlo.
`413`	—	El cuerpo supera 50 MB.	Reduce el tamaño del PDF, por ejemplo bajando la resolución de las imágenes escaneadas.
`409`	`FOLIO_YA_EXISTE`	Ya existe un avalúo con ese folio.	Consúltalo, o sube una versión nueva.
`422`	`FOLIO_NO_DETECTADO`	El PDF no trae `Folio:` con 11 dígitos.	Revisa la carátula del documento.
`422`	`INSTITUCION_NO_DETECTADA`	No se pudo leer el campo 1.16.	Revisa el campo en el PDF.
`422`	`INSTITUCION_NO_VALIDA`	La clave del 1.16 no está activa en el catálogo.	Ver instituciones.
`422`	`TIPO_INMUEBLE_NO_DETECTADO`	No se pudo leer el campo 1.10.	Revisa el campo en el PDF.
`422`	`TIPO_INMUEBLE_NO_VALIDO`	El tipo leído no se admite hoy.	Ver tipos de inmueble.

Subir una versión corregida

Cuando el PDF tiene errores, hallazgos que hay que corregir o el controlador lo rechazó, sube el documento corregido al mismo folio. Tiene que hacerlo la misma API Key que creó el avalúo:

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

Sube un PDF corregido (nueva versión)

{
  printf '{"document":{"type":"binary_file","filename":"avaluo-v2.pdf","base64":"'
  base64 < avaluo-v2.pdf | tr -d '\n'
  printf '"}}'
} > body.json

curl -X POST "$API_URL/v1/avaluos/26091000123/documento" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  --data-binary @body.json

202 Accepted

{ "folio": "26091000123", "status": "processing", "document_version": 2 }

El folio del PDF tiene que ser el de la ruta, y la institución y el tipo se vuelven a leer del documento con las mismas reglas que al crearlo. La versión nueva vuelve a leerse, pero su evaluación no arranca sola: cuando document.puede_evaluar sea true, lánzala con POST /v1/avaluos/{folio}/evaluar, igual que tras el alta. Mientras tanto, latest_evaluation sigue siendo la de la versión anterior. Qué pasa con lo anterior:

Se pierde	Se conserva
El certificado vigente (queda revocado).	Las justificaciones: se aplican solas a los mismos hallazgos.
El dictamen vigente (queda cerrado).	El historial de versiones del documento.

HTTP	`code`	Causa
`400`	`PDF_INVALIDO` / `PDF_PROTEGIDO`	El base64 no es un PDF, o el PDF tiene contraseña.
`403`	—	La API Key no es la que creó el avalúo.
`404`	—	El folio no existe.
`409`	`DOCUMENTO_DUPLICADO`	El texto del PDF es idéntico al de una versión ya subida a ese avalúo. Se compara el texto extraído, no el archivo: si solo cambian páginas escaneadas sin capa de texto, cuenta como duplicado.
`422`	`FOLIO_NO_COINCIDE`	El folio del PDF no es el de la ruta.
`422`	`FOLIO_NO_DETECTADO`	El PDF no trae folio legible.
`422`	`INSTITUCION_NO_DETECTADA` / `INSTITUCION_NO_VALIDA`	Problema con el campo 1.16.
`422`	`TIPO_INMUEBLE_NO_DETECTADO` / `TIPO_INMUEBLE_NO_VALIDO`	Problema con el campo 1.10.

Consultar las versiones

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

Historial de versiones del documento

curl "$API_URL/v1/avaluos/26091000123/documentos" -H "x-api-key: $API_KEY"

Devuelve cada versión con su nombre, páginas, tamaño, estado y una url temporal para descargar el PDF. Pide la url cuando la vayas a abrir: caduca.