Control y dictamen

El flujo del controlador, de la bandeja al dictamen, con sus requisitos y errores.

Cuando un avalúo tiene certificado, pasa a la revisión de un controlador: una persona que comprueba que el PDF que tiene en mano es exactamente el certificado y emite el dictamen final, aprobado o rechazado.

Se necesita una llave con control:read y control:write.

1. GET  /v1/control/inbox                           ¿qué hay que revisar?
2. POST /v1/control/verificaciones                  ¿el PDF es el certificado?  → verificacion_id
3. POST /v1/control/avaluos/{folio}/dictamen        aprobado | rechazado

1 · La bandeja

GET/v1/control/inboxcontrol:read

Bandeja de avalúos recibidos

curl "$API_URL/v1/control/inbox?bandeja=en_revision&page=1&page_size=20" \
  -H "x-api-key: $API_KEY"

Parámetro	Valores
`bandeja`	`en_revision` (por defecto), `requiere_correccion` o `dictaminados`.
`page`, `page_size`	Página desde 1 y tamaño de 1 a 100 (20 por defecto).
`search`	Parte del folio. No distingue mayúsculas.
`desde`, `hasta`	Rango de fecha de creación del avalúo, en ISO 8601 (`2026-06-24`). Una fecha inválida responde `400`.

Bandeja	Contiene
`en_revision`	Avalúos con certificado vigente y sin dictamen. Lo que hay que revisar.
`requiere_correccion`	Avalúos devueltos al perito, sin dictamen vigente.
`dictaminados`	Avalúos con dictamen vigente.

200 OK

{
  "data": [
    {
      "folio": "AVL-2026-000123",
      "avaluo_id": "5b2f7c1e-3a4d-4f6b-9e21-8c7d6a5b4f3e",
      "estado": "approved",
      "bandeja": "en_revision",
      "perito_id": "P-998",
      "institucion": "BBVA",
      "tipo_inmueble": "CASA_HABITACION",
      "documento_version": 1,
      "created_at": "2026-06-24T18:30:00.000Z",
      "updated_at": "2026-06-24T18:42:10.000Z",
      "certificado": { "emitido_at": "2026-06-24T18:42:10.000Z", "estado": "vigente", "sha256_certificado": "a41b09c3d2…" },
      "hallazgos": { "criticos": 0, "tecnicos": 1, "forma": 0, "justificados": 1 },
      "ultima_verificacion": null,
      "revision": null,
      "puede_dictaminar": false,
      "motivo_bloqueo": "sin_verificacion"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 1,
  "total_pages": 1
}

Los resultados vienen ordenados del más recientemente actualizado al más antiguo. En hallazgos, justificados también se cuenta dentro de criticos, tecnicos y forma.

Para un tablero con los totales, usa GET /v1/control/resumen. Para el detalle de un avalúo, GET /v1/control/avaluos/{folio}.

2 · Verificar el PDF

POST/v1/control/verificacionescontrol:write

Verifica la integridad del avalúo y deja constancia

El controlador envía el PDF que recibió y el XML del certificado. El API comprueba la firma y la huella del documento, y guarda la verificación como evidencia.

curl -X POST "$API_URL/v1/control/verificaciones" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"avaluo_base64\": \"$(base64 -i avaluo.pdf | tr -d '\n')\",
    \"certificado_xml\": $(jq -Rs . < certificado.xml),
    \"controlador\": { \"id\": \"u-102\", \"nombre\": \"Luis Ramírez\", \"email\": \"luis@banco.mx\" }
  }"

Campo	Regla
`avaluo_base64`	El PDF en base64, en una línea.
`certificado_xml`	El XML del certificado, como texto.
`controlador.id`	Identificador del controlador en tu sistema. Hasta 120 caracteres. Envíalo siempre.
`controlador.nombre`, `controlador.email`	Opcionales, hasta 160 caracteres.

201 Created

{
  "valido": true,
  "folio": "AVL-2026-000123",
  "firma_valida": true,
  "coincide_hash": true,
  "certificado_estado": "vigente",
  "hash_esperado": "9f2c4a1b7e…",
  "hash_calculado": "9f2c4a1b7e…",
  "resultado": "coincide",
  "verificacion_id": "c0ffee00-1234-4abc-9def-001122334455",
  "documento_version": 1,
  "puede_dictaminar": true,
  "motivo_bloqueo": null
}

`resultado`	Qué significa
`coincide`	El PDF es el certificado. Se puede dictaminar.
`discrepancia`	El PDF cambió respecto al certificado.
`certificado_invalido`	El XML fue alterado, es ilegible o no lo emitió este servicio.
`certificado_revocado`	Se subió una versión posterior del PDF.

Guarda verificacion_id: el dictamen lo exige.

Comprueba verificacion_id antes de seguir

Si el XML es ilegible o su folio no existe, no se guarda nada: la respuesta trae verificacion_id: null, puede_dictaminar: false y no trae motivo_bloqueo. Si el XML se lee pero la firma no es válida, sí se guarda como certificado_invalido y bloquea el dictamen hasta una verificación correcta.

Por qué no se puede dictaminar

Cuando puede_dictaminar es false, motivo_bloqueo dice por qué:

`motivo_bloqueo`	Qué hacer
`sin_certificado`	El avalúo no tiene certificado vigente: el perito debe emitirlo.
`sin_verificacion`	Verifica el PDF (paso 2).
`verificacion_fallida`	La última verificación no dio `coincide`: consigue el PDF correcto y vuelve a verificar.
`verificacion_desactualizada`	Hay una versión del PDF más nueva que la verificada: verifica de nuevo.
`ya_dictaminado`	Ya tiene dictamen: reábrelo antes de emitir otro.

3 · Dictaminar

POST/v1/control/avaluos/{folio}/dictamencontrol:write

Registra el dictamen técnico humano

curl -X POST "$API_URL/v1/control/avaluos/AVL-2026-000123/dictamen" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "dictamen": "aprobado",
    "verificacion_id": "c0ffee00-1234-4abc-9def-001122334455",
    "observaciones": "Sin observaciones.",
    "controlador": { "id": "u-102", "nombre": "Luis Ramírez" }
  }'

