> ## 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 verificació d'identitat: OCR i autenticitat > Verifica documents d'identitat amb Didit en 220+ països i 14,000+ tipus. Autenticitat, OCR, MRZ, inferència sub-2s, preu per ús i sense contractes. ## OpenAPI ````yaml ca/openapi-25.json POST /v3/id-verification/ 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/id-verification/: post: tags: - Standalone APIs summary: Verificació d'identitat (OCR del document + comprovacions de frau) description: >- Aplica l'OCR a un document d'identitat i executa controls de frau documental en una sola crida: retorna els camps extrets del titular, la MRZ analitzada, un `status` `Approved`/`Declined`/`In Review` i una llista de `warnings` que explica cada problema detectat. Admet 14,000+ tipus de documents de 220+ països i territoris. **Com funciona.** Envia la `front_image` del document (obligatòria) i, en el cas de documents de dues cares, la `back_image`. Puja fotografies sense retallar on siguin visibles les quatre cantonades del document; el servei mateix detecta, alinea i retalla el document, així que no el retallis prèviament. El document es classifica automàticament (mai has de declarar el país ni el tipus de document), la zona visual es llegeix mitjançant OCR i es descodifiquen la MRZ i els codis de barres que hi hagi. A continuació, les comprovacions creuades validen les dates, els formats dels números i els dígits de control de la MRZ, i comparen la zona visual amb la MRZ. Amb `perform_document_liveness=true`, les imatges s'analitzen a més per detectar reproduccions en pantalla, còpies impreses i manipulacions del retrat. **Lògica de decisió.** `status` és `Approved` llevat que com a mínim un advertiment es resolgui en un rebuig. Els riscos de frau i fallades crítiques sempre rebutgen: `DOCUMENT_EXPIRED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, a més de les fallades d'extracció (`NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`, `DOCUMENT_NUMBER_NOT_DETECTED`). (`PORTRAIT_IMAGE_NOT_DETECTED`, `INVALID_DATE` i `MRZ_NOT_DETECTED` existeixen a les sessions de flux de treball, però aquest endpoint independent mai no els produeix. `COULD_NOT_DETECT_DOCUMENT_TYPE` es retorna aquí quan la imatge frontal no coincideix amb un disseny oficial de document conegut amb prou confiança, i rebutja la sol·licitud.) Tres grups de risc es poden configurar per sol·licitud mitjançant `invalid_mrz_action`, `inconsistent_data_action` i `expiration_date_not_detected_action` (`DECLINE` o `NO_ACTION`). Tots els altres advertiments (p. ex., `POSSIBLE_DUPLICATED_USER`) són informatius i mai no provoquen un rebuig per si sols. Quan `perform_document_liveness=true` (per defecte) i el control de falsificació no retorna cap puntuació utilitzable —el proveïdor ha fallat, ha respost amb un codi diferent de 200 o ha respost HTTP 200 amb `status="ERR"`—, la crida retorna `200` amb `status: "In Review"` i un advertiment `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) en comptes d'`Approved`: una comprovació que no s'ha executat no és prova que el document sigui autèntic. Aquesta escalada no és configurable i mai no preval sobre un `Declined`; amb `perform_document_liveness=false` s'omet la comprovació i l'estat segueix els advertiments restants com abans. Un document que no es pot processar de cap manera retorna `400` amb `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`; un document llegible però amb problemes retorna `200` amb `status: "Declined"` —inspecciona sempre `id_verification.status` i `id_verification.warnings`, no només el codi HTTP. **Facturació.** Cada resposta `200` consumeix un crèdit de l'API de Verificació d'identitat (descomptat del crèdit del teu pla o del saldo de recàrrega). Quan el saldo de l'organització no pot cobrir la crida, l'endpoint retorna `403` amb l'error de crèdits insuficients abans de processar cap imatge. **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 `request_id` retornat és un identificador de sessió real que pots passar a `GET /v3/session/{sessionId}/decision/`, les imatges retallades del document/retrat s'emmagatzemen i es retornen com a URL de mitjans de curta durada (`https:///ocr/...`), i s'emet un webhook `status.updated` cap a les destinacions de webhook configurades. Quan és `false`, no s'emmagatzema res, el `request_id` és un UUID de correlació d'un sol ús i `portrait_image`/`front_image`/`back_image` es retornen incrustats com a cadenes JPEG codificades en base64. **Sandbox.** Les claus d'API de sandbox ometen tot el processament i la facturació: després de validar la sol·licitud (una entrada mal formada continua retornant `400`), l'endpoint retorna un payload simulat estàtic `Approved` (un document d'identitat fictici dels EUA a nom de «Sandbox User»), no es desa cap sessió i no es consumeix cap crèdit. **Autenticació.** Envia la clau d'API de la teva aplicació a la capçalera `x-api-key`. Si les credencials falten o són invàlides, es retorna un `403` (`{"detail": "You do not have permission to perform this action."}`) —aquesta API mai no retorna `401`. **Límit de freqüència.** Límit compartit d'escriptures de 300 sol·licituds/min per clau d'API entre tots els endpoints POST/PATCH/DELETE; superar-lo retorna `429`. operationId: post_v3id-verification parameters: [] requestBody: required: true content: multipart/form-data: schema: type: object required: - front_image properties: front_image: type: string format: binary description: >- Anvers del document d'identitat. Extensions permeses: `tiff`, `jpg`, `jpeg`, `png`, `webp`, `pdf`. Mida màxima de càrrega: **10 MB** (els fitxers més grans es rebutgen amb `400`). Els PDF es renderitzen a una imatge abans de l'OCR; els PDF xifrats requereixen `front_image_password`. Les imatges es comprimeixen automàticament a ~0.5 MB i s'aplica l'orientació EXIF. Carrega la captura completa, sense retallar, amb les quatre cantonades del document visibles. front_image_password: type: string description: >- Contrasenya per desxifrar `front_image` quan és un PDF xifrat. Enviar un PDF xifrat sense contrasenya (o amb una d'incorrecta) retorna `400`. writeOnly: true back_image: type: string format: binary description: >- Revers del document — envia'l sempre que el document en tingui (molts documents d'identitat porten la MRZ o un codi de barres al darrere; ometre'l simplement deixa buits la MRZ i els camps del revers a la resposta — aquest endpoint no genera cap advertència de MRZ absent). Mateix format i límits de mida que `front_image`. Si s'omet, `back_image` i els camps del revers són `null` a la resposta. back_image_password: type: string description: >- Contrasenya per desxifrar `back_image` quan és un PDF xifrat. writeOnly: true perform_document_liveness: type: boolean default: true description: >- Analitza ambdues imatges a la cerca d'atac de presentació: reproduccions en pantalla (`SCREEN_CAPTURE_DETECTED`), còpies impreses (`PRINTED_COPY_DETECTED`) i manipulació de retrats (`PORTRAIT_MANIPULATION_DETECTED`). Qualsevol d'aquests es rebutja automàticament. Activat per defecte; defineix-ho com a `false` per ometre l'anàlisi de frau i reduir la latència. Quan està activat i el proveïdor no retorna cap puntuació utilitzable, la resposta és `In Review` amb una advertència `DOCUMENT_LIVENESS_NOT_COMPUTED` en lloc d'`Approved`. example: true minimum_age: type: integer nullable: true default: null minimum: 1 maximum: 120 description: >- S'accepta i es valida (1–120), però **actualment aquest endpoint no ho aplica**; mai no genera una advertència `MINIMUM_AGE_NOT_MET` a partir d'aquest camp. Aplica les regles d'edat a partir del `date_of_birth`/`age` retornat, o utilitza un flux de treball de sessió de verificació amb restriccions d'edat. expiration_date_not_detected_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Què fer quan no es pot llegir cap data de caducitat (`EXPIRATION_DATE_NOT_DETECTED`). Per defecte és `NO_ACTION` perquè molts documents d'identitat no imprimeixen data de caducitat. Nota: una data de caducitat *detectada i vençuda* sempre es rebutja (`DOCUMENT_EXPIRED`), independentment d'aquesta opció. invalid_mrz_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- Què fer quan el MRZ extret no supera la validació del dígit de control (`MRZ_VALIDATION_FAILED`). Un MRZ absent no genera cap advertència en aquest endpoint. Només és rellevant per a documents que incloguin un MRZ. `REVIEW` no s'admet en aquest endpoint i retorna `400`. inconsistent_data_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- Què fer quan les dades extretes són internament incoherents: `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` (la zona visual no coincideix amb la MRZ) o `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`. critical_field_occlusion_action: type: string enum: - NO_ACTION - DECLINE default: DECLINE description: >- Què fer quan un camp imprès crític s'ha tapat físicament a la captura (`CRITICAL_FIELD_OCCLUSION_DETECTED`) - un número d'identitat, un nom, la data de naixement o la data de caducitat. Es rebutja per defecte, igual que els altres riscos d'integritat del document d'aquest endpoint: tapar els números amb què es concilia un informe és el que sembla un document redactat o ocultat. El valor llegit d'un camp tapat es descarta de l'extracció en qualsevol cas, de manera que l'advertència `*_NOT_DETECTED` corresponent sol acompanyar-lo. `REVIEW` no s'admet en aquest endpoint i retorna `400`. document_or_personal_number_format_mismatch_action: type: string enum: - NO_ACTION - DECLINE default: NO_ACTION description: >- Què fer quan un número no coincideix amb el format que la seva autoritat emissora utilitza per a aquest tipus de document (`DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH`). Per defecte és `NO_ACTION`, que informa de l'advertència sense canviar l'estat. `REVIEW` no s'admet en aquest endpoint i retorna `400`. preferred_characters: type: string enum: - latin - non_latin default: latin description: >- Sistema d'escriptura preferit per als camps de nom/adreça en documents que imprimeixen text tant llatí com no llatí (àrab, ciríl·lic, CJK, …). `latin` retorna valors transliterats/llatins; `non_latin` prefereix el sistema d'escriptura natiu. 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 les imatges del document retornades com a URL de mitjans. Quan és `false`, no s'emmagatzema res, `request_id` és un UUID transitori i les imatges es retornen integrades com a cadenes JPEG en base64. 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: front_image: (binary JPEG/PNG/PDF of the document front) back_image: (binary JPEG/PNG/PDF of the document back) perform_document_liveness: true save_api_request: true vendor_data: user-123 metadata: flow: onboarding responses: '200': description: >- Document processat. `id_verification.status` és `Approved`, `Declined` o `In Review`; cada problema detectat es detalla a `id_verification.warnings`. Es retorna `In Review` quan una comprovació sol·licitada de prova de vida del document no ha produït cap resultat utilitzable (`DOCUMENT_LIVENESS_NOT_COMPUTED`). Un document problemàtic 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 i els camps d'imatge són URL multimèdia de curta durada; amb `save_api_request=false` són cadenes JPEG en base64 en línia. content: application/json: examples: Approved: summary: >- Document d'identitat de dues cares llegit correctament (desat — imatges com a URL multimèdia) value: request_id: 11d219ed-d59c-4b1d-8d65-9b933f12d5b8 id_verification: status: Approved document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: CBX164224 personal_number: 20446581H portrait_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-portrait_image-8c2f.jpg?signature=... front_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-front_image-4a1e.jpg?signature=... back_image: >- https:///ocr/11d219ed-d59c-4b1d-8d65-9b933f12d5b8-back_image-77b0.jpg?signature=... front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 78 brightness_score: 83.2 brightness_issue: ok is_document_fully_visible: true resolution_score: 40.7 overall_score: 70.2 back_image_quality_score: focus_score: 100 brightness_score: 95.6 brightness_issue: ok is_document_fully_visible: true resolution_score: 43 overall_score: 84.4 date_of_birth: '1980-01-13' age: 46 expiration_date: '2032-03-31' date_of_issue: '2022-03-31' issuing_state: ESP issuing_state_name: Spain first_name: Julio Francisco last_name: Fores Sena full_name: Julio Francisco Fores Sena gender: M address: >- Brda. Urb. El Cardonal 0052 52 Po3 B,Taco,San Cristobal De La Laguna,Santa Cruz De Tenerife formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain place_of_birth: Valencia, Valencia marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Fores second_surname: Sena mrz: surname: FORES SENA name: JULIO FRANCISCO country: ESP nationality: ESP birth_date: '800113' expiry_date: '320331' sex: M document_type: ID document_number: CBX164224 optional_data: 20446581H optional_data_2: '' birth_date_hash: '9' expiry_date_hash: '8' document_number_hash: '3' final_hash: '3' personal_number: 20446581H warnings: [] errors: [] mrz_type: TD1 mrz_string: |- IDESPCBX164224320446581H<<<<<< 8001139M3203318ESP<<<<<<<<<<<3 FORES- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: address_components: - long_name: b short_name: b types: - subpremise - long_name: '52' short_name: '52' types: - street_number - long_name: Avenida el Cardonal short_name: Av. el Cardonal types: - route - long_name: La Laguna short_name: La Laguna types: - locality - political - long_name: Spain short_name: ES types: - country - political - long_name: '38108' short_name: '38108' types: - postal_code formatted_address: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain geometry: location: lat: 28.4501161 lng: -16.3004407 location_type: ROOFTOP types: - street_address - subpremise document_location: latitude: 28.4501161 longitude: -16.3004407 label: Spain Identity Card Address is_verified: true category: Residential warnings: [] barcodes: [] vendor_data: user-123 metadata: flow: onboarding created_at: '2026-06-12T02:21:56.013573+00:00' Declined - expired document: summary: Càrrega només de l'anvers d'un document d'identitat caducat value: request_id: f61681b8-9422-4378-ac3e-04c6a247fb45 id_verification: status: Declined document_type: Identity Card document_subtype: ID_CARD_GENERIC document_number: BNK123072 personal_number: 21771255F portrait_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-portrait_image-1d9a.jpg?signature=... front_image: >- https:///ocr/f61681b8-9422-4378-ac3e-04c6a247fb45-front_image-5c2b.jpg?signature=... back_image: null front_image_camera_front: null back_image_camera_front: null front_image_camera_front_face_match_score: null back_image_camera_front_face_match_score: null front_image_quality_score: focus_score: 100 brightness_score: 95.7 brightness_issue: ok is_document_fully_visible: true resolution_score: 22.2 overall_score: 79.3 back_image_quality_score: null date_of_birth: '1997-01-30' age: 29 expiration_date: '2025-11-26' date_of_issue: null issuing_state: ESP issuing_state_name: Spain first_name: Lucia last_name: Marin Castro full_name: Lucia Marin Castro gender: F address: null formatted_address: null place_of_birth: null marital_status: UNKNOWN nationality: ESP extra_fields: first_surname: Marin second_surname: Castro mrz: {} parsed_address: null warnings: - risk: DOCUMENT_EXPIRED feature: ID_VERIFICATION additional_data: null log_type: error short_description: Document expired long_description: >- The document's expiration date has passed, rendering it no longer valid for use. barcodes: [] vendor_data: user-123 metadata: null created_at: '2026-06-12T02:25:48.117204+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. id_verification: type: object properties: status: type: string enum: - Approved - Declined - In Review description: >- `Approved` quan cap advertència no es resol en un rebuig i la comprovació de prova de vida del document sol·licitada ha generat un resultat utilitzable; `In Review` quan la comprovació sol·licitada no ha generat cap resultat utilitzable (`DOCUMENT_LIVENESS_NOT_COMPUTED`); `Declined` quan una advertència es resol en un rebuig — la llista `warnings` n'explica el motiu. document_type: type: string nullable: true description: >- Nom visible del tipus de document detectat: `Identity Card`, `Passport`, `Driver's License`, `Residence Permit`, `Health Insurance Card` o `Tax Card`. `null` quan el document no s'ha pogut classificar. example: Identity Card document_subtype: type: string nullable: true description: >- Subtipus més detallat quan estigui disponible (p. ex. `ID_CARD_GENERIC`, `EPASSPORT`). example: ID_CARD_GENERIC document_number: type: string nullable: true example: CBX164224 personal_number: type: string nullable: true description: >- Número personal/nacional secundari imprès en alguns documents. example: 20446581H portrait_image: type: string nullable: true description: >- Foto de retrat retallada del document. Un URL de fitxer multimèdia de curta durada (`https:///ocr/...`) quan `save_api_request=true` (per defecte); una cadena JPEG codificada en base64 integrada quan `save_api_request=false`. `null` quan no s'ha detectat cap retrat. front_image: type: string nullable: true description: >- Retall alineat de l'anvers del document. URL del contingut multimèdia quan s'ha desat, JPEG en base64 en línia en cas contrari. back_image: type: string nullable: true description: >- Retall alineat del revers del document. `null` quan no s'ha pujat cap `back_image`. front_image_camera_front: type: string nullable: true description: >- Sempre `null` en aquest endpoint (només s'omple en sessions de verificació amb captura de càmera). back_image_camera_front: type: string nullable: true description: Sempre `null` en aquest endpoint. front_image_camera_front_face_match_score: type: number nullable: true description: Sempre `null` en aquest endpoint. back_image_camera_front_face_match_score: type: number nullable: true description: Sempre `null` en aquest endpoint. front_image_quality_score: type: object nullable: true description: >- Diagnòstics de qualitat de captura per a la imatge pujada (`null` quan no s'ha proporcionat el costat o la puntuació ha fallat). Totes les puntuacions són de 0 a 100. properties: focus_score: type: number format: float description: >- Nitidesa del retall del document (com més alt, més nítid). brightness_score: type: number format: float description: Qualitat de l'exposició (com més alta, millor). brightness_issue: type: string nullable: true description: >- `ok` quan l'exposició és correcta; en cas contrari, el problema detectat (p. ex., massa fosc / massa brillant). is_document_fully_visible: type: boolean nullable: true description: >- Indica si les quatre cantonades del document estan dins de l'enquadrament. resolution_score: type: number format: float description: Resolució efectiva de l'àrea del document. overall_score: type: number format: float description: Puntuació de qualitat agregada. back_image_quality_score: type: object nullable: true description: >- Diagnòstics de qualitat de captura per a la imatge pujada (`null` quan no s'ha proporcionat el costat o la puntuació ha fallat). Totes les puntuacions són de 0 a 100. properties: focus_score: type: number format: float description: >- Nitidesa del retall del document (com més alt, més nítid). brightness_score: type: number format: float description: Qualitat de l'exposició (com més alta, millor). brightness_issue: type: string nullable: true description: >- `ok` quan l'exposició és correcta; en cas contrari, el problema detectat (p. ex., massa fosc / massa brillant). is_document_fully_visible: type: boolean nullable: true description: >- Indica si les quatre cantonades del document estan dins de l'enquadrament. resolution_score: type: number format: float description: Resolució efectiva de l'àrea del document. overall_score: type: number format: float description: Puntuació de qualitat agregada. date_of_birth: type: string format: date nullable: true example: '1980-01-13' age: type: integer nullable: true description: >- Edat del titular en anys, calculada a partir de `date_of_birth`. example: 46 expiration_date: type: string format: date nullable: true example: '2032-03-31' date_of_issue: type: string format: date nullable: true example: '2022-03-31' issuing_state: type: string nullable: true description: País emissor (ISO 3166-1 alfa-3). example: ESP issuing_state_name: type: string nullable: true example: Spain first_name: type: string nullable: true example: Julio Francisco last_name: type: string nullable: true example: Fores Sena full_name: type: string nullable: true example: Julio Francisco Fores Sena gender: type: string nullable: true description: '`M`, `F` o `null` quan no està imprès o detectat.' example: M address: type: string nullable: true description: Adreça exactament com està impresa al document. formatted_address: type: string nullable: true description: Versió geocodificada i normalitzada de `address`. place_of_birth: type: string nullable: true example: Valencia, Valencia marital_status: type: string nullable: true description: >- `UNKNOWN` tret que el document imprimeixi l'estat civil. example: UNKNOWN nationality: type: string nullable: true description: Nacionalitat del titular (ISO 3166-1 alfa-3). example: ESP extra_fields: type: object nullable: true additionalProperties: true description: >- Camps addicionals específics del document que no tenen una columna dedicada (p. ex., `first_surname`/`second_surname` en DNIs espanyols, categories de permís en permisos de conduir). mrz: type: object description: >- Zona de lectura mecànica analitzada. Un **objecte buit** (`{}`) quan el document no té MRZ o no s'ha pogut llegir; en aquest cas, consulta també la llista `warnings`. Les dates de la MRZ utilitzen el format brut `YYMMDD`. properties: surname: type: string example: FORES SENA name: type: string example: JULIO FRANCISCO country: type: string description: País emissor (ISO 3166-1 alfa-3). example: ESP nationality: type: string description: Nacionalitat del titular (ISO 3166-1 alfa-3). example: ESP birth_date: type: string description: Data de naixement en brut de la MRZ (`YYMMDD`). example: '800113' expiry_date: type: string description: Data de caducitat en brut de la MRZ (`YYMMDD`). example: '320331' sex: type: string example: M document_type: type: string description: >- Codi de tipus de document de la MRZ (p. ex., `ID`, `P`). example: ID document_number: type: string example: CBX164224 optional_data: type: string nullable: true example: 20446581H optional_data_2: type: string nullable: true example: '' birth_date_hash: type: string description: >- Dígit de control de la MRZ per a la data de naixement. example: '9' expiry_date_hash: type: string description: >- Dígit de control de la MRZ per a la data de caducitat. example: '8' document_number_hash: type: string description: >- Dígit de control de la MRZ per al número de document. example: '3' final_hash: type: string description: Dígit de control compost de la MRZ. example: '3' personal_number: type: string nullable: true example: 20446581H warnings: type: array items: type: string description: Advertències no crítiques d'anàlisi de la MRZ. errors: type: array items: type: string description: >- Errors de dígits de control o d'anàlisi de la MRZ. Els errors que no siguin buits es mostren com una advertència `MRZ_VALIDATION_FAILED`. mrz_type: type: string description: >- Format de la MRZ: `TD1` (targetes d'identitat, 3 línies), `TD2` o `TD3` (passaports, 2 línies). example: TD1 mrz_string: type: string description: >- Text en brut de la MRZ tal com s'ha llegit, amb les línies separades per `\n`. mrz_key: type: string description: >- Clau composta (número de document + dígits de control) utilitzada per a comprovacions creuades. parsed_address: type: object nullable: true description: >- Desglossament estructurat i geocodificat de `address`. `null` quan el document no conté cap adreça o no s'ha pogut analitzar. properties: street_1: type: string nullable: true example: Avenida el Cardonal 52 street_2: type: string nullable: true example: b city: type: string nullable: true example: La Laguna region: type: string nullable: true example: Canarias country: type: string nullable: true description: Codi de país ISO 3166-1 alfa-2. example: ES postal_code: type: string nullable: true example: '38108' address_type: type: string nullable: true example: Avenida formatted_address: type: string nullable: true description: Cadena d'adreça geocodificada canònica. example: >- Av. el Cardonal, 52, b, 38108 La Laguna, Santa Cruz de Tenerife, Spain raw_results: type: object additionalProperties: true description: >- Payload de geocodificació en brut (`address_components`, `geometry.location`, `place_id`, …) per a consumidors avançats. document_location: type: object nullable: true properties: latitude: type: number longitude: type: number description: >- Coordenades geocodificades de l'adreça del document. label: type: string nullable: true description: De quin camp del document s'ha llegit l'adreça. example: Spain Identity Card Address is_verified: type: boolean description: >- Indica si la geocodificació ha confirmat que l'adreça existeix. category: type: string nullable: true description: >- Categoria de l'adreça (p. ex., `Residential`, `Commercial`). example: Residential 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`, i `DOCUMENT_LIVENESS_NOT_COMPUTED` (`log_type: "warning"`) l'estableix a `In Review`. items: type: object properties: risk: type: string description: >- Codi de risc llegible per màquina. Riscos de rebuig automàtic: `DOCUMENT_EXPIRED`, `MINIMUM_AGE_NOT_MET`, `PORTRAIT_IMAGE_NOT_DETECTED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT` (només 400, mai una advertència), `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`. Regulats per opcions de la sol·licitud: `MRZ_NOT_DETECTED` / `MRZ_VALIDATION_FAILED` (`invalid_mrz_action`), `DATA_INCONSISTENT` / `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` / `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` (`inconsistent_data_action`), `EXPIRATION_DATE_NOT_DETECTED` (`expiration_date_not_detected_action`). Altres riscos (p. ex. `POSSIBLE_DUPLICATED_USER`) són informatius. `DOCUMENT_LIVENESS_NOT_COMPUTED` es genera quan `perform_document_liveness=true` però la comprovació de falsificació no ha retornat cap puntuació utilitzable; estableix `status` a `In Review`. `COULD_NOT_DETECT_DOCUMENT_TYPE` també es retorna quan l'anvers del document no coincideix amb un disseny de document oficial conegut amb prou confiança, com ara un document editat o generat per ordinador, o un disseny que encara no és compatible. example: DOCUMENT_EXPIRED feature: type: string enum: - ID_VERIFICATION description: >- Funcionalitat que ha generat l'advertència. Sempre `ID_VERIFICATION` en aquest endpoint. additional_data: type: object nullable: true additionalProperties: true description: >- Context addicional per a alguns riscos (p. ex. `POSSIBLE_DUPLICATED_USER` inclou `duplicated_session_id`); `null` per a la majoria. log_type: type: string enum: - error - warning - information description: >- Gravetat. Les advertències `error` canvien `status` a `Declined`; `warning` (només `DOCUMENT_LIVENESS_NOT_COMPUTED`, quan la comprovació de falsificació sol·licitada no ha produït cap puntuació utilitzable) canvia `status` a `In Review`; les entrades `information` són consultives i mai no canvien l'estat. 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. barcodes: type: array description: >- Codis de barres descodificats del document (PDF417, QR, …). Buit quan el document no en té cap o no se n'ha pogut llegir cap. items: type: object properties: type: type: string description: >- Tipus de codi de barres (p. ex., `PDF417`, `QR_CODE`, `UNKNOWN`). position: type: object nullable: true additionalProperties: true description: >- Ubicació del codi de barres a la imatge, quan estigui disponible. data: type: string description: Payload descodificat. data_raw: type: string description: >- Payload en brut (sense descodificar), si és diferent. side: type: string nullable: true description: '`front` o `back`.' 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": ...}`. Una imatge de document en què no es pot reconèixer cap document retorna `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`. Les càrregues de PDF també poden fallar amb "The submitted PDF file is corrupted or invalid." o un error de document sense pàgines. content: application/json: examples: Missing front image: summary: '`front_image` no s''ha inclòs a les dades del formulari' value: front_image: - No file was submitted. Unsupported file extension: summary: >- Extensió de fitxer no permesa (només tiff/jpg/jpeg/png/webp/pdf) value: front_image: - >- File extension “txt” is not allowed. Allowed extensions are: tiff, jpg, jpeg, png, webp, pdf. File too large: summary: La pujada supera el límit de 10 MB value: front_image: - File size should not exceed 10 MB Invalid option value: summary: Les opcions només accepten DECLINE o NO_ACTION value: invalid_mrz_action: - '"REVIEW" is not a valid choice.' 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: >- `front_image_password` / `back_image_password` no desxifra el PDF value: detail: >- The PDF password is incorrect. Please provide the correct password. Document not recognized: summary: No s'ha pogut detectar cap document d'identitat a la imatge value: error: COULD_NOT_RECOGNIZE_DOCUMENT PDF conversion failure: summary: El PDF pujat no s'ha pogut convertir en una imatge value: error: Failed to convert front image PDF. '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 d'imatges. 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/id-verification/' \ -H 'x-api-key: YOUR_API_KEY' \ -F 'front_image=@./id_front.jpg' \ -F 'back_image=@./id_back.jpg' \ -F 'perform_document_liveness=true' \ -F 'save_api_request=true' \ -F 'vendor_data=user-123' - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.id_verification.verify( front_image=open("front_image.jpg", "rb"), back_image=open("back_image.jpg", "rb"), perform_document_liveness=True, save_api_request=True, vendor_data="user-123", metadata={"flow": "onboarding"}, ) 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.idVerification.verify({ front_image: await fileFromPath("front_image.jpg"), back_image: await fileFromPath("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" }, }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.IDVerification.Verify(ctx, didit.IDVerificationVerifyParams{\n\tFrontImage: didit.FileFromPath(\"front_image.jpg\"),\n\tBackImage: didit.Some(didit.FileFromPath(\"back_image.jpg\")),\n\tPerformDocumentLiveness: didit.Bool(true),\n\tSaveAPIRequest: didit.Bool(true),\n\tVendorData: didit.String(\"user-123\"),\n\tMetadata: didit.Some(map[string]any{\"flow\": \"onboarding\"}),\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 java.util.Map; import me.didit.Didit; import me.didit.types.IdVerificationVerifyParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.idVerification().verify(IdVerificationVerifyParams.builder() .frontImage(Path.of("front_image.jpg")) .backImage(Path.of("back_image.jpg")) .performDocumentLiveness(true) .saveApiRequest(true) .vendorData("user-123") .metadata(Map.of("flow", "onboarding")) .build()); System.out.println(result); - lang: php label: PHP source: |- idVerification->verify([ 'front_image' => File::fromPath('front_image.jpg'), 'back_image' => File::fromPath('back_image.jpg'), 'perform_document_liveness' => true, 'save_api_request' => true, 'vendor_data' => 'user-123', 'metadata' => ['flow' => 'onboarding'], ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.id_verification.verify( front_image: Pathname("front_image.jpg"), back_image: Pathname("back_image.jpg"), perform_document_liveness: true, save_api_request: true, vendor_data: "user-123", metadata: { flow: "onboarding" } ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Collections.Generic; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.IdVerification.VerifyAsync(new IdVerificationVerifyParams { FrontImage = FileUpload.FromPath("front_image.jpg"), BackImage = FileUpload.FromPath("back_image.jpg"), PerformDocumentLiveness = true, SaveApiRequest = true, VendorData = "user-123", Metadata = new Dictionary { ["flow"] = "onboarding" }, }); Console.WriteLine(JsonSerializer.Serialize(result)); components: 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.