> ## 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.

# Advertències i codis d'error de Comprovant de domicili

> Codis d'advertència de Comprovant de domicili a Didit: discordança de nom, documents caducats o no admesos i rebuig automàtic configurable.

## Visió general

La verificació del comprovant de domicili (POA) emet advertències a `poa_verifications[].warnings[]` per cada problema de qualitat, autenticitat o coincidència detectat durant l'extracció i l'anàlisi forense. Cada advertència és un [objecte Warning](https://docs.didit.me/ca/reference/data-models.md#objecte-d’advertència) amb `feature` establert a `"PROOF_OF_ADDRESS"`. Uns quants riscos sempre forcen l'estat `Declined`; la resta segueixen una acció per risc (`DECLINE` / `REVIEW` / `NO_ACTION`) configurada al teu flux de treball.

Tots els riscos següents estan verificats en el pipeline de decisió en producció; les cadenes exactes de descripció curta i llarga es reprodueixen textualment a les taules.

> [!NOTE]
>
> L'extracció de POA introdueix una latència de **5–15 segons** per document. Les advertències s'escriuen només quan es completa el pas del flux de treball; no facis sondeig més sovint que cada 5 s.

## Dues vies de producció

Les advertències de POA es generen per dues vies diferents, i el conjunt de riscos difereix entre elles:

* **Sessions de flux de treball** (el pas de POA dins d'una sessió de verificació) — l'endpoint de pujada executa primer una validació bloquejant amb un bucle de reintents (consulta [Comportament dels reintents](#comportament-dels-reintents-sessions-de-flux-de-treball)), i després es calculen les advertències finals emmagatzemades amb `check_poa_risks` més la comprovació de nom multidocument.
* **API independent** (`POST /v3/poa/`) — les advertències provenen únicament de `check_poa_risks`. No hi ha cap bucle de reintents, cap context d'identificació verificada i només hi ha un document, de manera que `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`, `POA_MAX_ATTEMPTS_EXCEEDED` i `FUTURE_ISSUE_DATE` **mai** les produeix l'API independent. Els errors de validació previs a l'extracció es descarten en aquesta via.

`POOR_DOCUMENT_QUALITY` està definit a l'enum de riscos i reservat al mapatge d'accions, però **cap camí de codi al pipeline de POA el produeix**; no apareix mai a `warnings[]` en cap de les dues vies. No bifurquis la lògica basant-te en aquest valor.

## Advertències de rebuig automàtic (sempre forcen `Declined`)

Aquests riscos es troben a `AUTO_DECLINE_RISKS`; quan es registren, l'estat de la POA és `Declined` independentment de la configuració, i `log_type` sempre és `error`.

| Risc | Causa | Correcció recomanada |
| - | - | - |
| `MISSING_ADDRESS_INFORMATION` | No s'ha pogut extreure cap adreça del document. | Demana a l'usuari que torni a enviar un document on es mostri clarament la seva adreça. |
| `POA_DOCUMENT_EXPIRED` | El document ha caducat per una d'aquestes dues vies: la seva **data de caducitat impresa** ha passat, o **té una antiguitat superior a l'antiguitat màxima configurada** per al seu tipus. Valors per defecte: **3 mesos** per a `UTILITY_BILL` i `BANK_STATEMENT`, **12 mesos** per a `GOVERNMENT_ISSUED_DOCUMENT` i `OTHER_POA_DOCUMENT` (un mes compta com a 30 dies; `-1` desactiva la comprovació). `additional_data` sempre inclou `expiration_reason` (`printed_expiration` o `age_window`), `document_type`, `document_subtype` i `issue_date`; la via `printed_expiration` afegeix `expiration_date`, i la via `age_window` afegeix `max_age_months`. | Demana a l'usuari un document vàlid o més recent, o augmenta `age_months` per a aquest tipus. |
| `INVALID_DOCUMENT_TYPE` | El document no s'ha pogut classificar en cap tipus de POA admès (`document_type` passa per defecte a `UNKNOWN`). | Demana a l'usuari que el torni a enviar; comprova que el fitxer no estigui malmès. |
| `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | La comprovació de l'antiguitat del document ha fallat (error en calcular la caducitat a partir de la data d'emissió). | Demana a l'usuari un document amb una data d'emissió clarament llegible. |

`FUTURE_ISSUE_DATE` també està llistat a `AUTO_DECLINE_RISKS`, però només es genera en la validació prèvia a l'extracció (quan la data d'emissió és més de 7 dies en el futur), i els errors d'aquesta validació només alimenten el **bucle de reintents del flux de treball** — allà es manifesta com un error de pujada que bloqueja el procés, mai el produeix l'API independent i no s'escriu a `warnings[]`. Consulta [Comportament dels reintents](#comportament-dels-reintents-sessions-de-flux-de-treball).

## Advertències configurables

Cadascuna d'aquestes advertències segueix un paràmetre d'acció del node POA del flux de treball (`DECLINE` / `REVIEW` / `NO_ACTION`). El `log_type` de l'advertència reflecteix l'acció configurada: `error` per a Rebutjar, `warning` per a Revisar, `information` per a Sense acció.

| Risc | Causa | Paràmetre d'acció | Per defecte |
| - | - | - | - |
| `NAME_MISMATCH_WITH_PROVIDED` | El nom del document puntua per sota de `poa_name_match_score_threshold` (per defecte 86) respecte del nom indicat en crear la sessió (`expected_details`). | `poa_name_or_address_mismatch_action` | Revisar |
| `NAME_MISMATCH_ID_VERIFICATION` | El nom del document puntua per sota del llindar respecte del document d'identitat verificat. `additional_data`: `{ poa_name, kyc_name, match_score }`. Només sessions de flux de treball. | `poa_name_or_address_mismatch_action` | Revisar |
| `ADDRESS_MISMATCH_WITH_PROVIDED` | L'adreça extreta difereix de l'adreça subministrada per API, o bé alguna de les dues adreces no s'ha pogut verificar com a adreça residencial. | `poa_name_or_address_mismatch_action` | Revisar |
| `POA_COUNTRY_MISMATCH_WITH_PROVIDED` | El país del document no coincideix amb el país subministrat per API (normalitzat 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 documents POA de la mateixa sessió tenen noms diferents. `additional_data` inclou els IDs dels dos nodes, els dos noms i la puntuació de coincidència. Només sessions de flux de treball. | `poa_name_or_address_mismatch_action` | Revisar |
| `DOCUMENT_METADATA_MISMATCH` | El fitxer és buit (`file_size` 0) o les dates EXIF tenen un format incorrecte. | `poa_document_issues_action` | Revisar |
| `SUSPECTED_DOCUMENT_MANIPULATION` | L'anàlisi forense ha trobat indicis de manipulació: modificació després de la signatura digital (`is_tampered`), manipulació de text superposat (amb rectangles a `additional_data.manipulated_regions`), un editor de PDF conegut, dates EXIF incoherents o una reexportació sospitosa. `additional_data.detection_method` indica quina comprovació s'ha activat. | `poa_document_authenticity_action` | **Rebutjar** |
| `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Un camp de text s'ha esborrat i reescrit amb una altra tipografia, i el fitxer no conté cap prova de si el contingut ha canviat: els editors en línia reescriuen també el text que no s'ha tocat. Aquesta advertència mai no activa `SUSPECTED_DOCUMENT_MANIPULATION` per si sola; si un altre senyal l'activa sobre el mateix document, decideix l'acció més estricta de les dues. `additional_data.detection_method` és `unproven_text_replacement`, amb `replaced_text` i `manipulated_regions`. Un fitxer que no s'ha pogut analitzar completament també genera aquesta advertència, perquè la part no analitzada podria contenir un camp d'aquest tipus: `detection_method` és aleshores `analysis_incomplete`, amb `replaced_text` i `manipulated_regions` buits, tret que s'hagi trobat un camp a la part analitzada. | `poa_document_unproven_text_replacement_action` | Revisar |
| `UNSUPPORTED_DOCUMENT_LANGUAGE` | L'idioma del document no és a `poa_languages_allowed`. | `poa_unsupported_language_action` | **Rebutjar** |
| `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | El tipus de document detectat no està habilitat a `poa_documents_allowed` per al país del document, o el seu subtipus està desactivat explícitament. | `poa_unsupported_document_type_action` | **Rebutjar** |
| `ISSUER_NOT_IDENTIFIED` | No s'ha pogut identificar l'entitat emissora a partir del document. | `poa_issuer_not_identified_action` | Revisar |
| `UNABLE_TO_EXTRACT_ISSUE_DATE` | No s'ha pogut localitzar cap data d'emissió vàlida al document. | `poa_issue_date_not_detected_action` | Revisar |
| `POA_NAME_NOT_DETECTED` | No s'ha detectat cap nom al document. | `poa_issue_date_not_detected_action` (paràmetre compartit) | Revisar |
| `UNPARSABLE_OR_INVALID_ADDRESS` | S'ha extret una adreça però no s'ha pogut analitzar ni geocodificar com a adreça residencial vàlida. | `poa_unparsable_or_invalid_address_action` | Revisar |
| `POA_MAX_ATTEMPTS_EXCEEDED` | L'usuari ha esgotat `poa_max_retry_attempts` (per defecte 2) al bucle de reintents del flux de treball. `additional_data`: `{ attempts }`. Només sessions de flux de treball. | `poa_max_attempts_exceeded_action` | **Rebutjar** |

> [!NOTE]
>
> Hi ha **una sola acció compartida** per a totes les discrepàncies de nom i d'adreça: `poa_name_or_address_mismatch_action` cobreix els dos riscos de nom, els dos riscos d'adreça i la comprovació de noms entre documents. No es poden configurar per separat els comportaments de discrepància de nom i de discrepància d'adreça. A l'API independent, el mateix grup segueix l'opció de sol·licitud `poa_address_mismatch_action` (l'opció `poa_name_mismatch_action` s'accepta però mai no es llegeix).

## Diferències de l'API independent (`POST /v3/poa/`)

L'endpoint independent construeix la mateixa assignació de risc a acció, però amb opcions a nivell de sol·licitud que només accepten `DECLINE` o `NO_ACTION` (totes establertes per defecte a `DECLINE`):

* `UNABLE_TO_EXTRACT_ISSUE_DATE` i `POA_NAME_NOT_DETECTED` estan **fixats a Rebutjar** en aquest endpoint.
* `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` i `UNPARSABLE_OR_INVALID_ADDRESS` són **informatius** aquí: les seves accions estan per defecte en Cap acció i no són configurables per sol·licitud.
* `FUTURE_ISSUE_DATE`, `POOR_DOCUMENT_QUALITY`, `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` i `POA_MAX_ATTEMPTS_EXCEEDED` mai no es produeixen: un document amb data futura **no** es rebutja automàticament en aquest endpoint.

Consulta la [referència de l'API POST /v3/poa/](https://docs.didit.me/ca/standalone-apis/proof-of-address.md) per conèixer les opcions de sol·licitud.

## Comportament dels reintents (sessions de flux de treball)

En una sessió de verificació, el pas de càrrega del POA executa una validació bloquejant abans que el document s'accepti. Quan troba un error bloquejant — `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 càrrega es rebutja amb `400` i el codi de risc com a missatge, i l'usuari pot tornar-ho a provar amb un document millor.

En el cas de `POA_DOCUMENT_EXPIRED`, el cos del `400` també inclou `expiration_reason` (`printed_expiration` o `age_window`) perquè la teva interfície d'usuari pugui mostrar el motiu exacte; en el camí `age_window` inclou addicionalment `max_age_months`. En el camí `printed_expiration` s'omet intencionadament `max_age_months`, perquè el document s'ha rebutjat per la data de caducitat que té impresa i no pas per una finestra d'antiguitat.

Un cop l'usuari ha esgotat els intents de `poa_max_retry_attempts` (per defecte 2, configurable de 2 a 5), l'enviament s'accepta igualment: les advertències emmagatzemades es tornen a calcular a partir del document desat, s'afegeix `POA_MAX_ATTEMPTS_EXCEEDED` i l'estat es resol a partir del conjunt complet de riscos. És per això que `FUTURE_ISSUE_DATE` pot bloquejar una càrrega i, tanmateix, no aparèixer mai a `warnings[]`.

## Paràmetres configurables

El node de POA del flux de treball exposa aquests controls (que coincideixen amb els camps de `VerificationSettings`):

| Paràmetre | Controla | Per defecte |
| - | - | - |
| `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` | Review |
| `poa_document_issues_action` | `DOCUMENT_METADATA_MISMATCH` | Review |
| `poa_document_authenticity_action` | `SUSPECTED_DOCUMENT_MANIPULATION` | Decline |
| `poa_document_unproven_text_replacement_action` | `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` | Review (un flux de treball que mai no revisa utilitza el seu propi `poa_document_authenticity_action` quan aquest és Decline, en cas contrari No action; l'API autònoma segueix el `poa_document_authenticity_action` de la sol·licitud) |
| `poa_unsupported_language_action` | `UNSUPPORTED_DOCUMENT_LANGUAGE` | Decline |
| `poa_unsupported_document_type_action` | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | Decline |
| `poa_issuer_not_identified_action` | `ISSUER_NOT_IDENTIFIED` | Review |
| `poa_issue_date_not_detected_action` | `UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED` | Review |
| `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS` | Review |
| `poa_max_attempts_exceeded_action` | `POA_MAX_ATTEMPTS_EXCEEDED` | Decline |
| `poa_documents_allowed` | Tipus de documents acceptats per país, cadascun amb `enabled` i `age_months` (`-1` = il·limitat); sobreescriptures per subtipus mitjançant `document_subtypes_config`. | Factura de serveis i extracte bancari: 3 mesos; emesos pel govern i altres: 12 mesos |
| `poa_languages_allowed` | Idiomes de documents acceptats. | Tots els idiomes admesos |
| `poa_name_match_score_threshold` | Puntuació mínima de coincidència de nom (0–100) abans que s'activin els riscos `NAME_MISMATCH*`. | 86 |
| `poa_max_retry_attempts` | Intents de càrrega abans que el bucle de reintents es rendeixi (2–5). | 2 |

## Lògica de coincidència de noms

La coincidència de noms en POA tolera variacions habituals:

* **Segons noms i inicials**: es comparen de manera flexible (se'n permet la presència o absència).
* **Noms candidats**: es puntua cada nom detectat al document (`name_on_document` més `additional_names`), i es conserva el candidat amb millor puntuació.
* **Llindar de coincidència**: el valor per defecte de `poa_name_match_score_threshold` és **86**; una puntuació inferior activa l'advertència `NAME_MISMATCH*` corresponent.

Les puntuacions numèriques s'exposen a l'informe com a `name_match_score_expected_details` i `name_match_score_id_verification` (0–100). Els valors de puntuació són útils per a una revisió detallada fins i tot quan no s'ha generat cap advertència.

## Exemples

### Manipulació per superposició (Rebutjada per defecte)

```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"
    }
  ]
}
```

### Document caducat + falta d'adreça (rebuig automàtic)

```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"
    }
  ]
}
```

### Discrepància de nom (En revisió per defecte)

```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"
    }
  ]
}
```

## Relacionat

* [Informe de comprovant de domicili](https://docs.didit.me/ca/core-technology/proof-of-address/report-proof-of-address.md) — format complet de la resposta, anàlisi forense de manipulació per superposició, semàntica dels estats
* [Visió general de comprovant de domicili](https://docs.didit.me/ca/core-technology/proof-of-address/overview.md) — tipus de documents admesos
* [Models de dades — Comprovant de domicili](https://docs.didit.me/ca/reference/data-models.md#comprovant-de-domicili) — esquema canònic i objecte Warning
* [Webhooks](https://docs.didit.me/ca/integration/webhooks.md) — `status.updated` transmet les advertències de POA

### Tipus d'advertència


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.