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

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

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), 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.

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

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/ 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)

{
  "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)

{
  "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)

{
  "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 — format complet de la resposta, anàlisi forense de manipulació per superposició, semàntica dels estats
Visió general de comprovant de domicili — tipus de documents admesos
Models de dades — Comprovant de domicili — esquema canònic i objecte Warning
Webhooks — status.updated transmet les advertències de POA

Autenticació

Verificació

Monitoratge

Plataforma

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

Visió general

Dues vies de producció

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

Advertències configurables

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

Comportament dels reintents (sessions de flux de treball)

Paràmetres configurables

Lògica de coincidència de noms

Exemples

Manipulació per superposició (Rebutjada per defecte)

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

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

Relacionat

Tipus d’advertència

​Visió general

​Dues vies de producció

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

​Advertències configurables

​Diferències de l’API independent (POST /v3/poa/)

​Comportament dels reintents (sessions de flux de treball)

​Paràmetres configurables

​Lògica de coincidència de noms

​Exemples

​Manipulació per superposició (Rebutjada per defecte)

​Document caducat + falta d’adreça (rebuig automàtic)

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

​Relacionat

​Tipus d’advertència

Visió general

Dues vies de producció

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

Advertències configurables

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

Comportament dels reintents (sessions de flux de treball)

Paràmetres configurables

Lògica de coincidència de noms

Exemples

Manipulació per superposició (Rebutjada per defecte)

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

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

Relacionat

Tipus d’advertència