Guía rápida
Tu primer avalúo de punta a punta con curl, en seis llamadas.
En esta guía subes un PDF de avalúo, lanzas y 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://<HOST> # el host del API que te entregó el equipo de Tasvalúo
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": "26091000123",
"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 GET /v1/avaluos/{folio}: si latest_evaluation es null, sigue desde el paso 2; si no, desde el paso 3. |
422 FOLIO_NO_DETECTADO | El PDF no trae el folio del formato SHF: Folio: seguido de 11 dígitos. |
422 INSTITUCION_NO_DETECTADA / INSTITUCION_NO_VALIDA | No se pudo leer la clave de entidad otorgante (campo 1.16), o esa clave no está activa en el catálogo de instituciones. |
422 TIPO_INMUEBLE_NO_DETECTADO / TIPO_INMUEBLE_NO_VALIDO | No se pudo leer el tipo de inmueble (campo 1.10), o ese tipo no está activo en el catálogo. |
400 | El base64 no es válido: debe ir en una sola línea y sin prefijo. |
Lanza la evaluación
El API no arranca la evaluación por su cuenta, y primero tiene que terminar de leer el PDF.
Consulta el avalúo cada 10–15 segundos hasta que document.puede_evaluar sea true:
curl "$API_URL/v1/avaluos/26091000123" -H "x-api-key: $API_KEY"Si en cambio document.errores trae elementos o document.estado pasa a error, no llegará
a true: sube una versión nueva del PDF.
Cuando sea true, lánzala:
curl -X POST "$API_URL/v1/avaluos/26091000123/evaluar" \
-H "x-api-key: $API_KEY"Responde 202 Accepted con el avalúo completo. Si el documento ya tenía una evaluación en
curso o completada, devuelve esa misma en vez de lanzar otra. Más detalle en
lanzar la evaluación.
| Si responde | Significa |
|---|---|
409 DOCUMENTO_NO_LISTO | El PDF aún no terminó de leerse (document.estado distinto de completed). Si está en processing, espera y reintenta; si está en error, sube una versión nueva. |
409 DOCUMENTO_CON_ERRORES | El PDF no sirve (document.errores trae elementos). Sube uno corregido. |
404 | El folio no existe o no tiene documento. |
Consulta el avance
La evaluación tarda unos minutos. Consulta el avalúo cada 10–15 segundos:
curl "$API_URL/v1/avaluos/26091000123" -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. |
document.puede_evaluar | true cuando el PDF ya se leyó sin errores y no tiene una evaluación en curso o completada: es el momento de llamar a /evaluar. |
latest_evaluation.stages | Las cinco etapas de la evaluación y el estado de cada una (latest_evaluation es null hasta que llamas a /evaluar). |
latest_evaluation.estado | completed cuando terminaron todas. |
status | approved o requires_correction cuando todo termina. |
{
"folio": "26091000123",
"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. La versión nueva no se evalúa sola: lanza su evaluación como en el paso 2.
- 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/26091000123/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/26091000123/certificado" \
-H "x-api-key: $API_KEY"{
"folio": "26091000123",
"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.