Informe de comprovant de domicili: camps extrets

Visió general

La verificació de comprovant de domicili (POA) accepta un únic PDF o imatge (TIFF, JPG, JPEG, PNG, WEBP, opcionalment comprimit en ZIP) de fins a 15 MB, executa la classificació del tipus de document, l’extracció basada en LLM i l’anàlisi forense de PDF/EXIF, i retorna:

L’adreça extreta: tant en format brut com estructurat (street_1, city, region, postal_code, lat/lng).
Metadades del document: mida del fitxer, tipus de contingut, dates de creació i modificació, dates EXIF, informació de la signatura i qualsevol evidència de manipulació per superposició procedent de l’anàlisi forense del PDF.
Puntuacions de coincidència del nom respecte al document d’identitat verificat i respecte a les dades esperades proporcionades en crear la sessió.
Camps addicionals relacionats amb el banc (número de compte, IBAN, codi de classificació, número d’encaminament, SWIFT/BIC, sucursal) quan el document és un extracte bancari.

Captura de pantalla de l'informe de comprovant de domicili de Didit que mostra els camps d'adreça extrets i el tipus de document

L’extracció de POA realitza una lectura de text no estructurat, la qual cosa introdueix una latència de 5–15 segons per document. Els webhooks només s’activen quan es completa tot el pas del flux de treball; no facis sondeig de l’endpoint de decisió més sovint que cada 5 s durant aquest període.

On apareix a les respostes de l’API

L’endpoint de decisió retorna el POA com la matriu en plural poa_verifications[] a GET /v3/session/{sessionId}/decision/. Cada entrada és una execució del node de POA al teu flux de treball; les sessions amb diversos passos de POA (p. ex., extracte bancari + factura de serveis públics) produeixen una entrada per cada execució amb el seu propi node_id.

GET /v3/session/{sessionId}/decision/
  ──▶ { "poa_verifications": [ { node_id, status, document_type, poa_address, … }, … ] }

L’estructura següent reflecteix l’esquema canònic; consulta Models de dades.

Esquema

Consulta Comprovant de domicili a la referència de models de dades per veure l’esquema canònic.

interface POAV3 {
  status: 'Not Finished' | 'Approved' | 'Declined' | 'In Review';
  node_id: string | null;

  issuing_state: string | null;         // ISO 3166-1 alpha-3
  document_type:                        // never null — falls back to 'UNKNOWN'
    | 'UTILITY_BILL'
    | 'BANK_STATEMENT'
    | 'GOVERNMENT_ISSUED_DOCUMENT'
    | 'OTHER_POA_DOCUMENT'
    | 'UNKNOWN';
  document_subtype: string;             // e.g. 'ELECTRICITY_BILL', 'ACCOUNT_STATEMENT';
                                        // never null — falls back to 'UNKNOWN'
  issuer: string | null;
  issue_date: string | null;            // YYYY-MM-DD
  expiration_date: string | null;       // YYYY-MM-DD when present

  // Extracted address
  poa_address: string | null;           // raw, single-line
  poa_formatted_address: string | null; // geocoded/formatted
  poa_parsed_address: {
    address_type?: string;
    street_1?: string;
    street_2?: string;
    city?: string;
    region?: string;
    postal_code?: string;
    country?: string;                   // ISO 3166-1 alpha-2
    raw_results?: object;
    document_location?: { latitude: number; longitude: number };
  } | null;

  document_file: string | null;         // presigned URL, expires after ~4 hours
  document_language: string | null;     // ISO 639-1, e.g. 'en'
  name_on_document: string | null;

  // Expected details (when supplied at session creation)
  expected_details_address: string | null;
  expected_details_formatted_address: string | null;
  expected_details_parsed_address: object | null;

  // Match scores (float, 0-100)
  name_match_score_expected_details: number | null;
  name_match_score_id_verification: number | null;

