> ## 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. # API de comprovant de domicili: verificació POA i OCR > Didit verifica comprovants de domicili via POST /v3/poa/: factures, extractes i contractes. OCR i detecció de falsificacions, sense contractes. ## OpenAPI ````yaml ca/openapi-25.json POST /v3/poa/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de verificació d'identitat. Autentica't amb la capçalera x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/poa/: post: tags: - Standalone APIs summary: Comprovant de domicili (OCR de documents + comprovacions d'adreça) description: >- Extreu i valida un document de comprovant de domicili —factures de serveis bàsics, extractes bancaris i documents emesos pel govern— en una sola crida. Retorna l'emissor, les dates d'emissió/caducitat, el nom del titular, l'adreça sense processar i analitzada/geocodificada, un `status` d'`Approved`/`Declined` i una llista de `warnings` que explica cada incidència trobada. **Latència.** L'extracció es basa en LLM: les crides habituals triguen entre **5 i 15 segons**, i els PDF de diverses pàgines fins a **~30 segons**. Configura un temps d'espera del client d'**almenys 45 segons** i no reintentis abans que la crida hagi finalitzat. **Com funciona.** El document (imatge o PDF, de fins a 15 MB; els PDF xifrats requereixen `document_password`) es classifica en un tipus i subtipus de document (p. ex., `UTILITY_BILL` / `WATER_BILL`), i l'emissor, les dates, el nom del titular i l'adreça s'extreuen mitjançant una extracció basada en LLM. L'adreça s'analitza i es geocodifica a `poa_parsed_address`. L'anàlisi forense de PDF/EXIF examina possibles manipulacions —modificació després de la signatura digital, editors de PDF coneguts, manipulació de text superposat, reexportacions sospitoses— i mostra `SUSPECTED_DOCUMENT_MANIPULATION` o `DOCUMENT_METADATA_MISMATCH`. Un camp de text que s'ha esborrat i s'ha tornat a escriure amb una altra font, on el propi fitxer no conté proves de si el seu contingut ha canviat, mostra `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT`. L'antiguitat del document es valida respecte a `poa_document_age_months`, i l'idioma respecte a `poa_languages_allowed`. Si proporciones `expected_address`, `expected_country` o `expected_first_name`/`expected_last_name`, els valors extrets es contrasten i s'assenyalen les discrepàncies. **Lògica de decisió.** `status` és `Approved` tret que com a mínim una advertència provoqui un rebuig. Els errors greus sempre el rebutgen: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, a més d'`UNABLE_TO_EXTRACT_ISSUE_DATE` i `POA_NAME_NOT_DETECTED` (no configurables en aquest endpoint). Cinc grups de risc són configurables per sol·licitud mitjançant les opcions `poa_*_action` (`DECLINE` o `NO_ACTION`, totes amb `DECLINE` com a valor predeterminat). `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` i `UNPARSABLE_OR_INVALID_ADDRESS` són informatius en aquest endpoint i mai no rebutgen. Un document que no es pugui processar en absolut retorna `400`; un document llegible però problemàtic retorna `200` amb `status: "Declined"` —inspecciona sempre `poa.status` i `poa.warnings`, no només el codi HTTP. **Facturació.** Cada resposta `200` consumeix un crèdit d'API de Comprovant de domicili (pagat des del crèdit del teu pla o saldo de recàrrega). Quan el saldo de l'organització no pugui cobrir la crida, l'endpoint retorna `403` amb l'error de crèdits insuficients abans de processar cap document. **Persistència de la sessió (`save_api_request`, per defecte `true`).** Quan és `true`, la crida es desa com una sessió de tipus API: apareix a la Business Console, el document pujat s'emmagatzema, el `request_id` retornat és un ID de sessió real que pots passar a `GET /v3/session/{sessionId}/decision/` (la decisió exposa addicionalment `document_file` i l'anàlisi forense de `document_metadata`, que aquesta resposta omet) i s'emet un webhook `status.updated`. Quan és `false`, no s'emmagatzema res i `request_id` és un UUID de correlació d'un sol ús que no es pot consultar posteriorment. **Sandbox.** Les claus d'API de sandbox ometen tot el processament i la facturació: després de validar la sol·licitud (l'entrada amb format incorrecte continua retornant `400`), l'endpoint retorna un payload simulat estàtic `Approved` (una factura d'electricitat fictícia de «Sandbox Power Co.»), no es desa cap sessió i no es consumeixen crèdits. **Autenticació.** Envia la clau d'API de la teva aplicació a la capçalera `x-api-key`. Les credencials absents o no vàlides retornen `403` (`{"detail": "You do not have permission to perform this action."}`) —aquesta API mai no retorna `401`. **Límit de freqüència.** Pressupost compartit d'escriptura de 300 sol·licituds/min per clau d'API entre tots els endpoints POST/PATCH/DELETE; si se supera, es retorna `429`. Nota: `FUTURE_ISSUE_DATE` i `POOR_DOCUMENT_QUALITY` existeixen a les sessions de flux de treball, però mai no es generen en aquest endpoint independent —aquí un document amb data futura no es rebutja automàticament. operationId: post_v3poa parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - document properties: document: type: string format: binary description: >- El document de comprovant de domicili. Extensions permeses: `tiff`, `jpg`, `jpeg`, `png`, `pdf`, `webp`. Mida màxima de càrrega: **15 MB** (els fitxers més grans es rebutgen amb `400`). S'admeten PDF multipàgina (espera una latència més alta); els PDF xifrats requereixen `document_password`. Les imatges es comprimeixen automàticament abans de processar-les. document_password: type: string description: >- Contrasenya per desxifrar `document` quan és un PDF xifrat. Enviar un PDF xifrat sense contrasenya (o amb una d'incorrecta) retorna `400`. writeOnly: true expected_address: type: string description: >- Adreça a verificar en comparació amb el document. Es geocodifica i es compara amb l'adreça extreta; una discrepància (o una adreça esperada que no es pot geocodificar/verificar) afegeix `ADDRESS_MISMATCH_WITH_PROVIDED`, regit per `poa_address_mismatch_action`. La forma geocodificada es retorna a `expected_details_formatted_address` / `expected_details_parsed_address`. example: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: type: string description: >- País per verificar respecte al document (codi ISO 3166-1, p. ex. `ARG` o `AR`). Una discrepància amb el país del document afegeix `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, regit per `poa_address_mismatch_action`. example: ARG expected_first_name: type: string description: >- Nom de pila a verificar respecte a `name_on_document` (coincidència difusa, compatible amb transliteració). Una puntuació inferior al llindar de coincidència afegeix `NAME_MISMATCH_WITH_PROVIDED`, regit per `poa_address_mismatch_action`. example: Sophia expected_last_name: type: string description: >- Cognom a verificar contra `name_on_document`, combinat amb `expected_first_name` per a la puntuació de coincidència. example: Martinez poa_languages_allowed: type: string description: >- Llista separada per comes dels idiomes de documents acceptats com a codis ISO 639-1 (p. ex. `en,es,fr`). Quan s'omet o es deixa en blanc, s'accepten **tots 51 idiomes admesos**. Un document en un idioma que no sigui a la llista afegeix `UNSUPPORTED_DOCUMENT_LANGUAGE` (regit per `poa_unsupported_language_action`); un codi desconegut a la llista retorna `400` amb el conjunt complet de codis admesos. example: en,es poa_document_age_months: type: string description: >- Parells `key:value` separats per comes que estableixen l'antiguitat màxima del document en mesos per tipus de document — claus: `utility_bill`, `bank_statement`, `government_issued_document`, `other_poa_document`; valors: `1`–`120`, o `-1` per a il·limitat (sense comprovació d'antiguitat). Valors per defecte si s'omet: `utility_bill:3,bank_statement:3,government_issued_document:12,other_poa_document:12`. Un document més antic que el seu límit es rebutja amb `POA_DOCUMENT_EXPIRED`. **Atenció:** quan proporcionis aquest camp, llista *tots* els tipus que acceptes — els tipus omesos es tracten com a no acceptats (informatiu `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`) i s'omet la seva comprovació d'antiguitat. example: utility_bill:3,bank_statement:6 poa_name_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- S'accepta però **actualment no s'aplica**: les advertències de discordança de nom (`NAME_MISMATCH_WITH_PROVIDED`) segueixen `poa_address_mismatch_action`. Defineix `poa_address_mismatch_action` per controlar el comportament de discordança tant de nom com d'adreça. poa_document_issues_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Què fer davant de problemes d'integritat del fitxer — a la pràctica, aquest endpoint només produeix `DOCUMENT_METADATA_MISMATCH`. poa_document_authenticity_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Què fer quan se sospita de manipulació del document (`SUSPECTED_DOCUMENT_MANIPULATION`) — p. ex., el PDF s'ha modificat després de la signatura digital, s'ha processat amb un editor de PDF conegut, mostra manipulació de text superposat o té dates EXIF incoherents. També regeix `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (un camp de text reescrit que el fitxer no pot demostrar si ha canviat o no): `DECLINE` també el rebutja, `NO_ACTION` el manté com a advertència. poa_unsupported_language_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Què fer quan l'idioma del document està fora de `poa_languages_allowed` (`UNSUPPORTED_DOCUMENT_LANGUAGE`). poa_address_mismatch_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Què fer quan les dades extretes no coincideixen amb els camps `expected_*`: `ADDRESS_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_WITH_PROVIDED` i `POA_COUNTRY_MISMATCH_WITH_PROVIDED` segueixen tots aquesta acció. poa_issuer_not_identified_action: type: string enum: - DECLINE - NO_ACTION default: DECLINE description: >- Què fer quan no es pot identificar cap empresa/organització emissora al document (`ISSUER_NOT_IDENTIFIED`). save_api_request: type: boolean default: true description: >- Quan és `true` (per defecte), manté la crida com una sessió de tipus API — visible a la Business Console, recuperable mitjançant `GET /v3/session/{sessionId}/decision/` utilitzant el `request_id` retornat, anunciada a través d'un webhook `status.updated` i amb el document carregat emmagatzemat. Quan és `false`, no s'emmagatzema res i `request_id` és un UUID transitori només per a la correlació de la resposta. example: true vendor_data: type: string description: >- Cadena opaca opcional (el teu ID d'usuari intern, correu electrònic, UUID…) desada a la sessió persistent i retornada a la resposta. Utilitza-la per correlacionar crides a l'API amb els teus propis registres i per filtrar sessions més endavant. example: user-123 metadata: type: object additionalProperties: true description: >- Objecte JSON opcional emmagatzemat amb la sessió (quan `save_api_request=true`) i retornat a la resposta. En sol·licituds multipart, envia'l com a camp de cadena codificat en JSON (p. ex., `metadata={"flow":"onboarding"}`); s'analitza com un objecte. example: flow: onboarding example: document: (binary JPEG/PNG/PDF of the utility bill or bank statement) expected_address: Av. Monseñor Tavella 1291, Salta, Argentina expected_country: ARG expected_first_name: Sophia expected_last_name: Martinez poa_languages_allowed: en,es save_api_request: true vendor_data: user-123 responses: '200': description: >- Document processat. `poa.status` és `Approved` o `Declined`; cada problema detectat es detalla a `poa.warnings`. Un document caducat, no coincident o sospitós continua retornant `200` amb `status: "Declined"`; inspecciona el cos, no només el codi HTTP. Quan `save_api_request=true`, `request_id` és l'id de sessió persistit. content: application/json: examples: Approved: summary: >- Factura de serveis llegida correctament, sense comprovacions dels detalls esperats value: request_id: 4b523a8d-ed32-45e4-8aa8-a89eda459d88 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2026-04-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. 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: - LA EMBOTELLADORA DEL NORTE SA 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: >- aHR0cHM6Ly9hZ3Vhc2RlbG5vcnRlLmNvbS9mYWN0dXJhLzk5ODgxMQ== parsed_payload: https://aguasdelnorte.com/factura/998811 - 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: MDA5OTg4MTEwMDA0Mg== parsed_payload: '0099881100042' status: Approved warnings: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:29:02.439655+00:00' Declined - document too old: summary: >- Data d'emissió anterior a la permesa per `poa_document_age_months` value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. 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: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: POA_DOCUMENT_EXPIRED feature: PROOF_OF_ADDRESS additional_data: expiration_reason: age_window max_age_months: 3 document_subtype: WATER_BILL document_type: UTILITY_BILL issue_date: '2021-02-10' 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. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:23:02.165493+00:00' Declined - name mismatch: summary: >- `expected_first_name`/`expected_last_name` no coincideixen amb `name_on_document` value: request_id: 0a7f2f9c-58f1-4b8e-b1e3-2f6f9d4f7a21 poa: issuing_state: ARG document_type: UTILITY_BILL document_subtype: WATER_BILL document_language: es issuer: Aguas del Norte issue_date: '2021-02-10' expiration_date: null poa_address: >- AVDA. MONSEÑOR TAVELLA N° 1291, B° VILLA LAVALLE CP: 4400, CAPITAL - SALTA poa_formatted_address: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: street_1: Avenida Monseñor Tavella 1291 street_2: b city: Salta region: Salta country: AR postal_code: A4400 document_location: latitude: -24.8208682 longitude: -65.4130954 expected_details_address: null expected_details_formatted_address: null expected_details_parsed_address: null name_on_document: OESTE EMBOTELLADORA S.A. 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: - LA EMBOTELLADORA DEL NORTE SA status: Declined warnings: - risk: NAME_MISMATCH_WITH_PROVIDED feature: PROOF_OF_ADDRESS additional_data: null log_type: error short_description: Name mismatch with provided information long_description: >- The full name on the document does not match the name from the user's verified identity documents, or the full name sent by API. vendor_data: user-123 metadata: null created_at: '2026-06-12T02:27:21.330172+00:00' schema: type: object properties: request_id: type: string format: uuid description: >- ID de sessió persistida quan `save_api_request=true` (utilitzable amb `GET /v3/session/{sessionId}/decision/`); en cas contrari, un UUID de correlació transitori. poa: type: object properties: status: type: string enum: - Approved - Declined description: >- `Approved` quan cap advertència no es resol en un rebuig; `Declined` en cas contrari — la llista `warnings` n'explica el motiu. issuing_state: type: string nullable: true description: >- País on s'ha emès el document, segons s'ha extret del document — normalment ISO 3166-1 alpha-3 (p. ex. `ARG`). example: ARG document_type: type: string enum: - UTILITY_BILL - BANK_STATEMENT - GOVERNMENT_ISSUED_DOCUMENT - OTHER_POA_DOCUMENT - UNKNOWN description: >- Categoria del document detectada. `UNKNOWN` significa que el document no s'ha pogut classificar com un Comprovant de domicili acceptable i es rebutja automàticament amb `INVALID_DOCUMENT_TYPE`. Mai és null: els errors de classificació es resolen com a `UNKNOWN`. document_subtype: type: string description: >- Classificació més detallada dins de `document_type` — p. ex. `ELECTRICITY_BILL`, `WATER_BILL`, `GAS_BILL`, `INTERNET_BILL`, `PHONE_BILL` (factures de serveis bàsics); `ACCOUNT_STATEMENT`, `CREDIT_CARD_STATEMENT` (extractes bancaris); `TAX_ASSESSMENT`, `RESIDENCY_CERTIFICATE` (documents oficials). `UNKNOWN` quan no s'ha pogut determinar cap subtipus. Mai és nul — les fallades de classificació passen per defecte a `UNKNOWN`. example: WATER_BILL document_language: type: string nullable: true description: Idioma del document detectat (ISO 639-1). example: es issuer: type: string nullable: true description: >- Empresa o organització que ha emès el document. `null` afegeix `ISSUER_NOT_IDENTIFIED`. example: Aguas del Norte issue_date: type: string format: date nullable: true description: >- Data d'emissió del document (`YYYY-MM-DD`). `null` quan no s'ha pogut extreure; això fa que es rebutgi amb `UNABLE_TO_EXTRACT_ISSUE_DATE` en aquest endpoint. example: '2021-02-10' expiration_date: type: string format: date nullable: true description: >- Data explícita de caducitat/validesa impresa al document, si n'hi ha. Independent de la comprovació d'antiguitat `poa_document_age_months`. poa_address: type: string nullable: true description: >- Adreça exactament com està impresa al document. `null` fa que es rebutgi automàticament amb `MISSING_ADDRESS_INFORMATION`. poa_formatted_address: type: string nullable: true description: Versió geocodificada i normalitzada de `poa_address`. example: Av. Monseñor Tavella 1291 b, A4400 Salta, Argentina poa_parsed_address: type: object nullable: true description: >- Desglossament estructurat i geocodificat de l'adreça del document. `null` quan no s'ha pogut analitzar l'adreça. properties: street_1: type: string nullable: true example: Avenida Monseñor Tavella 1291 street_2: type: string nullable: true city: type: string nullable: true example: Salta region: type: string nullable: true example: Salta country: type: string nullable: true description: Codi de país ISO 3166-1 alfa-2. example: AR postal_code: type: string nullable: true example: A4400 document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: >- Coordenades geocodificades de l'adreça del document. expected_details_address: type: string nullable: true description: >- Ressò de l'`expected_address` que has enviat, o `null`. expected_details_formatted_address: type: string nullable: true description: >- Versió geocodificada i normalitzada de `expected_address`; `null` quan no s'ha proporcionat o no es pot geocodificar. expected_details_parsed_address: type: object nullable: true additionalProperties: true description: >- Resultat complet de geocodificació per a `expected_address` (carrer/ciutat/regió/país/codi postal més la sortida en brut del geocodificador i un indicador `is_verified`). `null` quan no s'ha proporcionat `expected_address`. name_on_document: type: string nullable: true description: >- Nom del titular principal extret del document; es compara amb `expected_first_name`/`expected_last_name` quan es proporcionen. Si és `null`, es rebutja amb `POA_NAME_NOT_DETECTED` en aquest endpoint. example: OESTE EMBOTELLADORA S.A. extra_fields: type: object description: >- Camps addicionals específics del document. Els camps bancaris s'emplenen per a extractes bancaris quan estan impresos al document; `null` en cas contrari. properties: bank_account_number: type: string nullable: true bank_iban: type: string nullable: true bank_sort_code: type: string nullable: true bank_routing_number: type: string nullable: true bank_swift_bic: type: string nullable: true bank_branch_name: type: string nullable: true bank_branch_address: type: string nullable: true document_phone_number: type: string nullable: true description: Número de telèfon de contacte imprès al document. additional_names: type: array items: type: string description: >- Altres noms de titulars trobats al document (p. ex., cotitulars del compte, noms anteriors del compte). warnings: type: array description: >- Buit en cas d'aprovació neta. Cada entrada explica un risc detectat; les entrades amb `log_type: "error"` estableixen `status` a `Declined`. items: type: object properties: risk: type: string description: >- Codi de risc llegible per màquina. Rebuig automàtic: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, a més de `UNABLE_TO_EXTRACT_ISSUE_DATE` i `POA_NAME_NOT_DETECTED` (fixats per rebutjar en aquest endpoint). Regulats per opcions de la sol·licitud: `NAME_MISMATCH_WITH_PROVIDED` / `ADDRESS_MISMATCH_WITH_PROVIDED` / `POA_COUNTRY_MISMATCH_WITH_PROVIDED` (`poa_address_mismatch_action`), `POOR_DOCUMENT_QUALITY` (mai generat per aquest endpoint) / `DOCUMENT_METADATA_MISMATCH` (`poa_document_issues_action`), `SUSPECTED_DOCUMENT_MANIPULATION` i `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` (`poa_document_authenticity_action`), `UNSUPPORTED_DOCUMENT_LANGUAGE` (`poa_unsupported_language_action`), `ISSUER_NOT_IDENTIFIED` (`poa_issuer_not_identified_action`). Informatius en aquest endpoint: `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNPARSABLE_OR_INVALID_ADDRESS`. example: POA_DOCUMENT_EXPIRED feature: type: string enum: - PROOF_OF_ADDRESS description: >- Funcionalitat que ha generat l'advertència. Sempre `PROOF_OF_ADDRESS` en aquest endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Context addicional per a alguns riscos —p. ex. `POA_DOCUMENT_EXPIRED` inclou `expiration_reason` (`printed_expiration` o `age_window`), `document_type`, `document_subtype` i `issue_date`, a més d'`expiration_date` a la ruta `printed_expiration` o `max_age_months` a la ruta `age_window`; `SUSPECTED_DOCUMENT_MANIPULATION` inclou `reason` i `detection_method`; `POA_DOCUMENT_UNPROVEN_TEXT_REPLACEMENT` inclou `reason`, `detection_method` (`unproven_text_replacement`), `replaced_text`, `manipulated_regions` i `manipulated_blocks`. `null` per a la majoria dels riscos. log_type: type: string enum: - error - information description: >- Gravetat. Les advertències `error` canvien `status` a `Declined`; les entrades `information` són consultives i mai no rebutgen per si soles. (`warning` no es produeix en aquest endpoint; les seves opcions només accepten `DECLINE` o `NO_ACTION`.) short_description: type: string description: >- Resum d'una sola línia del risc, llegible per a humans. long_description: type: string description: Explicació fàcil de llegir del risc. detected_codes: type: array description: >- Codis QR i codis de barres detectats a totes les pàgines processades del document. Buit quan no se'n troba cap. Un codi QR localitzat però no descodificable té `parsed_payload: null`. items: $ref: '#/components/schemas/DocumentAIDetectedCode' vendor_data: type: string nullable: true description: Ressò de les `vendor_data` que has enviat, o `null`. metadata: type: object nullable: true additionalProperties: true description: Ressò de l'objecte `metadata` que has enviat, o `null`. created_at: type: string format: date-time description: >- Marca de temps ISO 8601 (UTC) de quan s'ha generat la resposta. '400': description: >- Error de validació o de processament. Els problemes a nivell de camp retornen l'embolcall estàndard de DRF (un array de missatges per camp afectat). Els problemes de PDF xifrats retornen `{"detail": ...}`. Un document que el procés d'extracció no pot processar retorna `{"error": ["Error extracting POA information"]}`. content: application/json: examples: Missing document: summary: '`document` no s''ha inclòs a les dades del formulari' value: document: - No file was submitted. Unsupported file extension: summary: >- Extensió de fitxer no permesa (només tiff/jpg/jpeg/png/pdf/webp) value: document: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, pdf, webp. File too large: summary: La pujada supera el límit de 15 MB value: document: - File size should not exceed 15 MB Encrypted PDF: summary: PDF pujat sense la contrasenya requerida value: detail: >- The PDF is encrypted. Please upload a decrypted PDF or a photo instead. Wrong PDF password: summary: '`document_password` no desxifra el PDF' value: detail: >- The PDF password is incorrect. Please provide the correct password. Invalid language code: summary: '`poa_languages_allowed` conté un codi no admès' value: poa_languages_allowed: - >- Invalid language code: 'xx'. Must be one of the supported languages: ['ar', 'bn', 'hy', 'bg', 'bs', 'ca', 'cnr', 'sq', 'zh', 'hr', 'cs', 'da', 'nl', 'en', 'et', 'fi', 'fr', 'ka', 'kk', 'de', 'el', 'he', 'hi', 'hu', 'id', 'it', 'ja', 'ko', 'ky', 'lv', 'lt', 'mk', 'mn', 'ms', 'no', 'fa', 'pl', 'pt', 'ro', 'ru', 'sr', 'sk', 'sl', 'so', 'es', 'sv', 'th', 'tr', 'uk', 'uz', 'vi']. Invalid document age value: summary: Valor de `poa_document_age_months` fora de 1–120 / -1 value: poa_document_age_months: - >- Invalid integer value for 'utility_bill': '999'. Must be -1 (unlimited) or a positive integer between 1 and 120. Extraction failure: summary: >- El document no s'ha pogut processar mitjançant el pipeline d'extracció value: error: - Error extracting POA information '403': description: >- Permís denegat. Es retorna quan falta la capçalera `x-api-key`, i també quan el saldo de l'organització que fa la crida no pot cobrir la crida; una clau incorrecta, revocada o caducada retorna `401`. Si falta la clau es retorna `403` amb `{"detail": ...}`; una clau incorrecta, revocada o caducada retorna `401`. La manca de crèdit retorna `403` amb `{"error": ...}` abans que es produeixi cap processament de documents. content: application/json: examples: Missing or invalid API key: summary: >- Sense capçalera `x-api-key`, o la clau no és vàlida/s'ha revocat value: detail: You do not have permission to perform this action. Not enough credits: summary: El saldo de l'organització no pot cobrir la crida value: error: >- You don't have enough credits to perform this request. Please top up at https://business.didit.me '429': description: >- S'ha superat el límit de freqüència. Els endpoints POST/PATCH/DELETE comparteixen un pressupost de 300 sol·licituds d'escriptura per minut per clau d'API (la creació de transaccions i la ingesta d'esdeveniments tenen un pressupost independent de 600). La resposta inclou les capçaleres `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` i `Retry-After`. content: application/json: examples: Write rate limit exceeded: summary: Més de 300 sol·licituds d'escriptura en el minut actual value: detail: >- Write request rate limit exceeded. You can make up to 300 requests per minute. schema: type: object properties: detail: type: string '503': $ref: '#/components/responses/DocumentProcessingBusy' security: - ApiKeyAuth: [] x-codeSamples: - lang: curl label: cURL source: |- curl -X POST 'https://verification.didit.me/v3/poa/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'document=@./utility-bill.pdf' \ -F 'expected_address=Av. Monseñor Tavella 1291, Salta, Argentina' \ -F 'expected_country=ARG' \ -F 'expected_first_name=Sophia' \ -F 'expected_last_name=Martinez' \ -F 'poa_languages_allowed=en,es' \ -F 'vendor_data=user-123' \ --max-time 45 - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.proof_of_address.verify( document=open("document.pdf", "rb"), expected_address="Av. Monseñor Tavella 1291, Salta, Argentina", expected_country="ARG", expected_first_name="Sophia", expected_last_name="Martinez", poa_languages_allowed="en,es", save_api_request=True, vendor_data="user-123", ) print(result) - lang: javascript label: Node.js source: |- import Didit, { fileFromPath } from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.proofOfAddress.verify({ document: await fileFromPath("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.ProofOfAddress.Verify(ctx, didit.ProofOfAddressVerifyParams{\n\tDocument: didit.FileFromPath(\"document.pdf\"),\n\tExpectedAddress: didit.String(\"Av. Monseñor Tavella 1291, Salta, Argentina\"),\n\tExpectedCountry: didit.String(\"ARG\"),\n\tExpectedFirstName: didit.String(\"Sophia\"),\n\tExpectedLastName: didit.String(\"Martinez\"),\n\tPOALanguagesAllowed: didit.String(\"en,es\"),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import java.nio.file.Path; import me.didit.Didit; import me.didit.types.ProofOfAddressVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.proofOfAddress().verify(ProofOfAddressVerifyParams.builder() .document(Path.of("document.pdf")) .expectedAddress("Av. Monseñor Tavella 1291, Salta, Argentina") .expectedCountry("ARG") .expectedFirstName("Sophia") .expectedLastName("Martinez") .poaLanguagesAllowed("en,es") .saveApiRequest(true) .vendorData("user-123") .build()); System.out.println(result); - lang: php label: PHP source: |- proofOfAddress->verify([ 'document' => File::fromPath('document.pdf'), 'expected_address' => 'Av. Monseñor Tavella 1291, Salta, Argentina', 'expected_country' => 'ARG', 'expected_first_name' => 'Sophia', 'expected_last_name' => 'Martinez', 'poa_languages_allowed' => 'en,es', 'save_api_request' => true, 'vendor_data' => 'user-123', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.proof_of_address.verify( document: Pathname("document.pdf"), expected_address: "Av. Monseñor Tavella 1291, Salta, Argentina", expected_country: "ARG", expected_first_name: "Sophia", expected_last_name: "Martinez", poa_languages_allowed: "en,es", save_api_request: true, vendor_data: "user-123" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.ProofOfAddress.VerifyAsync(new ProofOfAddressVerifyParams { Document = FileUpload.FromPath("document.pdf"), ExpectedAddress = "Av. Monseñor Tavella 1291, Salta, Argentina", ExpectedCountry = "ARG", ExpectedFirstName = "Sophia", ExpectedLastName = "Martinez", PoaLanguagesAllowed = "en,es", SaveApiRequest = true, VendorData = "user-123", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: DocumentAIDetectedCode: type: object required: - type - page_number - position - x - 'y' - width - height - page_width - page_height - raw_payload - parsed_payload properties: type: type: string description: >- Simbologia detectada, per exemple `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX` o `PDF_417`. page_number: type: integer minimum: 1 description: Número de pàgina, començant per 1. position: type: array nullable: true description: >- Polígon detectat en coordenades de píxels de la pàgina renderitzada. `null` quan no hi ha cap ubicació fiable disponible. items: type: array minItems: 2 maxItems: 2 items: type: integer x: type: integer nullable: true description: >- Vora esquerra del quadre delimitador en píxels de la pàgina renderitzada. 'y': type: integer nullable: true description: >- Vora superior del quadre delimitador en píxels de la pàgina renderitzada. width: type: integer nullable: true description: Amplària del quadre delimitador en píxels de la pàgina renderitzada. height: type: integer nullable: true description: Alçària del quadre delimitador en píxels de la pàgina renderitzada. page_width: type: integer description: Amplària de la pàgina renderitzada en píxels. page_height: type: integer description: Alçària de la pàgina renderitzada en píxels. raw_payload: type: string description: >- Payload del descodificador en brut com a cadena en base64 quan estigui disponible; en cas contrari, una cadena buida. parsed_payload: nullable: true description: >- Cadena descodificada o valor estructurat. `null` quan el codi s'ha localitzat però no s'ha pogut descodificar. responses: DocumentProcessingBusy: description: >- Ara mateix s'estan processant massa documents, de manera que aquesta càrrega no s'ha processat: no s'ha emmagatzemat res i no s'ha consumit cap intent. Torna a enviar el mateix fitxer després del nombre de segons indicat a `Retry-After`. Bifurca segons `code`, no segons el text del missatge. headers: Retry-After: description: >- Nombre de segons que cal esperar abans de tornar a enviar la mateixa sol·licitud. schema: type: integer example: 10 content: application/json: schema: type: object required: - detail - code properties: detail: type: string code: type: string enum: - document_processing_busy example: detail: We are busy processing documents. Please try again in a moment. code: document_processing_busy securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.