Guía rápida
Tu primer avalúo de punta a punta con curl, en cinco llamadas.
En esta guía subes un PDF de avalúo, sigues su evaluación, justificas un hallazgo y emites
el certificado. Necesitas curl, un PDF de avalúo en formato SHF y una llave de pruebas
con los scopes avaluos:read, avaluos:write y avaluos:justify.
export API_URL=https://tasvaluo-backend-testing.nexustma.dev
export API_KEY=sai_test_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxComprueba que la llave funciona:
curl "$API_URL/v1/instituciones" -H "x-api-key: $API_KEY"Si responde una lista de instituciones, estás listo. Si responde 401 o 403, revisa
autenticación.
Sube el PDF
Envía el PDF en base64. El API lee del documento el folio, la institución y el tipo de inmueble, así que no tienes que mandarlos.
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')\"}}"{
"folio": "AVL-2026-000123",
"avaluo_id": "5b2f7c1e-3a4d-4f6b-9e21-8c7d6a5b4f3e",
"estado": "processing",
"institution": "BBVA",
"property_type": "CASA_HABITACION"
}Guarda el folio: todas las llamadas siguientes lo usan.
| Si responde | Significa |
|---|---|
409 FOLIO_YA_EXISTE | Ese avalúo ya se subió. Consúltalo con el paso 2. |
422 FOLIO_NO_DETECTADO | El PDF no trae un folio legible en la carátula. |
422 TIPO_INMUEBLE_NO_VALIDO | El tipo de inmueble del PDF (campo 1.10) no se admite. |
400 | El base64 no es válido: debe ir en una sola línea y sin prefijo. |
Consulta el avance
La respuesta anterior llega en segundos, pero el análisis tarda unos minutos. Consulta el avalúo cada 10–15 segundos:
curl "$API_URL/v1/avaluos/AVL-2026-000123" -H "x-api-key: $API_KEY"Mira estos campos:
| Campo | Qué te dice |
|---|---|
document.estado | Lectura del PDF: processing → completed. |
document.errores | Si trae elementos, el PDF no sirve: hay que subir uno corregido. |
latest_evaluation.stages | Las cinco etapas de la evaluación y el estado de cada una. |
latest_evaluation.estado | completed cuando terminaron todas. |
status | approved o requires_correction cuando todo termina. |
{
"folio": "AVL-2026-000123",
"status": "requires_correction",
"puede_certificar": false,
"hallazgos_pendientes": 1,
"document": { "version": 1, "estado": "completed", "errores": [] },
"latest_evaluation": {
"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": [
{
"id": "7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
"codigo_regla": "DAT-011",
"severidad": "tecnico",
"titulo": "Superficie construida no coincide con escritura",
"valor_encontrado": "186.40 m2",
"valor_esperado": "172.00 m2",
"sugerencia": "Verifica la superficie contra la escritura.",
"estado": "pending"
}
]
}
}En una aplicación real es mejor recibir los cambios en tiempo real: ver seguir el avance.
Revisa los hallazgos
Cada elemento de latest_evaluation.errors es un hallazgo: algo que el motor encontró
mal. Para cada uno tienes dos opciones:
- Corregir el PDF y volver a subirlo, si el hallazgo es real.
- Justificarlo, si el valor es correcto y hay un motivo que lo explique.
El certificado no se emite mientras quede algún hallazgo en pending
(hallazgos_pendientes te dice cuántos faltan).
Justifica el hallazgo
Usa el id del hallazgo:
curl -X POST "$API_URL/v1/avaluos/AVL-2026-000123/errores/7c1d2e3f-4a5b-4c6d-8e7f-9a0b1c2d3e4f/justificar" \
-H "x-api-key: $API_KEY" \
-H "Content-Type: application/json" \
-d '{"justificacion":"La diferencia corresponde a la ampliación regularizada en 2021; se anexa licencia de construcción."}'La respuesta es el avalúo completo, con el hallazgo en dismissed, hallazgos_pendientes: 0
y puede_certificar: true.
| Si responde | Significa |
|---|---|
400 | El id no es un UUID o la justificación tiene menos de 3 caracteres. |
404 | El folio no existe o el hallazgo no es de ese avalúo. |
Emite el certificado
curl -X POST "$API_URL/v1/avaluos/AVL-2026-000123/certificado" \
-H "x-api-key: $API_KEY"{
"folio": "AVL-2026-000123",
"status": "approved",
"certificado": {
"estado": "vigente",
"emitido_at": "2026-06-24T18:42:10.000Z",
"hash_avaluo": "9f2c…",
"sha256_certificado": "a41b…",
"url": "https://…?X-Amz-Signature=…"
}
}Descarga el XML firmado desde url (la URL caduca; vuelve a llamar al endpoint para obtener
una nueva). Si quedan hallazgos sin justificar la respuesta es
409 HALLAZGOS_PENDIENTES.