Comprobante de domicilio: advertencias y códigos de error

Visión general

La verificación de comprobantes de domicilio (POA) emite advertencias en poa_verifications[].warnings[] por cada problema de calidad, autenticidad o coincidencia detectado durante la extracción y el análisis forense. Cada advertencia es un objeto Warning con feature establecido en "PROOF_OF_ADDRESS". Unos pocos riesgos siempre fuerzan Declined; el resto sigue la acción configurada para cada riesgo (DECLINE / REVIEW / NO_ACTION) configurada en tu flujo. Cada riesgo de la lista siguiente se ha verificado en el pipeline de decisiones en producción; las cadenas exactas de las descripciones corta y larga se reproducen literalmente en las tablas.

La extracción de POA añade una latencia de 5–15 segundos por documento. Las advertencias se escriben solo cuando se completa el paso del flujo; no consultes con una frecuencia mayor de una vez cada 5 s.

Dos rutas de producción

Las advertencias de POA se generan en dos rutas distintas, y el conjunto de riesgos difiere entre ellas:

Sesiones de flujo de trabajo (el paso de POA dentro de una sesión de verificación): el endpoint de carga ejecuta primero una validación bloqueante con un bucle de reintentos (consulta Comportamiento de reintentos) y, después, las advertencias finales almacenadas se calculan con check_poa_risks más la comprobación de nombres entre varios documentos.
API independiente (POST /v3/poa/): las advertencias provienen únicamente de check_poa_risks. No hay bucle de reintentos, ni contexto de documento de identidad verificado, y solo hay un documento, por lo que la API independiente nunca genera NAME_MISMATCH_ID_VERIFICATION, POA_NAME_MISMATCH_BETWEEN_DOCUMENTS, POA_MAX_ATTEMPTS_EXCEEDED ni FUTURE_ISSUE_DATE. En esta ruta se descartan los errores de validación previos a la extracción.

POOR_DOCUMENT_QUALITY está definido en el enum de riesgos y reservado en el mapeo de acciones, pero ninguna ruta de código del pipeline de POA lo genera: nunca aparece en warnings[] en ninguna de las dos rutas. No bases tu lógica en él.

Advertencias de rechazo automático (siempre fuerzan `Declined`)

Estos riesgos están en AUTO_DECLINE_RISKS; cuando se registran, el estado de la POA es Declined independientemente de la configuración, y log_type es siempre error.

Riesgo	Causa	Solución recomendada
`MISSING_ADDRESS_INFORMATION`	No se pudo extraer ninguna dirección del documento.	Pide al usuario que vuelva a enviar un documento que muestre claramente su dirección.
`POA_DOCUMENT_EXPIRED`	El documento ha expirado por una de dos vías: su fecha de caducidad impresa ya ha pasado, o supera la antigüedad máxima configurada para su tipo. Valores predeterminados: 3 meses para `UTILITY_BILL` y `BANK_STATEMENT`, 12 meses para `GOVERNMENT_ISSUED_DOCUMENT` y `OTHER_POA_DOCUMENT` (un mes equivale a 30 días; `-1` desactiva la comprobación). `additional_data` siempre incluye `expiration_reason` (`printed_expiration` o `age_window`), `document_type`, `document_subtype` e `issue_date`; la vía `printed_expiration` añade `expiration_date`, y la vía `age_window` añade `max_age_months`.	Pide al usuario un documento válido o más reciente, o aumenta `age_months` para ese tipo.
`INVALID_DOCUMENT_TYPE`	No se pudo clasificar el documento en ningún tipo de POA admitido (`document_type` toma el valor `UNKNOWN`).	Pide al usuario que vuelva a enviarlo; comprueba que el archivo no esté dañado.
`UNABLE_TO_VALIDATE_DOCUMENT_AGE`	Falló la propia comprobación de la antigüedad del documento (error al calcular la caducidad a partir de la fecha de emisión).	Pide al usuario un documento con una fecha de emisión claramente legible.

FUTURE_ISSUE_DATE también figura en AUTO_DECLINE_RISKS, pero tiene un único origen en la validación previa a la extracción (una fecha de emisión más de 7 días en el futuro), cuyos errores solo alimentan el bucle de reintentos del flujo: allí aparece como un error de subida bloqueante, la API independiente nunca lo genera y no se escribe en warnings[]. Consulta Comportamiento de reintentos.

Advertencias configurables