  // PDF + image forensics
  document_metadata: {
    file_size: number | null;
    content_type: string | null;
    creation_date: string | null;
    modified_date: string | null;
    creator: string | null;
    producer: string | null;
    software: string | null;
    encryption: string | null;
    is_signed: boolean | null;
    is_tampered: boolean | null;
    signature_info: object | null;
    exif_original_date: string | null;
    exif_digitized_date: string | null;
    processed_by_known_editor: boolean | string | null;
    has_different_creation_mod_date: boolean | null;
    overlay_manipulation: {
      detected: boolean;
      analyzed: boolean;
      signals: string[];                // 'duplicate_font_subset', 'glyph_fragmentation'
      duplicate_font_subsets: object[];
      fragmented_fonts: object[];
      manipulated_regions: {
        page: number;
        x: number;
        y: number;
        width: number;
        height: number;
        page_width: number;
        page_height: number;
      }[];
    } | null;                           // null for non-PDF uploads or when not analyzed
  } | null;

  // Bank-related and custom fields
  extra_fields: {
    bank_account_number: string | null;
    bank_iban: string | null;
    bank_sort_code: string | null;
    bank_routing_number: string | null;
    bank_swift_bic: string | null;
    bank_branch_name: string | null;
    bank_branch_address: string | null;
    document_phone_number: string | null;
    additional_names: string[];
    [customField: string]: unknown;
  };

  extra_files: string[];                // presigned URLs for additional uploaded files

  // QR codes and barcodes
  detected_codes: {
    type: string;                       // 'QR_CODE', 'CODE_128', 'EAN_13', 'DATA_MATRIX', 'PDF_417', …
    page_number: number;                // 1-based
    position: [number, number][] | null;
    x: number | null;
    y: number | null;
    width: number | null;
    height: number | null;
    page_width: number;
    page_height: number;
    raw_payload: string;                // base64, empty string when unavailable
    parsed_payload: unknown | null;      // null when located but undecodable
  }[];

  warnings: Warning[];                  // see Data Models — Warning object
}

Cada entrada a warnings[] és un objecte d’advertència: { feature, risk, additional_data, log_type, short_description, long_description, node_id }, amb feature sempre fixat a "PROOF_OF_ADDRESS" per a aquest informe.

Valors d’estat

status utilitza l’enumeració d’estat a nivell de funcionalitat (FeatureStatusChoices).

Valor	Significat
`Not Finished`	El node de POA no s’ha completat per a aquesta sessió (estat per defecte).
`Approved`	El document s’ha analitzat correctament i cap advertència ha donat lloc a Rebuig o Revisió.
`In Review`	Com a mínim una advertència configurable està establerta en Revisió per al teu flux de treball (i res no s’ha rebutjat).
`Declined`	S’ha activat una advertència de rebuig directe (`MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`), o una advertència configurable està establerta en Rebutjar per al teu flux de treball.

Les regles d’estat personalitzades configurades al node del flux de treball poden ajustar encara més l’estat calculat; les regles es combinen amb la precedència Declined > In Review > Approved. Consulta Advertències del comprovant de domicili per a la correspondència completa de risc a acció, inclòs el comportament de reintent només per al flux de treball de FUTURE_ISSUE_DATE.

Evidència de manipulació per superposició en PDF

Quan el document enviat és un PDF, document_metadata.overlay_manipulation pot contenir evidència forense de possibles superposicions de text:

detected: true quan la comprovació ha trobat evidència de manipulació.
analyzed: true quan s’ha pogut analitzar el PDF.
analysis_incomplete: hi és i és true només quan el fitxer no s’ha pogut comprovar completament. Allò que s’ha comprovat conserva les seves conclusions on sigui possible, i el document genera POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT.
signals: les comprovacions que s’han activat (duplicate_font_subset, glyph_fragmentation).
manipulated_regions: rectangles en coordenades de pàgina que envolten el text possiblement editat. Cada rectangle utilitza l’espai de coordenades de pàgina del PDF (x, y, width, height, page_width, page_height), perquè els revisors puguin ressaltar l’àrea afectada en una vista prèvia del PDF.

El camp és null quan el document no és un PDF o quan el PDF no s’ha pogut analitzar. Quan detected=true, el sistema també emet un avís SUSPECTED_DOCUMENT_MANIPULATION l’additional_data del qual reflecteix els senyals i els rectangles anteriors (tret que hi hagi un senyal més fort —modificació després de la signatura digital, is_tampered=true—, que té prioritat; en aquest cas, additional_data descriu la manipulació de la signatura).

