Models de dades de Didit

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

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. 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	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://<media-host>/....

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"`

{
  "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 KYC/ID 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	Anul·lable	Descripció	Exemple
`status`	cadena	No	Consulta Enumeració d’estats.	`"Approved"`
`document_type`	cadena	Sí	Classe de document llegible per a persones (`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 el que accepta la configuració de documents del flux de treball. Els documents específics d’una regió inclouen la regió. Llista completa de codis: Subtipus de document.	`"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 del rostre.	`"https://<media-host>/.../portrait.jpg?..."`
`front_image`	cadena (URL)	Sí	URL prefirmada de l’anvers del document netejat.	`"https://<media-host>/.../front.jpg?..."`
`front_video`	cadena (URL)	Sí	URL prefirmada del vídeo de captura de l’anvers (quan estigui disponible).	`"https://<media-host>/.../front.mp4?..."`
`back_image`	cadena (URL)	Sí	URL prefirmada del revers del document netejat.	`"https://<media-host>/.../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 (fotograma complet).	`"https://<media-host>/.../full_front.jpg?..."`
`full_back_image`	cadena (URL)	Sí	Captura del revers sense retallar (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`	float (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`	float (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 presa durant la captura del document. Mateix format d’entrada que `liveness_checks[].matches`. `null` quan la cerca no s’ha executat, `[]` 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í	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’emissió 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 extreta per OCR sense processar.	`"Calle Mayor 1, 28001 Madrid"`
`formatted_address`	cadena	Sí	Adreça geocodificada i 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 estan coberts per l’esquema canònic (per exemple, categories del carnet de conduir).	`{ "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 document 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 prefirmada.	`[]`
`verification_method`	string	No	Quin mètode de verificació d’identitat 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 del catàleg de carteres 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’identitat: `{ method, reason, action }`. S’estableix quan una consulta o un inici de sessió amb cartera ha fallat: a la fila rebutjada quan la configuració 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 de residència 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 de font separats; confirmeu la implantació en producció), `registry_portrait` (URL prefirmada, només per a les fonts que en retornen una) i `face_match_score`.	consulteu més avall
`wallet_verification`	object \| null	Sí	Evidència de credencial, 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`.	consulteu 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 un avís com si no. Cadascuna: `score` (0-100, més alt = més probablement autèntic; el valor més baix, que és el valor utilitzat per a 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, tot i que les puntuacions emmagatzemades continuen visibles. `null` quan la comprovació no s’ha executat. Consulteu 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	Consulteu 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 a la persona que revisés les dades.
`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.	`[]`

{
  "status": "Approved",
  "document_type": "Passport",
  "document_subtype": "PASSPORT_GENERIC",
  "document_number": "AB1234567",
  "personal_number": "99999999R",
  "portrait_image": "https://<media-host>/.../portrait.jpg?signature=...",
  "front_image": "https://<media-host>/.../front.jpg?signature=...",
  "front_video": null,
  "back_image": "https://<media-host>/.../back.jpg?signature=...",
  "back_video": null,
  "full_front_image": "https://<media-host>/.../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 del document s’omple a partir del registre de la font o dels atributs de la cartera, i les claus que no s’apliquen són 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://<media-host>/.../registry_portrait.jpg?signature=...",
    "face_match_score": 96.4
  },
  "wallet_verification": null,
  "warnings": []
}

{
  "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 d’ePassport o eID ICAO 9303, o una lectura de la My Number Card del Japó a través de JPKI (chip_protocol: "jpki"). Apareix com a nfc_verifications[] a GET /v3/session/{sessionId}/decision/ (un per cada registre KYC pare). Font: kyc/serializers/epassport.py:121-139 (NFCV3Serializer, que hereta de NFCV2Serializer a kyc/serializers/epassport.py:83-118).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	string	No	Consulteu Enumeració d’estats.	`"Approved"`
`portrait_image`	string (URL)	Sí	URL prefirmada de la imatge facial extreta del xip.	`"https://<media-host>/.../nfc_portrait.jpg?..."`
`signature_image`	string (URL)	Sí	URL prefirmada de la imatge de la signatura extreta del xip (quan n’hi ha una emmagatzemada al xip).	`null`
`chip_data`	object	Sí	Dades personals extretes 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 MRZ), `document_number`, `optional_data`, dígits de control 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 de `place_of_birth` i `address` (i `full_name` / `full_name_non_latin` per a 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` en una lectura JPKI. `sod_integrity` valida que la signatura del Document Security Object (SOD) s’encadena 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. Quan tots dos són `true`, el xip és autèntic i no s’ha manipulat.	`{ "sod_integrity": true, "dg_integrity": true }`
`certificate_summary`	object	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`), a més d’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`	string \| null	Sí	Identificador del node del flux de treball (V3).	`"first_nfc"`
`is_nfc_skipped`	boolean	No	`true` quan aquest pas NFC s’ha omès explícitament en lloc de llegir-lo; `skip_reason` n’indica el motiu.	`false`
`skip_reason`	string	Sí	Motiu pel qual s’ha omès 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`; consulteu 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 omesos abans de crear cap informe.	`null`
`chip_protocol`	string	No	Com es llegeix el xip: `icao` (xip de passaport electrònic o d’eID segons ICAO 9303) o `jpki` (targeta My Number del Japó). Per a `jpki`, `portrait_image`, `signature_image`, `chip_data`, `authenticity` i `certificate_summary` són `null`. També s’estableix en els passos omesos.	`"icao"`
`jpki`	object	Sí	Què demostra una lectura de la targeta My Number: `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`. No inclou mai els certificats, els seus números de sèrie ni les signatures. `null` per als xips ICAO, per als passos omesos i quan el pas s’ha tancat sense cap lectura de la targeta. Consulteu Camps JPKI.	`null`
`warnings`	array	No	Consulteu Objecte d’advertència.	`[]`

{
  "status": "Approved",
  "portrait_image": "https://<media-host>/.../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<ESPGARCIA<LOPEZ<<MARIA<<<<<<<<<<<<<<<<<<<<AB1234567ESP9005124F3205117<<<<<<<<<<<<<<08",
    "mrz_type": "TD3",
    "place_of_birth": "MADRID",
    "address": "CALLE MAYOR 1, MADRID"
  },
  "authenticity": { "sod_integrity": true, "dg_integrity": true },
  "certificate_summary": {
    "issuer": "Common Name: CSCA SPAIN, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
    "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
    "serial_number": 118120836164494130086420187336801405660,
    "not_valid_before": "2020-11-18 10:21:11",
    "not_valid_after": "2031-02-18 10:21:11",
    "validation": {
      "csca_verified": true,
      "dsc_revoked": false,
      "dsc_expired": false,
      "csca_expired": false
    }
  },
  "node_id": "first_nfc",
  "is_nfc_skipped": false,
  "skip_reason": null,
  "chip_protocol": "icao",
  "jpki": null,
  "warnings": []
}

Comprovació de la prova de vida

Es retorna per cada sessió de prova de vida. Apareix com a liveness_checks[] a GET /v3/session/{sessionId}/decision/. Font: face/serializers/face.py:301-320 (LivenessV3Serializer, amplia LivenessV2Serializer a face/serializers/face.py:216-298).

Camp	Tipus	Admet null	Descripció	Exemple
`status`	string	No	Consulteu Enumeració d’estats.	`"Approved"`
`method`	string (enum)	Sí	`ACTIVE_3D`, `FLASHING` o `PASSIVE` (`LivenessMethodChoices`, `common/config/choices.py:514-517`). La prova passiva s’executa quan les sessions d’escriptori estan permeses i l’usuari utilitza un ordinador d’escriptori.	`"PASSIVE"`
`score`	float (0-100)	Sí	Confiança de la prova de vida, arrodonida amb dos decimals.	`92.41`
`reference_image`	string (URL)	Sí	URL prefirmada del retall facial de referència de l’usuari.	`"https://<media-host>/.../reference.jpg?..."`
`video_url`	string (URL)	Sí	URL prefirmada de la gravació de la prova de vida quan la captura n’ha emmagatzemat una, tant per a la prova activa com per a la passiva. `null` quan la sessió no ha conservat cap gravació.	`"https://<media-host>/.../liveness.webm?..."`
`age_estimation`	float	Sí	Edat estimada (en anys) del rostre més gran de la imatge de referència.	`34.2`
`matches`	array 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 conservada té `vendor_user_id`, `vendor_data` i `biometric_template_id`; els seus camps de sessió, imatge, dades d’identitat, estat i servei d’API són `null`.	`[]`
`face_quality`	float (0-100)	Sí	Puntuació de qualitat facial de la prova passiva (normalitzada com a percentatge).	`87.50`
`face_luminance`	float (0-100)	Sí	Puntuació de lluminositat facial de la prova passiva (normalitzada de 0-255 a un percentatge).	`54.12`
`node_id`	string \| null	Sí	Identificador del node del flux (V3).	`"first_liveness"`
`warnings`	array	No	Consulteu Objecte d’advertència.	`[]`

{
  "status": "Approved",
  "method": "PASSIVE",
  "score": 92.41,
  "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
  "video_url": null,
  "age_estimation": 34.2,
  "matches": [],
  "face_quality": 87.50,
  "face_luminance": 54.12,
  "node_id": "first_liveness",
  "warnings": []
}

Una sessió PASSIVE retorna aquest camp quan la seva captura ha emmagatzemat una gravació, i null quan la sessió no ha conservat cap gravació; l’exemple anterior és una sessió que no n’ha conservat cap.

Coincidència facial

Es retorna per cada comparació de coincidència facial (normalment el rostre en directe de l’usuari contra el retrat del document). Apareix com a face_matches[] a GET /v3/session/{sessionId}/decision/. Font: face/serializers/face.py:367-389 (FaceMatchV3Serializer, amplia FaceMatchV2Serializer a face/serializers/face.py:323-364).

Camp	Tipus	Admet null	Descripció	Exemple
`status`	string	No	Consulteu Enumeració d’estats.	`"Approved"`
`score`	float (0-100)	Sí	Similitud, arrodonida amb dos decimals. Quan el proveïdor només retorna un `unmatched_faces[].Confidence`, es converteix a `100 - confidence`.	`97.83`
`source_image_session_id`	string (UUID)	Sí	La sessió el retrat emmagatzemat de la qual ha proporcionat la imatge d’origen (de referència). S’estableix en fluxos basats en retrat (autenticació biomètrica, o un retrat proporcionat en crear la sessió). `null` quan la referència és el retrat del document de la mateixa sessió.	`null`
`source_image`	string (URL)	Sí	URL prefirmada de la imatge d’origen (de referència): normalment el retrat del document, o el retrat emmagatzemat en fluxos d’autenticació biomètrica.	`"https://<media-host>/.../source.jpg?..."`
`target_image`	string (URL)	Sí	URL prefirmada de la imatge objectiu (rostre en directe) capturada durant la prova de vida.	`"https://<media-host>/.../target.jpg?..."`
`node_id`	string \| null	Sí	Identificador del node del flux (V3).	`"first_face_match"`
`warnings`	array	No	Consulteu Objecte d’advertència.	`[]`
`face_coverage`	object	Sí	Indica si `eyes`, `mouth` i `face` estan coberts a la imatge capturada. Cada regió té `covered`, `calibrated` i `visibility_score`; `calibrated: false` indica una evidència d’ombra sobre la qual no s’activa cap advertència. Retornat només per `GET /v3/session/{sessionId}/decision/`, mai en payloads de webhook.	`{ "eyes": { "covered": false, "calibrated": true, "visibility_score": 0.98 } }`

{
  "status": "Approved",
  "score": 97.83,
  "source_image_session_id": null,
  "source_image": "https://<media-host>/.../source.jpg?signature=...",
  "target_image": "https://<media-host>/.../target.jpg?signature=...",
  "node_id": "first_face_match",
  "warnings": []
}

Cerca facial

Retornat per l’API independent de Cerca facial (POST /v3/face-search/). La Cerca facial mai no apareix com una matriu amb diversos elements a /v3/session/{sessionId}/decision/. Quan es desa amb save_api_request=true, la sessió hi apareix com una entrada FACE_SEARCH dins de features[], més un element de liveness_checks[] que conté les matches desades. Fonts: apis/serializers/face_search.py:8-79 (FaceSearchResponseSerializer que envolta FaceSearchDetailsSerializer); els diccionaris de coincidència es construeixen a face/utils/utils.py:869-884. Resposta de nivell superior:

Camp	Tipus	Nul·lable	Descripció	Exemple
`request_id`	cadena (UUID)	No	L’identificador de la 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`	objecte	No	La càrrega de dades amb els detalls de la cerca; vegeu els camps següents.	—
`vendor_data`	cadena	Sí	El `vendor_data` de la sol·licitud, retornat tal com s’ha enviat.	`null`
`metadata`	objecte	Sí	El `metadata` de la sol·licitud, retornat tal com s’ha enviat.	`null`
`created_at`	cadena (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`	cadena	No	`Declined` només quan s’ha activat una advertència `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST`; `Approved` en cas contrari. Les coincidències duplicades per si soles mai no porten al rebuig (`apis/views/face_search.py:242-248`).	`"Approved"`
`total_matches`	enter	No	Nombre de coincidències retornades a `matches[]` (0–5).	`1`
`matches`	matriu d’objectes de coincidència de cerca facial (vegeu Objecte de coincidència de cerca facial)	No	Fins a 5 coincidències per sobre del llindar de similitud, ordenades per similitud descendent (primer les entrades de la llista de bloqueig, amb `search_type=blocklisted_or_approved`).	`[…]`
`user_image`	objecte	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`	matriu 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 de dades en temps d’execució també inclou `feature`, que sempre és `"LIVENESS"` (`apis/views/face_search.py:332-341`).	`[]`

Objecte de coincidència de cerca facial

Camp	Tipus	Nul·lable	Descripció	Exemple
`session_id`	cadena (UUID)	Sí	La sessió de verificació coincident. `null` quan `source` és `imported`, `list_entry` o `retained_template`.	`"a3f2a6f1-…"`
`session_number`	enter	Sí	Número de la sessió coincident, 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`	cadena (enum)	No	D’on s’ha registrat la cara coincident: `session` (sessió de verificació o crida independent desada), `imported` (cara pujada directament al perfil d’usuari), `list_entry` (cara afegida a una llista) i `retained_template` (plantilla biomètrica sense imatge conservada després que s’eliminés la sessió d’origen).	`"session"`
`vendor_data`	cadena	Sí	El `vendor_data` de la sessió coincident, o el de l’usuari enllaçat per a les coincidències `imported` i `retained_template`.	`"user-12345"`
`vendor_user_id`	cadena (UUID)	Sí	L’usuari enllaçat. `null` per a les coincidències `list_entry` i per a les sessions sense usuari.	`"2f7c1a9e-…"`
`biometric_template_id`	cadena (UUID)	Sí	La plantilla conservada que ha coincidit. Només s’estableix per a les coincidències `retained_template`; utilitzeu-la amb `GET`/`DELETE /v3/biometric-templates/{id}/`.	`null`
`verification_date`	cadena (ISO 8601)	Sí	Quan es va capturar la cara coincident, o quan es va conservar una `retained_template`; `null` per a les coincidències `list_entry`.	`"2024-11-04T09:14:02Z"`
`user_details`	objecte	Sí	`{ full_name, document_type, document_number }` de la verificació del document de la sessió coincident; per a les coincidències `imported` només s’estableix `full_name`; `null` quan no hi ha dades d’identitat i sempre `null` per a les coincidències `retained_template`.	`{ "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" }`
`match_image_url`	cadena (URL)	Sí	La cara de referència de l’usuari coincident: URL signada quan `save_api_request=true`, o la ruta d’emmagatzematge en brut en cas contrari. Sempre `null` per a les coincidències `retained_template`, que no conserven cap imatge.	`"https://<media-host>/.../matched.jpg?..."`
`status`	cadena	Sí	L’estat de verificació de la sessió coincident (vegeu Enumeració d’estats); `null` per a les coincidències que no són de sessió.	`"Approved"`
`is_blocklisted`	booleà	No	Indica si la cara coincident és a la vostra llista de bloqueig facial. Sempre `false` per a les coincidències `retained_template`; una cara de la llista de bloqueig s’informa per separat com a coincidència `list_entry`.	`false`
`is_allowlisted`	booleà	No	Indica si la cara coincident és en una de les vostres llistes d’autorització.	`false`
`api_service`	cadena (enum)	Sí	Tipus d’API independent en majúscules de la sessió coincident (per exemple, `PASSIVE_LIVENESS`, `FACE_MATCH`); `null` per a sessions de flux de treball i per a coincidències que no són de sessió.	`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://<media-host>/.../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

Es retorna per a cada entitat sotmesa a cribratge. Apareix com a aml_screenings[] a GET /v3/session/{sessionId}/decision/ tant per a sessions KYC com KYB. Fonts: 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`	cadena	No	Vegeu Enumeració d’estats.	`"Approved"`
`total_hits`	enter	No	Nombre de coincidències del cribratge (sempre present, per defecte `0`).	`2`
`entity_type`	cadena (enum)	Sí	`person` o `company` (`EntityTypeChoices`, `common/config/choices.py:675-677`).	`"person"`
`hits`	matriu d’objectes	No	Una entrada per cada coincidència. Camps principals: `id`, `caption`, `match` (bool), `target` (bool \| null: si l’entitat és l’objectiu directe de la llista), `match_score` (float 0-100, confiança d’identitat), `risk_score` (float 0-100, risc de l’entitat), `score` (float 0-1, obsolet), `datasets[]` (per exemple, `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`; editable mitjançant l’endpoint d’actualització de l’estat de la coincidència AML, `AMLHitStatusChoices`).	`[…]`
`score`	float (0-100)	Sí	Puntuació general del 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 totes les coincidències 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	Indica 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. És 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 ha canviat com si no. `null` quan mai no s’hi ha fet un recribratge; mai no s’emplena retroactivament.	`"2026-09-12T04:03:11Z"`
`last_ongoing_screening_datasets_updated_at`	string (ISO 8601)	Sí	Actualització més recent del conjunt de dades AML que el proveïdor ha informat per a aquest recribratge. `null` quan el proveïdor no ha informat 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.	`[]`

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

Retornada 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	Pot ser nul	Descripció	Exemple
`status`	string	No	Vegeu 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 derivada 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 estable de l’empremta digital del 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 capturada.	`"203.0.113.42"`
`isp`	string	Sí	Nom del ISP.	`"Telefonica de Espana"`
`organization`	string	Sí	Nom de l’organització (sovint igual que el 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 d’allotjament o de centre de dades conegut.	`false`
`time_zone`	string	Sí	Nom de la zona horària 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 ubicacions.	`{ "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`	matriu d’objectes	No	Coincidències d’IP i 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`). Limitades a 5 coincidències d’IP i 5 de dispositiu.	`[]`
`warnings`	array	No	Vegeu Objecte d’advertència.	`[]`
`browser_version`, `os_version`	string	Sí	Versions del navegador i del sistema operatiu a partir 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 ha enviat el navegador.	`"en-US,en;q=0.9"`
`session_identifier`, `session_age_ms`	string, integer	Sí	La sessió de navegació on s’ha executat el pas i la seva antiguitat en mil·lisegons.	`48210`
`coords_accuracy`	float	Sí	Radi de precisió, en metres, de les coordenades que ha informat el dispositiu.	`35.0`
`raw_device_data`	object	Sí	Senyals bruts del dispositiu recollits per al pas.	`{}`

{
  "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ó d’ubicació

Retornada per cada pas de Verificació d’ubicació. Apareix com a geolocation_checks[] a GET /v3/session/{sessionId}/decision/: un element per pas: l’intent acceptat de cada pas. geolocation_attempts[] enumera 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	Pot ser nul	Descripció	Exemple
`node_id`	string	Sí	Node del flux de treball que ha produït el resultat.	`"geolocation_1"`
`status`	string	No	Vegeu Enumeració d’estats.	`"Declined"`
`outcome`	string	Sí	Què va passar 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`	string	Sí	Què ha concedit el sistema: `granted_precise`, `granted_approximate`, `denied`, `restricted`, `unavailable`, `timeout`, `dismissed` o `not_requested`.	`"granted_precise"`
`latitude`, `longitude`	float	Sí	Posició WGS84. `null` quan no hi ha posició.	`48.8566`
`accuracy_m`	float	Sí	Radi d’incertesa en metres.	`35.0`
`accuracy_confidence`	string	Sí	`p95`, `p68` o `unspecified`.	`"p95"`
`measured_at`, `age_seconds`	datetime, integer	Sí	Quan el dispositiu va obtenir la posició, i els segons que van passar fins que Didit la va rebre.	`2`
`source`, `platform`, `sdk_version`	string	Sí	D’on procedeix la posició, el client que la va produir i la seva versió de l’SDK.	`"browser"`
`is_mock`, `produced_by_accessory`	boolean	Sí	Evidència de suplantació que informa la plataforma. `null` vol dir que la plataforma no la informa.	`null`
`integrity`	string	No	`attested`, `not_attested`, `failed`, `unsupported` (web) o `not_determined`.	`"unsupported"`
`country_code`, `region_code`, `city`	string	Sí	El lloc on es resol la posició.	`"FR"`
`geofence`, `inside_geofence`, `geofence_basis`, `inside_areas`, `blocked_areas`	object, boolean, string, arrays	Sí	El resultat relatiu al país i a l’àrea.	`{ "enabled": true, "result": "outside" }`
`position_source`, `anonymizers`	string, object	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`	number, boolean, integer	Sí	Les comparacions amb la ubicació de la IP i amb l’adreça registrada.	`12.4`
`attempts`	integer	No	El número de l’intent dins del pas.	`3`
`consent`	object	Sí	`accepted_at`, `version` i `locale` de l’avís que la persona va acceptar.
`warnings`	matriu d’objectes 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ó.

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, que amplia POAV2Serializer a poa/serializers/poa.py:173-209).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	string	No	Vegeu Enumeració d’estats.	`"Approved"`
`issuing_state`	string (ISO 3166-1 alpha-3)	Sí	Codi de país de l’emissor del document.	`"ESP"`
`document_type`	string	No	Tipus d’alt nivell de `PoaDocumentTypeChoices` (`common/config/choices.py:868-873`): `UTILITY_BILL`, `BANK_STATEMENT`, `GOVERNMENT_ISSUED_DOCUMENT`, `OTHER_POA_DOCUMENT`. Torna a `UNKNOWN` si no es troba cap valor; mai és `null`.	`"UTILITY_BILL"`
`document_subtype`	string	No	Codi de subtipus de `PoaDocumentSubtypeChoices` (p. ex. `ELECTRICITY_BILL`, `WATER_BILL`, `ACCOUNT_STATEMENT`). Torna a `UNKNOWN` si no es troba cap valor; mai és `null`.	`"ELECTRICITY_BILL"`
`issuer`	string	Sí	Nom de l’entitat emissora.	`"Iberdrola"`
`issue_date`	string (YYYY-MM-DD)	Sí	Data d’emissió del document.	`"2026-04-15"`
`expiration_date`	string (YYYY-MM-DD)	Sí	Data de caducitat impresa al document, quan hi és.	`null`
`poa_address`	string	Sí	Adreça extreta amb OCR sense processar.	`"Calle Mayor 1, 28001 Madrid"`
`poa_formatted_address`	string	Sí	Adreça geocodificada i formatada.	`"Calle Mayor 1, 28001 Madrid, Spain"`
`poa_parsed_address`	object	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`	string (URL)	Sí	URL pre-signada al document pujat.	`"https://<media-host>/.../poa.pdf?..."`
`document_language`	string	Sí	Idioma detectat del document (ISO 639-1).	`"es"`
`document_metadata`	object	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`	object	No	Camps de 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`, i qualsevol clau personalitzada desada al registre.	`{ "bank_iban": null, "additional_names": [] }`
`name_on_document`	string	Sí	Nom tal com apareix al comprovant.	`"María García López"`
`expected_details_address`	string	Sí	Adreça que el client va escriure textualment durant el registre.	`"Calle Mayor 1, Madrid"`
`expected_details_formatted_address`	string	Sí	Adreça esperada geocodificada.	`"Calle Mayor 1, 28001 Madrid, Spain"`
`expected_details_parsed_address`	object	Sí	Adreça esperada estructurada.	`{ "city": "Madrid", "postal_code": "28001" }`
`name_match_score_expected_details`	float (0-100)	Sí	Coincidència aproximada entre `name_on_document` i el nom proporcionat en crear la sessió.	`94.0`
`name_match_score_id_verification`	float (0-100)	Sí	Coincidència aproximada entre `name_on_document` i el `full_name` del document d’identitat verificat.	`100.0`
`extra_files`	array de cadenes (URL)	No	URL prefirmades dels fitxers addicionals pujats.	`[]`
`detected_codes`	array d’objectes	No	Codis QR i de barres detectats a totes les pàgines processades del document: `type`, `page_number` (començant per 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). Array buit 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`	array	No	Vegeu Objecte d’advertència.	`[]`

{
  "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://<media-host>/.../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 KYC com KYB. Font: phone/serializers/phone.py:251-266 (PhoneV3Serializer, amplia PhoneV2Serializer a phone/serializers/phone.py:103-248).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	string	No	Vegeu Enumeració d’estats.	`"Approved"`
`phone_number_prefix`	string	No	Prefix de país E.164 (amb `+`).	`"+34"`
`phone_number`	string	No	Número de l’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 descartable.	`false`
`is_virtual`	boolean	No	`true` quan `carrier.type` és un dels valors `voip`, `isp` o `vpn`.	`false`
`verification_method`	string	No	Canal usat per enviar l’OTP (`whatsapp`, `sms`, …). Es llegeix de `actual_channel` de l’últim intent d’enviament (si no n’hi ha, usa el `channel` sol·licitat i, si tampoc, `sms`).	`"whatsapp"`
`verification_attempts`	integer	No	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è es va introduir correctament l’OTP.	`"2026-05-17T10:14:02Z"`
`lifecycle`	array 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`	array d’objectes	No	Coincidències de 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`	array	No	Vegeu Objecte d’advertència.	`[]`
`phone_intelligence`	objecte	Sí	Senyals d’intel·ligència del telèfon. Només hi són quan s’ha executat el complement d’intel·ligència per al número.
`phone_social`	objecte	Sí	Petjada social del número. Només hi és quan s’ha executat el complement de petjada social.

{
  "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 KYC com KYB. Font: email_verification/serializers/email.py:149-164 (EmailV3Serializer, amplia EmailV2Serializer a email_verification/serializers/email.py:38-146).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	string	No	Vegeu 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 l’adreça apareix en una filtració de dades coneguda.	`false`
`breaches`	array d’objectes	No	Detall de cada 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 l’adreça pertany a un proveïdor de correu descartable.	`false`
`is_undeliverable`	boolean	No	`true` quan la prova de lliurament SMTP indica que la bústia no accepta correu.	`false`
`verification_attempts`	integer	No	Total d’intents de comprovació de l’OTP.	`1`
`verified_at`	string (ISO 8601)	Sí	Marca de temps en què es va introduir correctament l’OTP.	`"2026-05-17T10:15:22Z"`
`lifecycle`	array 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`	array d’objectes	No	Coincidències de 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`	array	No	Vegeu Objecte d’advertència.	`[]`
`email_intelligence`	objecte	Sí	Senyals d’intel·ligència del correu electrònic. Només hi són quan s’ha executat el complement d’intel·ligència per a l’adreça.
`email_social`	objecte	Sí	Petjada social de l’adreça. Només hi és quan s’ha executat el complement de petjada social.

{
  "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 a una base de dades executada 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, amplia DatabaseValidationV2Serializer).

Camp	Tipus	Pot ser nul	Descripció	Exemple
`issuing_state`	cadena (ISO 3166-1 alpha-3)	Sí	País del registre que s’ha consultat.	`"ESP"`
`validation_type`	cadena (enumeració)	No	Com s’ha corroborat el resultat: `one_by_one` (resultat d’un únic servei), `two_by_two` (dos o més serveis diferents han obtingut 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 continua produint `one_by_one`). Mai no és `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`) es signen 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 amb el veredicte del proveïdor), `outcome_code`, `outcome_detail` i `source_data` (perfil de ciutadà depurat: `full_name`, `gender`, `date_of_birth`, `photo` (URL signada prèviament), `signature` (URL signada prèviament), …).	`[…]`
`errors`	matriu d’objectes	Sí	Errors per servei quan una consulta ha fallat; la clau s’omet completament 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 (enumeració)	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 Enumeració de l’estat.	`"Approved"`
`node_id`	cadena \| null	Sí	Identificador del node del flux de treball (V3).	`"first_db_validation"`
`warnings`	matriu	No	Vegeu Objecte d’advertència.	`[]`

{
  "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://<media-host>/.../registry_photo.jpg?signature=...",
        "signature": null
      }
    }
  ],
  "match_type": "full_match",
  "status": "Approved",
  "node_id": "first_db_validation",
  "warnings": []
}

Resposta del qüestionari

Es retorna 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, estén QuestionnaireResponseSerializer a questionnaires/serializers/questionnaire.py:520-588).

Camp	Tipus	Pot ser nul	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 Console.	`"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	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 entre les versions d’un 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í	Quan 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` inicial, ja traduïts). Cada element és un camp 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 omès en els elements de disposició `HEADING`/`PARAGRAPH`/`SEPARATOR`). Les respostes de fitxer contenen `{ files: [<presigned URL>, …] }`.	`[…]`
`node_id`	cadena \| null	Sí	Identificador del node del flux de treball (V3).	`"first_questionnaire"`

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

Es retorna per cada signant d’un pas de Signatura electrònica. Apareix com a signatures[] a GET /v3/session/{sessionId}/decision/ tant per a sessions KYC com KYB, només quan el flux de treball conté el pas. A diferència de la resta d’objectes d’informe, el seu status és la fase 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.

Camp	Tipus	Pot ser nul	Descripció	Exemple
`id`	cadena (UUID)	No	La signatura de la persona 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	Fase 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), `aes` o `qes` (qualificada, un complement).	`"aes"`
`format`	cadena	No	`pdf` per a una signatura simple, `pades` per a l’avançada (AES) i la qualificada (QES).	`"pades"`
`profile`	cadena	Sí	`PAdES-B-LT` quan s’ha signat una signatura avançada (AES) o qualificada (QES); en cas contrari, 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` per a 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, així que `channel` i `destination` són `null`.	`{ "channel": "email", … }`
`timestamp`	objecte	Sí	`{ time, qualified, valid }`. `qualified` és sempre `false` per a AES, on Didit emet la marca de temps; per a QES, la marca la emet el prestador qualificat de serveis de confiança. `null` fins que es signa, i sempre `null` en una signatura simple.	`{ "qualified": false, … }`
`documents`	matriu d’objectes	No	`{ id, uuid, title, language, source_revision, translation_id, 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[].language`	cadena	Sí	Idioma de la versió seleccionada quan va començar l’intent, o `null` si no s’ha definit. S’utilitza una traducció completa i coincident; si no n’hi ha, l’original. Una vegada signat, aquest és l’idioma en què s’ha signat realment.	`"en"`
`documents[].source_revision`	cadena (UUID)	No	Revisió d’origen copiada a l’intent, inclosa quan se selecciona una traducció. És diferent de l’`id` del document del signant.	`"22222222-2222-4222-8222-222222222222"`
`documents[].translation_id`	cadena (UUID)	Sí	Traducció seleccionada, o `null` per a l’original. La còpia del document i la seva selecció d’idioma es mantenen fixes després que comenci l’intent.	`null`
`documents[].fields`	matriu 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 unes inicials aplicades. Buida per a un document sense camps.	`[…]`
`adopted_signature`	objecte	Sí	`{ method, font, adopted_at }`: la signatura i les inicials que ha adoptat el signant. `method` és `typed` o `drawn`; `font` és l’estil manuscrit d’una signatura teclejada. `null` fins que s’adopti.	`{ "method": "drawn", … }`
`electronic_signature_consent_at`	cadena (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`	cadena	Sí	Ruta del PDF d’evidència, una vegada signat.	`"/v3/session/…/evidence/?signature_id=…"`
`warnings`	matriu d’objectes	No	`{ code, node_id }`, amb `code` un de `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 se signin. `{ valid: null, reason: "signature_provider_outcome_unknown", checked_at }` quan no s’ha pogut confirmar el resultat de la signatura.	`{ "valid": true, … }`
`declined_at`	cadena (ISO 8601)	Sí	Quan el signant va rebutjar.	`null`
`declined_action`	cadena	No	L’`signature_declined_action` del pas.	`"REVIEW"`
`signed_at`	cadena (ISO 8601)	Sí	Quan es van signar els documents.	`"2026-11-03T10:42:24Z"`
`expires_at`	cadena (ISO 8601)	No	Quan deixa de funcionar l’enllaç de signatura.	`"2026-11-10T10:30:00Z"`
`email_sent_at`	cadena (ISO 8601)	Sí	Quan es va enviar al signant, per correu electrònic, una còpia signada.	`"2026-11-03T10:42:30Z"`
`email_unavailable_reason`	cadena	Sí	Per què no es va enviar cap còpia per correu electrònic, quan se n’havia sol·licitat una.	`null`
`ip_address`	cadena	Sí	L’adreça IP del signant quan va sol·licitar el seu codi.	`"203.0.113.10"`
`place`	cadena	Sí	No es recull: sempre `null`.	`null`
`place_unavailable_reason`	cadena	Sí	`not_collected`.	`"not_collected"`

L’informe de signatura electrònica conté un exemple complet i tots els camps imbricats.

Estimació d’edat

Retornat per l’API d’Estimació d’edat independent (POST /v3/age-estimation/). La resposta conté un subconjunt de l’estructura de Liveness check dins d’un embolcall age_estimation amb status, method, score, age_estimation i warnings, i a més inclou un bloc user_image de detecció facial 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 una matriu separada: 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), envoltura muntada a apis/views/age_estimation.py:138-174.

Camp	Tipus	Pot ser nul	Descripció	Exemple
`request_id`	cadena (UUID)	No	Identificador de sessió persistit quan `save_api_request=true` (el valor per defecte); en cas contrari, un UUID de correlació temporal.	`"3b1f1e2c-…"`
`age_estimation`	objecte	No	Envoltura del resultat: `status` (`Approved` / `Declined`), `method` (sempre `PASSIVE`), `score` (prova de vida, de 0 a 100, pot ser nul), `age_estimation` (edat predita en anys de la cara més gran, pot ser nul), `user_image` (`entities[]` amb `age` per cara, `bbox` `[x_min, y_min, x_max, y_max]`, `confidence`, `gender`; i també `best_angle`), `warnings[]`.	`{ … }`
`vendor_data`	cadena	Sí	`vendor_data` reenviat des de la sol·licitud.	`null`
`metadata`	objecte	Sí	`metadata` reenviat des de la sol·licitud.	`null`
`created_at`	cadena (ISO 8601)	No	Marca de temps de la sol·licitud al servidor.	`"2026-05-17T10:22:13.512941+00:00"`

{
  "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 procés de prova de vida i coincidència facial que s’utilitza en el KYC estàndard, però configurat per comparar la cara capturada amb la imatge de referència d’un usuari existent, en lloc d’un retrat del document recentment extret amb OCR. No hi ha un serialitzador dedicat: GET /v3/session/{sessionId}/decision/ retorna els objectes estàndard de Comprovació de prova de vida i de Coincidència facial dins de liveness_checks[] i face_matches[]. El flux de treball de la sessió està configurat amb workflow_type = "biometric_authentication" (WorkflowTypeChoices, common/config/choices.py:636).

Camp	Tipus	Nul·lable	Descripció	Exemple
`liveness_checks`	matriu de Comprovació de prova de vida	No	Resultat de la prova de vida per a l’intent d’autenticació.	`[ { "status": "Approved", … } ]`
`face_matches`	matriu de Coincidència facial	No	Resultat de la coincidència amb la referència registrada. `source_image_session_id` es defineix amb el `session_id` propi de la sessió: la cara de referència (el `portrait_image` proporcionat, o la cara emmagatzemada que es reutilitza mitjançant `vendor_data` quan s’omet `portrait_image`) es registra sota la pròpia sessió d’autenticació (`face/views/face.py:656-659`).	`[ { "status": "Approved", "source_image_session_id": "…", … } ]`
`status`	cadena	No	Estat de la sessió de primer nivell (vegeu Enumeració d’estats).	`"Approved"`

{
  "session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
  "status": "Approved",
  "liveness_checks": [
    {
      "status": "Approved",
      "method": "PASSIVE",
      "score": 95.10,
      "reference_image": "https://<media-host>/.../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://<media-host>/.../source.jpg?signature=...",
      "target_image": "https://<media-host>/.../target.jpg?signature=...",
      "node_id": "biometric_auth_face_match",
      "warnings": []
    }
  ]
}

Registre KYB

Retornat 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’empreses. Font: kyb/serializers/kyb.py:939-964 (RegistryCheckV3Serializer).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	cadena	No	Vegeu Enumeració d’estats.	`"Approved"`
`node_id`	cadena \| null	Sí	Identificador del node del flux de treball (V3).	`"first_registry"`
`data_resolved`	booleà	No	`true` quan la consulta al registre ha finalitzat (o quan `is_from_registry` és `false`, és a dir, les dades s’han introduït manualment).	`true`
`company`	objecte	No	Payload complet de l’empresa: vegeu Objecte d’empresa més avall.	`{ … }`
`ownership_structure`	objecte	Sí	La taula de participacions que el registre va acreditar: `shareholders[]` i `beneficial_owners[]`, amb cada titular, la seva identitat al registre, la seva participació i el `shareholding` canònic.	`{ "shareholders": [...], "beneficial_owners": [] }`
`warnings`	matriu	No	Vegeu Objecte d’advertència.	`[]`

Objecte d’empresa

Des de kyb/serializers/kyb.py:220-321 (KYBCompanyResponseSerializer).

Camp	Tipus	Nul·lable	Descripció
`uuid`	cadena (UUID)	No	Identificador intern de l’empresa.
`node_id`	cadena \| null	Sí	Identificador del node del flux de treball.
`status`	cadena	No	Estat de la funcionalitat (`FeatureStatusChoices`).
`registry_status`	cadena	Sí	Estat de l’empresa al registre (`active`, `dissolved`, …).
`data_resolved`	booleà	No	La mateixa definició que a l’objecte pare.
`company_name`	cadena	Sí	Nom registrat de l’empresa.
`registration_number`	cadena	Sí	Identificador del registre.
`country_code`	cadena (ISO 3166-1 alpha-2)	Sí	País de constitució.
`region`	cadena	Sí	Subdivisió ISO 3166-2, quan escaigui (p. ex. `US-CA`).
`company_type`	cadena	Sí	Forma jurídica (`LLC`, `SL`, …).
`incorporation_date`	cadena (YYYY-MM-DD)	Sí	Data de constitució.
`registered_address`	cadena	Sí	Adreça legal registrada.
`tax_number`	cadena	Sí	Identificador fiscal o d’IVA.
`risk_level`	cadena	Sí	Qualificació de risc proporcionada pel proveïdor.
`verification_status`	cadena	Sí	Enumeració interna de l’estat de verificació.
`is_from_registry`	booleà	No	`true` quan la informació procedeix del registre (en lloc d’una entrada manual).
`fetch_status`	cadena	Sí	`pending`, `resolved`, `failed`.
`alternative_names`	cadena	Sí	Noms comercials alternatius separats per comes.
`nature_of_business`	cadena	Sí	Descripció lliure de l’activitat empresarial.
`registered_capital`	cadena	Sí	Capital social registrat com a cadena en un format llegible per a les persones.
`registered_capital_amount`	cadena (decimal)	Sí	Import del capital social registrat obtingut després de l’anàlisi.
`registered_capital_currency`	cadena (ISO 4217)	Sí	Codi de moneda.
`website`	cadena (URL)	Sí	Lloc web de l’empresa.
`email`	cadena	Sí	Correu electrònic de contacte públic.
`phone`	cadena	Sí	Telèfon de contacte públic.
`legal_entity_identifier`	cadena	Sí	LEI, quan està disponible.
`location_of_registration`	cadena	Sí	Oficina o regió del registre.
`vat_number`	cadena	Sí	Número d’IVA enviat per a l’empresa.
`vat_validation_status`	cadena	No	Resultat de validar el número d’IVA o, si no n’hi ha, el `tax_number`: `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate` o `not_applicable`. Vegeu Validació d’IVA i de l’identificador fiscal.
`vat_validated_number`	cadena	Sí	El número que es va comprovar, tal com el coneix la font.
`vat_validation_source`	cadena	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`	cadena	Sí	Nom registrat a la font (buit quan no en revela cap).
`vat_validated_address`	cadena	Sí	Adreça registrada a la font (buida quan no es revela).
`vat_checked_at`	cadena (ISO 8601)	Sí	Marca de temps de la comprovació; `null` quan no s’ha fet cap comprovació.
`financial_summary`	objecte	Sí	Instantània dels principals indicadors financers més recents, quan els proporciona el registre.
`officers`	matriu d’objectes	No	Llista de responsables apta per a B2C: `{ uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }`.
`beneficial_owners`	matriu d’objectes	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`	matriu d’objectes	Sí	Detall de cada adreça del registre.
`industries`	matriu d’objectes	Sí	Classificacions d’estil SIC/NAICS.
`accounts`	matriu d’objectes	Sí	Metadades dels comptes presentats.
`registry_data`	objecte	Sí	Detall normalitzat del registre de Didit (resultat de la titularitat, correccions de la consola, dades del registre sense camp propi). No és un contracte estable.
`user_provided_data`	objecte	Sí	Instantània dels camps editats per l’usuari.
`confirmed_by_user_at`	cadena (ISO 8601)	Sí	Marca de temps en què l’usuari va confirmar les dades extretes.
`last_console_edit_at`	string (ISO 8601)	Sí	Marca de temps de l’última edició des de la consola.
`is_editable`	boolean	No	`true` mentre les dades obtingudes del registre encara puguin ser editades per l’usuari final.

{
  "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 sessions d’empreses: hi ha una entrada per cada 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	Pot ser nul	Descripció	Exemple
`status`	string	No	Estat agregat de tots els documents d’aquest node: `Approved` només quan tots els documents del pipeline estan aprovats; `Declined` si algun està rebutjat; `In Review` en qualsevol altre cas; `Not Finished` mentre hi ha pendents. Consulta Enumeració d’estats.	`"Approved"`
`node_id`	string \| null	Sí	Identificador del node del flux (V3).	`"first_kyb_documents"`
`items`	array d’objectes d’element de document KYB	No	Una entrada per cada document pujat o sol·licitat.	`[…]`
`groups`	object	No	Recomptes per grup de documents: `{ <group_name>: { 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`	array de cadenes	No	Grups de documents que exigeix la configuració del flux.	`["incorporation_certificate", "shareholder_register"]`
`warnings`	array	No	Consulta Objecte d’advertència.	`[]`

Objecte d’element de document KYB

Camp	Tipus	Pot ser nul	Descripció
`uuid`	string (UUID)	No	Identificador intern del document.
`document_type`	string	Sí	Grup de nivell alt (`incorporation_certificate`, `shareholder_register`, …).
`document_subtype`	string	Sí	Subtipus específic del proveïdor.
`document_group`	string	Sí	Reflex de `document_type` (àlies mantingut per claredat).
`file_url`	string (URL)	Sí	URL prefirmada del fitxer netejat.
`original_filename`	string	Sí	Nom del fitxer tal com es va pujar.
`file_size`	integer	Sí	Mida del fitxer en bytes.
`status`	string	No	Estat per document (`FeatureStatusChoices`).
`created_at`	string (ISO 8601)	No	Marca de temps de la pujada.
`cross_check_result`	object	Sí	Veredicte de la contraverificació amb el registre o amb altres documents.
`document_metadata`	object	Sí	La mateixa estructura de metadades filtrades que `document_metadata` del POA.
`description`	string	Sí	Descripció proporcionada pel revisor o pel sistema.
`is_requested`	boolean	No	`true` quan el flux esperava aquest document.
`ocr_data`	object	Sí	Camps extrets per OCR quan n’hi ha.
`is_console_upload`	boolean	No	`true` quan el document l’ha pujat un revisor de la consola (s’exclou del veredicte agregat).
`is_confirmed`	boolean	No	`true` quan el revisor ha confirmat explícitament el document.

{
  "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://<media-host>/.../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 KYB. Apareix com a key_people_checks[] a GET /v3/session/{sessionId}/decision/ per a sessions d’empreses. Font: kyb/serializers/kyb.py:967-1050 (KeyPeopleCheckV3Serializer).

Camp	Tipus	Pot ser nul	Descripció	Exemple
`status`	string	No	Consulta Enumeració d’estats.	`"Approved"`
`node_id`	string \| null	Sí	Identificador del node del flux (V3).	`"first_key_people"`
`registry`	object	No	`{ officers[], beneficial_owners[] }` extret del registre. Els directius 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 de 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`	object	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` marquen una sessió filla eliminada: el seu estat queda congelat amb el valor que tenia, el `*_session_url` corresponent torna `null` perquè l’enllaç ja no es resol, i la part deixa de bloquejar la sessió principal (la comprovació passa a `In Review`). Esborra el marcador amb `PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`.	`{ "parties": [...] }`
`ubo_kyc_summary`	object	Sí	Recomptes entre els titulars reals actius amb KYC enllaçat: `{ total, approved, flagged, pending }`. `null` quan cap titular real actiu no té KYC enllaçat.	`{ "total": 2, "approved": 2, "flagged": 0, "pending": 0 }`
`warnings`	array	No	Consulta Objecte d’advertència.	`[]`

{
  "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ó 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. 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:

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

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

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.