Cada una de estas advertencias sigue un ajuste de acción del nodo POA del flujo (DECLINE / REVIEW / NO_ACTION). El log_type de la advertencia refleja la acción configurada: error para Rechazar, warning para Revisar y information para Sin acción.

Riesgo	Causa	Ajuste de acción	Valor predeterminado
`NAME_MISMATCH_WITH_PROVIDED`	El nombre del documento obtiene una puntuación inferior a `poa_name_match_score_threshold` (86 por defecto) frente al nombre proporcionado al crear la sesión (`expected_details`).	`poa_name_or_address_mismatch_action`	Revisar
`NAME_MISMATCH_ID_VERIFICATION`	El nombre del documento obtiene una puntuación inferior al umbral frente al documento de identidad verificado. `additional_data`: `{ poa_name, kyc_name, match_score }`. Solo en sesiones de flujo.	`poa_name_or_address_mismatch_action`	Revisar
`ADDRESS_MISMATCH_WITH_PROVIDED`	La dirección extraída difiere de la dirección proporcionada mediante la API, o alguna de las dos direcciones no se pudo verificar como dirección residencial.	`poa_name_or_address_mismatch_action`	Revisar
`POA_COUNTRY_MISMATCH_WITH_PROVIDED`	El país del documento no coincide con el país proporcionado mediante la API (normalizado a ISO-3). `additional_data`: `{ expected_country, extracted_country }`.	`poa_name_or_address_mismatch_action`	Revisar
`POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`	Dos o más documentos POA de la misma sesión contienen nombres distintos. `additional_data` incluye los ID de ambos nodos, ambos nombres y la puntuación de coincidencia. Solo en sesiones de flujo.	`poa_name_or_address_mismatch_action`	Revisar
`DOCUMENT_METADATA_MISMATCH`	El archivo está vacío (`file_size` 0) o sus fechas EXIF están mal formadas.	`poa_document_issues_action`	Revisar
`SUSPECTED_DOCUMENT_MANIPULATION`	El análisis forense encontró indicios de manipulación: modificación posterior a la firma digital (`is_tampered`), manipulación mediante texto superpuesto (con rectángulos en `additional_data.manipulated_regions`), un editor de PDF conocido, fechas EXIF incoherentes o una reexportación sospechosa. `additional_data.detection_method` indica la comprobación que se activó.	`poa_document_authenticity_action`	Rechazar
`UNSUPPORTED_DOCUMENT_LANGUAGE`	El idioma del documento no está en `poa_languages_allowed`.	`poa_unsupported_language_action`	Rechazar
`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`	El tipo de documento detectado no está habilitado en `poa_documents_allowed` para el país del documento, o su subtipo está deshabilitado explícitamente.	`poa_unsupported_document_type_action`	Rechazar
`ISSUER_NOT_IDENTIFIED`	No se pudo identificar la institución emisora a partir del documento.	`poa_issuer_not_identified_action`	Revisar
`UNABLE_TO_EXTRACT_ISSUE_DATE`	No se pudo localizar una fecha de emisión válida en el documento.	`poa_issue_date_not_detected_action`	Revisar
`POA_NAME_NOT_DETECTED`	No se detectó ningún nombre en el documento.	`poa_issue_date_not_detected_action` (ajuste compartido)	Revisar
`UNPARSABLE_OR_INVALID_ADDRESS`	Se extrajo una dirección, pero no se pudo analizar ni geocodificar como una dirección residencial válida.	`poa_unparsable_or_invalid_address_action`	Revisar
`POA_MAX_ATTEMPTS_EXCEEDED`	El usuario agotó los `poa_max_retry_attempts` (2 por defecto) en el ciclo de reintentos del flujo. `additional_data`: `{ attempts }`. Solo en sesiones de flujo.	`poa_max_attempts_exceeded_action`	Rechazar

Hay una única acción compartida para todas las discrepancias de nombre y dirección: poa_name_or_address_mismatch_action abarca ambos riesgos de nombre, ambos riesgos de dirección y la comprobación de nombre entre documentos, por lo que no puedes configurar por separado el comportamiento ante discrepancias de nombre y de dirección. En la API independiente, ese mismo grupo sigue la opción de solicitud poa_address_mismatch_action (la opción poa_name_mismatch_action se acepta, pero nunca se lee).

Diferencias de la API independiente (`POST /v3/poa/`)

El endpoint independiente construye la misma correspondencia entre riesgos y acciones, pero con opciones a nivel de solicitud que solo aceptan DECLINE o NO_ACTION (todas con DECLINE como valor predeterminado):