Codis QR i codis de barres

Cada informe de POA inclou detected_codes, que cobreix totes les pàgines processades. Cada element conté:

Camp	Descripció
`type`	Simbologia detectada, com ara `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX` o `PDF_417`
`page_number`	Número de pàgina, començant per 1
`position`	Polígon detectat en píxels de la pàgina renderitzada, o `null` quan no hi ha cap ubicació fiable disponible
`x`, `y`, `width`, `height`	Caixa delimitadora en píxels de la pàgina renderitzada, o `null` quan no hi ha cap ubicació fiable disponible
`page_width`, `page_height`	Dimensions de la pàgina renderitzada utilitzades per les coordenades
`parsed_payload`	Cadena descodificada o valor estructurat, o `null` quan el codi només es pot localitzar
`raw_payload`	Payload brut del descodificador com a cadena en base64 quan estigui disponible; en cas contrari, una cadena buida

detected_codes és un array buit quan no es troba cap codi compatible. Didit mai no endevina un payload: els codis danyats o il·legibles es poden retornar amb la seva ubicació i parsed_payload: null, mentre que els errors en la detecció de codis no fan fallar la verificació de POA.

Exemples

Aprovat — extracte bancari

{
  "poa_verifications": [
    {
      "status": "Approved",
      "node_id": "feature_poa_1",
      "issuing_state": "USA",
      "document_type": "BANK_STATEMENT",
      "document_subtype": "ACCOUNT_STATEMENT",
      "issuer": "National Bank",
      "issue_date": "2026-04-15",
      "expiration_date": null,
      "document_language": "en",
      "name_on_document": "John A. Smith",
      "poa_address": "123 Main St, Apartment 4B, New York, NY 10001",
      "poa_formatted_address": "123 Main St, Apartment 4B, New York, NY 10001, USA",
      "poa_parsed_address": {
        "address_type": "Street",
        "street_1": "123 Main St",
        "street_2": "Apartment 4B",
        "city": "New York",
        "region": "NY",
        "postal_code": "10001",
        "country": "US",
        "document_location": { "latitude": 40.7128, "longitude": -74.0060 }
      },
      "document_file": "https://<media-host>/.../poa.pdf?X-Amz-Expires=14400",
      "document_metadata": {
        "file_size": 246810,
        "content_type": "application/pdf",
        "creation_date": "2026-04-15",
        "modified_date": "2026-04-15",
        "creator": "PDFKit",
        "producer": "Quartz",
        "software": null,
        "encryption": null,
        "is_signed": false,
        "is_tampered": false,
        "signature_info": null,
        "exif_original_date": null,
        "exif_digitized_date": null,
        "processed_by_known_editor": false,
        "has_different_creation_mod_date": false,
        "overlay_manipulation": null
      },
      "name_match_score_expected_details": 100,
      "name_match_score_id_verification": 98,
      "expected_details_address": null,
      "expected_details_formatted_address": null,
      "expected_details_parsed_address": null,
      "extra_fields": {
        "bank_account_number": "****1234",
        "bank_iban": null,
        "bank_sort_code": null,
        "bank_routing_number": "021000089",
        "bank_swift_bic": "NABNUS33",
        "bank_branch_name": "Manhattan Midtown",
        "bank_branch_address": "111 Wall St, New York, NY",
        "document_phone_number": null,
        "additional_names": []
      },
      "extra_files": [],
      "detected_codes": [
        {
          "type": "QR_CODE",
          "page_number": 1,
          "position": [[820, 1120], [1002, 1120], [1002, 1302], [820, 1302]],
          "x": 820,
          "y": 1120,
          "width": 182,
          "height": 182,
          "page_width": 1190,
          "page_height": 1684,
          "raw_payload": "aHR0cHM6Ly9uYXRpb25hbGJhbmsuZXhhbXBsZS9zdG10Lzk5ODE=",
          "parsed_payload": "https://nationalbank.example/stmt/9981"
        },
        {
          "type": "CODE_128",
          "page_number": 1,
          "position": [[112, 1480], [560, 1480], [560, 1540], [112, 1540]],
          "x": 112,
          "y": 1480,
          "width": 448,
          "height": 60,
          "page_width": 1190,
          "page_height": 1684,
          "raw_payload": "MDAxMjM0NTY3ODk=",
          "parsed_payload": "001234567 89"
        }
      ],
      "warnings": []
    }
  ]
}

