Crear un avalúo

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

Hay dos maneras de crear un avalúo. Elige según lo que sepas del documento:

	PDF en base64	Referencia a un archivo
Endpoint	`POST /v1/avaluos/procesar`	`POST /v1/avaluos`
Llamadas	1	2 (subir archivo + crear)
Folio, institución y tipo	Se leen del PDF	Los envías tú
Tamaño del PDF	Hasta ~37 MB (el base64 ocupa un tercio más)	Hasta 30 MB por `POST /v1/files`; más con URL prefirmada
Respuesta	`201`	`202`

Recomendado: PDF en base64. Es una sola llamada y evita errores al capturar el folio.

Ambas responden en cuanto el avalúo existe; la lectura y la evaluación siguen en segundo plano. Después, sigue el avance.

Opción 1 · PDF en base64

POST/v1/avaluos/procesaravaluos:write

Crea un avalúo subiendo el PDF en base64

curl -X POST "$API_URL/v1/avaluos/procesar" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"document\": {
      \"type\": \"binary_file\",
      \"filename\": \"avaluo.pdf\",
      \"base64\": \"$(base64 -i avaluo.pdf | tr -d '\n')\"
    },
    \"metadata\": { \"perito_id\": \"P-998\" }
  }"

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": "AVL-2026-000123",
  "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.

Qué se lee del PDF

Dato	Campo del PDF (formato SHF)	Si no se encuentra
Folio	Carátula	Falla: `422 FOLIO_NO_DETECTADO`.
Tipo de inmueble	`1.10 Tipo de Inmueble`	Falla: `422 TIPO_INMUEBLE_NO_DETECTADO`, o `422 TIPO_INMUEBLE_NO_VALIDO` si la clave no está activa en el catálogo.
Institución	`1.16 Clave de entidad otorgante`	No falla: se usa `BBVA`.

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.	Usa la opción 2 con URL prefirmada.
`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 legible.	Revisa la carátula del documento.
`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.

Opción 2 · Referencia a un archivo

Primero pones el PDF en el almacenamiento y luego creas el avalúo indicando folio, institución y tipo de inmueble.

Paso 1: sube el archivo

POST/v1/filesavaluos:write

Sube un PDF (multipart)

curl -X POST "$API_URL/v1/files" \
  -H "x-api-key: $API_KEY" \
  -F "file=@avaluo.pdf;type=application/pdf"

201 Created

{
  "file_id": "uploads/4f3c9a2e-1b7d-4c5e-8f6a-2d3b4c5e6f7a.pdf",
  "url": "https://…?X-Amz-Signature=…",
  "tamano_bytes": 482133,
  "nombre_archivo": "avaluo.pdf"
}

HTTP	Causa
`400`	Falta el campo `file`, el archivo no es `application/pdf`, o el campo tiene otro nombre.
`413`	El archivo supera 30 MB.

Paso 2: crea el avalúo

POST/v1/avaluosavaluos:write

Crea un avalúo por referencia y dispara su procesamiento

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",
    "canal": "api",
    "document": {
      "type": "binary_file",
      "file_id": "uploads/4f3c9a2e-1b7d-4c5e-8f6a-2d3b4c5e6f7a.pdf"
    }
  }'

202 Accepted

{
  "id": "5b2f7c1e-3a4d-4f6b-9e21-8c7d6a5b4f3e",
  "folio": "AVL-2026-000123",
  "status": "processing",
  "created_at": "2026-06-24T18:30:00.000Z"
}

Campo	Valor
`folio`	El folio del avalúo. Es único en todo el sistema.
`institution`	El `codigo` de una institución activa, p. ej. `BBVA`.
`property_type`	El `codigo` de un tipo de inmueble activo, p. ej. `CASA_HABITACION`.
`canal`	Origen del avalúo: `api` (por defecto), `frontend`, `whatsapp` o `ideas`.
`document.type`	`binary_file` con `file_id`, o `document_url` con una URL pública del PDF en `document_url`.

HTTP	Causa	Solución
`400`	Falta un campo, `document.type` no es válido o sobra un campo.	Revisa el cuerpo contra la tabla anterior.
`409`	`FOLIO_YA_EXISTE`: ya hay un avalúo con ese folio.	Consúltalo, o sube una versión nueva.
`422`	`institution 'X' no existe en el catálogo` o `property_type 'X' no existe en el catálogo`.	Usa un `codigo` de `GET /v1/instituciones` o `GET /v1/tipos-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)

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\",\"filename\":\"avaluo-v2.pdf\",\"base64\":\"$(base64 -i avaluo-v2.pdf | tr -d '\n')\"}}"

202 Accepted

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

La versión nueva vuelve a leerse y evaluarse. 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 PDF es igual a una versión ya subida a ese avalúo: no hay nada nuevo que evaluar.
`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`	`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/AVL-2026-000123/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.

Crear un avalúo

On this page