> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Comprobante de domicilio: advertencias y códigos de error > Advertencias de comprobante de domicilio en Didit: nombre no coincidente, documento expirado, metadatos, tipos no admitidos y rechazo automático. ## 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](https://docs.didit.me/es/reference/data-models.md#objeto-de-advertencia) 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. > [!NOTE] > > 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](#comportamiento-de-reintento-sesiones-de-flujo)) 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](#comportamiento-de-reintento-sesiones-de-flujo). ## 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** | > [!NOTE] > > 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/](https://docs.didit.me/es/standalone-apis/proof-of-address.md) 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) ```json theme={null} { "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) ```json theme={null} { "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) ```json theme={null} { "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](https://docs.didit.me/es/core-technology/proof-of-address/report-proof-of-address.md): 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](https://docs.didit.me/es/core-technology/proof-of-address/overview.md): tipos de documento aceptados * [Modelos de datos: prueba de domicilio](https://docs.didit.me/es/reference/data-models.md#prueba-de-domicilio): esquema canónico y objeto Warning * [Webhooks](https://docs.didit.me/es/integration/webhooks.md): `status.updated` incluye las advertencias de POA ### Tipos de advertencia This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.