Rebutjat — manipulació per superposició + discordança de nom

{
  "poa_verifications": [
    {
      "status": "Declined",
      "node_id": "feature_poa_1",
      "issuing_state": "GBR",
      "document_type": "UTILITY_BILL",
      "document_subtype": "ELECTRICITY_BILL",
      "issuer": "BritishEnergy",
      "issue_date": "2026-03-10",
      "expiration_date": null,
      "document_language": "en",
      "name_on_document": "JOHN B SMYTH",
      "poa_address": "44 King's Road, London, SW3 4UD",
      "poa_formatted_address": "44 King's Road, London, SW3 4UD, United Kingdom",
      "poa_parsed_address": {
        "street_1": "44 King's Road",
        "city": "London",
        "postal_code": "SW3 4UD",
        "country": "GB",
        "document_location": { "latitude": 51.4880, "longitude": -0.1690 }
      },
      "document_file": "https://<media-host>/.../poa.pdf?X-Amz-Expires=14400",
      "document_metadata": {
        "file_size": 412910,
        "content_type": "application/pdf",
        "creation_date": "2026-03-10",
        "modified_date": "2026-05-12",
        "creator": "Adobe Acrobat Pro",
        "producer": "Adobe PDF Library",
        "software": "Adobe Acrobat",
        "encryption": null,
        "is_signed": false,
        "is_tampered": false,
        "signature_info": null,
        "exif_original_date": null,
        "exif_digitized_date": null,
        "processed_by_known_editor": false,
        "has_different_creation_mod_date": true,
        "overlay_manipulation": {
          "detected": true,
          "analyzed": true,
          "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 }
          ]
        }
      },
      "name_match_score_expected_details": 62,
      "name_match_score_id_verification": 60,
      "expected_details_address": null,
      "expected_details_formatted_address": null,
      "expected_details_parsed_address": null,
      "extra_fields": {
        "bank_account_number": null, "bank_iban": null, "bank_sort_code": null,
        "bank_routing_number": null, "bank_swift_bic": null,
        "bank_branch_name": null, "bank_branch_address": null,
        "document_phone_number": null, "additional_names": []
      },
      "extra_files": [],
      "detected_codes": [],
      "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"
        },
        {
          "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

Advertències del comprovant de domicili — tots els codis d’advertència que pot emetre el POA
Visió general del comprovant de domicili — tipus de documents acceptats i regles de verificació
Models de dades — Comprovant de domicili — esquema canònic
Webhooks — status.updated transmet els payloads de POA

document_file i extra_files[] són URL presignades que caduquen al cap d’unes 4 hores. Torna a cridar l’endpoint de decisió per actualitzar les URL. Emmagatzema només l’estat de verificació i els camps d’adreça analitzats als teus sistemes; minimitza les dades de documents retingudes.

Autenticació

Verificació

Monitoratge

Plataforma

Informe de comprovant de domicili: camps extrets

Visió general

On apareix a les respostes de l’API

Esquema

Valors d’estat

Evidència de manipulació per superposició en PDF

Codis QR i codis de barres

Exemples

Aprovat — extracte bancari

Rebutjat — manipulació per superposició + discordança de nom

Relacionat

​Visió general

​On apareix a les respostes de l’API

​Esquema

​Valors d’estat

​Evidència de manipulació per superposició en PDF

​Codis QR i codis de barres

​Exemples

​Aprovat — extracte bancari

​Rebutjat — manipulació per superposició + discordança de nom

​Relacionat

Visió general

On apareix a les respostes de l’API

Esquema

Valors d’estat

Evidència de manipulació per superposició en PDF

Codis QR i codis de barres

Exemples

Aprovat — extracte bancari

Rebutjat — manipulació per superposició + discordança de nom

Relacionat