UNABLE_TO_EXTRACT_ISSUE_DATE y POA_NAME_NOT_DETECTED están fijadas en Rechazar en este endpoint.
POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION y UNPARSABLE_OR_INVALID_ADDRESS son informativas aquí: sus acciones son Sin acción por defecto y no se pueden configurar por solicitud.
FUTURE_ISSUE_DATE, POOR_DOCUMENT_QUALITY, NAME_MISMATCH_ID_VERIFICATION, POA_NAME_MISMATCH_BETWEEN_DOCUMENTS y POA_MAX_ATTEMPTS_EXCEEDED nunca se generan: un documento con fecha futura no se rechaza automáticamente en este endpoint.

Consulta la referencia de la API POST /v3/poa/ para ver las opciones de solicitud.

Comportamiento de reintento (sesiones de flujo)

En una sesión de verificación, el paso de carga de POA ejecuta una validación bloqueante antes de aceptar el documento. Cuando encuentra un error bloqueante (INVALID_DOCUMENT_TYPE, UNABLE_TO_EXTRACT_ISSUE_DATE, FUTURE_ISSUE_DATE, POA_NAME_NOT_DETECTED, MISSING_ADDRESS_INFORMATION, POA_COUNTRY_MISMATCH_WITH_PROVIDED, POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION, UNSUPPORTED_DOCUMENT_LANGUAGE o POA_DOCUMENT_EXPIRED), la carga se rechaza con 400 y el código de riesgo como mensaje, y el usuario puede volver a intentarlo con un documento mejor. Para POA_DOCUMENT_EXPIRED, el cuerpo del 400 también incluye expiration_reason (printed_expiration o age_window) para que tu interfaz pueda mostrar el motivo exacto; en el caso de age_window incluye además max_age_months. En el caso de printed_expiration, max_age_months se omite intencionadamente, porque el documento se rechazó por su fecha de caducidad impresa y no por una ventana de antigüedad. Una vez que el usuario ha agotado los poa_max_retry_attempts intentos (2 por defecto, configurable entre 2 y 5), el envío se acepta de todos modos: las advertencias almacenadas se vuelven a calcular a partir del documento guardado, se añade POA_MAX_ATTEMPTS_EXCEEDED y el estado se resuelve a partir del conjunto completo de riesgos. Por eso FUTURE_ISSUE_DATE puede bloquear una carga y, aun así, nunca aparecer en warnings[].

Ajustes configurables

El nodo POA del flujo expone estos ajustes (que corresponden a los campos de VerificationSettings):

Ajuste	Controla	Valor predeterminado
`poa_name_or_address_mismatch_action`	`NAME_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_ID_VERIFICATION`, `ADDRESS_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`	Revisión
`poa_document_issues_action`	`DOCUMENT_METADATA_MISMATCH`	Revisión
`poa_document_authenticity_action`	`SUSPECTED_DOCUMENT_MANIPULATION`	Rechazo
`poa_unsupported_language_action`	`UNSUPPORTED_DOCUMENT_LANGUAGE`	Rechazo
`poa_unsupported_document_type_action`	`POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`	Rechazo
`poa_issuer_not_identified_action`	`ISSUER_NOT_IDENTIFIED`	Revisión
`poa_issue_date_not_detected_action`	`UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED`	Revisión
`poa_unparsable_or_invalid_address_action`	`UNPARSABLE_OR_INVALID_ADDRESS`	Revisión
`poa_max_attempts_exceeded_action`	`POA_MAX_ATTEMPTS_EXCEEDED`	Rechazo
`poa_documents_allowed`	Tipos de documento aceptados por país, cada uno con `enabled` y `age_months` (`-1` = sin límite); ajustes específicos por subtipo mediante `document_subtypes_config`.	Factura de servicios y extracto bancario: 3 meses; emitidos por el gobierno y otros: 12 meses
`poa_languages_allowed`	Idiomas de documento aceptados.	Todos los idiomas admitidos
`poa_name_match_score_threshold`	Puntuación mínima de coincidencia de nombre (0–100) por debajo de la cual se activan los riesgos `NAME_MISMATCH*`.	86
`poa_max_retry_attempts`	Intentos de subida antes de que el ciclo de reintentos se detenga (2–5).	2

Lógica de coincidencia de nombres

La coincidencia de nombres de POA tolera las variaciones habituales:

Segundos nombres e iniciales: se comparan con flexibilidad (se permite que estén presentes o ausentes).
Nombres candidatos: se puntúa cada nombre detectado en el documento (name_on_document más additional_names) y se conserva el candidato con la mejor puntuación.
Umbral de coincidencia: el valor predeterminado de poa_name_match_score_threshold es 86; una puntuación inferior activa la advertencia NAME_MISMATCH* correspondiente.

Las puntuaciones numéricas se muestran en el informe como name_match_score_expected_details y name_match_score_id_verification (0–100). Los valores de puntuación son útiles para una revisión detallada incluso cuando no se ha generado ninguna advertencia.

Ejemplos

Manipulación mediante superposición (rechazo por defecto)

{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "SUSPECTED_DOCUMENT_MANIPULATION",
      "additional_data": {
        "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).",
        "detection_method": "overlay_text_manipulation",
        "signals": ["duplicate_font_subset", "glyph_fragmentation"],
        "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
        "fragmented_fonts": [],
        "manipulated_regions": [
          { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
        ]
      },
      "log_type": "error",
      "short_description": "Suspected document manipulation",
      "long_description": "The system detected signs of potential document manipulation or editing.",
      "node_id": "feature_poa_1"
    }
  ]
}

Documento expirado + dirección ausente (rechazo automático)

{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "POA_DOCUMENT_EXPIRED",
      "additional_data": {
        "expiration_reason": "age_window",
        "max_age_months": 3,
        "document_subtype": "ELECTRICITY_BILL",
        "document_type": "UTILITY_BILL",
        "issue_date": "2025-11-02"
      },
      "log_type": "error",
      "short_description": "Document expired",
      "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity.",
      "node_id": "feature_poa_1"
    },
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "MISSING_ADDRESS_INFORMATION",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Missing address information",
      "long_description": "The document does not contain complete or clear address information that can be extracted.",
      "node_id": "feature_poa_1"
    }
  ]
}

Nombre que no coincide (revisión por defecto)

{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "NAME_MISMATCH_ID_VERIFICATION",
      "additional_data": {
        "poa_name": "JOHN B SMYTH",
        "kyc_name": "John A. Smith",
        "match_score": 60
      },
      "log_type": "warning",
      "short_description": "Name mismatch with ID verification",
      "long_description": "The full name on the document does not match the name from the user's verified identity documents.",
      "node_id": "feature_poa_1"
    }
  ]
}

Relacionado

Informe de prueba de domicilio: estructura completa de la respuesta, análisis forense de manipulación por superposición y significado de los estados
Visión general de la prueba de domicilio: tipos de documento aceptados
Modelos de datos: prueba de domicilio: esquema canónico y objeto Warning
Webhooks: status.updated incluye las advertencias de POA

Autenticación

Verificación

Monitorización

Plataforma

Comprobante de domicilio: advertencias y códigos de error

Visión general

Dos rutas de producción

Advertencias de rechazo automático (siempre fuerzan `Declined`)

Advertencias configurables

Diferencias de la API independiente (`POST /v3/poa/`)

Comportamiento de reintento (sesiones de flujo)

Ajustes configurables

Lógica de coincidencia de nombres

Ejemplos

Manipulación mediante superposición (rechazo por defecto)

Documento expirado + dirección ausente (rechazo automático)

Nombre que no coincide (revisión por defecto)

Relacionado

Tipos de advertencia

​Visión general

​Dos rutas de producción

​Advertencias de rechazo automático (siempre fuerzan Declined)

​Advertencias configurables

​Diferencias de la API independiente (POST /v3/poa/)

​Comportamiento de reintento (sesiones de flujo)

​Ajustes configurables

​Lógica de coincidencia de nombres

​Ejemplos

​Manipulación mediante superposición (rechazo por defecto)

​Documento expirado + dirección ausente (rechazo automático)

​Nombre que no coincide (revisión por defecto)

​Relacionado

​Tipos de advertencia

Visión general

Dos rutas de producción

Advertencias de rechazo automático (siempre fuerzan `Declined`)

Advertencias configurables

Diferencias de la API independiente (`POST /v3/poa/`)

Comportamiento de reintento (sesiones de flujo)

Ajustes configurables

Lógica de coincidencia de nombres

Ejemplos

Manipulación mediante superposición (rechazo por defecto)

Documento expirado + dirección ausente (rechazo automático)

Nombre que no coincide (revisión por defecto)

Relacionado

Tipos de advertencia