> ## 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. # Models de dades de Didit > Esquemes JSON canònics dels informes de Didit: NFC, ID, Liveness, Face Match, AML, IP, POA, telèfon, correu, KYB, documents i persones clau. ## Visió general Cada informe per funcionalitat segueix la forma del serialitzador V3 definida a `service-didit-verification`. El mateix objecte apareix en tres llocs, de manera que l'esquema que veus aquí és la font única de veritat per a tots tres: * `GET /v3/session/{sessionId}/decision/`: cada funcionalitat es retorna com una matriu amb un nom en plural (`id_verifications[]`, `nfc_verifications[]`, `liveness_checks[]`, `face_matches[]`, `poa_verifications[]`, `phone_verifications[]`, `email_verifications[]`, `aml_screenings[]`, `ip_analyses[]`, `database_validations[]`, `questionnaire_responses[]`, `signatures[]`, `bank_verifications[]` (consulta [Mètodes de verificació bancària](https://docs.didit.me/ca/core-technology/bank-verification/verification-methods.md#com-llegir-el-mètode-al-resultat)), i els equivalents de KYB `registry_checks[]`, `document_verifications[]`, `key_people_checks[]`). * Payloads de webhook (`status.updated`, `data.updated`): la mateixa forma dins de l'embolcall `decision`. * APIs independents: les respostes d'un sol objecte (Cerca facial, Estimació d'edat, Autenticació biomètrica) reutilitzen el mateix conjunt de camps. > [!NOTE] > > V3 va introduir fluxos de treball multiinstància: cada objecte de funcionalitat porta un `node_id` que vincula l'informe al node del graf de flux de treball que l'ha generat. Els endpoints V2 (en singular `kyc`, `face`, `aml`, etc.) continuen sent compatibles amb versions anteriors, però només retornen la primera instància. ## Camps comuns Cada objecte d'informe exposa els camps següents: | Camp | Tipus | Descripció | | - | - | - | | `status` | string | Estat del cicle de vida a nivell de funcionalitat: un dels valors de l'[enumeració d'estats](#referència-d’enumeració-d’estats). Font: `common/config/choices.py:FeatureStatusChoices` (línies 343-348). El `status` de nivell superior de la sessió pare utilitza l'enumeració de sessió més àmplia (`StatusChoices`, línies 106-117). | | `node_id` | string \| null | Identificador del node del graf de flux de treball. S'omple per als fluxos de treball multiinstància de V3; `null` per a sessions antigues d'una sola funcionalitat. | | `warnings` | matriu d'[objectes d'advertència](#objecte-d’advertència) | Senyals de risc filtrats per a aquesta funcionalitat i `node_id`. Retornats per `Session.get_logs(...)` (`sessions/models/session.py:1611`). | Els camps multimèdia (`portrait_image`, `front_image`, `document_file`, …) són URL prefirmades amb una finestra de validesa limitada: descarrega-les aviat en lloc de guardar la URL. Els exemples els mostren com a `https:///...`. ## Objecte d'advertència Es retorna en cada matriu `warnings[]`. Esquema de `logs/serializers/log.py:8-65` (`LogV3Serializer`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `feature` | string (enum) | No | Funcionalitat que ha emès l'advertència. Valors de `LogWarningChoices` (`common/config/choices.py:190-204`): `ID_VERIFICATION`, `NFC`, `LIVENESS`, `FACEMATCH`, `PROOF_OF_ADDRESS`, `PHONE`, `EMAIL`, `AML`, `LOCATION`, `DATABASE_VALIDATION`, `QUESTIONNAIRE`, `KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`. | `"ID_VERIFICATION"` | | `risk` | string | No | Codi de risc estable (p. ex. `DOCUMENT_EXPIRED`, `LOW_LIVENESS_SCORE`). Valors de `logs/choices.py:RiskChoices`. S'utilitza com a clau en les taules de descripcions. | `"DOCUMENT_EXPIRED"` | | `additional_data` | object \| null | Sí | Context específic del risc (p. ex. llindars de puntuació, camps coincidents). La forma varia segons el codi de risc. | `{ "score": 42.1, "threshold": 70 }` | | `log_type` | string (enum) | No | Un dels valors `error`, `warning` o `information`. De `LogTypeChoices` (`common/config/choices.py:207-210`). | `"error"` | | `short_description` | string | No | Etiqueta del risc comprensible per a les persones. De `logs/choices.py:RISK_SHORT_DESCRIPTIONS`. | `"Document expired"` | | `long_description` | string | No | Explicació més llarga i comprensible, adequada per a interfícies adreçades a l'usuari final. De `logs/choices.py:RISK_LONG_DESCRIPTIONS`. | `"The document's expiration date has passed, rendering it no longer valid for use."` | | `node_id` | string \| null | Sí | Node del graf de flux de treball on s'ha generat l'advertència. `null` per als registres V2 antics sense `node_id`. | `"first_id_verification"` | ```json theme={null} { "feature": "ID_VERIFICATION", "risk": "DOCUMENT_EXPIRED", "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.", "node_id": "first_id_verification" } ``` ## Objectes d'informe Les seccions restants descriuen cada objecte d'informe per funcionalitat. El text dels encapçalaments H3 és estable de manera intencionada perquè altres documents puguin enllaçar-hi directament. ### Verificació d'identitat Es retorna per a cada document de KYC o d'identitat que envia un usuari. Apareix com a `id_verifications[]` a `GET /v3/session/{sessionId}/decision/` i dins del camp `kyc` de les respostes V2. Font: `kyc/serializers/kyc.py:383-414` (`IDVerificationV3Serializer`, que amplia `IDVerificationV2Serializer` a `kyc/serializers/kyc.py:320-380`). | Camp | Tipus | Pot ser nul | Descripció | Exemple | | - | - | - | - | - | | `status` | cadena | No | Consulta [Enumeració d'estats](#referència-d’enumeració-d’estats). | `"Approved"` | | `document_type` | cadena | Sí | Classe de document en un format llegible (`Passport`, `Identity Card`, `Driver's License`, `Residence Permit`, `Health Insurance Card`, `Tax Card`, `Social Security Card`, `Work Permit`, `Visa`, `Public Service Card`, `Birth Certificate`, `Firearm License`, `Other`). Font: `DOC_TYPE_MAPPING` (`common/config/choices.py:1275-1289`). | `"Passport"` | | `document_subtype` | cadena | Sí | Codi de subtipus de document del registre de documents de Didit, filtrat segons els tipus de document que accepta la configuració documental del flux de treball. Els documents específics d'una regió inclouen la regió. Llista completa de codis: [Subtipus de document](https://docs.didit.me/ca/core-technology/id-verification/document-subtypes-id-verification.md). | `"QUEENSLAND_DRIVER_LICENSE_GENERIC"` | | `document_number` | cadena | Sí | Número de document extret per OCR. | `"AB1234567"` | | `personal_number` | cadena | Sí | Identificador personal o nacional extret per OCR. | `"99999999R"` | | `portrait_image` | cadena (URL) | Sí | URL prefirmada del retall facial. | `"https:///.../portrait.jpg?..."` | | `front_image` | cadena (URL) | Sí | URL prefirmada de l'anvers del document netejat. | `"https:///.../front.jpg?..."` | | `front_video` | cadena (URL) | Sí | URL prefirmada del vídeo de captura de l'anvers (quan està disponible). | `"https:///.../front.mp4?..."` | | `back_image` | cadena (URL) | Sí | URL prefirmada del revers del document netejat. | `"https:///.../back.jpg?..."` | | `back_video` | cadena (URL) | Sí | URL prefirmada del vídeo de captura del revers. | `null` | | `full_front_image` | cadena (URL) | Sí | Captura de l'anvers sense retallar (de fotograma complet). | `"https:///.../full_front.jpg?..."` | | `full_back_image` | cadena (URL) | Sí | Captura del revers sense retallar (de fotograma complet). | `null` | | `front_image_camera_front` | cadena (URL) | Sí | Imatge de la càmera frontal presa al mateix temps que l'anvers del document. | `null` | | `back_image_camera_front` | cadena (URL) | Sí | Imatge de la càmera frontal presa al mateix temps que el revers del document. | `null` | | `front_image_camera_front_face_match_score` | flotant (0-100) | Sí | Similitud entre el retrat del document i la captura de la càmera frontal. | `null` | | `back_image_camera_front_face_match_score` | flotant (0-100) | Sí | Igual que l'anterior però per a la captura del revers. | `null` | | `document_selfie_face_matches` | matriu | Sí | Sessions anteriors o entrades de la llista de bloqueig facial que coincideixen amb la selfie feta durant la captura del document. Té el mateix format d'entrada que `liveness_checks[].matches`. És `null` quan la cerca no s'ha executat i `[]` quan no hi ha cap coincidència. | `null` | | `front_image_quality_score` | objecte | Sí | Mètriques de qualitat de la imatge de l'anvers: puntuacions de 0 a 100 (`focus_score`, `brightness_score`, `resolution_score`, `overall_score`), a més de `brightness_issue` (`ok`, `too_dark`, `too_bright`) i `is_document_fully_visible` (booleà). | `{ "focus_score": 91.0, "overall_score": 88.5 }` | | `back_image_quality_score` | objecte | Sí | Té la mateixa estructura que `front_image_quality_score`. | `null` | | `date_of_birth` | cadena (YYYY-MM-DD) | Sí | Data de naixement extreta per OCR. | `"1990-05-12"` | | `age` | enter | Sí | Edat calculada en anys en el moment de l'extracció. | `35` | | `expiration_date` | cadena (YYYY-MM-DD) | Sí | Data de caducitat del document. | `"2032-05-11"` | | `date_of_issue` | cadena (YYYY-MM-DD) | Sí | Data d'expedició del document. | `"2022-05-11"` | | `issuing_state` | cadena (ISO 3166-1 alpha-3) | Sí | Codi del país emissor. | `"ESP"` | | `issuing_state_name` | cadena | Sí | Nom localitzat del país emissor. | `"Spain"` | | `first_name` | cadena | Sí | Nom o noms de pila extrets per OCR. | `"María"` | | `last_name` | cadena | Sí | Cognom o cognoms extrets per OCR. | `"García López"` | | `full_name` | cadena | Sí | Nom complet normalitzat (proporcionat pel proveïdor). | `"María García López"` | | `gender` | cadena | Sí | `M`, `F` o un altre valor proporcionat pel proveïdor. | `"F"` | | `address` | cadena | Sí | Línia d'adreça en brut extreta per OCR. | `"Calle Mayor 1, 28001 Madrid"` | | `formatted_address` | cadena | Sí | Adreça geocodificada o formatada (quan es pot analitzar). | `"Calle Mayor 1, 28001 Madrid, Spain"` | | `parsed_address` | objecte | Sí | Adreça estructurada i geocodificada: `street_1`, `street_2`, `city`, `region`, `country`, `postal_code`, `address_type`, `formatted_address`, `document_location` (`{latitude, longitude}`), `raw_results` i `is_best_match`. Font: `kyc/utils/address.py:147-197`. | `{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" }` | | `place_of_birth` | cadena | Sí | Lloc de naixement extret per OCR. | `"Madrid"` | | `marital_status` | cadena | Sí | Quan es pot extreure. | `null` | | `nationality` | cadena (ISO 3166-1 alpha-3) | Sí | Nacionalitat extreta per OCR. | `"ESP"` | | `extra_fields` | objecte | Sí | Camps específics del tipus de document que no es cobreixen amb l'esquema canònic (p. ex., categories del permís de conducció). | `{ "DL Class": "B" }` | | `mrz` | objecte | Sí | Camps MRZ analitzats quan hi són (`document_number`, `birth_date`, `expiry_date`, `surname`, `given_names`, …). | `{ "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA" }` | | `extra_files` | matriu de cadenes (URL) | No | URL prefirmades de qualsevol fitxer addicional pujat. | `[]` | | `matches` | matriu d'objectes | No | Coincidències de documents entre sessions. Cada element: `{ session_id, session_number, vendor_data, verification_date, user_details: { name, document_type, document_number }, status, is_blocklisted, api_service, front_image_url }`. `front_image_url` és una URL prefirmada. | `[]` | | `verification_method` | string | No | Quin [mètode de verificació d'identitat](https://docs.didit.me/ca/core-technology/id-verification/verification-methods.md) ha produït aquesta fila: `document`, `id_lookup` o `wallet`. Sempre `document` per a un document fotografiat, incloses totes les sessions creades abans que existissin els altres mètodes. | `"id_lookup"` | | `assurance` | string | No | Nivell de garantia derivat de `verification_method`: `documentary`, `data_match` o `cryptographic`. | `"data_match"` | | `wallet_provider` | string \| null | Sí | Identificador de la cartera del catàleg quan una cartera ha produït aquesta fila (`mitid`, `bankid_se`, `itsme`, ...). `null` en cas contrari. | `"mitid"` | | `fallback_from` | object \| null | Sí | Motiu pel qual un mètode que no és de document ha finalitzat el pas d'identificació: `{ method, reason, action }`. S'estableix quan una consulta o un inici de sessió amb cartera ha fallat: a la fila rebutjada quan el commutador del país era `decline` (`action: "decline"`), i al document de verificació amb què continua l'usuari quan era `fallback_to_document` (`action: "fallback_to_document"`). `null` quan no hi ha cap fallada prèvia d'un mètode que no és de document registrada. | `{ "method": "id_lookup", "reason": "no_match", "action": "decline" }` | | `id_lookup` | object \| null | Sí | Evidència de la font, present només quan `verification_method` és `id_lookup`: `source` (la font exacta consultada: un registre governamental en la majoria de països, o un fitxer d'una agència de crèdit o de registres residencials en alguns), `checked_at`, `attempts`, `max_attempts`, `outcome` (`match`, `partial_match`, `no_match`, `provider_error`, `format_rejected`), `comparison[]` (`{ field, label, provided, record, result }`; `field` és un de `identification_number`, `full_name`, `date_of_birth`, `address`, i `result` és `match`, `partial` o `no_match`; les versions anteriors poden incloure una fila `provider` amb `error`), `source_errors[]` (entorn de preproducció actual: diagnòstics separats per font; confirmeu el desplegament en producció), `registry_portrait` (URL prefirmada, només per a les fonts que en retornen una) i `face_match_score`. | vegeu més avall | | `wallet_verification` | object \| null | Sí | Evidència de credencials, present només quan `verification_method` és `wallet`: `provider`, `provider_name`, `issuing_authority`, `issuing_country`, `credential_type`, `level_of_assurance` (`low`, `substantial`, `high`), `verified_at`, `signature_valid`, `attributes` (el que ha compartit la cartera), `portrait` (URL prefirmada quan la cartera en comparteix una) i `face_match_score`. | vegeu més avall | | `document_liveness` | object \| null | Sí | Puntuacions de prova de vida del document per tipus de frau (`portrait_replace`, `printed_copy`, `screen_replay`), informades tant si s'ha activat una advertència com si no. Cadascuna conté: `score` (0-100, més alt = més probabilitat que sigui genuí; el valor més baix, que és el que va utilitzar la decisió), `front`, `back`, `decline_threshold`, `review_threshold`, `bucket` (`approve`, `review`, `decline` o `null`). Els llindars i la categoria es desen en el moment de l'avaluació; els tres són `null` quan no hi ha evidència d'avaluació històrica disponible, però les puntuacions emmagatzemades continuen visibles. `null` quan la comprovació no s'ha executat. Consulteu [Puntuacions de prova de vida del document](https://docs.didit.me/ca/core-technology/id-verification/report-id-verification.md#puntuacions-de-prova-de-vida-del-document). Només V3. | `{ "portrait_replace": { "score": 96.46, "bucket": "approve" } }` | | `node_id` | string \| null | Sí | Identificador del node del flux de treball (V3). | `"first_id_verification"` | | `warnings` | array | No | Vegeu [Objecte d'advertència](#objecte-d’advertència). | `[]` | | `region` | string | Sí | Regió o estat del país emissor, quan el document n'identifica un. | `"CA"` | | `extracted_data` | object | Sí | Instantània de les dades extretes del document que es va mostrar a la persona perquè les revisés, guardada al costat dels valors confirmats perquè pugueu comparar-los. `null` quan no se li va demanar que revisés. | | | `barcodes` | matriu d'objectes | No | Dades llegides dels codis de barres del document, una entrada per codi de barres amb `type`, `position`, `data`, `data_raw` i `side`. `[]` quan no n'hi ha cap. | `[]` | ```json theme={null} { "status": "Approved", "document_type": "Passport", "document_subtype": "PASSPORT_GENERIC", "document_number": "AB1234567", "personal_number": "99999999R", "portrait_image": "https:///.../portrait.jpg?signature=...", "front_image": "https:///.../front.jpg?signature=...", "front_video": null, "back_image": "https:///.../back.jpg?signature=...", "back_video": null, "full_front_image": "https:///.../full_front.jpg?signature=...", "full_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": 91.0, "brightness_score": 88.0, "brightness_issue": "ok", "is_document_fully_visible": true, "resolution_score": 95.0, "overall_score": 88.5 }, "back_image_quality_score": null, "date_of_birth": "1990-05-12", "age": 35, "expiration_date": "2032-05-11", "date_of_issue": "2022-05-11", "issuing_state": "ESP", "issuing_state_name": "Spain", "first_name": "María", "last_name": "García López", "full_name": "María García López", "gender": "F", "address": "Calle Mayor 1, 28001 Madrid", "formatted_address": "Calle Mayor 1, 28001 Madrid, Spain", "parsed_address": { "street_1": "Calle Mayor 1", "street_2": null, "city": "Madrid", "region": "Madrid", "postal_code": "28001", "country": "ES", "address_type": "Calle" }, "place_of_birth": "Madrid", "marital_status": null, "nationality": "ESP", "extra_fields": {}, "mrz": { "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA", "birth_date": "900512", "expiry_date": "320511" }, "extra_files": [], "matches": [], "node_id": "first_id_verification", "verification_method": "document", "assurance": "documentary", "wallet_provider": null, "fallback_from": null, "id_lookup": null, "wallet_verification": null, "document_liveness": { "portrait_replace": { "score": 96.46, "front": 96.46, "back": 98.2, "decline_threshold": 35, "review_threshold": 70, "bucket": "approve" }, "printed_copy": { "score": 91.2, "front": 91.2, "back": 93.7, "decline_threshold": 35, "review_threshold": 77, "bucket": "approve" }, "screen_replay": { "score": 99.9, "front": 99.9, "back": 99.5, "decline_threshold": 30, "review_threshold": 70, "bucket": "approve" } }, "warnings": [] } ``` El mateix objecte amb un mètode que no és de document. Només canvien les claus específiques del mètode: tot el que omple una lectura de document s'omple amb el registre de la font o els atributs de la cartera, i les claus que no s'apliquen són `null`. ```json theme={null} { "status": "Approved", "issuing_state": "ZAF", "first_name": "Thabo", "last_name": "Mokoena", "full_name": "Thabo Mokoena", "date_of_birth": "1991-06-15", "personal_number": "9106155043088", "node_id": "first_id_verification", "verification_method": "id_lookup", "assurance": "data_match", "wallet_provider": null, "fallback_from": null, "id_lookup": { "source": "Department of Home Affairs", "checked_at": "2026-09-04T09:12:44Z", "attempts": 1, "max_attempts": 2, "outcome": "match", "comparison": [ { "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" }, { "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" }, { "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" } ], "registry_portrait": "https:///.../registry_portrait.jpg?signature=...", "face_match_score": 96.4 }, "wallet_verification": null, "warnings": [] } ``` ```json theme={null} { "status": "Approved", "issuing_state": "DNK", "first_name": "Freja", "last_name": "Nielsen", "full_name": "Freja Nielsen", "date_of_birth": "1988-03-02", "node_id": "first_id_verification", "verification_method": "wallet", "assurance": "cryptographic", "wallet_provider": "mitid", "fallback_from": null, "id_lookup": null, "wallet_verification": { "provider": "mitid", "provider_name": "MitID", "issuing_authority": "Danish Agency for Digital Government", "issuing_country": "DNK", "credential_type": "person_identification", "level_of_assurance": "substantial", "verified_at": "2026-09-04T09:12:44Z", "signature_valid": true, "attributes": { "full_name": "Freja Nielsen", "date_of_birth": "1988-03-02", "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678" }, "portrait": null, "face_match_score": null }, "warnings": [] } ``` ### Verificació NFC Es retorna per a cada lectura del xip d'un document d'identitat: un xip ICAO 9303 ePassport o eID, o una lectura de la Japan My Number Card mitjançant JPKI (`chip_protocol: "jpki"`). Apareix com a `nfc_verifications[]` a `GET /v3/session/{sessionId}/decision/` (un per registre KYC principal). Font: `kyc/serializers/epassport.py:121-139` (`NFCV3Serializer`, amplia `NFCV2Serializer` a `kyc/serializers/epassport.py:83-118`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `status` | string | No | Vegeu [Enumeració d'estat](#referència-d’enumeració-d’estats). | `"Approved"` | | `portrait_image` | string (URL) | Sí | URL prefirmada de la imatge facial extreta del xip. | `"https:///.../nfc_portrait.jpg?..."` | | `signature_image` | string (URL) | Sí | URL prefirmada de la imatge de la signatura extreta del xip (quan s'hi emmagatzema). | `null` | | `chip_data` | object | Sí | Dades personals analitzades dels Data Groups del xip, aplanades (`kyc/utils/epassport.py:165-212`): `dgs` (Data Groups llegits), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (codi de document de la MRZ), `document_number`, `optional_data`, dígits de control de la MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string`, `mrz_type` (`TD1`/`TD2`/`TD3`); a més, `place_of_birth` i `address` (i `full_name` / `full_name_non_latin` per als noms en alfabets no llatins) quan el xip conté DG11; aquestes claus no hi són en cas contrari. `null` quan el pas NFC s'ha omès. | `{ "document_number": "AB1234567", "name": "MARIA" }` | | `authenticity` | object | Sí | `{ sod_integrity, dg_integrity }`; `null` per a una lectura JPKI. `sod_integrity` valida que la signatura del Document Security Object (SOD) forma una cadena de confiança fins a una CSCA vàlida del país emissor (i que la DSC no està revocada ni caducada); `dg_integrity` valida que els hashes de cada Data Group coincideixen amb el SOD. Si tots dos són `true`, el xip és genuí i no s'ha alterat. | `{ "sod_integrity": true, "dg_integrity": true }` | | `certificate_summary` | objecte | Sí | Resum del certificat del signant del document (`kyc/utils/epassport.py:338-348`): `issuer`, `subject`, `serial_number` (enter), `not_valid_before`, `not_valid_after` (`YYYY-MM-DD HH:MM:SS`), més un objecte `validation` `{ csca_verified, dsc_revoked, dsc_expired, csca_expired }` (`kyc/views/epassport.py:86`). | `{ "issuer": "Common Name: CSCA SPAIN, Country: ES", "not_valid_after": "2031-02-18 10:21:11" }` | | `node_id` | cadena \| null | Sí | Identificador del node del flux de treball (V3). | `"first_nfc"` | | `is_nfc_skipped` | booleà | No | `true` quan aquest pas NFC s'ha omès explícitament en lloc de llegir-se; `skip_reason` indica el motiu. | `false` | | `skip_reason` | cadena | Sí | Motiu pel qual es va omitir el pas; només s'estableix quan `is_nfc_skipped` és `true`. Un dels valors següents: `USER_SKIPPED`, `DOCUMENT_WITHOUT_CHIP`, `CHIP_CERTIFICATE_UNAVAILABLE`, `DEVICE_WITHOUT_NFC`, `INTEGRATION_WITHOUT_NFC_ACCESS`, `MRZ_KEY_UNAVAILABLE`, `JPKI_UNAVAILABLE`; consulta [Motius d'omissió](https://docs.didit.me/ca/core-technology/nfc-verification/warnings-nfc-verification.md#motius-d’omissió). El payload de la decisió també inclou un `nfc_skip_reason` a nivell de sessió amb la mateixa taxonomia, que cobreix els passos NFC que es van ometre abans de crear cap informe. | `null` | | `chip_protocol` | cadena | No | Com es llegeix el xip: `icao` (xip ePassport o eID de l'ICAO 9303) o `jpki` (My Number Card del Japó). En el cas de `jpki`, `portrait_image`, `signature_image`, `chip_data`, `authenticity` i `certificate_summary` són `null`. També s'estableix en els passos omesos. | `"icao"` | | `jpki` | objecte | Sí | El que demostra una lectura de la My Number Card: `certificate_types`, `chain_valid`, `signature_valid`, `revocation_status` (`good`, `revoked` o `unchecked`), `ca_generation`, `certificate_expires_at`, `certificates[]`, `attributes` (nom, data de naixement, sexe i adreça del certificat de signatura), `attributes_match_ocr` i `mismatched_attributes`. Mai inclou els certificats, els seus números de sèrie ni les signatures. És `null` per als xips ICAO, per als passos omesos i quan el pas s'ha tancat sense cap lectura de la targeta. Consulta [Camps de JPKI](https://docs.didit.me/ca/core-technology/nfc-verification/report-nfc-verification.md#camps-jpki). | `null` | | `warnings` | matriu | No | Consulta [Objecte d'advertència](#objecte-d’advertència). | `[]` | ```json theme={null} { "status": "Approved", "portrait_image": "https:///.../nfc_portrait.jpg?signature=...", "signature_image": null, "chip_data": { "dgs": ["DG1", "DG2", "DG11"], "surname": "GARCIA LOPEZ", "name": "MARIA", "country": "ESP", "nationality": "ESP", "birth_date": "1990-05-12", "expiry_date": "2032-05-11", "sex": "F", "document_type": "P", "document_number": "AB1234567", "optional_data": "", "birth_date_hash": "4", "expiry_date_hash": "7", "document_number_hash": "3", "optional_data_hash": "", "final_hash": "8", "mrz_string": "P/.../reference.jpg?..."` | | `video_url` | cadena (URL) | Sí | URL pre-signada del vídeo de la prova de vida (només en mode actiu). | `"https:///.../liveness.webm?..."` | | `age_estimation` | float | Sí | Edat estimada (en anys) del rostre més gran de la imatge de referència. | `34.2` | | `matches` | matriu d'objectes | No | Coincidències facials entre sessions. Cada element: `{ session_id, session_number, similarity_percentage, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details: { full_name, document_type, document_number }, match_image_url, status, is_blocklisted, is_allowlisted, api_service, source }`. `source` és `session`, `imported`, `list_entry` o `retained_template`. Una coincidència de plantilla retinguda té `vendor_user_id`, `vendor_data` i `biometric_template_id`; els seus camps de sessió, imatge, detalls d'identitat, estat i servei d'API són `null`. | `[]` | | `face_quality` | float (0-100) | Sí | Puntuació de qualitat facial de la prova de vida passiva (normalitzada a un percentatge). | `87.50` | | `face_luminance` | float (0-100) | Sí | Puntuació de lluminositat facial de la prova de vida passiva (normalitzada de 0-255 a un percentatge). | `54.12` | | `node_id` | cadena \| null | Sí | Identificador del node del flux de treball (V3). | `"first_liveness"` | | `warnings` | matriu | No | Consulta [Objecte d'advertència](#objecte-d’advertència). | `[]` | ```json theme={null} { "status": "Approved", "method": "PASSIVE", "score": 92.41, "reference_image": "https:///.../reference.jpg?signature=...", "video_url": null, "age_estimation": 34.2, "matches": [], "face_quality": 87.50, "face_luminance": 54.12, "node_id": "first_liveness", "warnings": [] } ``` ### Coincidència facial Es retorna per cada comparació facial (normalment el rostre de la prova de vida de l'usuari amb el retrat del document). Apareix com a `face_matches[]` a `GET /v3/session/{sessionId}/decision/`. Font: `face/serializers/face.py:367-389` (`FaceMatchV3Serializer`, que estén `FaceMatchV2Serializer` a `face/serializers/face.py:323-364`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `status` | cadena | No | Consulta [Enumeració d'estats](#referència-d’enumeració-d’estats). | `"Approved"` | | `score` | float (0-100) | Sí | Similitud, arrodonida a 2 decimals. Quan el proveïdor només retorna un `unmatched_faces[].Confidence`, es converteix a `100 - confidence`. | `97.83` | | `source_image_session_id` | cadena (UUID) | Sí | La sessió que va proporcionar la imatge d'origen (de referència) a partir del seu retrat emmagatzemat. S'estableix en fluxos basats en retrats (autenticació biomètrica, o un retrat aportat en crear la sessió). És `null` quan la referència és el retrat del document de la mateixa sessió. | `null` | | `source_image` | cadena (URL) | Sí | URL pre-signada de la imatge d'origen (de referència): normalment el retrat del document, o el retrat emmagatzemat en els fluxos d'autenticació biomètrica. | `"https:///.../source.jpg?..."` | | `target_image` | cadena (URL) | Sí | URL pre-signada de la imatge objectiu (rostre en directe) capturada durant la prova de vida. | `"https:///.../target.jpg?..."` | | `node_id` | cadena \| null | Sí | Identificador del node del flux de treball (V3). | `"first_face_match"` | | `warnings` | matriu | No | Consulta [Objecte d'advertència](#objecte-d’advertència). | `[]` | | `face_coverage` | objecte | Sí | Indica si els `eyes`, la `mouth` i el `face` estan coberts a la imatge capturada. Cada regió té `covered`, `calibrated` i `visibility_score`; `calibrated: false` és una evidència d'ombra que no activa cap advertència. Es retorna només a `GET /v3/session/{sessionId}/decision/`, mai en payloads de webhook. | `{ "eyes": { "covered": false, "calibrated": true, "visibility_score": 0.98 } }` | ```json theme={null} { "status": "Approved", "score": 97.83, "source_image_session_id": null, "source_image": "https:///.../source.jpg?signature=...", "target_image": "https:///.../target.jpg?signature=...", "node_id": "first_face_match", "warnings": [] } ``` ### Cerca facial Retornat per l'API de cerca facial independent (`POST /v3/face-search/`). La cerca facial mai no apareix com un array en plural a `/v3/session/{sessionId}/decision/`. Quan es persisteix amb `save_api_request=true`, la sessió apareix allà com una entrada `FACE_SEARCH` dins de `features[]`, més un element `liveness_checks[]` que conté els `matches` emmagatzemats. Fonts: `apis/serializers/face_search.py:8-79` (`FaceSearchResponseSerializer`, que envolta `FaceSearchDetailsSerializer`); els diccionaris de coincidències es construeixen a `face/utils/utils.py:869-884`. Resposta de nivell superior: | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `request_id` | string (UUID) | No | L'id de sessió persistit quan `save_api_request=true` (utilitzable amb `GET /v3/session/{sessionId}/decision/`); en cas contrari, un UUID de correlació transitori. | `"4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f"` | | `face_search` | object | No | Dades de detall de la cerca; vegeu els camps següents. | — | | `vendor_data` | string | Sí | `vendor_data` de la sol·licitud, retornat tal qual. | `null` | | `metadata` | object | Sí | `metadata` de la sol·licitud, retornat tal qual. | `null` | | `created_at` | string (ISO 8601) | No | Marca de temps de la sol·licitud al servidor. | `"2026-06-12T01:04:42.763237+00:00"` | Objecte `face_search`: | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `status` | string | No | `Declined` només quan s'ha activat una advertència `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST`; `Approved` en la resta de casos. Les coincidències duplicades per si soles mai no rebutgen (`apis/views/face_search.py:242-248`). | `"Approved"` | | `total_matches` | integer | No | Nombre de coincidències retornades a `matches[]` (0–5). | `1` | | `matches` | array d'[objectes de coincidència de cerca facial](#objecte-de-coincidència-de-cerca-facial) | No | Fins a 5 coincidències per sobre del llindar mínim de similitud, ordenades per similitud descendent (primer les entrades de la llista de bloqueig, amb `search_type=blocklisted_or_approved`). | `[…]` | | `user_image` | object | No | Resultat de la detecció per a la imatge enviada: `{ entities: [{ bbox, confidence }], best_angle }`, amb una entitat per cada cara detectada. | `{ "entities": [{ "bbox": [40, 40, 120, 120], "confidence": 0.73 }], "best_angle": 0 }` | | `warnings` | array d'objectes | No | Forma reduïda de les advertències per a aquesta API independent, sense `node_id`. El contracte del serialitzador declara `{ risk, additional_data, log_type, short_description, long_description }` (`apis/serializers/face_search.py:49-54`); la càrrega en temps d'execució també inclou `feature`, sempre `"LIVENESS"` (`apis/views/face_search.py:332-341`). | `[]` | #### Objecte de coincidència de cerca facial | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `session_id` | string (UUID) | Sí | La sessió de verificació coincident. `null` quan `source` és `imported`, `list_entry` o `retained_template`. | `"a3f2a6f1-…"` | | `session_number` | integer | Sí | Número de la sessió coincident, més fàcil de llegir a la consola; `null` per a coincidències que no són de sessió. | `1024` | | `similarity_percentage` | float (0-100) | No | Similitud entre la cara enviada i la cara coincident. | `96.42` | | `source` | string (enum) | No | D'on es va registrar la cara coincident: `session` (sessió de verificació o crida independent desada), `imported` (càrrega directa de la cara al perfil d'usuari), `list_entry` (cara afegida a una llista) i `retained_template` ([plantilla biomètrica](https://docs.didit.me/ca/management-api/biometric-templates/overview.md) sense imatge, conservada després que s'eliminés la sessió d'origen). | `"session"` | | `vendor_data` | string | Sí | El `vendor_data` de la sessió coincident o, per a coincidències `imported` i `retained_template`, el de l'usuari vinculat. | `"user-12345"` | | `vendor_user_id` | string (UUID) | Sí | L'usuari vinculat. `null` per a coincidències `list_entry` i per a sessions sense usuari. | `"2f7c1a9e-…"` | | `biometric_template_id` | string (UUID) | Sí | La plantilla conservada que ha coincidit. Només es defineix per a coincidències `retained_template`; utilitzeu-la amb `GET`/`DELETE /v3/biometric-templates/{id}/`. | `null` | | `verification_date` | string (ISO 8601) | Sí | Quan es va capturar la cara coincident, o quan es va conservar una `retained_template`; `null` per a coincidències `list_entry`. | `"2024-11-04T09:14:02Z"` | | `user_details` | object | Sí | `{ full_name, document_type, document_number }` de la verificació de document de la sessió coincident. Per a coincidències `imported` només es defineix `full_name`; és `null` quan no hi ha dades d'identitat, i sempre `null` per a coincidències `retained_template`. | `{ "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" }` | | `match_image_url` | string (URL) | Sí | Cara de referència de l'usuari coincident: URL presignada quan `save_api_request=true`, ruta d'emmagatzematge en brut en cas contrari. Sempre `null` per a coincidències `retained_template`, que no contenen imatge. | `"https:///.../matched.jpg?..."` | | `status` | string | Sí | L'estat de verificació de la sessió coincident (vegeu l'[enumeració d'estats](#referència-d’enumeració-d’estats)); `null` per a coincidències que no són de sessió. | `"Approved"` | | `is_blocklisted` | boolean | No | Indica si la cara coincident és a la vostra llista de bloqueig facial. Sempre `false` per a coincidències `retained_template`; una cara en llista de bloqueig es reporta a part, com a coincidència `list_entry`. | `false` | | `is_allowlisted` | boolean | No | Indica si la cara coincident és en alguna de les vostres llistes d'autorització. | `false` | | `api_service` | string (enum) | Sí | Tipus d'API independent, en majúscules, de la sessió coincident (p. ex. `PASSIVE_LIVENESS`, `FACE_MATCH`); `null` per a sessions de flux de treball i per a coincidències que no són de sessió. | `null` | ```json theme={null} { "request_id": "4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f", "face_search": { "status": "Approved", "total_matches": 1, "matches": [ { "session_id": "a3f2a6f1-1c1c-4eec-8b69-1c1c2f3a2c7f", "session_number": 1024, "similarity_percentage": 96.42, "source": "session", "vendor_data": "user-12345", "verification_date": "2024-11-04T09:14:02Z", "user_details": { "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" }, "match_image_url": "https:///.../matched.jpg?signature=...", "status": "Approved", "is_blocklisted": false, "is_allowlisted": false, "api_service": null } ], "user_image": { "entities": [ { "bbox": [40, 40, 120, 120], "confidence": 0.732973 } ], "best_angle": 0 }, "warnings": [] }, "vendor_data": null, "metadata": null, "created_at": "2026-06-12T01:04:42.763237+00:00" } ``` ### Cribratge AML Retornat per cada entitat cribada. Apareix com a `aml_screenings[]` a `GET /v3/session/{sessionId}/decision/`, tant per a sessions KYC com KYB. Font: `aml/serializers/aml.py:63-85` (`AMLV3Serializer`, que estén `AMLV2Serializer` a `aml/serializers/aml.py:28-60`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `status` | string | No | Vegeu l'[enumeració d'estats](#referència-d’enumeració-d’estats). | `"Approved"` | | `total_hits` | integer | No | Nombre de coincidències del cribratge (sempre present, per defecte `0`). | `2` | | `entity_type` | string (enum) | Sí | `person` o `company` (`EntityTypeChoices`, `common/config/choices.py:675-677`). | `"person"` | | `hits` | array d'objectes | No | Una entrada per cada coincidència. Camps clau: `id`, `caption`, `match` (booleà), `target` (booleà \| null, que indica si l'entitat és l'objectiu directe de la llista), `match_score` (flotant 0-100, confiança d'identitat), `risk_score` (flotant 0-100, risc de l'entitat), `score` (flotant 0-1, obsolet), `datasets[]` (p. ex. `PEP`, `PEP Level 1`-`4`, `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`), `properties` (noms, àlies, dates de naixement, …), `features`, `url`, `first_seen`, `last_seen`, `rca_name`, `risk_view`, `score_breakdown`, `pep_matches`, `sanction_matches`, `warning_matches`, `adverse_media_matches`, `adverse_media_details`, `linked_entities`, `additional_information` i `review_status` (`Unreviewed`, `Confirmed Match`, `False Positive`, `Inconclusive`; es pot editar mitjançant l'endpoint d'actualització de l'estat de les coincidències AML, `AMLHitStatusChoices`). | `[…]` | | `score` | float (0-100) | Sí | Puntuació global de cribratge: la `risk_score` més alta entre les coincidències que no estan marcades com a `False Positive` (`aml/services/aml.py:832-842`); `0` quan tots els resultats són falsos positius. `null` fins que es calcula. | `42.7` | | `screened_data` | object | Sí | Instantània de les dades enviades al cribratge: `full_name`, `nationality`, `date_of_birth`, `document_number`. | `{ "full_name": "María García López", "date_of_birth": "1990-05-12" }` | | `is_ongoing_monitoring_enabled` | boolean | No | Si l'entitat està subscrita als recribratges del monitoratge continu. | `false` | | `next_ongoing_monitoring_bill_date` | string (YYYY-MM-DD) | Sí | Calculada com a `last_aml_bill_date + 365 days` quan el monitoratge continu està activat. Una data de **facturació**, no una data de cribratge. | `null` | | `last_ongoing_screening_at` | string (ISO 8601) | Sí | Moment en què el monitoratge continu va completar per última vegada un recribratge d'aquest registre, tant si el resultat va canviar com si no. `null` quan mai no s'ha recribrat; mai no s'omple retroactivament. | `"2026-09-12T04:03:11Z"` | | `last_ongoing_screening_datasets_updated_at` | string (ISO 8601) | Sí | L'actualització més recent del conjunt de dades AML que el proveïdor va informar per a aquest cribratge. `null` quan no es va informar cap data del conjunt de dades; mai no s'estima. | `null` | | `node_id` | string \| null | Sí | Identificador del node del flux de treball (V3). | `"first_aml"` | | `warnings` | array | No | Vegeu [Objecte d'advertència](#objecte-d’advertència). | `[]` | ```json theme={null} { "status": "In Review", "total_hits": 1, "entity_type": "person", "hits": [ { "id": "Q7XW3-aml-hit-1", "caption": "Maria Garcia Lopez", "match": true, "target": true, "match_score": 86.4, "risk_score": 42.7, "datasets": ["PEP Level 2"], "properties": { "name": ["María García López", "M. García"], "alias": ["Maria Garcia"], "birthDate": ["1990-05-12"] }, "url": "https://example.org/registry/entities/Q7XW3", "first_seen": "2023-11-02T00:00:00Z", "last_seen": "2026-05-01T00:00:00Z", "review_status": "Unreviewed" } ], "score": 42.7, "screened_data": { "full_name": "María García López", "date_of_birth": "1990-05-12", "nationality": "ES", "document_number": "AB1234567" }, "is_ongoing_monitoring_enabled": false, "next_ongoing_monitoring_bill_date": null, "last_ongoing_screening_at": null, "last_ongoing_screening_datasets_updated_at": null, "node_id": "first_aml", "warnings": [] } ``` ### Anàlisi d'IP Es retorna per cada ubicació de xarxa capturada. Apareix com a `ip_analyses[]` a `GET /v3/session/{sessionId}/decision/` tant per a sessions KYC com KYB. Font: `kyc/serializers/location.py:196-243` (`IPAnalysisSerializerV3`). | Camp | Tipus | Admet null | Descripció | Exemple | | - | - | - | - | - | | `status` | string | No | Vegeu [Enumeració d'estats](#referència-d’enumeració-d’estats). | `"Approved"` | | `node_id` | string \| null | Sí | Identificador del node del flux de treball (V3). | `"first_ip_analysis"` | | `device_brand` | string | Sí | Marca del dispositiu obtinguda de l'agent d'usuari. | `"Apple"` | | `device_model` | string | Sí | Model del dispositiu. | `"iPhone"` | | `browser_family` | string | Sí | Família del navegador. | `"Mobile Safari"` | | `os_family` | string | Sí | Família del sistema operatiu. | `"iOS"` | | `platform` | string | Sí | Plataforma d'alt nivell (`mobile`, `desktop`, `tablet`). | `"mobile"` | | `device_fingerprint` | string | Sí | Hash d'empremta del dispositiu, estable per a cada dispositiu. | `"f2a3…"` | | `ip_country` | string | Sí | Nom del país resolt a partir de la IP. | `"Spain"` | | `ip_country_code` | string (ISO 3166-1 alpha-2) | Sí | Codi del país resolt a partir de la IP. | `"ES"` | | `ip_state` | string | Sí | Regió o estat resolt a partir de la IP. | `"Comunidad de Madrid"` | | `ip_city` | string | Sí | Ciutat resolta a partir de la IP. | `"Madrid"` | | `latitude` | float | Sí | Latitud derivada de la IP. | `40.4168` | | `longitude` | float | Sí | Longitud derivada de la IP. | `-3.7038` | | `ip_address` | string | Sí | L'adreça IP capturada. | `"203.0.113.42"` | | `isp` | string | Sí | Nom de l'ISP. | `"Telefonica de Espana"` | | `organization` | string | Sí | Nom de l'organització (sovint igual que l'ISP). | `"Telefonica de Espana"` | | `is_vpn_or_tor` | boolean | Sí | `true` quan la IP pertany a una VPN, un proxy o un node de sortida de Tor. | `false` | | `is_data_center` | boolean | Sí | `true` quan la IP pertany a un ASN conegut d'allotjament o de centre de dades. | `false` | | `time_zone` | string | Sí | Nom del fus horari IANA. | `"Europe/Madrid"` | | `time_zone_offset` | string | Sí | Desplaçament respecte a UTC. | `"+02:00"` | | `ip` | object | No | `{ location, distance_from_id_document, distance_from_poa_document }`. `location = { latitude, longitude }`. Distàncies en km, `null` quan falta alguna de les dues parts. | `{ "location": { "latitude": 40.4168, "longitude": -3.7038 }, "distance_from_id_document": 3.4, "distance_from_poa_document": 1.1 }` | | `id_document` | object | No | `{ location, distance_from_ip, distance_from_poa_document }`. Ubicació del document d'identitat resolta a partir de `issuing_state` i de l'adreça analitzada. | `{ "location": { "latitude": 40.4165, "longitude": -3.7026 }, "distance_from_ip": 3.4, "distance_from_poa_document": 4.0 }` | | `poa_document` | object | No | `{ location, distance_from_ip, distance_from_id_document }`. Adreça del comprovant de domicili geocodificada. | `{ "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }` | | `matches` | array of objects | No | Coincidències d'IP i de dispositiu entre sessions. Cada element: `{ session_id, session_number, vendor_data, verification_date, match_type, match_source, matched_value, status, is_blocklisted, api_service, source, device_info, location_info, confidence, match_mode }`. `match_type` és `ip_address` o `device_fingerprint`; `match_source` és `ip_address`, `persistent_id`, `legacy_fp` o `recovered_high` (les coincidències recuperades també porten `recovery_similarity`, `tls_ja4_corroborated` i `recovery_gate_reason`). Limitat a 5 coincidències d'IP i 5 de dispositiu. | `[]` | | `warnings` | array | No | Vegeu [Objecte d'advertència](#objecte-d’advertència). | `[]` | | `browser_version`, `os_version` | string | Sí | Versions del navegador i del sistema operatiu obtingudes de l'agent d'usuari. | `"17.4"` | | `user_agent`, `accept_language` | string | Sí | La cadena d'agent d'usuari i la capçalera `Accept-Language` que va enviar el navegador. | `"en-US,en;q=0.9"` | | `session_identifier`, `session_age_ms` | string, integer | Sí | La sessió de navegació en què es va executar el pas i la seva antiguitat en mil·lisegons. | `48210` | | `coords_accuracy` | float | Sí | Radi de precisió, en metres, de les coordenades que va informar el dispositiu. | `35.0` | | `raw_device_data` | object | Sí | Senyals bruts del dispositiu recollits per al pas. | `{}` | ```json theme={null} { "status": "Approved", "node_id": "first_ip_analysis", "device_brand": "Apple", "device_model": "iPhone", "browser_family": "Mobile Safari", "os_family": "iOS", "platform": "mobile", "device_fingerprint": "f2a3c1de8b994a3f9e4cdf3a02b1a7c9", "ip_country": "Spain", "ip_country_code": "ES", "ip_state": "Comunidad de Madrid", "ip_city": "Madrid", "latitude": 40.4168, "longitude": -3.7038, "ip_address": "203.0.113.42", "isp": "Telefonica de Espana", "organization": "Telefonica de Espana", "is_vpn_or_tor": false, "is_data_center": false, "time_zone": "Europe/Madrid", "time_zone_offset": "+02:00", "ip": { "location": { "latitude": 40.4168, "longitude": -3.7038 }, "distance_from_id_document": 3.4, "distance_from_poa_document": 1.1 }, "id_document": { "location": { "latitude": 40.4165, "longitude": -3.7026 }, "distance_from_ip": 3.4, "distance_from_poa_document": 4.0 }, "poa_document": { "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }, "matches": [], "warnings": [] } ``` ### Verificació de la ubicació Es retorna per cada pas de [Verificació de la ubicació](https://docs.didit.me/ca/core-technology/location-verification/overview.md). Apareix com a `geolocation_checks[]` a `GET /v3/session/{sessionId}/decision/`: un element per pas, el de l'intent acceptat. `geolocation_attempts[]` llista tots els intents de tots els passos, del més antic al més recent. Tots dos són `null` per a un flux de treball sense el pas. Font: `GeolocationDecisionSerializer`. | Camp | Tipus | Admet null | Descripció | Exemple | | - | - | - | - | - | | `node_id` | string | Sí | Node del flux de treball que va produir el resultat. | `"geolocation_1"` | | `status` | cadena | No | Consulteu [Enumeració d'estats](#referència-d’enumeració-d’estats). | `"Declined"` | | `outcome` | cadena | Sí | Què ha passat en l'intent: `verified`, `low_accuracy`, `accuracy_undetermined`, `stale`, `approximate`, `denied`, `restricted`, `unavailable`, `timeout`, `mock_detected`, `outside_geofence`, `in_blocked_area`, `anonymizer_detected`, `skipped`, `replay_rejected` o `unsupported_client`. | `"outside_geofence"` | | `permission` | cadena | Sí | Què ha concedit el sistema: `granted_precise`, `granted_approximate`, `denied`, `restricted`, `unavailable`, `timeout`, `dismissed` o `not_requested`. | `"granted_precise"` | | `latitude`, `longitude` | flotant | Sí | Posició WGS84. `null` quan no hi ha posició. | `48.8566` | | `accuracy_m` | flotant | Sí | Radi d'incertesa en metres. | `35.0` | | `accuracy_confidence` | cadena | Sí | `p95`, `p68` o `unspecified`. | `"p95"` | | `measured_at`, `age_seconds` | data i hora, enter | Sí | Quan el dispositiu va obtenir la posició, i els segons fins que Didit la va rebre. | `2` | | `source`, `platform`, `sdk_version` | cadena | Sí | D'on prové la posició, el client que la va produir i la seva versió de l'SDK. | `"browser"` | | `is_mock`, `produced_by_accessory` | booleà | Sí | Evidència de suplantació que reporta la plataforma. `null` vol dir que la plataforma no la reporta. | `null` | | `integrity` | cadena | No | `attested`, `not_attested`, `failed`, `unsupported` (web) o `not_determined`. | `"unsupported"` | | `country_code`, `region_code`, `city` | cadena | Sí | El lloc que correspon a la posició. | `"FR"` | | `geofence`, `inside_geofence`, `geofence_basis`, `inside_areas`, `blocked_areas` | objecte, booleà, cadena, matrius | Sí | El resultat del país i de l'àrea. | `{ "enabled": true, "result": "outside" }` | | `position_source`, `anonymizers` | cadena, objecte | Sí | D'on obté la posició el pas, i els senyals de VPN, proxy, Tor, suplantació i emulador. | `"device_and_ip"` | | `ip_distance_km`, `ip_distance_uncertainty_km`, `ip_consistent`, `document_distance_km`, `travel_excused`, `consecutive_mismatches` | nombre, booleà, enter | Sí | Les comparacions amb la ubicació de la IP i l'adreça registrada. | `12.4` | | `attempts` | enter | No | El número de l'intent dins del pas. | `3` | | `consent` | objecte | Sí | `accepted_at`, `version` i `locale` de l'avís que la persona ha acceptat. | | | `warnings` | matriu d'[objectes d'advertència](#objecte-d’advertència) | No | Les advertències `LOCATION_*` del pas. No hi són a `geolocation_attempts[]`, que afegeix `received_at` i `created_at`. | `[]` | Tots els camps i exemples són a l'[Informe de verificació de ubicació](https://docs.didit.me/ca/core-technology/location-verification/report-location-verification.md). ### Comprovant de domicili Es retorna per cada document d'adreça enviat. Apareix com a `poa_verifications[]` a `GET /v3/session/{sessionId}/decision/`. Font: `poa/serializers/poa.py:212-227` (`POAV3Serializer`, amplia `POAV2Serializer` a `poa/serializers/poa.py:173-209`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `status` | cadena | No | Consulteu [Enumeració d'estats](#referència-d’enumeració-d’estats). | `"Approved"` | | `issuing_state` | cadena (ISO 3166-1 alpha-3) | Sí | Codi de país de l'emissor del document. | `"ESP"` | | `document_type` | cadena | No | Tipus general de `PoaDocumentTypeChoices` (`common/config/choices.py:868-873`): `UTILITY_BILL`, `BANK_STATEMENT`, `GOVERNMENT_ISSUED_DOCUMENT`, `OTHER_POA_DOCUMENT`. Té `UNKNOWN` com a valor alternatiu — mai `null`. | `"UTILITY_BILL"` | | `document_subtype` | cadena | No | Codi de subtipus de `PoaDocumentSubtypeChoices` (p. ex. `ELECTRICITY_BILL`, `WATER_BILL`, `ACCOUNT_STATEMENT`). Té `UNKNOWN` com a valor alternatiu — mai `null`. | `"ELECTRICITY_BILL"` | | `issuer` | cadena | Sí | Nom de l'entitat emissora. | `"Iberdrola"` | | `issue_date` | cadena (YYYY-MM-DD) | Sí | Data d'emissió del document. | `"2026-04-15"` | | `expiration_date` | cadena (YYYY-MM-DD) | Sí | Data de caducitat impresa al document, quan hi és. | `null` | | `poa_address` | cadena | Sí | Adreça en brut extreta per OCR. | `"Calle Mayor 1, 28001 Madrid"` | | `poa_formatted_address` | cadena | Sí | Adreça geocodificada i formatada. | `"Calle Mayor 1, 28001 Madrid, Spain"` | | `poa_parsed_address` | objecte | Sí | Adreça estructurada (`street_1`, `street_2`, `city`, `region`, `postal_code`, `country` (alpha-2), `address_type`, `document_location`, …). | `{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001" }` | | `document_file` | cadena (URL) | Sí | URL signada prèviament al document pujat. | `"https:///.../poa.pdf?..."` | | `document_language` | cadena | Sí | Idioma detectat del document (ISO 639-1). | `"es"` | | `document_metadata` | objecte | Sí | Metadades filtrades: `file_size`, `content_type`, `creation_date`, `modified_date`, `creator`, `producer`, `software`, `encryption`, `is_signed`, `is_tampered`, `signature_info`, `exif_original_date`, `exif_digitized_date`, `processed_by_known_editor`, `has_different_creation_mod_date`, `overlay_manipulation`. | `{ "file_size": 184221, "content_type": "application/pdf", "is_tampered": false }` | | `extra_fields` | objecte | No | Camps del compte bancari (`bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`), `document_phone_number`, `additional_names`, més qualsevol clau personalitzada desada al registre. | `{ "bank_iban": null, "additional_names": [] }` | | `name_on_document` | cadena | Sí | Nom tal com apareix al comprovant. | `"María García López"` | | `expected_details_address` | cadena | Sí | Adreça que la persona ha escrit durant el registre (textualment). | `"Calle Mayor 1, Madrid"` | | `expected_details_formatted_address` | cadena | Sí | Adreça esperada geocodificada. | `"Calle Mayor 1, 28001 Madrid, Spain"` | | `expected_details_parsed_address` | objecte | Sí | Adreça esperada estructurada. | `{ "city": "Madrid", "postal_code": "28001" }` | | `name_match_score_expected_details` | flotant (0-100) | Sí | Coincidència aproximada entre `name_on_document` i el nom indicat en crear la sessió. | `94.0` | | `name_match_score_id_verification` | flotant (0-100) | Sí | Coincidència aproximada entre `name_on_document` i el `full_name` del document d'identitat verificat. | `100.0` | | `extra_files` | matriu de strings (URL) | No | URL prefirmades dels fitxers addicionals pujats. | `[]` | | `detected_codes` | matriu d'objectes | No | Codis QR i codis de barres detectats a totes les pàgines processades del document: `type`, `page_number` (basat en 1), `position` (polígon), `x`/`y`/`width`/`height` (quadre delimitador), `page_width`/`page_height`, `raw_payload` (base64), `parsed_payload` (valor descodificat, `null` quan s'ha localitzat un codi però no s'ha pogut descodificar). Matriu buida quan la detecció no troba res. | `[{ "type": "QR_CODE", "page_number": 1, "parsed_payload": "https://issuer.example/inv/9981" }]` | | `node_id` | string \| null | Sí | Identificador del node del flux de treball (V3). | `"first_poa"` | | `warnings` | matriu | No | Consulta [Objecte d'advertència](#objecte-d’advertència). | `[]` | ```json theme={null} { "status": "Approved", "issuing_state": "ESP", "document_type": "UTILITY_BILL", "document_subtype": "ELECTRICITY_BILL", "issuer": "Iberdrola", "issue_date": "2026-04-15", "expiration_date": null, "poa_address": "Calle Mayor 1, 28001 Madrid", "poa_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain", "poa_parsed_address": { "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" }, "document_file": "https:///.../poa.pdf?signature=...", "document_language": "es", "document_metadata": { "file_size": 184221, "content_type": "application/pdf", "creation_date": "2026-04-15T08:11:32Z", "modified_date": "2026-04-15T08:11:32Z", "creator": "Iberdrola Billing", "producer": "Adobe PDF Library 15.0", "software": null, "encryption": null, "is_signed": true, "is_tampered": false, "signature_info": { "signer_name": "Iberdrola Clientes", "date": "2026-04-15T08:11:32Z" }, "exif_original_date": null, "exif_digitized_date": null, "processed_by_known_editor": false, "has_different_creation_mod_date": false, "overlay_manipulation": 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": [] }, "name_on_document": "María García López", "expected_details_address": "Calle Mayor 1, Madrid", "expected_details_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain", "expected_details_parsed_address": { "city": "Madrid", "postal_code": "28001", "country": "ES" }, "name_match_score_expected_details": 94.0, "name_match_score_id_verification": 100.0, "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": "aHR0cHM6Ly9pYmVyZHJvbGEuZXMvZmFjdHVyYS85OTgx", "parsed_payload": "https://iberdrola.es/factura/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": "MDA5OTgxMDAwNDI=", "parsed_payload": "0099810042" } ], "node_id": "first_poa", "warnings": [] } ``` ### Verificació de telèfon Es retorna per cada intent de verificació de telèfon. Apareix com a `phone_verifications[]` a `GET /v3/session/{sessionId}/decision/` tant per a sessions de KYC com de KYB. Font: `phone/serializers/phone.py:251-266` (`PhoneV3Serializer`, que amplia `PhoneV2Serializer` a `phone/serializers/phone.py:103-248`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `status` | string | No | Consulta [Enumeració d'estats](#referència-d’enumeració-d’estats). | `"Approved"` | | `phone_number_prefix` | string | No | Prefix de país E.164 (amb `+`). | `"+34"` | | `phone_number` | string | No | Número d'abonat sense el prefix. | `"612345678"` | | `full_number` | string | No | El número E.164 complet (`phone_number_prefix + phone_number`). | `"+34612345678"` | | `country_code` | string (ISO 3166-1 alpha-2) | Sí | País del número. | `"ES"` | | `country_name` | string | Sí | Nom del país localitzat. | `"Spain"` | | `carrier` | objecte | No | `{ name, type }` on `type` és un valor de `LineTypeChoices` (`common/config/choices.py:648-667`): `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, `satellite`, `pager`, `payphone`, `voice_mail`, `unknown`, i altres classes de línia. | `{ "name": "Movistar", "type": "mobile" }` | | `is_disposable` | boolean | No | `true` quan l'operador marca el número com a temporal o d'un sol ús. | `false` | | `is_virtual` | boolean | No | `true` quan `carrier.type` és un dels valors `voip`, `isp` o `vpn`. | `false` | | `verification_method` | string | No | Canal utilitzat per lliurar l'OTP (`whatsapp`, `sms`, …). Es llegeix de `actual_channel` de l'últim intent d'enviament (si no hi és, usa el `channel` sol·licitat i, després, `sms`). | `"whatsapp"` | | `verification_attempts` | integer | No | Nombre total d'intents d'enviament de l'OTP (l'enviament inicial més els reenviaments). | `1` | | `verified_at` | string (ISO 8601) | Sí | Marca de temps en què s'ha introduït correctament l'OTP. | `"2026-05-17T10:14:02Z"` | | `lifecycle` | matriu d'objectes | No | Esdeveniments en ordre cronològic: intents d'enviament, callbacks de lliurament, comprovacions del codi i l'esdeveniment d'estat final. Cada esdeveniment és `{ type, timestamp, details, fee }`. Els tipus d'esdeveniment provenen de `PhoneEventChoices`. | `[…]` | | `matches` | matriu d'objectes | No | Coincidències del número de telèfon entre sessions. Cada element: `{ session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service, source }`. `source` és `session` o `list_entry`. | `[]` | | `node_id` | string \| null | Sí | Identificador del node del flux de treball (V3). | `"first_phone"` | | `warnings` | matriu | No | Consulta [Objecte d'advertència](#objecte-d’advertència). | `[]` | | `phone_intelligence` | objecte | Sí | Senyals d'intel·ligència del telèfon. Només és present quan el complement d'intel·ligència ha processat el número. | | | `phone_social` | objecte | Sí | Petjada social del número. Només és present quan el complement de petjada social ha processat el número. | | ```json theme={null} { "status": "Approved", "phone_number_prefix": "+34", "phone_number": "612345678", "full_number": "+34612345678", "country_code": "ES", "country_name": "Spain", "carrier": { "name": "Movistar", "type": "mobile" }, "is_disposable": false, "is_virtual": false, "verification_method": "whatsapp", "verification_attempts": 1, "verified_at": "2026-05-17T10:14:02Z", "lifecycle": [ { "type": "PHONE_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-05-17T10:13:51Z", "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" }, "fee": 0.02 }, { "type": "PHONE_DELIVERY_DELIVERED", "timestamp": "2026-05-17T10:13:52Z", "details": { "channel": "whatsapp", "status": "delivered" }, "fee": 0 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-05-17T10:14:02Z", "details": { "code_tried": "482917", "status": "Approved" }, "fee": 0 }, { "type": "PHONE_VERIFICATION_APPROVED", "timestamp": "2026-05-17T10:14:02Z", "details": null, "fee": 0 } ], "matches": [], "node_id": "first_phone", "warnings": [] } ``` ### Verificació de correu electrònic Es retorna per cada intent de verificació de correu electrònic. Apareix com a `email_verifications[]` a `GET /v3/session/{sessionId}/decision/` tant per a sessions de KYC com de KYB. Font: `email_verification/serializers/email.py:149-164` (`EmailV3Serializer`, que amplia `EmailV2Serializer` a `email_verification/serializers/email.py:38-146`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `status` | string | No | Consulta [Enumeració d'estats](#referència-d’enumeració-d’estats). | `"Approved"` | | `email` | string | No | L'adreça de correu electrònic enviada. | `"maria.garcia@example.com"` | | `is_breached` | boolean | No | `true` quan el correu apareix en una filtració de dades coneguda. | `false` | | `breaches` | matriu d'objectes | No | Detall per filtració quan `is_breached` és `true`: `{ name, domain, logo_path, breach_date, description, is_verified, data_classes, breach_emails_count }`. | `[]` | | `is_disposable` | boolean | No | `true` quan el correu pertany a un proveïdor de correu d'un sol ús. | `false` | | `is_undeliverable` | boolean | No | `true` quan la sonda de lliurament SMTP indica que la bústia no accepta correu. | `false` | | `verification_attempts` | integer | No | Nombre total d'intents de comprovació de l'OTP. | `1` | | `verified_at` | string (ISO 8601) | Sí | Marca de temps en què s'ha introduït correctament l'OTP. | `"2026-05-17T10:15:22Z"` | | `lifecycle` | matriu d'objectes | No | Esdeveniments en ordre cronològic: intents d'enviament, comprovacions del codi i l'esdeveniment d'estat final. Cada esdeveniment és `{ type, timestamp, details, fee }`. Els tipus d'esdeveniment provenen de `EmailEventChoices`. | `[…]` | | `matches` | matriu d'objectes | No | Coincidències del correu electrònic entre sessions. Cada element: `{ session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service, source }`. `source` és `session` o `list_entry`. | `[]` | | `node_id` | string \| null | Sí | Identificador del node del flux de treball (V3). | `"first_email"` | | `warnings` | matriu | No | Consulta [Objecte d'advertència](#objecte-d’advertència). | `[]` | | `email_intelligence` | objecte | Sí | Senyals d'intel·ligència del correu electrònic. Només és present quan el complement d'intel·ligència ha processat l'adreça. | | | `email_social` | objecte | Sí | Petjada social de l'adreça. Només és present quan el complement de petjada social ha processat l'adreça. | | ```json theme={null} { "status": "Approved", "email": "maria.garcia@example.com", "is_breached": false, "breaches": [], "is_disposable": false, "is_undeliverable": false, "verification_attempts": 1, "verified_at": "2026-05-17T10:15:22Z", "lifecycle": [ { "type": "EMAIL_VERIFICATION_MESSAGE_SENT", "timestamp": "2026-05-17T10:15:11Z", "details": { "status": "Success", "reason": null }, "fee": 0.02 }, { "type": "VALID_CODE_ENTERED", "timestamp": "2026-05-17T10:15:22Z", "details": { "code_tried": "739204", "status": "Approved" }, "fee": 0 }, { "type": "EMAIL_VERIFICATION_APPROVED", "timestamp": "2026-05-17T10:15:22Z", "details": null, "fee": 0 } ], "matches": [], "node_id": "first_email", "warnings": [] } ``` ### Validació en bases de dades Es retorna per cada consulta en bases de dades feta amb les dades enviades per l'usuari. Apareix com a `database_validations[]` a `GET /v3/session/{sessionId}/decision/`. Font: `database_validation/serializers/database_validation.py:21-142` (`DatabaseValidationV3Serializer`, que amplia `DatabaseValidationV2Serializer`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `issuing_state` | cadena (ISO 3166-1 alpha-3) | Sí | País el registre del qual s'ha consultat. | `"ESP"` | | `validation_type` | cadena (enum) | No | Com es va corroborar el resultat: `one_by_one` (resultat d'un únic servei), `two_by_two` (dos o més serveis diferents han fet una coincidència completa del número d'identificació de manera independent) o `not_enabled` (el validador s'ha omès o cap proveïdor no ha respost; un `no_match` definitiu encara retorna `one_by_one`). Mai `null`. Font: `DatabaseValidationChoices` (`common/config/choices.py:1097-1100`). | `"one_by_one"` | | `screened_data` | objecte | No | Les dades enviades al registre. Els camps de fitxer (`selfie`, `cnh_qr_code_image`, `document_image`) contenen URL signades prèviament en el moment de la lectura. | `{ "document_number": "99999999R", "date_of_birth": "1990-05-12" }` | | `validations` | matriu d'objectes | No | Una entrada per cada servei del catàleg que ha produït una coincidència. Cada entrada pot incloure `service_id`, `service_name`, `validation` (objecte de veredicte del proveïdor), `outcome_code`, `outcome_detail` i `source_data` (perfil del ciutadà depurat: `full_name`, `gender`, `date_of_birth`, `photo` (URL prefirmada), `signature` (URL prefirmada), …). | `[…]` | | `errors` | matriu d'objectes | Sí | Errors per servei quan una consulta ha fallat; la clau s'omet del tot quan està buida. Cada entrada és l'objecte d'error del servei d'origen més el `service_id` que l'ha produït. | `[]` | | `match_type` | cadena (enum) | Sí | Veredicte de coincidència agregat entre els serveis consultats: `full_match`, `partial_match` o `no_match` (`DatabaseValidationMatchTypeChoices`, `common/config/choices.py:1103-1106`). `null` fins que s'avalua. | `"full_match"` | | `status` | cadena | No | Vegeu l'[enumeració d'estat](#referència-d’enumeració-d’estats). | `"Approved"` | | `node_id` | cadena \| null | Sí | Identificador del node del flux de treball (V3). | `"first_db_validation"` | | `warnings` | matriu | No | Vegeu l'[objecte d'advertència](#objecte-d’advertència). | `[]` | ```json theme={null} { "issuing_state": "ESP", "validation_type": "one_by_one", "screened_data": { "document_number": "99999999R", "date_of_birth": "1990-05-12", "first_name": "María", "last_name": "García López" }, "validations": [ { "service_id": "esp_dni", "service_name": "Spain - DNI/NIE verification", "validation": { "is_valid": true, "match_score": 100 }, "outcome_code": "MATCH", "outcome_detail": "All identifiers match the registry record.", "source_data": { "full_name": "María García López", "gender": "F", "date_of_birth": "1990-05-12", "photo": "https:///.../registry_photo.jpg?signature=...", "signature": null } } ], "match_type": "full_match", "status": "Approved", "node_id": "first_db_validation", "warnings": [] } ``` ### Resposta del qüestionari Retornada per cada enviament de qüestionari. Apareix com a `questionnaire_responses[]` a `GET /v3/session/{sessionId}/decision/` tant per a sessions KYC com KYB. Font: `questionnaires/serializers/questionnaire.py:591-597` (`QuestionnaireResponseV3Serializer`, que amplia `QuestionnaireResponseSerializer` a `questionnaires/serializers/questionnaire.py:520-588`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `questionnaire_id` | cadena (UUID) | No | Identificador de la versió del qüestionari que s'ha respost. | `"6a0f1c2c-…"` | | `title` | cadena | No | Nom del qüestionari, tal com s'ha definit a la Consola. | `"Customer risk profile"` | | `description` | cadena | Sí | Descripció del qüestionari. | `"Short risk-profile questions."` | | `languages` | matriu de cadenes | No | Codis d'idioma en què es publica el qüestionari. | `["en", "es"]` | | `default_language` | cadena | No | Codi d'idioma de reserva. | `"en"` | | `is_active` | booleà | No | Indica si aquesta versió del qüestionari és la activa. | `true` | | `is_simple_questionnaire` | booleà | No | `true` quan el qüestionari no té bifurcacions (llista plana). | `true` | | `questionnaire_group_id` | cadena (UUID) | No | Identificador compartit per totes les versions del mateix qüestionari. | `"a7c2c2c2-…"` | | `version` | enter | No | Número de versió de la plantilla activa. | `3` | | `status` | cadena | No | Un de `Approved`, `In Review` o `Not Finished` (un rebuig a nivell de qüestionari es correspon amb `In Review`). | `"Approved"` | | `published_at` | cadena (ISO 8601) | Sí | Moment en què es va publicar la plantilla. | `"2026-01-12T11:00:00Z"` | | `sections` | matriu d'objectes | No | Seccions ordenades després d'aplicar el recorregut del graf i el filtratge de visibilitat. Cada secció és `{ title, description, items[] }` (title i description provenen del `SECTION_HEADER` d'obertura, ja traduïts). Cada element és un element de formulari (`uuid`, `value` (identificador del node), `element_type`, `is_required`, `title`, `description`, `placeholder`, `choices`, `max_files`, `required_if`, `repeatable_config`, més un camp `answer`: `null` quan no s'ha respost, i s'omet en els elements de disposició `HEADING`/`PARAGRAPH`/`SEPARATOR`). Les respostes de fitxer contenen `{ files: [, …] }`. | `[…]` | | `node_id` | cadena \| null | Sí | Identificador del node del flux de treball (V3). | `"first_questionnaire"` | ```json theme={null} { "questionnaire_id": "6a0f1c2c-3b7d-4d2c-9eb6-fdc6c7c92ef9", "title": "Customer risk profile", "description": "Short risk-profile questions.", "languages": ["en", "es"], "default_language": "en", "is_active": true, "is_simple_questionnaire": true, "questionnaire_group_id": "a7c2c2c2-1111-4d2c-9eb6-fdc6c7c92ef9", "version": 3, "status": "Approved", "published_at": "2026-01-12T11:00:00Z", "sections": [ { "title": "Source of funds", "description": null, "items": [ { "uuid": "4f1d5e2c-aaaa-4d2c-9eb6-fdc6c7c92ef9", "value": "q_source_of_funds", "element_type": "SINGLE_CHOICE", "is_required": true, "title": "What is your main source of funds?", "description": null, "placeholder": null, "choices": [ { "label": "Salary", "value": "salary" }, { "label": "Business income", "value": "business" }, { "label": "Investments", "value": "investments" } ], "max_files": 1, "required_if": null, "repeatable_config": null, "answer": { "value": "salary" } } ] } ], "node_id": "first_questionnaire" } ``` ### Signatura electrònica Retornada per cada signant d'un pas de [signatura electrònica](https://docs.didit.me/ca/core-technology/electronic-signature/overview.md). Apareix com a `signatures[]` a `GET /v3/session/{sessionId}/decision/` tant per a sessions KYC com KYB, només quan el flux de treball té el pas. A diferència de la resta d'objectes d'informe, el seu `status` és l'etapa de signatura i el resultat és a `verdict`, i els elements de `warnings[]` són `{ code, node_id }` en lloc d'[objectes d'advertència](#objecte-d’advertència). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `id` | cadena (UUID) | No | La signatura del signant. Utilitza-la com a `signature_id` a les rutes d'evidència i de validació. | `"0e6c2a8e-…"` | | `node_id` | cadena | No | Identificador del node del flux de treball. | `"feature_signature"` | | `status` | cadena | No | Etapa de signatura: `intro`, `review`, `code`, `signing`, `signed` o `declined`. Només `signed` significa que els documents estan signats. | `"signed"` | | `verdict` | cadena | No | `Not Finished`, `Approved`, `In Review` o `Declined`. | `"Approved"` | | `level` | cadena | No | `simple` (per defecte) o `aes`. `qes` és un complement que encara no està disponible. | `"aes"` | | `format` | cadena | No | `pdf` per a una signatura simple, `pades` per a una signatura avançada (AES). | `"pades"` | | `profile` | cadena | Sí | `PAdES-B-LT` quan una signatura avançada (AES) està signada; altrament, null. | `"PAdES-B-LT"` | | `signer` | objecte | No | `{ name, capacity, company, role, roles, identity_session_id }`. `capacity` és `self` (KYC) o `company` (KYB). | `{ "name": "Jane Doe", "capacity": "self", … }` | | `identity_used` | objecte | No | `{ session_id, kyc_id, verified, expected_name }`: la identitat verificada en què es basa la signatura. Buit per a una signatura simple sense identitat verificada. | `{ "verified": true, … }` | | `certificate` | objecte | Sí | `{ issuer, issued_to, serial, valid_from, valid_until }`. `null` fins que es signa, i sempre `null` en una signatura simple. | `{ "serial": "5A3F9C21", … }` | | `confirmation` | objecte | No | `{ channel, destination, confirmed_at, attempts }`. `destination` està emmascarat; `attempts` compta els codis introduïts, inclòs el correcte. Una signatura simple no té codi, de manera que `channel` i `destination` són `null`. | `{ "channel": "email", … }` | | `timestamp` | objecte | Sí | `{ time, qualified, valid }`. `qualified` és sempre `false` per a AES. `null` fins que es signi, i sempre `null` per a una signatura simple. | `{ "qualified": false, … }` | | `documents` | array d'objectes | No | `{ id, uuid, title, file_name, pages, size_bytes, sha256_original, sha256_signed, status, opened_at, read_at, read_to_end, consented_at, consent, signed_file, mode, source_format, conversion, fields }`. `status` és `signed`, `declined`, `not_signed` o `not_reached`. `mode` és `fields` o `read_and_agree`. `source_format` és `pdf` o `docx`; `conversion` descriu el fitxer Word original, o és `null` per a un PDF. | `[…]` | | `documents[].fields` | array d'objectes | No | `{ key, type, role, label, page, x, y, width, height, required, value, display_value, value_source, filled_at, image_url, value_unavailable_reason }` per a cada camp del document. `value` és una cadena, un booleà per a una casella de verificació, o `true` per a una signatura o inicials aplicades. Buit per a un document sense camps. | `[…]` | | `adopted_signature` | objecte | Sí | `{ method, font, adopted_at }`: la signatura i les inicials que el signant ha adoptat. `method` és `typed` o `drawn`; `font` és l'estil de cal·ligrafia d'una signatura escrita amb teclat. `null` fins que s'adoptin. | `{ "method": "drawn", … }` | | `electronic_signature_consent_at` | string (ISO 8601) | Sí | Quan el signant va acceptar signar els documents electrònicament. S'estableix quan algun document té camps. | `"2026-11-03T10:41:40Z"` | | `evidence_file` | string | Sí | Ruta del PDF d'evidències, un cop signat. | `"/v3/session/…/evidence/?signature_id=…"` | | `warnings` | array d'objectes | No | `{ code, node_id }`, amb `code` un dels valors següents: `SIGNATURE_DECLINED`, `SIGNATURE_OTP_FAILED`, `SIGNATURE_NAME_MISMATCH`, `SIGNATURE_IDENTITY_NOT_VERIFIED`, `SIGNATURE_DOCUMENT_CHANGED`. | `[]` | | `validation` | objecte | Sí | `{ valid, checked_at, documents[] }`: l'última comprovació criptogràfica dels documents signats. `null` fins que s'hagin signat. `{ valid: null, reason: "signature_provider_outcome_unknown", checked_at }` quan no s'ha pogut confirmar el resultat de la signatura. | `{ "valid": true, … }` | | `declined_at` | string (ISO 8601) | Sí | Quan el signant va rebutjar la signatura. | `null` | | `declined_action` | string | No | L'`signature_declined_action` del pas. | `"REVIEW"` | | `signed_at` | string (ISO 8601) | Sí | Quan es van signar els documents. | `"2026-11-03T10:42:24Z"` | | `expires_at` | string (ISO 8601) | No | Quan l'enllaç de signatura deixa de funcionar. | `"2026-11-10T10:30:00Z"` | | `email_sent_at` | string (ISO 8601) | Sí | Quan es va enviar al signant una còpia signada per correu electrònic. | `"2026-11-03T10:42:30Z"` | | `email_unavailable_reason` | string | Sí | Per què no es va enviar cap còpia, quan se n'havia sol·licitat una. | `null` | | `ip_address` | string | Sí | L'adreça IP del signant quan va demanar el seu codi. | `"203.0.113.10"` | | `place` | string | Sí | No es recull: sempre `null`. | `null` | | `place_unavailable_reason` | string | Sí | `not_collected`. | `"not_collected"` | L'[Informe de signatura electrònica](https://docs.didit.me/ca/core-technology/electronic-signature/report-electronic-signature.md) té un exemple complet i tots els camps imbricats. ### Estimació d'edat Retornat per l'API independent d'Estimació d'edat (`POST /v3/age-estimation/`). La resposta conté un subconjunt de la forma de [`Liveness check`](#prova-de-vida) sota un embolcall `age_estimation` (`status`, `method`, `score`, `age_estimation`, `warnings`), més un bloc `user_image` de detecció de rostres exclusiu de l'API independent; **no** inclou `reference_image`, `video_url`, `matches`, `face_quality` ni `face_luminance`. En les sessions de flux de treball no hi ha un array separat: l'edat estimada apareix com a `liveness_checks[].age_estimation` a `GET /v3/session/{sessionId}/decision/`. Font: `apis/serializers/age_estimation.py:50-55` (`AgeEstimationResponseSerializer`), embolcall muntat a `apis/views/age_estimation.py:138-174`. | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `request_id` | string (UUID) | No | Identificador de sessió persistit quan `save_api_request=true` (el valor per defecte); en cas contrari, un UUID de correlació transitori. | `"3b1f1e2c-…"` | | `age_estimation` | objecte | No | Embolcall del resultat: `status` (`Approved` / `Declined`), `method` (sempre `PASSIVE`), `score` (puntuació de prova de vida de 0 a 100, nul·lable), `age_estimation` (edat predita en anys del rostre més gran, nul·lable), `user_image` (`entities[]` amb `age`, `bbox` `[x_min, y_min, x_max, y_max]`, `confidence` i `gender` per rostre; més `best_angle`), `warnings[]`. | `{ … }` | | `vendor_data` | string | Sí | Valor de `vendor_data` retornat de la sol·licitud. | `null` | | `metadata` | objecte | Sí | Valor de `metadata` retornat de la sol·licitud. | `null` | | `created_at` | string (ISO 8601) | No | Marca de temps de la sol·licitud al servidor. | `"2026-05-17T10:22:13.512941+00:00"` | ```json theme={null} { "request_id": "3b1f1e2c-7777-4d2c-9eb6-fdc6c7c92ef9", "age_estimation": { "status": "Approved", "method": "PASSIVE", "score": 94.10, "age_estimation": 28.7, "user_image": { "entities": [ { "age": 28.7, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" } ], "best_angle": 0 }, "warnings": [] }, "vendor_data": null, "metadata": null, "created_at": "2026-05-17T10:22:13.512941+00:00" } ``` ### Autenticació biomètrica L'autenticació biomètrica executa el mateix flux de processament de prova de vida i coincidència facial que s'usa en el KYC estàndard, però configurat per comparar el rostre capturat amb la imatge de referència d'un usuari existent, en lloc d'un retrat de document extret amb OCR. No hi ha cap serialitzador dedicat: `GET /v3/session/{sessionId}/decision/` retorna els objectes estàndard de [Prova de vida](#prova-de-vida) i [Coincidència facial](#coincidència-facial) sota `liveness_checks[]` i `face_matches[]`. El flux de treball de la sessió es configura amb `workflow_type = "biometric_authentication"` (`WorkflowTypeChoices`, `common/config/choices.py:636`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `liveness_checks` | array de [Prova de vida](#prova-de-vida) | No | Resultat de la prova de vida per al intent d'autenticació. | `[ { "status": "Approved", … } ]` | | `face_matches` | array de [Coincidència facial](#coincidència-facial) | No | Resultat de la coincidència amb la referència registrada. `source_image_session_id` s'estableix al `session_id` propi de la sessió: el rostre de referència (el `portrait_image` proporcionat, o el rostre emmagatzemat reutilitzat mitjançant `vendor_data` quan s'omet `portrait_image`) queda registrat sota la mateixa sessió d'autenticació (`face/views/face.py:656-659`). | `[ { "status": "Approved", "source_image_session_id": "…", … } ]` | | `status` | string | No | Estat de la sessió de nivell superior (vegeu [Enumeració d'estats](#referència-d’enumeració-d’estats)). | `"Approved"` | ```json theme={null} { "session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9", "status": "Approved", "liveness_checks": [ { "status": "Approved", "method": "PASSIVE", "score": 95.10, "reference_image": "https:///.../reference.jpg?signature=...", "video_url": null, "age_estimation": null, "matches": [], "face_quality": 91.20, "face_luminance": 53.10, "node_id": "biometric_auth_liveness", "warnings": [] } ], "face_matches": [ { "status": "Approved", "score": 98.42, "source_image_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9", "source_image": "https:///.../source.jpg?signature=...", "target_image": "https:///.../target.jpg?signature=...", "node_id": "biometric_auth_face_match", "warnings": [] } ] } ``` ### Registre KYB Es retorna per cada empresa confirmada pel registre en un flux de treball KYB. Apareix com a `registry_checks[]` a `GET /v3/session/{sessionId}/decision/` per a les sessions d'empresa. Font: `kyb/serializers/kyb.py:939-964` (`RegistryCheckV3Serializer`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `status` | string | No | Vegeu [Enumeració d'estats](#referència-d’enumeració-d’estats). | `"Approved"` | | `node_id` | string \| null | Sí | Identificador del node del flux de treball (V3). | `"first_registry"` | | `data_resolved` | boolean | No | `true` quan la consulta al registre ha finalitzat (o quan `is_from_registry` és `false`, és a dir, quan les dades s'han introduït manualment). | `true` | | `company` | object | No | Payload complet de l'empresa; vegeu [Objecte d'empresa](#objecte-d’empresa) més avall. | `{ … }` | | `ownership_structure` | object | Sí | La taula de titularitat que el registre va confirmar: `shareholders[]` i `beneficial_owners[]`, amb cada titular, la seva identitat al registre, la participació i el `shareholding` canònic. | `{ "shareholders": [...], "beneficial_owners": [] }` | | `warnings` | array | No | Vegeu [Objecte d'advertència](#objecte-d’advertència). | `[]` | #### Objecte d'empresa Des de `kyb/serializers/kyb.py:220-321` (`KYBCompanyResponseSerializer`). | Camp | Tipus | Nul·lable | Descripció | | - | - | - | - | | `uuid` | string (UUID) | No | Identificador intern de l'empresa. | | `node_id` | string \| null | Sí | Identificador del node del flux de treball. | | `status` | string | No | Estat de la funcionalitat (`FeatureStatusChoices`). | | `registry_status` | string | Sí | Estat de l'empresa al registre (`active`, `dissolved`, …). | | `data_resolved` | boolean | No | Mateixa definició que a l'objecte pare. | | `company_name` | string | Sí | Nom registrat de l'empresa. | | `registration_number` | string | Sí | Identificador del registre. | | `country_code` | string (ISO 3166-1 alpha-2) | Sí | País de constitució. | | `region` | string | Sí | Subdivisió ISO 3166-2 quan escaigui (p. ex. `US-CA`). | | `company_type` | string | Sí | Forma jurídica (`LLC`, `SL`, …). | | `incorporation_date` | string (YYYY-MM-DD) | Sí | Data de constitució. | | `registered_address` | string | Sí | Adreça jurídica registrada. | | `tax_number` | string | Sí | Identificador fiscal o d'IVA. | | `risk_level` | string | Sí | Qualificació de risc facilitada pel proveïdor. | | `verification_status` | string | Sí | Enumeració interna de l'estat de verificació. | | `is_from_registry` | boolean | No | `true` quan la informació procedeix del registre (en lloc de l'entrada manual). | | `fetch_status` | string | Sí | `pending`, `resolved`, `failed`. | | `alternative_names` | string | Sí | Noms comercials alternatius separats per comes. | | `nature_of_business` | string | Sí | Descripció en text lliure de l'activitat empresarial. | | `registered_capital` | string | Sí | Capital social registrat com a cadena de text llegible per a humans. | | `registered_capital_amount` | string (decimal) | Sí | Import processat del capital social registrat. | | `registered_capital_currency` | string (ISO 4217) | Sí | Codi de moneda. | | `website` | string (URL) | Sí | Lloc web de l'empresa. | | `email` | string | Sí | Correu electrònic de contacte públic. | | `phone` | string | Sí | Telèfon de contacte públic. | | `legal_entity_identifier` | string | Sí | LEI quan està disponible. | | `location_of_registration` | string | Sí | Oficina o regió del registre. | | `vat_number` | string | Sí | Número d'IVA presentat per a l'empresa. | | `vat_validation_status` | string | No | Resultat de validar el número d'IVA, o del `tax_number` quan no n'hi ha: `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate` o `not_applicable`. Vegeu [Validació d'IVA i identificador fiscal](https://docs.didit.me/ca/business-verification/company-data.md#validació-de-l’iva-i-del-identificador-fiscal). | | `vat_validated_number` | string | Sí | El número que s'ha comprovat, tal com el coneix la font. | | `vat_validation_source` | string | Sí | Font que va decidir l'estat: `eu_vies`, `pl_vat_white_list`, `no_brreg`, `ch_uid_register`, `br_receita_federal`, `co_rues`, `cr_hacienda`, `ec_sri`, `py_dnit` o `format_rules`. | | `vat_validated_name` | string | Sí | Nom registrat a la font (buit quan no en revela cap). | | `vat_validated_address` | string | Sí | Adreça registrada a la font (buida quan no es revela). | | `vat_checked_at` | string (ISO 8601) | Sí | Marca temporal de la comprovació; `null` quan no s'ha fet cap comprovació. | | `financial_summary` | object | Sí | Instantània dels principals indicadors financers quan els facilita el registre. | | `officers` | array of objects | No | Llista de càrrecs apta per a B2C: `{ uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }`. | | `beneficial_owners` | array of objects | No | Llista de titulars reals (UBO) apta per a B2C: `{ uuid, name, first_name, last_name, entity_type, roles, ownership_min_shares, ownership_max_shares, is_active, kyc_status, kyc_session_url, effective_ownership_percent }`. | | `addresses` | array of objects | Sí | Detall per adreça procedent del registre. | | `industries` | array of objects | Sí | Classificacions d'estil SIC/NAICS. | | `accounts` | array of objects | Sí | Metadades dels comptes presentats. | | `registry_data` | object | Sí | Detall normalitzat del registre de Didit (resultat de la titularitat, correccions de la consola, dades del registre que no tenen camp propi). No és un contracte estable. | | `user_provided_data` | object | Sí | Instantània dels camps editats per l'usuari. | | `confirmed_by_user_at` | string (ISO 8601) | Sí | Marca temporal en què l'usuari va confirmar les dades extretes. | | `last_console_edit_at` | string (ISO 8601) | Sí | Marca temporal de l'última edició a la consola. | | `is_editable` | boolean | No | `true` mentre l'usuari final encara pugui editar les dades procedents del registre. | ```json theme={null} { "status": "Approved", "node_id": "first_registry", "data_resolved": true, "company": { "uuid": "b1f1e2c2-9999-4d2c-9eb6-fdc6c7c92ef9", "node_id": "first_registry", "status": "Approved", "registry_status": "active", "data_resolved": true, "company_name": "Sante Clinics SL", "registration_number": "B12345678", "country_code": "ES", "region": null, "company_type": "SL", "incorporation_date": "2018-03-22", "registered_address": "Calle Mayor 1, 28001 Madrid, Spain", "tax_number": "B12345678", "risk_level": "low", "verification_status": "verified", "is_from_registry": true, "fetch_status": "resolved", "alternative_names": "Sante Clinics", "nature_of_business": "Medical clinic operations", "registered_capital": "EUR 50,000", "registered_capital_amount": "50000.00", "registered_capital_currency": "EUR", "website": "https://santeclinics.com", "email": "info@santeclinics.com", "phone": "+34911223344", "legal_entity_identifier": null, "location_of_registration": "Registro Mercantil de Madrid", "vat_number": "ESB12345678", "vat_validation_status": "valid", "vat_validated_name": "SANTE CLINICS SL", "vat_validated_address": "CALLE MAYOR 1, 28001 MADRID", "vat_checked_at": "2026-05-17T10:11:05Z", "financial_summary": null, "officers": [ { "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9", "name": "María García López", "designation": "Administrador único", "role": "Director", "nationality": "ESP", "is_active": true, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/s/…" } ], "beneficial_owners": [ { "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9", "name": "María García López", "first_name": "María", "last_name": "García López", "entity_type": "person", "roles": ["UBO"], "ownership_min_shares": "75.00", "ownership_max_shares": "75.00", "is_active": true, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/s/…", "effective_ownership_percent": 75.0 } ], "addresses": [], "industries": [], "accounts": [], "registry_data": {}, "user_provided_data": {}, "confirmed_by_user_at": "2026-05-17T10:11:02Z", "last_console_edit_at": null, "is_editable": false }, "ownership_structure": null, "warnings": [] } ``` ### Document KYB Es retorna per cada node que recull documents de suport KYB. Apareix com a `document_verifications[]` a `GET /v3/session/{sessionId}/decision/` per a les sessions d'empresa: una entrada per `node_id`, amb `items[]` que enumera cada document pujat. Font: `kyb/serializers/kyb.py:1053-1068` (`DocumentVerificationV3Serializer`); cada element segueix `kyb/serializers/kyb.py:811-851` (`KYBDocumentResponseSerializer`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `status` | cadena | No | Estat agregat dels documents d'aquest node: `Approved` només quan tots els documents del flux estan aprovats; `Declined` si algun està rebutjat; `In Review` en cas contrari; `Not Finished` mentre estigui pendent. Consulta [Enumeració d'estats](#referència-d’enumeració-d’estats). | `"Approved"` | | `node_id` | cadena \| null | Sí | Identificador del node del flux de treball (V3). | `"first_kyb_documents"` | | `items` | matriu d'[objectes d'elements de documents KYB](#objecte-d’element-d’un-document-kyb) | No | Una entrada per cada document pujat o sol·licitat. | `[…]` | | `groups` | objecte | No | Recomptes per grup de documents: `{ : { total, approved, pending, declined, in_review, other, missing } }`. | `{ "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 } }` | | `required_groups` | matriu de cadenes | No | Grups de documents que requereix la configuració del flux de treball. | `["incorporation_certificate", "shareholder_register"]` | | `warnings` | matriu | No | Consulta [Objecte d'advertència](#objecte-d’advertència). | `[]` | #### Objecte d'element d'un document KYB | Camp | Tipus | Nul·lable | Descripció | | - | - | - | - | | `uuid` | cadena (UUID) | No | Identificador intern del document. | | `document_type` | cadena | Sí | Grup d'alt nivell (`incorporation_certificate`, `shareholder_register`, …). | | `document_subtype` | cadena | Sí | Subtipus específic del proveïdor. | | `document_group` | cadena | Sí | Reflex de `document_type` (àlies mantingut per claredat). | | `file_url` | cadena (URL) | Sí | URL prefirmada del fitxer netejat. | | `original_filename` | cadena | Sí | Nom del fitxer tal com s'ha pujat. | | `file_size` | enter | Sí | Mida del fitxer en bytes. | | `status` | cadena | No | Estat per document (`FeatureStatusChoices`). | | `created_at` | cadena (ISO 8601) | No | Marca de temps de la pujada. | | `cross_check_result` | objecte | Sí | Veredicte de la verificació creuada amb el registre o altres documents. | | `document_metadata` | objecte | Sí | Mateixa estructura de metadades filtrades que `document_metadata` del comprovant de domicili. | | `description` | cadena | Sí | Descripció facilitada pel revisor o pel sistema. | | `is_requested` | booleà | No | `true` quan el flux de treball esperava aquest document. | | `ocr_data` | objecte | Sí | Camps extrets per OCR quan n'hi ha. | | `is_console_upload` | booleà | No | `true` quan el document l'ha pujat un revisor de la consola (exclòs del veredicte agregat). | | `is_confirmed` | booleà | No | `true` quan el revisor ha confirmat explícitament el document. | ```json theme={null} { "status": "Approved", "node_id": "first_kyb_documents", "items": [ { "uuid": "e1f1e2c2-cccc-4d2c-9eb6-fdc6c7c92ef9", "document_type": "incorporation_certificate", "document_subtype": "registro_mercantil_extract", "document_group": "incorporation_certificate", "file_url": "https:///.../incorporation.pdf?signature=...", "original_filename": "incorporation_certificate.pdf", "file_size": 256412, "status": "Approved", "created_at": "2026-05-17T10:08:00Z", "cross_check_result": { "matches_registry_name": true, "matches_registration_number": true }, "document_metadata": { "file_size": 256412, "content_type": "application/pdf", "is_signed": true, "is_tampered": false }, "description": null, "is_requested": true, "ocr_data": { "company_name": "Sante Clinics SL", "registration_number": "B12345678" }, "is_console_upload": false, "is_confirmed": true } ], "groups": { "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 } }, "required_groups": ["incorporation_certificate", "shareholder_register"], "warnings": [] } ``` ### Persona clau KYB Es retorna per cada node de persones clau d'un flux de treball KYB. Apareix com a `key_people_checks[]` a `GET /v3/session/{sessionId}/decision/` per a sessions d'empresa. Font: `kyb/serializers/kyb.py:967-1050` (`KeyPeopleCheckV3Serializer`). | Camp | Tipus | Nul·lable | Descripció | Exemple | | - | - | - | - | - | | `status` | cadena | No | Consulta [Enumeració d'estats](#referència-d’enumeració-d’estats). | `"Approved"` | | `node_id` | cadena \| null | Sí | Identificador del node del flux de treball (V3). | `"first_key_people"` | | `registry` | objecte | No | `{ officers[], beneficial_owners[] }` extrets del registre. Els administradors segueixen `KYBPersonResponseSerializer` (`kyb/serializers/kyb.py:533-645`); els titulars reals segueixen `KYBBeneficialOwnerResponseSerializer` (`kyb/serializers/kyb.py:648-788`, que afegeix `date_of_birth`, `country_of_birth`, `email`, `company_name`, `registration_number`, `entity_type`, `roles`, `ownership_min_shares`, `ownership_max_shares`, `child_beneficial_owners`, `effective_ownership_percent`). Tots dos inclouen l'enriquiment AML i KYC per a cada part (`aml_status`, `kyc_status`, `kyc_session_url`, `kyc_session_id`, `verification_workflow_type`, `verification_workflow_id`, `verification_workflow_label`, `verification_workflow_features`, `didit_internal_id`, `kyc_document_type`, `kyc_nationality`, `kyc_liveness_passed`, `kyc_verified_at`, `kyc_aml_categories`, `kyc_notification_sent_at`). | `{ "officers": [...], "beneficial_owners": [...] }` | | `submitted` | objecte | No | `{ parties[] }` - entrades que l'empresa ha confirmat o enviat mitjançant el flux de persones clau (files de `BusinessParty` amb `source=USER`). Cada part segueix `BusinessPartySubmissionResponseSerializer` (`kyb/serializers/party.py:146-194`): `uuid`, `entity_type`, `source`, `name`, `first_name`, `last_name`, `company_name`, `registration_number`, `email`, `nationality`, `phone_number`, `date_of_birth`, `position`, `custom_fields`, `is_active`, `is_skipped`, `requires_verification`, `roles[]` (`{ role, ownership_percent, voting_percent }`), `kyc_session_id`, `kyc_session_status`, `kyc_session_url`, `kyc_session_deleted`, `kyb_sub_session_id`, `kyb_sub_session_status`, `kyb_sub_session_url`, `kyb_sub_session_deleted`, `verification_workflow_type`, `verification_workflow_id`, `verification_workflow_label`, `verification_workflow_features`, `didit_internal_id`. `kyc_session_deleted` i `kyb_sub_session_deleted` indiquen que una sessió filla s'ha eliminat: el seu estat es manté congelat amb el valor que tenia, el `*_session_url` corresponent torna `null` perquè l'enllaç ja no resol, i la part deixa de bloquejar la sessió pare (la verificació passa a `In Review`). Restableix-lo amb [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](https://docs.didit.me/ca/sessions-api/update-data#omet-una-part-de-key-people). | `{ "parties": [...] }` | | `ubo_kyc_summary` | objecte | Sí | Recomptes dels UBO actius amb KYC vinculat: `{ total, approved, flagged, pending }`. `null` quan cap UBO actiu no té KYC vinculat. | `{ "total": 2, "approved": 2, "flagged": 0, "pending": 0 }` | | `warnings` | matriu | No | Consulta [Objecte d'advertència](#objecte-d’advertència). | `[]` | ```json theme={null} { "status": "Approved", "node_id": "first_key_people", "registry": { "officers": [ { "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9", "name": "María García López", "designation": "Administrador único", "role": "Director", "nationality": "ESP", "appointment_date": "2018-03-22", "termination_date": null, "is_active": true, "address": "Calle Mayor 1, 28001 Madrid", "aml_status": "Approved", "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/s/…", "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9", "verification_workflow_type": "kyc", "verification_workflow_id": "11111111-1111-1111-1111-111111111111", "verification_workflow_label": "KYB officer KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" }, { "feature": "FACE_MATCH", "status": "Approved" } ], "didit_internal_id": "user-12345", "kyc_document_type": "Passport", "kyc_nationality": "ESP", "kyc_liveness_passed": true, "kyc_verified_at": "2026-05-17T10:10:11Z", "kyc_aml_categories": [], "kyc_notification_sent_at": "2026-05-15T08:00:00Z" } ], "beneficial_owners": [] }, "submitted": { "parties": [ { "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9", "entity_type": "person", "source": "USER", "name": "María García López", "first_name": "María", "last_name": "García López", "company_name": null, "registration_number": null, "email": "maria.garcia@example.com", "nationality": "ESP", "phone_number": null, "date_of_birth": "1990-05-12", "position": "Administrador único", "custom_fields": {}, "is_active": true, "is_skipped": false, "requires_verification": true, "roles": [ { "role": "UBO", "ownership_percent": 75.0, "voting_percent": null } ], "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9", "kyc_session_status": "Approved", "kyc_session_url": "https://verify.didit.me/s/…", "kyb_sub_session_id": null, "kyb_sub_session_status": null, "kyb_sub_session_url": null, "verification_workflow_type": "kyc", "verification_workflow_id": "11111111-1111-1111-1111-111111111111", "verification_workflow_label": "KYB officer KYC", "verification_workflow_features": [ { "feature": "ID_VERIFICATION", "status": "Approved" }, { "feature": "LIVENESS", "status": "Approved" } ], "didit_internal_id": "user-12345" } ] }, "ubo_kyc_summary": { "total": 1, "approved": 1, "flagged": 0, "pending": 0 }, "warnings": [] } ``` ## Camps a nivell de decisió Aquestes claus es troben al costat de les matrius de funcionalitats a `GET /v3/session/{sessionId}/decision/` i dins del `decision` d'un webhook. | Camp | Tipus | Admet null | Descripció | | - | - | - | - | | `status_override` | object | Sí | `{ overridden_at, automatic_status }` després que un revisor establís `status` manualment; `null` quan l'estat és l'estat automàtic. | | `decision_trace` | object | No | Com s'ha arribat a l'estat: `status`, `decided_by` (`manual`, `automatic` o `investigator`), `decided_at`, `automatic_status`, `terminal_node_id`, `actor`, `warning_counts` i `status_warnings`. | | `linked_records` | object | Sí | Resums de `same_face`, `earlier_verifications` i `networks`; `null` quan no hi ha res per mostrar. | | `biometric_retention` | object | No | `{ jurisdictions, deletes_at }`. `deletes_at` és la data en què se n'eliminen les dades biomètriques en directe de la sessió, i `null` quan encara no s'aplica cap data. | | `database_validation_not_performed_reason` | object | Sí | `{ code, message }` que explica per què una validació en bases de dades configurada no ha produït cap resultat. | | `assignee`, `waiting_since`, `sla_due_at` | object, datetime | Sí | El revisor de la Console a qui s'ha assignat la sessió i el seu rellotge de revisió; el rellotge és `null` tret que la sessió estigui `In Review`. | | `shared_from_session`, `shared_from_session_number` | UUID, integer | Sí | La sessió d'origen d'una sessió importada. | | `sandbox_scenario` | string | Sí | L'escenari amb què es va crear una sessió de sandbox. | | `fraud_check` | object | Sí | El resultat de l'API de Fraud Check; `null` per a totes les altres sessions. | | `full_session_video`, `full_session_video_recorded_at` | URL, datetime | Sí | La gravació i el moment en què es va fer. Només es retorna quan la teva organització grava vídeo de la sessió completa. | Consulta [Obtenir sessió](https://docs.didit.me/ca/sessions-api/retrieve-session.md#estat-traça-de-decisió-i-camps-de-revisió) per saber com llegir-los. ## Consentiment biomètric Cada decisió de Verificació d'usuaris i cada webhook de sessió inclou un únic objecte `biometric_consent` (no un array): si la sessió requeria consentiment biomètric explícit, per quin motiu, i les proves de la resposta. És `null` quan la sessió mai no es va avaluar, per exemple un flux de treball sense captura facial. Font: `BiometricConsentDecisionSerializer` (`sessions/serializers/biometric_consent.py`). Quan apareix el pas, i què significa cada cas, s'explica a [Consentiment biomètric](https://docs.didit.me/ca/getting-started/biometric-consent.md). Els camps sense valor registrat són `null`, mai una cadena buida. | Camp | Tipus | Descripció | | - | - | - | | `required` | boolean | Si la sessió ha de recollir un consentiment biomètric explícit. Mai no torna a `false`. | | `trigger` | string (enum) \| null | Per què es requereix el consentiment, o com es va complir: `declared_state`, `ip_state`, `ip_unknown`, `document_issuer`, `forced` (el mode de l'aplicació és Always), `customer_collected` (vas enviar `biometric_consent` en crear la sessió). `null` mentre no es requereixi. | | `status` | string (enum) | `not_required`, `pending` (requerit, no concedit), `given`, `declined` (es va registrar una denegació; avui cap pantalla de Didit ofereix l'opció de denegar-lo). | | `given_at` | string (ISO 8601) \| null | Quan es va concedir el consentiment. Per a `customer_collected`, el `given_at` que vas enviar. | | `declined_at` | string (ISO 8601) \| null | Quan es va registrar una denegació. | | `text_version` | string \| null | Identificador de versió del text de consentiment al qual va respondre la persona, o el que vas enviar. | | `text_hash` | string \| null | SHA-256 (hex) del text exacte mostrat, en l'idioma en què es va mostrar. | | `locale` | string \| null | Idioma en què es va mostrar el text. | | `policy_url` | string \| null | La política de dades biomètriques a què enllaçava el pas. | | `step` | string \| null | Pas del flux de treball en què estava la sessió quan la persona va respondre (per exemple `LIVENESS`). | | `node_id` | string \| null | Node del graf del flux de treball en què estava la sessió quan la persona va respondre. | | `ip_address` | string \| null | IP des de la qual va arribar la resposta. | | `ip_country_code` | string \| null | Codi de país ISO 3166-1 alpha-2 de l'adreça IP de la resposta. | | `ip_state` | string \| null | Subdivisió ISO 3166-2 de la IP de la resposta (per exemple `US-IL`). | | `ip_city` | string \| null | Ciutat de la IP de la resposta. | | `user_agent` | string \| null | Agent d'usuari de la sol·licitud de resposta. | | `detected_ip_address` | string \| null | IP de la persona des de la qual es va avaluar per última vegada el requisit. Pot diferir de `ip_address` quan la persona va respondre des d'un altre dispositiu. | | `detected_country_code` | string \| null | Codi de país ISO 3166-1 alpha-2 de l'adreça IP detectada. | | `detected_state` | string \| null | Subdivisió ISO 3166-2 de la IP detectada. | | `detected_city` | string \| null | Ciutat de la IP detectada. | | `declared_state` | string \| null | Subdivisió ISO 3166-2 que vas declarar: `user_state`, o l'estat d'una adreça dels EUA a `expected_details`. | | `document_state` | string \| null | Subdivisió ISO 3166-2 que va emetre el document d'identitat, llegida en la captura de l'ID. | | `jurisdictions` | array de cadenes | Estats dels EUA (codis USPS, per exemple `IL`) als quals la llei biomètrica afecta la persona. `US` quan les proves situen la persona als EUA però no es coneix cap estat. Buida quan no n'és aplicable cap. | | `retention_months` | integer \| null | El límit de retenció biomètrica més breu, en mesos, entre `jurisdictions`. `null` quan no n'és aplicable cap. | | `reason` | string (enum) \| null | `BIOMETRIC_CONSENT_UNSUPPORTED_SDK`: es requeria consentiment i un SDK natiu anterior a 4.10.0, o un que no va informar de la seva versió, va capturar un rostre sense el pas; `status` es manté en `pending`, o en `given` si la persona va acceptar més tard en el flux allotjat. `BIOMETRIC_CONSENT_DECLINED`: es va registrar una denegació (substitueix el motiu del SDK). `null` en cas contrari, i sempre `null` quan la sessió no requeria consentiment. | | `decline_reason` | string \| null | `BIOMETRIC_CONSENT_DECLINED` quan una denegació registrada va acabar la sessió; en cas contrari, `null`. | | `face_data_deleted_at` | string (ISO 8601) \| null | Quan la denegació va eliminar les imatges facials, els vídeos i les plantilles biomètriques facials de la sessió. `null` tret que s'hagi registrat una denegació. | Una sessió a Illinois atesa per un SDK natiu anterior a 4.10.0, que va capturar la selfie sense el pas: ```json theme={null} { "required": true, "trigger": "ip_state", "status": "pending", "given_at": null, "declined_at": null, "text_version": null, "text_hash": null, "locale": null, "policy_url": null, "step": null, "node_id": null, "ip_address": null, "ip_country_code": null, "ip_state": null, "ip_city": null, "user_agent": null, "detected_ip_address": "203.0.113.42", "detected_country_code": "US", "detected_state": "US-IL", "detected_city": "Chicago", "declared_state": null, "document_state": null, "jurisdictions": ["IL"], "retention_months": 36, "reason": "BIOMETRIC_CONSENT_UNSUPPORTED_SDK", "decline_reason": null, "face_data_deleted_at": null } ``` Una persona amb una VPN que surt fora dels EUA, que va acceptar al flux allotjat: ```json theme={null} { "required": true, "trigger": "declared_state", "status": "given", "given_at": "2026-10-13T18:31:07.412000Z", "declined_at": null, "text_version": "bio-consent-2026-10-12", "text_hash": "9b2f0c5e4d8a7f61c3e2b4a5d6f7081923a4b5c6d7e8f90a1b2c3d4e5f6a7b8c", "locale": "en", "policy_url": "https://didit.me/legal/biometric-data-policy", "step": "LIVENESS", "node_id": "feature_liveness_1", "ip_address": "198.51.100.23", "ip_country_code": "ES", "ip_state": "ES-M", "ip_city": "Madrid", "user_agent": "Mozilla/5.0 (iPhone; CPU iPhone OS 18_0_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/18.0 Mobile/15E148 Safari/604.1", "detected_ip_address": "198.51.100.23", "detected_country_code": "ES", "detected_state": "ES-M", "detected_city": "Madrid", "declared_state": null, "document_state": null, "jurisdictions": ["IL"], "retention_months": 36, "reason": null, "decline_reason": null, "face_data_deleted_at": null } ``` ## Referència d'enumeració d'estats Dos espais de valors relacionats comparteixen el nom de camp `status`. Tots els objectes d'informe per funcionalitat d'aquesta pàgina utilitzen l'enumeració a nivell de funcionalitat. El camp `status` de nivell superior de la sessió pare utilitza l'enumeració de sessió, més àmplia. ### Estats a nivell de funcionalitat El camp `status` de tots els objectes d'informe utilitza aquesta enumeració. Font: `common/config/choices.py:343-348` (`FeatureStatusChoices`). | Valor | Significat | | - | - | | `Not Finished` | La funcionalitat s'ha aprovisionat, però l'usuari encara no l'ha completada. | | `Approved` | La funcionalitat ha superat totes les comprovacions. | | `Declined` | La funcionalitat no ha superat almenys una comprovació estricta (consulteu `warnings[]` amb `log_type: "error"`). | | `In Review` | La funcionalitat ha activat senyals de fallada lleu i està pendent de revisió manual (consulteu `warnings[]` amb `log_type: "warning"`). | | `Resub Requested` | Un revisor ha demanat a l'usuari que torni a enviar aquesta funcionalitat. | La verificació de telèfon, de correu electrònic i d'identitat pot mostrar, a més, `Expired` quan el seu pas caduca (`PhoneStatusChoices` a `common/config/choices.py:377-382`, `EmailStatusChoices` a `common/config/choices.py:434-439`). ### Estats a nivell de sessió El camp `status` de nivell superior de la sessió pare utilitza aquesta enumeració. Font: `common/config/choices.py:106-117` (`StatusChoices`). | Valor | Significat | | - | - | | `Not Started` | La sessió s'ha creat, però l'usuari encara no l'ha iniciada. | | `In Progress` | L'usuari ha iniciat el flux; el resultat encara no és definitiu. | | `Approved` | La sessió ha superat totes les comprovacions. | | `Declined` | La sessió no ha superat almenys una comprovació estricta. | | `In Review` | La sessió està pendent de revisió manual. | | `Expired` | La sessió ha caducat abans de completar-se. | | `Abandoned` | L'usuari ha abandonat el flux sense completar-lo. | | `Kyc Expired` | Ha caducat el període de validesa del KYC (s'utilitza en els fluxos de reverificació). | | `Resubmitted` | L'usuari ha tornat a enviar després d'un rebuig anterior; aquesta sessió queda substituïda per una de més recent. | | `Awaiting User` | El sistema espera una acció de l'usuari (per exemple, introduir un codi OTP). | > [!TIP] > > Els valors finals de sessió són `Approved`, `Declined`, `In Review`, `Expired`, `Kyc Expired` i `Abandoned`. Una sessió pot arribar a la seva decisió global mentre una funcionalitat individual continua en `In Review`. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.