El estado del avalúo no cambia; el dictamen queda registrado en dictamen_control.

201 Created

{
  "id": "d1c7a0b2-5e6f-4a1b-8c9d-0e1f2a3b4c5d",
  "dictamen": "rechazado",
  "observaciones": null,
  "motivo_rechazo": "El comparable 3 está fuera de la zona homogénea.",
  "documento_version": 1,
  "verificacion_id": "c0ffee00-1234-4abc-9def-001122334455",
  "controlador_id": "u-102",
  "controlador_nombre": "Luis Ramírez",
  "controlador_email": null,
  "vigente": true,
  "created_at": "2026-06-24T19:05:00.000Z"
}

Errores

El API comprueba en este orden:

HTTP	`code`	Causa	Qué hacer
`400`	`MOTIVO_REQUERIDO`	Rechazo sin motivo o con menos de 10 caracteres.	Escribe el motivo.
`400`	—	`dictamen` no es `aprobado`/`rechazado`, `verificacion_id` no es un UUID o falta `controlador`.	Revisa el cuerpo.
`404`	—	El folio no existe.	Revisa el folio.
`409`	`YA_DICTAMINADO`	Ya hay un dictamen vigente.	Reábrelo primero.
`409`	`SIN_CERTIFICADO`	No hay certificado vigente.	El perito debe emitirlo.
`409`	`VERIFICACION_REQUERIDA`	Nunca se verificó el PDF.	Verifica (paso 2).
`409`	`VERIFICACION_FALLIDA`	La última verificación no dio `coincide`.	Verifica con el PDF correcto.
`409`	`VERIFICACION_DESACTUALIZADA`	`verificacion_id` no es la última verificación, o el PDF cambió de versión.	Verifica de nuevo y usa el `verificacion_id` nuevo.

Reabrir un dictamen

POST/v1/control/avaluos/{folio}/dictamen/reabrircontrol:write

Deja sin efecto el dictamen vigente

curl -X POST "$API_URL/v1/control/avaluos/AVL-2026-000123/dictamen/reabrir" \
  -H "x-api-key: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "motivo": "El perito aportó la documentación que faltaba.",
    "controlador": { "id": "u-102" }
  }'

motivo: de 10 a 2000 caracteres.
controlador es obligatorio: queda registrado quién reabrió.
El dictamen anterior queda como historial (vigente: false) y se le añade Reabierto por <nombre> (<id>): <motivo> a sus observaciones.
Si era un rechazo y el certificado sigue vigente, el avalúo vuelve a approved.
Para dictaminar otra vez, la última verificación debe seguir siendo coincide.

HTTP	`code`	Causa
`400`	—	`motivo` falta o no cumple la longitud, o falta `controlador`.
`404`	—	El folio no existe.
`409`	`SIN_DICTAMEN`	No hay dictamen vigente que reabrir.

Qué invalida el dictamen

Si el perito sube una versión nueva del PDF, el certificado se revoca y el dictamen vigente se cierra. El avalúo vuelve al principio: nueva evaluación, nuevo certificado, nueva verificación y nuevo dictamen.