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 de KYC o d’identitat que envia un usuari. Apareix com a id_verifications[] a GET /v3/session/{sessionId}/decision/ i dins del camp kyc de les respostes V2. Font: kyc/serializers/kyc.py:383-414 (IDVerificationV3Serializer, que amplia IDVerificationV2Serializer a kyc/serializers/kyc.py:320-380).

Camp	Tipus	Pot ser nul	Descripció	Exemple
`status`	cadena	No	Consulta Enumeració d’estats.	`"Approved"`
`document_type`	cadena	Sí	Classe de document en un format llegible (`Passport`, `Identity Card`, `Driver's License`, `Residence Permit`, `Health Insurance Card`, `Tax Card`, `Social Security Card`, `Work Permit`, `Visa`, `Public Service Card`, `Birth Certificate`, `Firearm License`, `Other`). Font: `DOC_TYPE_MAPPING` (`common/config/choices.py:1275-1289`).	`"Passport"`
`document_subtype`	cadena	Sí	Codi de subtipus de document del registre de documents de Didit, filtrat segons els tipus de document que accepta la configuració documental del flux de treball. Els documents específics d’una regió inclouen la regió. Llista completa de codis: Subtipus de document.	`"QUEENSLAND_DRIVER_LICENSE_GENERIC"`
`document_number`	cadena	Sí	Número de document extret per OCR.	`"AB1234567"`
`personal_number`	cadena	Sí	Identificador personal o nacional extret per OCR.	`"99999999R"`
`portrait_image`	cadena (URL)	Sí	URL prefirmada del retall facial.	`"https://<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 està 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 (de fotograma complet).	`"https://<media-host>/.../full_front.jpg?..."`
`full_back_image`	cadena (URL)	Sí	Captura del revers sense retallar (de fotograma complet).	`null`
`front_image_camera_front`	cadena (URL)	Sí	Imatge de la càmera frontal presa al mateix temps que l’anvers del document.	`null`
`back_image_camera_front`	cadena (URL)	Sí	Imatge de la càmera frontal presa al mateix temps que el revers del document.	`null`
`front_image_camera_front_face_match_score`	flotant (0-100)	Sí	Similitud entre el retrat del document i la captura de la càmera frontal.	`null`
`back_image_camera_front_face_match_score`	flotant (0-100)	Sí	Igual que l’anterior però per a la captura del revers.	`null`
`document_selfie_face_matches`	matriu	Sí	Sessions anteriors o entrades de la llista de bloqueig facial que coincideixen amb la selfie feta durant la captura del document. Té el mateix format d’entrada que `liveness_checks[].matches`. És `null` quan la cerca no s’ha executat i `[]` quan no hi ha cap coincidència.	`null`
`front_image_quality_score`	objecte	Sí	Mètriques de qualitat de la imatge de l’anvers: puntuacions de 0 a 100 (`focus_score`, `brightness_score`, `resolution_score`, `overall_score`), a més de `brightness_issue` (`ok`, `too_dark`, `too_bright`) i `is_document_fully_visible` (booleà).	`{ "focus_score": 91.0, "overall_score": 88.5 }`
`back_image_quality_score`	objecte	Sí	Té la mateixa estructura que `front_image_quality_score`.	`null`
`date_of_birth`	cadena (YYYY-MM-DD)	Sí	Data de naixement extreta per OCR.	`"1990-05-12"`
`age`	enter	Sí	Edat calculada en anys en el moment de l’extracció.	`35`
`expiration_date`	cadena (YYYY-MM-DD)	Sí	Data de caducitat del document.	`"2032-05-11"`
`date_of_issue`	cadena (YYYY-MM-DD)	Sí	Data d’expedició del document.	`"2022-05-11"`
`issuing_state`	cadena (ISO 3166-1 alpha-3)	Sí	Codi del país emissor.	`"ESP"`
`issuing_state_name`	cadena	Sí	Nom localitzat del país emissor.	`"Spain"`
`first_name`	cadena	Sí	Nom o noms de pila extrets per OCR.	`"María"`
`last_name`	cadena	Sí	Cognom o cognoms extrets per OCR.	`"García López"`
`full_name`	cadena	Sí	Nom complet normalitzat (proporcionat pel proveïdor).	`"María García López"`
`gender`	cadena	Sí	`M`, `F` o un altre valor proporcionat pel proveïdor.	`"F"`
`address`	cadena	Sí	Línia d’adreça en brut extreta per OCR.	`"Calle Mayor 1, 28001 Madrid"`
`formatted_address`	cadena	Sí	Adreça geocodificada o formatada (quan es pot analitzar).	`"Calle Mayor 1, 28001 Madrid, Spain"`
`parsed_address`	objecte	Sí	Adreça estructurada i geocodificada: `street_1`, `street_2`, `city`, `region`, `country`, `postal_code`, `address_type`, `formatted_address`, `document_location` (`{latitude, longitude}`), `raw_results` i `is_best_match`. Font: `kyc/utils/address.py:147-197`.	`{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" }`
`place_of_birth`	cadena	Sí	Lloc de naixement extret per OCR.	`"Madrid"`
`marital_status`	cadena	Sí	Quan es pot extreure.	`null`
`nationality`	cadena (ISO 3166-1 alpha-3)	Sí	Nacionalitat extreta per OCR.	`"ESP"`
`extra_fields`	objecte	Sí	Camps específics del tipus de document que no es cobreixen amb l’esquema canònic (p. ex., categories del permís de conducció).	`{ "DL Class": "B" }`
`mrz`	objecte	Sí	Camps MRZ analitzats quan hi són (`document_number`, `birth_date`, `expiry_date`, `surname`, `given_names`, …).	`{ "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA" }`
`extra_files`	matriu de cadenes (URL)	No	URL prefirmades de qualsevol fitxer addicional pujat.	`[]`
`matches`	matriu d’objectes	No	Coincidències de documents entre sessions. Cada element: `{ session_id, session_number, vendor_data, verification_date, user_details: { name, document_type, document_number }, status, is_blocklisted, api_service, front_image_url }`. `front_image_url` és una URL prefirmada.	`[]`
`verification_method`	string	No	Quin mètode de verificació d’identitat ha produït aquesta fila: `document`, `id_lookup` o `wallet`. Sempre `document` per a un document fotografiat, incloses totes les sessions creades abans que existissin els altres mètodes.	`"id_lookup"`
`assurance`	string	No	Nivell de garantia derivat de `verification_method`: `documentary`, `data_match` o `cryptographic`.	`"data_match"`
`wallet_provider`	string \| null	Sí	Identificador de la cartera del catàleg quan una cartera ha produït aquesta fila (`mitid`, `bankid_se`, `itsme`, …). `null` en cas contrari.	`"mitid"`
`fallback_from`	object \| null	Sí	Motiu pel qual un mètode que no és de document ha finalitzat el pas d’identificació: `{ method, reason, action }`. S’estableix quan una consulta o un inici de sessió amb cartera ha fallat: a la fila rebutjada quan el commutador del país era `decline` (`action: "decline"`), i al document de verificació amb què continua l’usuari quan era `fallback_to_document` (`action: "fallback_to_document"`). `null` quan no hi ha cap fallada prèvia d’un mètode que no és de document registrada.	`{ "method": "id_lookup", "reason": "no_match", "action": "decline" }`
`id_lookup`	object \| null	Sí	Evidència de la font, present només quan `verification_method` és `id_lookup`: `source` (la font exacta consultada: un registre governamental en la majoria de països, o un fitxer d’una agència de crèdit o de registres residencials en alguns), `checked_at`, `attempts`, `max_attempts`, `outcome` (`match`, `partial_match`, `no_match`, `provider_error`, `format_rejected`), `comparison[]` (`{ field, label, provided, record, result }`; `field` és un de `identification_number`, `full_name`, `date_of_birth`, `address`, i `result` és `match`, `partial` o `no_match`; les versions anteriors poden incloure una fila `provider` amb `error`), `source_errors[]` (entorn de preproducció actual: diagnòstics separats per font; confirmeu el desplegament en producció), `registry_portrait` (URL prefirmada, només per a les fonts que en retornen una) i `face_match_score`.	vegeu més avall
`wallet_verification`	object \| null	Sí	Evidència de credencials, present només quan `verification_method` és `wallet`: `provider`, `provider_name`, `issuing_authority`, `issuing_country`, `credential_type`, `level_of_assurance` (`low`, `substantial`, `high`), `verified_at`, `signature_valid`, `attributes` (el que ha compartit la cartera), `portrait` (URL prefirmada quan la cartera en comparteix una) i `face_match_score`.	vegeu més avall
`document_liveness`	object \| null	Sí	Puntuacions de prova de vida del document per tipus de frau (`portrait_replace`, `printed_copy`, `screen_replay`), informades tant si s’ha activat una advertència com si no. Cadascuna conté: `score` (0-100, més alt = més probabilitat que sigui genuí; el valor més baix, que és el que va utilitzar la decisió), `front`, `back`, `decline_threshold`, `review_threshold`, `bucket` (`approve`, `review`, `decline` o `null`). Els llindars i la categoria es desen en el moment de l’avaluació; els tres són `null` quan no hi ha evidència d’avaluació històrica disponible, però les puntuacions emmagatzemades continuen visibles. `null` quan la comprovació no s’ha executat. Consulteu Puntuacions de prova de vida del document. Només V3.	`{ "portrait_replace": { "score": 96.46, "bucket": "approve" } }`
`node_id`	string \| null	Sí	Identificador del node del flux de treball (V3).	`"first_id_verification"`
`warnings`	array	No	Vegeu Objecte d’advertència.	`[]`
`region`	string	Sí	Regió o estat del país emissor, quan el document n’identifica un.	`"CA"`
`extracted_data`	object	Sí	Instantània de les dades extretes del document que es va mostrar a la persona perquè les revisés, guardada al costat dels valors confirmats perquè pugueu comparar-los. `null` quan no se li va demanar que revisés.
`barcodes`	matriu d’objectes	No	Dades llegides dels codis de barres del document, una entrada per codi de barres amb `type`, `position`, `data`, `data_raw` i `side`. `[]` quan no n’hi ha cap.	`[]`

{
  "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 de document s’omple amb el registre de la font o els atributs de la cartera, i les claus que no s’apliquen són null.

{
  "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 ICAO 9303 ePassport o eID, o una lectura de la Japan My Number Card mitjançant JPKI (chip_protocol: "jpki"). Apareix com a nfc_verifications[] a GET /v3/session/{sessionId}/decision/ (un per registre KYC principal). Font: kyc/serializers/epassport.py:121-139 (NFCV3Serializer, amplia NFCV2Serializer a kyc/serializers/epassport.py:83-118).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	string	No	Vegeu Enumeració d’estat.	`"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 s’hi emmagatzema).	`null`
`chip_data`	object	Sí	Dades personals analitzades dels Data Groups del xip, aplanades (`kyc/utils/epassport.py:165-212`): `dgs` (Data Groups llegits), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (codi de document de la MRZ), `document_number`, `optional_data`, dígits de control de la MRZ (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string`, `mrz_type` (`TD1`/`TD2`/`TD3`); a més, `place_of_birth` i `address` (i `full_name` / `full_name_non_latin` per als noms en alfabets no llatins) quan el xip conté DG11; aquestes claus no hi són en cas contrari. `null` quan el pas NFC s’ha omès.	`{ "document_number": "AB1234567", "name": "MARIA" }`
`authenticity`	object	Sí	`{ sod_integrity, dg_integrity }`; `null` per a una lectura JPKI. `sod_integrity` valida que la signatura del Document Security Object (SOD) forma una cadena de confiança fins a una CSCA vàlida del país emissor (i que la DSC no està revocada ni caducada); `dg_integrity` valida que els hashes de cada Data Group coincideixen amb el SOD. Si tots dos són `true`, el xip és genuí i no s’ha alterat.	`{ "sod_integrity": true, "dg_integrity": true }`
`certificate_summary`	objecte	Sí	Resum del certificat del signant del document (`kyc/utils/epassport.py:338-348`): `issuer`, `subject`, `serial_number` (enter), `not_valid_before`, `not_valid_after` (`YYYY-MM-DD HH:MM:SS`), més un objecte `validation` `{ csca_verified, dsc_revoked, dsc_expired, csca_expired }` (`kyc/views/epassport.py:86`).	`{ "issuer": "Common Name: CSCA SPAIN, Country: ES", "not_valid_after": "2031-02-18 10:21:11" }`
`node_id`	cadena \| null	Sí	Identificador del node del flux de treball (V3).	`"first_nfc"`
`is_nfc_skipped`	booleà	No	`true` quan aquest pas NFC s’ha omès explícitament en lloc de llegir-se; `skip_reason` indica el motiu.	`false`
`skip_reason`	cadena	Sí	Motiu pel qual es va omitir el pas; només s’estableix quan `is_nfc_skipped` és `true`. Un dels valors següents: `USER_SKIPPED`, `DOCUMENT_WITHOUT_CHIP`, `CHIP_CERTIFICATE_UNAVAILABLE`, `DEVICE_WITHOUT_NFC`, `INTEGRATION_WITHOUT_NFC_ACCESS`, `MRZ_KEY_UNAVAILABLE`, `JPKI_UNAVAILABLE`; consulta Motius d’omissió. El payload de la decisió també inclou un `nfc_skip_reason` a nivell de sessió amb la mateixa taxonomia, que cobreix els passos NFC que es van ometre abans de crear cap informe.	`null`
`chip_protocol`	cadena	No	Com es llegeix el xip: `icao` (xip ePassport o eID de l’ICAO 9303) o `jpki` (My Number Card del Japó). En el cas de `jpki`, `portrait_image`, `signature_image`, `chip_data`, `authenticity` i `certificate_summary` són `null`. També s’estableix en els passos omesos.	`"icao"`
`jpki`	objecte	Sí	El que demostra una lectura de la My Number Card: `certificate_types`, `chain_valid`, `signature_valid`, `revocation_status` (`good`, `revoked` o `unchecked`), `ca_generation`, `certificate_expires_at`, `certificates[]`, `attributes` (nom, data de naixement, sexe i adreça del certificat de signatura), `attributes_match_ocr` i `mismatched_attributes`. Mai inclou els certificats, els seus números de sèrie ni les signatures. És `null` per als xips ICAO, per als passos omesos i quan el pas s’ha tancat sense cap lectura de la targeta. Consulta Camps de JPKI.	`null`
`warnings`	matriu	No	Consulta 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": []
}

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, que estén LivenessV2Serializer a face/serializers/face.py:216-298).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	cadena	No	Consulta Enumeració d’estats.	`"Approved"`
`method`	cadena (enumeració)	Sí	`ACTIVE_3D`, `FLASHING` o `PASSIVE` (`LivenessMethodChoices`, `common/config/choices.py:514-517`). El mode passiu 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 a 2 decimals.	`92.41`
`reference_image`	cadena (URL)	Sí	URL pre-signada del retall facial de referència de l’usuari.	`"https://<media-host>/.../reference.jpg?..."`
`video_url`	cadena (URL)	Sí	URL pre-signada del vídeo de la prova de vida (només en mode actiu).	`"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`	matriu d’objectes	No	Coincidències facials entre sessions. Cada element: `{ session_id, session_number, similarity_percentage, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details: { full_name, document_type, document_number }, match_image_url, status, is_blocklisted, is_allowlisted, api_service, source }`. `source` és `session`, `imported`, `list_entry` o `retained_template`. Una coincidència de plantilla retinguda té `vendor_user_id`, `vendor_data` i `biometric_template_id`; els seus camps de sessió, imatge, detalls d’identitat, estat i servei d’API són `null`.	`[]`
`face_quality`	float (0-100)	Sí	Puntuació de qualitat facial de la prova de vida passiva (normalitzada a un percentatge).	`87.50`
`face_luminance`	float (0-100)	Sí	Puntuació de lluminositat facial de la prova de vida passiva (normalitzada de 0-255 a un percentatge).	`54.12`
`node_id`	cadena \| null	Sí	Identificador del node del flux de treball (V3).	`"first_liveness"`
`warnings`	matriu	No	Consulta Objecte d’advertència.	`[]`

{
  "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": []
}

Coincidència facial

Es retorna per cada comparació facial (normalment el rostre de la prova de vida de l’usuari amb el retrat del document). Apareix com a face_matches[] a GET /v3/session/{sessionId}/decision/. Font: face/serializers/face.py:367-389 (FaceMatchV3Serializer, que estén FaceMatchV2Serializer a face/serializers/face.py:323-364).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	cadena	No	Consulta Enumeració d’estats.	`"Approved"`
`score`	float (0-100)	Sí	Similitud, arrodonida a 2 decimals. Quan el proveïdor només retorna un `unmatched_faces[].Confidence`, es converteix a `100 - confidence`.	`97.83`
`source_image_session_id`	cadena (UUID)	Sí	La sessió que va proporcionar la imatge d’origen (de referència) a partir del seu retrat emmagatzemat. S’estableix en fluxos basats en retrats (autenticació biomètrica, o un retrat aportat en crear la sessió). És `null` quan la referència és el retrat del document de la mateixa sessió.	`null`
`source_image`	cadena (URL)	Sí	URL pre-signada de la imatge d’origen (de referència): normalment el retrat del document, o el retrat emmagatzemat en els fluxos d’autenticació biomètrica.	`"https://<media-host>/.../source.jpg?..."`
`target_image`	cadena (URL)	Sí	URL pre-signada de la imatge objectiu (rostre en directe) capturada durant la prova de vida.	`"https://<media-host>/.../target.jpg?..."`
`node_id`	cadena \| null	Sí	Identificador del node del flux de treball (V3).	`"first_face_match"`
`warnings`	matriu	No	Consulta Objecte d’advertència.	`[]`
`face_coverage`	objecte	Sí	Indica si els `eyes`, la `mouth` i el `face` estan coberts a la imatge capturada. Cada regió té `covered`, `calibrated` i `visibility_score`; `calibrated: false` és una evidència d’ombra que no activa cap advertència. Es retorna només a `GET /v3/session/{sessionId}/decision/`, mai en payloads de webhook.	`{ "eyes": { "covered": false, "calibrated": true, "visibility_score": 0.98 } }`

{
  "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 de cerca facial independent (POST /v3/face-search/). La cerca facial mai no apareix com un array en plural a /v3/session/{sessionId}/decision/. Quan es persisteix amb save_api_request=true, la sessió apareix allà com una entrada FACE_SEARCH dins de features[], més un element liveness_checks[] que conté els matches emmagatzemats. Fonts: apis/serializers/face_search.py:8-79 (FaceSearchResponseSerializer, que envolta FaceSearchDetailsSerializer); els diccionaris de coincidències es construeixen a face/utils/utils.py:869-884. Resposta de nivell superior:

Camp	Tipus	Nul·lable	Descripció	Exemple
`request_id`	string (UUID)	No	L’id de sessió persistit quan `save_api_request=true` (utilitzable amb `GET /v3/session/{sessionId}/decision/`); en cas contrari, un UUID de correlació transitori.	`"4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f"`
`face_search`	object	No	Dades de detall de la cerca; vegeu els camps següents.	—
`vendor_data`	string	Sí	`vendor_data` de la sol·licitud, retornat tal qual.	`null`
`metadata`	object	Sí	`metadata` de la sol·licitud, retornat tal qual.	`null`
`created_at`	string (ISO 8601)	No	Marca de temps de la sol·licitud al servidor.	`"2026-06-12T01:04:42.763237+00:00"`

Objecte face_search:

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	string	No	`Declined` només quan s’ha activat una advertència `FACE_IN_BLOCKLIST` o `POSSIBLE_FACE_IN_BLOCKLIST`; `Approved` en la resta de casos. Les coincidències duplicades per si soles mai no rebutgen (`apis/views/face_search.py:242-248`).	`"Approved"`
`total_matches`	integer	No	Nombre de coincidències retornades a `matches[]` (0–5).	`1`
`matches`	array d’objectes de coincidència de cerca facial	No	Fins a 5 coincidències per sobre del llindar mínim de similitud, ordenades per similitud descendent (primer les entrades de la llista de bloqueig, amb `search_type=blocklisted_or_approved`).	`[…]`
`user_image`	object	No	Resultat de la detecció per a la imatge enviada: `{ entities: [{ bbox, confidence }], best_angle }`, amb una entitat per cada cara detectada.	`{ "entities": [{ "bbox": [40, 40, 120, 120], "confidence": 0.73 }], "best_angle": 0 }`
`warnings`	array d’objectes	No	Forma reduïda de les advertències per a aquesta API independent, sense `node_id`. El contracte del serialitzador declara `{ risk, additional_data, log_type, short_description, long_description }` (`apis/serializers/face_search.py:49-54`); la càrrega en temps d’execució també inclou `feature`, sempre `"LIVENESS"` (`apis/views/face_search.py:332-341`).	`[]`

Objecte de coincidència de cerca facial

Camp	Tipus	Nul·lable	Descripció	Exemple
`session_id`	string (UUID)	Sí	La sessió de verificació coincident. `null` quan `source` és `imported`, `list_entry` o `retained_template`.	`"a3f2a6f1-…"`
`session_number`	integer	Sí	Número de la sessió coincident, més fàcil de llegir a la consola; `null` per a coincidències que no són de sessió.	`1024`
`similarity_percentage`	float (0-100)	No	Similitud entre la cara enviada i la cara coincident.	`96.42`
`source`	string (enum)	No	D’on es va registrar la cara coincident: `session` (sessió de verificació o crida independent desada), `imported` (càrrega directa de la cara al perfil d’usuari), `list_entry` (cara afegida a una llista) i `retained_template` (plantilla biomètrica sense imatge, conservada després que s’eliminés la sessió d’origen).	`"session"`
`vendor_data`	string	Sí	El `vendor_data` de la sessió coincident o, per a coincidències `imported` i `retained_template`, el de l’usuari vinculat.	`"user-12345"`
`vendor_user_id`	string (UUID)	Sí	L’usuari vinculat. `null` per a coincidències `list_entry` i per a sessions sense usuari.	`"2f7c1a9e-…"`
`biometric_template_id`	string (UUID)	Sí	La plantilla conservada que ha coincidit. Només es defineix per a coincidències `retained_template`; utilitzeu-la amb `GET`/`DELETE /v3/biometric-templates/{id}/`.	`null`
`verification_date`	string (ISO 8601)	Sí	Quan es va capturar la cara coincident, o quan es va conservar una `retained_template`; `null` per a coincidències `list_entry`.	`"2024-11-04T09:14:02Z"`
`user_details`	object	Sí	`{ full_name, document_type, document_number }` de la verificació de document de la sessió coincident. Per a coincidències `imported` només es defineix `full_name`; és `null` quan no hi ha dades d’identitat, i sempre `null` per a coincidències `retained_template`.	`{ "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" }`
`match_image_url`	string (URL)	Sí	Cara de referència de l’usuari coincident: URL presignada quan `save_api_request=true`, ruta d’emmagatzematge en brut en cas contrari. Sempre `null` per a coincidències `retained_template`, que no contenen imatge.	`"https://<media-host>/.../matched.jpg?..."`
`status`	string	Sí	L’estat de verificació de la sessió coincident (vegeu l’enumeració d’estats); `null` per a coincidències que no són de sessió.	`"Approved"`
`is_blocklisted`	boolean	No	Indica si la cara coincident és a la vostra llista de bloqueig facial. Sempre `false` per a coincidències `retained_template`; una cara en llista de bloqueig es reporta a part, com a coincidència `list_entry`.	`false`
`is_allowlisted`	boolean	No	Indica si la cara coincident és en alguna de les vostres llistes d’autorització.	`false`
`api_service`	string (enum)	Sí	Tipus d’API independent, en majúscules, de la sessió coincident (p. ex. `PASSIVE_LIVENESS`, `FACE_MATCH`); `null` per a sessions de flux de treball i per a coincidències que no són de sessió.	`null`

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

Retornat per cada entitat cribada. Apareix com a aml_screenings[] a GET /v3/session/{sessionId}/decision/, tant per a sessions KYC com KYB. Font: aml/serializers/aml.py:63-85 (AMLV3Serializer, que estén AMLV2Serializer a aml/serializers/aml.py:28-60).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	string	No	Vegeu l’enumeració d’estats.	`"Approved"`
`total_hits`	integer	No	Nombre de coincidències del cribratge (sempre present, per defecte `0`).	`2`
`entity_type`	string (enum)	Sí	`person` o `company` (`EntityTypeChoices`, `common/config/choices.py:675-677`).	`"person"`
`hits`	array d’objectes	No	Una entrada per cada coincidència. Camps clau: `id`, `caption`, `match` (booleà), `target` (booleà \| null, que indica si l’entitat és l’objectiu directe de la llista), `match_score` (flotant 0-100, confiança d’identitat), `risk_score` (flotant 0-100, risc de l’entitat), `score` (flotant 0-1, obsolet), `datasets[]` (p. ex. `PEP`, `PEP Level 1`-`4`, `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`), `properties` (noms, àlies, dates de naixement, …), `features`, `url`, `first_seen`, `last_seen`, `rca_name`, `risk_view`, `score_breakdown`, `pep_matches`, `sanction_matches`, `warning_matches`, `adverse_media_matches`, `adverse_media_details`, `linked_entities`, `additional_information` i `review_status` (`Unreviewed`, `Confirmed Match`, `False Positive`, `Inconclusive`; es pot editar mitjançant l’endpoint d’actualització de l’estat de les coincidències AML, `AMLHitStatusChoices`).	`[…]`
`score`	float (0-100)	Sí	Puntuació global de cribratge: la `risk_score` més alta entre les coincidències que no estan marcades com a `False Positive` (`aml/services/aml.py:832-842`); `0` quan tots els resultats són falsos positius. `null` fins que es calcula.	`42.7`
`screened_data`	object	Sí	Instantània de les dades enviades al cribratge: `full_name`, `nationality`, `date_of_birth`, `document_number`.	`{ "full_name": "María García López", "date_of_birth": "1990-05-12" }`
`is_ongoing_monitoring_enabled`	boolean	No	Si l’entitat està subscrita als recribratges del monitoratge continu.	`false`
`next_ongoing_monitoring_bill_date`	string (YYYY-MM-DD)	Sí	Calculada com a `last_aml_bill_date + 365 days` quan el monitoratge continu està activat. Una data de facturació, no una data de cribratge.	`null`
`last_ongoing_screening_at`	string (ISO 8601)	Sí	Moment en què el monitoratge continu va completar per última vegada un recribratge d’aquest registre, tant si el resultat va canviar com si no. `null` quan mai no s’ha recribrat; mai no s’omple retroactivament.	`"2026-09-12T04:03:11Z"`
`last_ongoing_screening_datasets_updated_at`	string (ISO 8601)	Sí	L’actualització més recent del conjunt de dades AML que el proveïdor va informar per a aquest cribratge. `null` quan no es va informar cap data del conjunt de dades; mai no s’estima.	`null`
`node_id`	string \| null	Sí	Identificador del node del flux de treball (V3).	`"first_aml"`
`warnings`	array	No	Vegeu Objecte d’advertència.	`[]`

{
  "status": "In Review",
  "total_hits": 1,
  "entity_type": "person",
  "hits": [
    {
      "id": "Q7XW3-aml-hit-1",
      "caption": "Maria Garcia Lopez",
      "match": true,
      "target": true,
      "match_score": 86.4,
      "risk_score": 42.7,
      "datasets": ["PEP Level 2"],
      "properties": {
        "name": ["María García López", "M. García"],
        "alias": ["Maria Garcia"],
        "birthDate": ["1990-05-12"]
      },
      "url": "https://example.org/registry/entities/Q7XW3",
      "first_seen": "2023-11-02T00:00:00Z",
      "last_seen": "2026-05-01T00:00:00Z",
      "review_status": "Unreviewed"
    }
  ],
  "score": 42.7,
  "screened_data": {
    "full_name": "María García López",
    "date_of_birth": "1990-05-12",
    "nationality": "ES",
    "document_number": "AB1234567"
  },
  "is_ongoing_monitoring_enabled": false,
  "next_ongoing_monitoring_bill_date": null,
  "last_ongoing_screening_at": null,
  "last_ongoing_screening_datasets_updated_at": null,
  "node_id": "first_aml",
  "warnings": []
}

Anàlisi d’IP

Es retorna per cada ubicació de xarxa capturada. Apareix com a ip_analyses[] a GET /v3/session/{sessionId}/decision/ tant per a sessions KYC com KYB. Font: kyc/serializers/location.py:196-243 (IPAnalysisSerializerV3).

Camp	Tipus	Admet null	Descripció	Exemple
`status`	string	No	Vegeu Enumeració d’estats.	`"Approved"`
`node_id`	string \| null	Sí	Identificador del node del flux de treball (V3).	`"first_ip_analysis"`
`device_brand`	string	Sí	Marca del dispositiu obtinguda de l’agent d’usuari.	`"Apple"`
`device_model`	string	Sí	Model del dispositiu.	`"iPhone"`
`browser_family`	string	Sí	Família del navegador.	`"Mobile Safari"`
`os_family`	string	Sí	Família del sistema operatiu.	`"iOS"`
`platform`	string	Sí	Plataforma d’alt nivell (`mobile`, `desktop`, `tablet`).	`"mobile"`
`device_fingerprint`	string	Sí	Hash d’empremta del dispositiu, estable per a cada dispositiu.	`"f2a3…"`
`ip_country`	string	Sí	Nom del país resolt a partir de la IP.	`"Spain"`
`ip_country_code`	string (ISO 3166-1 alpha-2)	Sí	Codi del país resolt a partir de la IP.	`"ES"`
`ip_state`	string	Sí	Regió o estat resolt a partir de la IP.	`"Comunidad de Madrid"`
`ip_city`	string	Sí	Ciutat resolta a partir de la IP.	`"Madrid"`
`latitude`	float	Sí	Latitud derivada de la IP.	`40.4168`
`longitude`	float	Sí	Longitud derivada de la IP.	`-3.7038`
`ip_address`	string	Sí	L’adreça IP capturada.	`"203.0.113.42"`
`isp`	string	Sí	Nom de l’ISP.	`"Telefonica de Espana"`
`organization`	string	Sí	Nom de l’organització (sovint igual que l’ISP).	`"Telefonica de Espana"`
`is_vpn_or_tor`	boolean	Sí	`true` quan la IP pertany a una VPN, un proxy o un node de sortida de Tor.	`false`
`is_data_center`	boolean	Sí	`true` quan la IP pertany a un ASN conegut d’allotjament o de centre de dades.	`false`
`time_zone`	string	Sí	Nom del fus horari IANA.	`"Europe/Madrid"`
`time_zone_offset`	string	Sí	Desplaçament respecte a UTC.	`"+02:00"`
`ip`	object	No	`{ location, distance_from_id_document, distance_from_poa_document }`. `location = { latitude, longitude }`. Distàncies en km, `null` quan falta alguna de les dues parts.	`{ "location": { "latitude": 40.4168, "longitude": -3.7038 }, "distance_from_id_document": 3.4, "distance_from_poa_document": 1.1 }`
`id_document`	object	No	`{ location, distance_from_ip, distance_from_poa_document }`. Ubicació del document d’identitat resolta a partir de `issuing_state` i de l’adreça analitzada.	`{ "location": { "latitude": 40.4165, "longitude": -3.7026 }, "distance_from_ip": 3.4, "distance_from_poa_document": 4.0 }`
`poa_document`	object	No	`{ location, distance_from_ip, distance_from_id_document }`. Adreça del comprovant de domicili geocodificada.	`{ "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }`
`matches`	array of objects	No	Coincidències d’IP i de dispositiu entre sessions. Cada element: `{ session_id, session_number, vendor_data, verification_date, match_type, match_source, matched_value, status, is_blocklisted, api_service, source, device_info, location_info, confidence, match_mode }`. `match_type` és `ip_address` o `device_fingerprint`; `match_source` és `ip_address`, `persistent_id`, `legacy_fp` o `recovered_high` (les coincidències recuperades també porten `recovery_similarity`, `tls_ja4_corroborated` i `recovery_gate_reason`). Limitat a 5 coincidències d’IP i 5 de dispositiu.	`[]`
`warnings`	array	No	Vegeu Objecte d’advertència.	`[]`
`browser_version`, `os_version`	string	Sí	Versions del navegador i del sistema operatiu obtingudes de l’agent d’usuari.	`"17.4"`
`user_agent`, `accept_language`	string	Sí	La cadena d’agent d’usuari i la capçalera `Accept-Language` que va enviar el navegador.	`"en-US,en;q=0.9"`
`session_identifier`, `session_age_ms`	string, integer	Sí	La sessió de navegació en què es va executar el pas i la seva antiguitat en mil·lisegons.	`48210`
`coords_accuracy`	float	Sí	Radi de precisió, en metres, de les coordenades que va informar el dispositiu.	`35.0`
`raw_device_data`	object	Sí	Senyals bruts del dispositiu recollits per al pas.	`{}`

{
  "status": "Approved",
  "node_id": "first_ip_analysis",
  "device_brand": "Apple",
  "device_model": "iPhone",
  "browser_family": "Mobile Safari",
  "os_family": "iOS",
  "platform": "mobile",
  "device_fingerprint": "f2a3c1de8b994a3f9e4cdf3a02b1a7c9",
  "ip_country": "Spain",
  "ip_country_code": "ES",
  "ip_state": "Comunidad de Madrid",
  "ip_city": "Madrid",
  "latitude": 40.4168,
  "longitude": -3.7038,
  "ip_address": "203.0.113.42",
  "isp": "Telefonica de Espana",
  "organization": "Telefonica de Espana",
  "is_vpn_or_tor": false,
  "is_data_center": false,
  "time_zone": "Europe/Madrid",
  "time_zone_offset": "+02:00",
  "ip": {
    "location": { "latitude": 40.4168, "longitude": -3.7038 },
    "distance_from_id_document": 3.4,
    "distance_from_poa_document": 1.1
  },
  "id_document": {
    "location": { "latitude": 40.4165, "longitude": -3.7026 },
    "distance_from_ip": 3.4,
    "distance_from_poa_document": 4.0
  },
  "poa_document": {
    "location": { "latitude": 40.4170, "longitude": -3.7040 },
    "distance_from_ip": 1.1,
    "distance_from_id_document": 4.0
  },
  "matches": [],
  "warnings": []
}

Verificació de la ubicació

Es retorna per cada pas de Verificació de la ubicació. Apareix com a geolocation_checks[] a GET /v3/session/{sessionId}/decision/: un element per pas, el de l’intent acceptat. geolocation_attempts[] llista tots els intents de tots els passos, del més antic al més recent. Tots dos són null per a un flux de treball sense el pas. Font: GeolocationDecisionSerializer.

Camp	Tipus	Admet null	Descripció	Exemple
`node_id`	string	Sí	Node del flux de treball que va produir el resultat.	`"geolocation_1"`
`status`	cadena	No	Consulteu Enumeració d’estats.	`"Declined"`
`outcome`	cadena	Sí	Què ha passat en l’intent: `verified`, `low_accuracy`, `accuracy_undetermined`, `stale`, `approximate`, `denied`, `restricted`, `unavailable`, `timeout`, `mock_detected`, `outside_geofence`, `in_blocked_area`, `anonymizer_detected`, `skipped`, `replay_rejected` o `unsupported_client`.	`"outside_geofence"`
`permission`	cadena	Sí	Què ha concedit el sistema: `granted_precise`, `granted_approximate`, `denied`, `restricted`, `unavailable`, `timeout`, `dismissed` o `not_requested`.	`"granted_precise"`
`latitude`, `longitude`	flotant	Sí	Posició WGS84. `null` quan no hi ha posició.	`48.8566`
`accuracy_m`	flotant	Sí	Radi d’incertesa en metres.	`35.0`
`accuracy_confidence`	cadena	Sí	`p95`, `p68` o `unspecified`.	`"p95"`
`measured_at`, `age_seconds`	data i hora, enter	Sí	Quan el dispositiu va obtenir la posició, i els segons fins que Didit la va rebre.	`2`
`source`, `platform`, `sdk_version`	cadena	Sí	D’on prové la posició, el client que la va produir i la seva versió de l’SDK.	`"browser"`
`is_mock`, `produced_by_accessory`	booleà	Sí	Evidència de suplantació que reporta la plataforma. `null` vol dir que la plataforma no la reporta.	`null`
`integrity`	cadena	No	`attested`, `not_attested`, `failed`, `unsupported` (web) o `not_determined`.	`"unsupported"`
`country_code`, `region_code`, `city`	cadena	Sí	El lloc que correspon a la posició.	`"FR"`
`geofence`, `inside_geofence`, `geofence_basis`, `inside_areas`, `blocked_areas`	objecte, booleà, cadena, matrius	Sí	El resultat del país i de l’àrea.	`{ "enabled": true, "result": "outside" }`
`position_source`, `anonymizers`	cadena, objecte	Sí	D’on obté la posició el pas, i els senyals de VPN, proxy, Tor, suplantació i emulador.	`"device_and_ip"`
`ip_distance_km`, `ip_distance_uncertainty_km`, `ip_consistent`, `document_distance_km`, `travel_excused`, `consecutive_mismatches`	nombre, booleà, enter	Sí	Les comparacions amb la ubicació de la IP i l’adreça registrada.	`12.4`
`attempts`	enter	No	El número de l’intent dins del pas.	`3`
`consent`	objecte	Sí	`accepted_at`, `version` i `locale` de l’avís que la persona ha acceptat.
`warnings`	matriu d’objectes d’advertència	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, amplia POAV2Serializer a poa/serializers/poa.py:173-209).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	cadena	No	Consulteu Enumeració d’estats.	`"Approved"`
`issuing_state`	cadena (ISO 3166-1 alpha-3)	Sí	Codi de país de l’emissor del document.	`"ESP"`
`document_type`	cadena	No	Tipus general de `PoaDocumentTypeChoices` (`common/config/choices.py:868-873`): `UTILITY_BILL`, `BANK_STATEMENT`, `GOVERNMENT_ISSUED_DOCUMENT`, `OTHER_POA_DOCUMENT`. Té `UNKNOWN` com a valor alternatiu — mai `null`.	`"UTILITY_BILL"`
`document_subtype`	cadena	No	Codi de subtipus de `PoaDocumentSubtypeChoices` (p. ex. `ELECTRICITY_BILL`, `WATER_BILL`, `ACCOUNT_STATEMENT`). Té `UNKNOWN` com a valor alternatiu — mai `null`.	`"ELECTRICITY_BILL"`
`issuer`	cadena	Sí	Nom de l’entitat emissora.	`"Iberdrola"`
`issue_date`	cadena (YYYY-MM-DD)	Sí	Data d’emissió del document.	`"2026-04-15"`
`expiration_date`	cadena (YYYY-MM-DD)	Sí	Data de caducitat impresa al document, quan hi és.	`null`
`poa_address`	cadena	Sí	Adreça en brut extreta per OCR.	`"Calle Mayor 1, 28001 Madrid"`
`poa_formatted_address`	cadena	Sí	Adreça geocodificada i formatada.	`"Calle Mayor 1, 28001 Madrid, Spain"`
`poa_parsed_address`	objecte	Sí	Adreça estructurada (`street_1`, `street_2`, `city`, `region`, `postal_code`, `country` (alpha-2), `address_type`, `document_location`, …).	`{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001" }`
`document_file`	cadena (URL)	Sí	URL signada prèviament al document pujat.	`"https://<media-host>/.../poa.pdf?..."`
`document_language`	cadena	Sí	Idioma detectat del document (ISO 639-1).	`"es"`
`document_metadata`	objecte	Sí	Metadades filtrades: `file_size`, `content_type`, `creation_date`, `modified_date`, `creator`, `producer`, `software`, `encryption`, `is_signed`, `is_tampered`, `signature_info`, `exif_original_date`, `exif_digitized_date`, `processed_by_known_editor`, `has_different_creation_mod_date`, `overlay_manipulation`.	`{ "file_size": 184221, "content_type": "application/pdf", "is_tampered": false }`
`extra_fields`	objecte	No	Camps del compte bancari (`bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`), `document_phone_number`, `additional_names`, més qualsevol clau personalitzada desada al registre.	`{ "bank_iban": null, "additional_names": [] }`
`name_on_document`	cadena	Sí	Nom tal com apareix al comprovant.	`"María García López"`
`expected_details_address`	cadena	Sí	Adreça que la persona ha escrit durant el registre (textualment).	`"Calle Mayor 1, Madrid"`
`expected_details_formatted_address`	cadena	Sí	Adreça esperada geocodificada.	`"Calle Mayor 1, 28001 Madrid, Spain"`
`expected_details_parsed_address`	objecte	Sí	Adreça esperada estructurada.	`{ "city": "Madrid", "postal_code": "28001" }`
`name_match_score_expected_details`	flotant (0-100)	Sí	Coincidència aproximada entre `name_on_document` i el nom indicat en crear la sessió.	`94.0`
`name_match_score_id_verification`	flotant (0-100)	Sí	Coincidència aproximada entre `name_on_document` i el `full_name` del document d’identitat verificat.	`100.0`
`extra_files`	matriu de strings (URL)	No	URL prefirmades dels fitxers addicionals pujats.	`[]`
`detected_codes`	matriu d’objectes	No	Codis QR i codis de barres detectats a totes les pàgines processades del document: `type`, `page_number` (basat en 1), `position` (polígon), `x`/`y`/`width`/`height` (quadre delimitador), `page_width`/`page_height`, `raw_payload` (base64), `parsed_payload` (valor descodificat, `null` quan s’ha localitzat un codi però no s’ha pogut descodificar). Matriu buida quan la detecció no troba res.	`[{ "type": "QR_CODE", "page_number": 1, "parsed_payload": "https://issuer.example/inv/9981" }]`
`node_id`	string \| null	Sí	Identificador del node del flux de treball (V3).	`"first_poa"`
`warnings`	matriu	No	Consulta Objecte d’advertència.	`[]`

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

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	string	No	Consulta Enumeració d’estats.	`"Approved"`
`phone_number_prefix`	string	No	Prefix de país E.164 (amb `+`).	`"+34"`
`phone_number`	string	No	Número d’abonat sense el prefix.	`"612345678"`
`full_number`	string	No	El número E.164 complet (`phone_number_prefix + phone_number`).	`"+34612345678"`
`country_code`	string (ISO 3166-1 alpha-2)	Sí	País del número.	`"ES"`
`country_name`	string	Sí	Nom del país localitzat.	`"Spain"`
`carrier`	objecte	No	`{ name, type }` on `type` és un valor de `LineTypeChoices` (`common/config/choices.py:648-667`): `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, `satellite`, `pager`, `payphone`, `voice_mail`, `unknown`, i altres classes de línia.	`{ "name": "Movistar", "type": "mobile" }`
`is_disposable`	boolean	No	`true` quan l’operador marca el número com a temporal o d’un sol ús.	`false`
`is_virtual`	boolean	No	`true` quan `carrier.type` és un dels valors `voip`, `isp` o `vpn`.	`false`
`verification_method`	string	No	Canal utilitzat per lliurar l’OTP (`whatsapp`, `sms`, …). Es llegeix de `actual_channel` de l’últim intent d’enviament (si no hi és, usa el `channel` sol·licitat i, després, `sms`).	`"whatsapp"`
`verification_attempts`	integer	No	Nombre total d’intents d’enviament de l’OTP (l’enviament inicial més els reenviaments).	`1`
`verified_at`	string (ISO 8601)	Sí	Marca de temps en què s’ha introduït correctament l’OTP.	`"2026-05-17T10:14:02Z"`
`lifecycle`	matriu d’objectes	No	Esdeveniments en ordre cronològic: intents d’enviament, callbacks de lliurament, comprovacions del codi i l’esdeveniment d’estat final. Cada esdeveniment és `{ type, timestamp, details, fee }`. Els tipus d’esdeveniment provenen de `PhoneEventChoices`.	`[…]`
`matches`	matriu d’objectes	No	Coincidències del número de telèfon entre sessions. Cada element: `{ session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service, source }`. `source` és `session` o `list_entry`.	`[]`
`node_id`	string \| null	Sí	Identificador del node del flux de treball (V3).	`"first_phone"`
`warnings`	matriu	No	Consulta Objecte d’advertència.	`[]`
`phone_intelligence`	objecte	Sí	Senyals d’intel·ligència del telèfon. Només és present quan el complement d’intel·ligència ha processat el número.
`phone_social`	objecte	Sí	Petjada social del número. Només és present quan el complement de petjada social ha processat el número.

{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "612345678",
  "full_number": "+34612345678",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Movistar", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2026-05-17T10:14:02Z",
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2026-05-17T10:13:51Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
      "fee": 0.02
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2026-05-17T10:13:52Z",
      "details": { "channel": "whatsapp", "status": "delivered" },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2026-05-17T10:14:02Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2026-05-17T10:14:02Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "first_phone",
  "warnings": []
}

Verificació de correu electrònic

Es retorna per cada intent de verificació de correu electrònic. Apareix com a email_verifications[] a GET /v3/session/{sessionId}/decision/ tant per a sessions de KYC com de KYB. Font: email_verification/serializers/email.py:149-164 (EmailV3Serializer, que amplia EmailV2Serializer a email_verification/serializers/email.py:38-146).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	string	No	Consulta Enumeració d’estats.	`"Approved"`
`email`	string	No	L’adreça de correu electrònic enviada.	`"maria.garcia@example.com"`
`is_breached`	boolean	No	`true` quan el correu apareix en una filtració de dades coneguda.	`false`
`breaches`	matriu d’objectes	No	Detall per filtració quan `is_breached` és `true`: `{ name, domain, logo_path, breach_date, description, is_verified, data_classes, breach_emails_count }`.	`[]`
`is_disposable`	boolean	No	`true` quan el correu pertany a un proveïdor de correu d’un sol ús.	`false`
`is_undeliverable`	boolean	No	`true` quan la sonda de lliurament SMTP indica que la bústia no accepta correu.	`false`
`verification_attempts`	integer	No	Nombre total d’intents de comprovació de l’OTP.	`1`
`verified_at`	string (ISO 8601)	Sí	Marca de temps en què s’ha introduït correctament l’OTP.	`"2026-05-17T10:15:22Z"`
`lifecycle`	matriu d’objectes	No	Esdeveniments en ordre cronològic: intents d’enviament, comprovacions del codi i l’esdeveniment d’estat final. Cada esdeveniment és `{ type, timestamp, details, fee }`. Els tipus d’esdeveniment provenen de `EmailEventChoices`.	`[…]`
`matches`	matriu d’objectes	No	Coincidències del correu electrònic entre sessions. Cada element: `{ session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service, source }`. `source` és `session` o `list_entry`.	`[]`
`node_id`	string \| null	Sí	Identificador del node del flux de treball (V3).	`"first_email"`
`warnings`	matriu	No	Consulta Objecte d’advertència.	`[]`
`email_intelligence`	objecte	Sí	Senyals d’intel·ligència del correu electrònic. Només és present quan el complement d’intel·ligència ha processat l’adreça.
`email_social`	objecte	Sí	Petjada social de l’adreça. Només és present quan el complement de petjada social ha processat l’adreça.

{
  "status": "Approved",
  "email": "maria.garcia@example.com",
  "is_breached": false,
  "breaches": [],
  "is_disposable": false,
  "is_undeliverable": false,
  "verification_attempts": 1,
  "verified_at": "2026-05-17T10:15:22Z",
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2026-05-17T10:15:11Z",
      "details": { "status": "Success", "reason": null },
      "fee": 0.02
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2026-05-17T10:15:22Z",
      "details": { "code_tried": "739204", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "EMAIL_VERIFICATION_APPROVED",
      "timestamp": "2026-05-17T10:15:22Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "first_email",
  "warnings": []
}

Validació en bases de dades

Es retorna per cada consulta en bases de dades feta amb les dades enviades per l’usuari. Apareix com a database_validations[] a GET /v3/session/{sessionId}/decision/. Font: database_validation/serializers/database_validation.py:21-142 (DatabaseValidationV3Serializer, que amplia DatabaseValidationV2Serializer).

Camp	Tipus	Nul·lable	Descripció	Exemple
`issuing_state`	cadena (ISO 3166-1 alpha-3)	Sí	País el registre del qual s’ha consultat.	`"ESP"`
`validation_type`	cadena (enum)	No	Com es va corroborar el resultat: `one_by_one` (resultat d’un únic servei), `two_by_two` (dos o més serveis diferents han fet una coincidència completa del número d’identificació de manera independent) o `not_enabled` (el validador s’ha omès o cap proveïdor no ha respost; un `no_match` definitiu encara retorna `one_by_one`). Mai `null`. Font: `DatabaseValidationChoices` (`common/config/choices.py:1097-1100`).	`"one_by_one"`
`screened_data`	objecte	No	Les dades enviades al registre. Els camps de fitxer (`selfie`, `cnh_qr_code_image`, `document_image`) contenen URL signades prèviament en el moment de la lectura.	`{ "document_number": "99999999R", "date_of_birth": "1990-05-12" }`
`validations`	matriu d’objectes	No	Una entrada per cada servei del catàleg que ha produït una coincidència. Cada entrada pot incloure `service_id`, `service_name`, `validation` (objecte de veredicte del proveïdor), `outcome_code`, `outcome_detail` i `source_data` (perfil del ciutadà depurat: `full_name`, `gender`, `date_of_birth`, `photo` (URL prefirmada), `signature` (URL prefirmada), …).	`[…]`
`errors`	matriu d’objectes	Sí	Errors per servei quan una consulta ha fallat; la clau s’omet del tot quan està buida. Cada entrada és l’objecte d’error del servei d’origen més el `service_id` que l’ha produït.	`[]`
`match_type`	cadena (enum)	Sí	Veredicte de coincidència agregat entre els serveis consultats: `full_match`, `partial_match` o `no_match` (`DatabaseValidationMatchTypeChoices`, `common/config/choices.py:1103-1106`). `null` fins que s’avalua.	`"full_match"`
`status`	cadena	No	Vegeu l’enumeració d’estat.	`"Approved"`
`node_id`	cadena \| null	Sí	Identificador del node del flux de treball (V3).	`"first_db_validation"`
`warnings`	matriu	No	Vegeu l’objecte d’advertència.	`[]`

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

Retornada per cada enviament de qüestionari. Apareix com a questionnaire_responses[] a GET /v3/session/{sessionId}/decision/ tant per a sessions KYC com KYB. Font: questionnaires/serializers/questionnaire.py:591-597 (QuestionnaireResponseV3Serializer, que amplia QuestionnaireResponseSerializer a questionnaires/serializers/questionnaire.py:520-588).

Camp	Tipus	Nul·lable	Descripció	Exemple
`questionnaire_id`	cadena (UUID)	No	Identificador de la versió del qüestionari que s’ha respost.	`"6a0f1c2c-…"`
`title`	cadena	No	Nom del qüestionari, tal com s’ha definit a la Consola.	`"Customer risk profile"`
`description`	cadena	Sí	Descripció del qüestionari.	`"Short risk-profile questions."`
`languages`	matriu de cadenes	No	Codis d’idioma en què es publica el qüestionari.	`["en", "es"]`
`default_language`	cadena	No	Codi d’idioma de reserva.	`"en"`
`is_active`	booleà	No	Indica si aquesta versió del qüestionari és la activa.	`true`
`is_simple_questionnaire`	booleà	No	`true` quan el qüestionari no té bifurcacions (llista plana).	`true`
`questionnaire_group_id`	cadena (UUID)	No	Identificador compartit per totes les versions del mateix qüestionari.	`"a7c2c2c2-…"`
`version`	enter	No	Número de versió de la plantilla activa.	`3`
`status`	cadena	No	Un de `Approved`, `In Review` o `Not Finished` (un rebuig a nivell de qüestionari es correspon amb `In Review`).	`"Approved"`
`published_at`	cadena (ISO 8601)	Sí	Moment en què es va publicar la plantilla.	`"2026-01-12T11:00:00Z"`
`sections`	matriu d’objectes	No	Seccions ordenades després d’aplicar el recorregut del graf i el filtratge de visibilitat. Cada secció és `{ title, description, items[] }` (title i description provenen del `SECTION_HEADER` d’obertura, ja traduïts). Cada element és un element de formulari (`uuid`, `value` (identificador del node), `element_type`, `is_required`, `title`, `description`, `placeholder`, `choices`, `max_files`, `required_if`, `repeatable_config`, més un camp `answer`: `null` quan no s’ha respost, i s’omet en els elements de disposició `HEADING`/`PARAGRAPH`/`SEPARATOR`). Les respostes de fitxer contenen `{ files: [<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

Retornada 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 té el pas. A diferència de la resta d’objectes d’informe, el seu status és l’etapa de signatura i el resultat és a verdict, i els elements de warnings[] són { code, node_id } en lloc d’objectes d’advertència.

Camp	Tipus	Nul·lable	Descripció	Exemple
`id`	cadena (UUID)	No	La signatura del signant. Utilitza-la com a `signature_id` a les rutes d’evidència i de validació.	`"0e6c2a8e-…"`
`node_id`	cadena	No	Identificador del node del flux de treball.	`"feature_signature"`
`status`	cadena	No	Etapa de signatura: `intro`, `review`, `code`, `signing`, `signed` o `declined`. Només `signed` significa que els documents estan signats.	`"signed"`
`verdict`	cadena	No	`Not Finished`, `Approved`, `In Review` o `Declined`.	`"Approved"`
`level`	cadena	No	`simple` (per defecte) o `aes`. `qes` és un complement que encara no està disponible.	`"aes"`
`format`	cadena	No	`pdf` per a una signatura simple, `pades` per a una signatura avançada (AES).	`"pades"`
`profile`	cadena	Sí	`PAdES-B-LT` quan una signatura avançada (AES) està signada; altrament, null.	`"PAdES-B-LT"`
`signer`	objecte	No	`{ name, capacity, company, role, roles, identity_session_id }`. `capacity` és `self` (KYC) o `company` (KYB).	`{ "name": "Jane Doe", "capacity": "self", … }`
`identity_used`	objecte	No	`{ session_id, kyc_id, verified, expected_name }`: la identitat verificada en què es basa la signatura. Buit per a una signatura simple sense identitat verificada.	`{ "verified": true, … }`
`certificate`	objecte	Sí	`{ issuer, issued_to, serial, valid_from, valid_until }`. `null` fins que es signa, i sempre `null` en una signatura simple.	`{ "serial": "5A3F9C21", … }`
`confirmation`	objecte	No	`{ channel, destination, confirmed_at, attempts }`. `destination` està emmascarat; `attempts` compta els codis introduïts, inclòs el correcte. Una signatura simple no té codi, de manera que `channel` i `destination` són `null`.	`{ "channel": "email", … }`
`timestamp`	objecte	Sí	`{ time, qualified, valid }`. `qualified` és sempre `false` per a AES. `null` fins que es signi, i sempre `null` per a una signatura simple.	`{ "qualified": false, … }`
`documents`	array d’objectes	No	`{ id, uuid, title, file_name, pages, size_bytes, sha256_original, sha256_signed, status, opened_at, read_at, read_to_end, consented_at, consent, signed_file, mode, source_format, conversion, fields }`. `status` és `signed`, `declined`, `not_signed` o `not_reached`. `mode` és `fields` o `read_and_agree`. `source_format` és `pdf` o `docx`; `conversion` descriu el fitxer Word original, o és `null` per a un PDF.	`[…]`
`documents[].fields`	array d’objectes	No	`{ key, type, role, label, page, x, y, width, height, required, value, display_value, value_source, filled_at, image_url, value_unavailable_reason }` per a cada camp del document. `value` és una cadena, un booleà per a una casella de verificació, o `true` per a una signatura o inicials aplicades. Buit per a un document sense camps.	`[…]`
`adopted_signature`	objecte	Sí	`{ method, font, adopted_at }`: la signatura i les inicials que el signant ha adoptat. `method` és `typed` o `drawn`; `font` és l’estil de cal·ligrafia d’una signatura escrita amb teclat. `null` fins que s’adoptin.	`{ "method": "drawn", … }`
`electronic_signature_consent_at`	string (ISO 8601)	Sí	Quan el signant va acceptar signar els documents electrònicament. S’estableix quan algun document té camps.	`"2026-11-03T10:41:40Z"`
`evidence_file`	string	Sí	Ruta del PDF d’evidències, un cop signat.	`"/v3/session/…/evidence/?signature_id=…"`
`warnings`	array d’objectes	No	`{ code, node_id }`, amb `code` un dels valors següents: `SIGNATURE_DECLINED`, `SIGNATURE_OTP_FAILED`, `SIGNATURE_NAME_MISMATCH`, `SIGNATURE_IDENTITY_NOT_VERIFIED`, `SIGNATURE_DOCUMENT_CHANGED`.	`[]`
`validation`	objecte	Sí	`{ valid, checked_at, documents[] }`: l’última comprovació criptogràfica dels documents signats. `null` fins que s’hagin signat. `{ valid: null, reason: "signature_provider_outcome_unknown", checked_at }` quan no s’ha pogut confirmar el resultat de la signatura.	`{ "valid": true, … }`
`declined_at`	string (ISO 8601)	Sí	Quan el signant va rebutjar la signatura.	`null`
`declined_action`	string	No	L’`signature_declined_action` del pas.	`"REVIEW"`
`signed_at`	string (ISO 8601)	Sí	Quan es van signar els documents.	`"2026-11-03T10:42:24Z"`
`expires_at`	string (ISO 8601)	No	Quan l’enllaç de signatura deixa de funcionar.	`"2026-11-10T10:30:00Z"`
`email_sent_at`	string (ISO 8601)	Sí	Quan es va enviar al signant una còpia signada per correu electrònic.	`"2026-11-03T10:42:30Z"`
`email_unavailable_reason`	string	Sí	Per què no es va enviar cap còpia, quan se n’havia sol·licitat una.	`null`
`ip_address`	string	Sí	L’adreça IP del signant quan va demanar el seu codi.	`"203.0.113.10"`
`place`	string	Sí	No es recull: sempre `null`.	`null`
`place_unavailable_reason`	string	Sí	`not_collected`.	`"not_collected"`

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

Estimació d’edat

Retornat per l’API independent d’Estimació d’edat (POST /v3/age-estimation/). La resposta conté un subconjunt de la forma de Liveness check sota un embolcall age_estimation (status, method, score, age_estimation, warnings), més un bloc user_image de detecció de rostres exclusiu de l’API independent; no inclou reference_image, video_url, matches, face_quality ni face_luminance. En les sessions de flux de treball no hi ha un array separat: l’edat estimada apareix com a liveness_checks[].age_estimation a GET /v3/session/{sessionId}/decision/. Font: apis/serializers/age_estimation.py:50-55 (AgeEstimationResponseSerializer), embolcall muntat a apis/views/age_estimation.py:138-174.

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

{
  "request_id": "3b1f1e2c-7777-4d2c-9eb6-fdc6c7c92ef9",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 94.10,
    "age_estimation": 28.7,
    "user_image": {
      "entities": [
        { "age": 28.7, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": null,
  "metadata": null,
  "created_at": "2026-05-17T10:22:13.512941+00:00"
}

Autenticació biomètrica

L’autenticació biomètrica executa el mateix flux de processament de prova de vida i coincidència facial que s’usa en el KYC estàndard, però configurat per comparar el rostre capturat amb la imatge de referència d’un usuari existent, en lloc d’un retrat de document extret amb OCR. No hi ha cap serialitzador dedicat: GET /v3/session/{sessionId}/decision/ retorna els objectes estàndard de Prova de vida i Coincidència facial sota liveness_checks[] i face_matches[]. El flux de treball de la sessió es configura amb workflow_type = "biometric_authentication" (WorkflowTypeChoices, common/config/choices.py:636).

Camp	Tipus	Nul·lable	Descripció	Exemple
`liveness_checks`	array de Prova de vida	No	Resultat de la prova de vida per al intent d’autenticació.	`[ { "status": "Approved", … } ]`
`face_matches`	array de Coincidència facial	No	Resultat de la coincidència amb la referència registrada. `source_image_session_id` s’estableix al `session_id` propi de la sessió: el rostre de referència (el `portrait_image` proporcionat, o el rostre emmagatzemat reutilitzat mitjançant `vendor_data` quan s’omet `portrait_image`) queda registrat sota la mateixa sessió d’autenticació (`face/views/face.py:656-659`).	`[ { "status": "Approved", "source_image_session_id": "…", … } ]`
`status`	string	No	Estat de la sessió de nivell superior (vegeu Enumeració d’estats).	`"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

Es retorna per cada empresa confirmada pel registre en un flux de treball KYB. Apareix com a registry_checks[] a GET /v3/session/{sessionId}/decision/ per a les sessions d’empresa. Font: kyb/serializers/kyb.py:939-964 (RegistryCheckV3Serializer).

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

Objecte d’empresa

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

Camp	Tipus	Nul·lable	Descripció
`uuid`	string (UUID)	No	Identificador intern de l’empresa.
`node_id`	string \| null	Sí	Identificador del node del flux de treball.
`status`	string	No	Estat de la funcionalitat (`FeatureStatusChoices`).
`registry_status`	string	Sí	Estat de l’empresa al registre (`active`, `dissolved`, …).
`data_resolved`	boolean	No	Mateixa definició que a l’objecte pare.
`company_name`	string	Sí	Nom registrat de l’empresa.
`registration_number`	string	Sí	Identificador del registre.
`country_code`	string (ISO 3166-1 alpha-2)	Sí	País de constitució.
`region`	string	Sí	Subdivisió ISO 3166-2 quan escaigui (p. ex. `US-CA`).
`company_type`	string	Sí	Forma jurídica (`LLC`, `SL`, …).
`incorporation_date`	string (YYYY-MM-DD)	Sí	Data de constitució.
`registered_address`	string	Sí	Adreça jurídica registrada.
`tax_number`	string	Sí	Identificador fiscal o d’IVA.
`risk_level`	string	Sí	Qualificació de risc facilitada pel proveïdor.
`verification_status`	string	Sí	Enumeració interna de l’estat de verificació.
`is_from_registry`	boolean	No	`true` quan la informació procedeix del registre (en lloc de l’entrada manual).
`fetch_status`	string	Sí	`pending`, `resolved`, `failed`.
`alternative_names`	string	Sí	Noms comercials alternatius separats per comes.
`nature_of_business`	string	Sí	Descripció en text lliure de l’activitat empresarial.
`registered_capital`	string	Sí	Capital social registrat com a cadena de text llegible per a humans.
`registered_capital_amount`	string (decimal)	Sí	Import processat del capital social registrat.
`registered_capital_currency`	string (ISO 4217)	Sí	Codi de moneda.
`website`	string (URL)	Sí	Lloc web de l’empresa.
`email`	string	Sí	Correu electrònic de contacte públic.
`phone`	string	Sí	Telèfon de contacte públic.
`legal_entity_identifier`	string	Sí	LEI quan està disponible.
`location_of_registration`	string	Sí	Oficina o regió del registre.
`vat_number`	string	Sí	Número d’IVA presentat per a l’empresa.
`vat_validation_status`	string	No	Resultat de validar el número d’IVA, o del `tax_number` quan no n’hi ha: `valid`, `invalid`, `format_valid`, `invalid_format`, `could_not_validate` o `not_applicable`. Vegeu Validació d’IVA i identificador fiscal.
`vat_validated_number`	string	Sí	El número que s’ha comprovat, tal com el coneix la font.
`vat_validation_source`	string	Sí	Font que va decidir l’estat: `eu_vies`, `pl_vat_white_list`, `no_brreg`, `ch_uid_register`, `br_receita_federal`, `co_rues`, `cr_hacienda`, `ec_sri`, `py_dnit` o `format_rules`.
`vat_validated_name`	string	Sí	Nom registrat a la font (buit quan no en revela cap).
`vat_validated_address`	string	Sí	Adreça registrada a la font (buida quan no es revela).
`vat_checked_at`	string (ISO 8601)	Sí	Marca temporal de la comprovació; `null` quan no s’ha fet cap comprovació.
`financial_summary`	object	Sí	Instantània dels principals indicadors financers quan els facilita el registre.
`officers`	array of objects	No	Llista de càrrecs apta per a B2C: `{ uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }`.
`beneficial_owners`	array of objects	No	Llista de titulars reals (UBO) apta per a B2C: `{ uuid, name, first_name, last_name, entity_type, roles, ownership_min_shares, ownership_max_shares, is_active, kyc_status, kyc_session_url, effective_ownership_percent }`.
`addresses`	array of objects	Sí	Detall per adreça procedent del registre.
`industries`	array of objects	Sí	Classificacions d’estil SIC/NAICS.
`accounts`	array of objects	Sí	Metadades dels comptes presentats.
`registry_data`	object	Sí	Detall normalitzat del registre de Didit (resultat de la titularitat, correccions de la consola, dades del registre que no tenen camp propi). No és un contracte estable.
`user_provided_data`	object	Sí	Instantània dels camps editats per l’usuari.
`confirmed_by_user_at`	string (ISO 8601)	Sí	Marca temporal en què l’usuari va confirmar les dades extretes.
`last_console_edit_at`	string (ISO 8601)	Sí	Marca temporal de l’última edició a la consola.
`is_editable`	boolean	No	`true` mentre l’usuari final encara pugui editar les dades procedents del registre.

{
  "status": "Approved",
  "node_id": "first_registry",
  "data_resolved": true,
  "company": {
    "uuid": "b1f1e2c2-9999-4d2c-9eb6-fdc6c7c92ef9",
    "node_id": "first_registry",
    "status": "Approved",
    "registry_status": "active",
    "data_resolved": true,
    "company_name": "Sante Clinics SL",
    "registration_number": "B12345678",
    "country_code": "ES",
    "region": null,
    "company_type": "SL",
    "incorporation_date": "2018-03-22",
    "registered_address": "Calle Mayor 1, 28001 Madrid, Spain",
    "tax_number": "B12345678",
    "risk_level": "low",
    "verification_status": "verified",
    "is_from_registry": true,
    "fetch_status": "resolved",
    "alternative_names": "Sante Clinics",
    "nature_of_business": "Medical clinic operations",
    "registered_capital": "EUR 50,000",
    "registered_capital_amount": "50000.00",
    "registered_capital_currency": "EUR",
    "website": "https://santeclinics.com",
    "email": "info@santeclinics.com",
    "phone": "+34911223344",
    "legal_entity_identifier": null,
    "location_of_registration": "Registro Mercantil de Madrid",
    "vat_number": "ESB12345678",
    "vat_validation_status": "valid",
    "vat_validated_name": "SANTE CLINICS SL",
    "vat_validated_address": "CALLE MAYOR 1, 28001 MADRID",
    "vat_checked_at": "2026-05-17T10:11:05Z",
    "financial_summary": null,
    "officers": [
      {
        "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "designation": "Administrador único",
        "role": "Director",
        "nationality": "ESP",
        "is_active": true,
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…"
      }
    ],
    "beneficial_owners": [
      {
        "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "first_name": "María",
        "last_name": "García López",
        "entity_type": "person",
        "roles": ["UBO"],
        "ownership_min_shares": "75.00",
        "ownership_max_shares": "75.00",
        "is_active": true,
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "effective_ownership_percent": 75.0
      }
    ],
    "addresses": [],
    "industries": [],
    "accounts": [],
    "registry_data": {},
    "user_provided_data": {},
    "confirmed_by_user_at": "2026-05-17T10:11:02Z",
    "last_console_edit_at": null,
    "is_editable": false
  },
  "ownership_structure": null,
  "warnings": []
}

Document KYB

Es retorna per cada node que recull documents de suport KYB. Apareix com a document_verifications[] a GET /v3/session/{sessionId}/decision/ per a les sessions d’empresa: una entrada per node_id, amb items[] que enumera cada document pujat. Font: kyb/serializers/kyb.py:1053-1068 (DocumentVerificationV3Serializer); cada element segueix kyb/serializers/kyb.py:811-851 (KYBDocumentResponseSerializer).

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	cadena	No	Estat agregat dels documents d’aquest node: `Approved` només quan tots els documents del flux estan aprovats; `Declined` si algun està rebutjat; `In Review` en cas contrari; `Not Finished` mentre estigui pendent. Consulta Enumeració d’estats.	`"Approved"`
`node_id`	cadena \| null	Sí	Identificador del node del flux de treball (V3).	`"first_kyb_documents"`
`items`	matriu d’objectes d’elements de documents KYB	No	Una entrada per cada document pujat o sol·licitat.	`[…]`
`groups`	objecte	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`	matriu de cadenes	No	Grups de documents que requereix la configuració del flux de treball.	`["incorporation_certificate", "shareholder_register"]`
`warnings`	matriu	No	Consulta Objecte d’advertència.	`[]`

Objecte d’element d’un document KYB

Camp	Tipus	Nul·lable	Descripció
`uuid`	cadena (UUID)	No	Identificador intern del document.
`document_type`	cadena	Sí	Grup d’alt nivell (`incorporation_certificate`, `shareholder_register`, …).
`document_subtype`	cadena	Sí	Subtipus específic del proveïdor.
`document_group`	cadena	Sí	Reflex de `document_type` (àlies mantingut per claredat).
`file_url`	cadena (URL)	Sí	URL prefirmada del fitxer netejat.
`original_filename`	cadena	Sí	Nom del fitxer tal com s’ha pujat.
`file_size`	enter	Sí	Mida del fitxer en bytes.
`status`	cadena	No	Estat per document (`FeatureStatusChoices`).
`created_at`	cadena (ISO 8601)	No	Marca de temps de la pujada.
`cross_check_result`	objecte	Sí	Veredicte de la verificació creuada amb el registre o altres documents.
`document_metadata`	objecte	Sí	Mateixa estructura de metadades filtrades que `document_metadata` del comprovant de domicili.
`description`	cadena	Sí	Descripció facilitada pel revisor o pel sistema.
`is_requested`	booleà	No	`true` quan el flux de treball esperava aquest document.
`ocr_data`	objecte	Sí	Camps extrets per OCR quan n’hi ha.
`is_console_upload`	booleà	No	`true` quan el document l’ha pujat un revisor de la consola (exclòs del veredicte agregat).
`is_confirmed`	booleà	No	`true` quan el revisor ha confirmat explícitament el document.

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

Camp	Tipus	Nul·lable	Descripció	Exemple
`status`	cadena	No	Consulta Enumeració d’estats.	`"Approved"`
`node_id`	cadena \| null	Sí	Identificador del node del flux de treball (V3).	`"first_key_people"`
`registry`	objecte	No	`{ officers[], beneficial_owners[] }` extrets del registre. Els administradors segueixen `KYBPersonResponseSerializer` (`kyb/serializers/kyb.py:533-645`); els titulars reals segueixen `KYBBeneficialOwnerResponseSerializer` (`kyb/serializers/kyb.py:648-788`, que afegeix `date_of_birth`, `country_of_birth`, `email`, `company_name`, `registration_number`, `entity_type`, `roles`, `ownership_min_shares`, `ownership_max_shares`, `child_beneficial_owners`, `effective_ownership_percent`). Tots dos inclouen l’enriquiment AML i KYC per a cada part (`aml_status`, `kyc_status`, `kyc_session_url`, `kyc_session_id`, `verification_workflow_type`, `verification_workflow_id`, `verification_workflow_label`, `verification_workflow_features`, `didit_internal_id`, `kyc_document_type`, `kyc_nationality`, `kyc_liveness_passed`, `kyc_verified_at`, `kyc_aml_categories`, `kyc_notification_sent_at`).	`{ "officers": [...], "beneficial_owners": [...] }`
`submitted`	objecte	No	`{ parties[] }` - entrades que l’empresa ha confirmat o enviat mitjançant el flux de persones clau (files de `BusinessParty` amb `source=USER`). Cada part segueix `BusinessPartySubmissionResponseSerializer` (`kyb/serializers/party.py:146-194`): `uuid`, `entity_type`, `source`, `name`, `first_name`, `last_name`, `company_name`, `registration_number`, `email`, `nationality`, `phone_number`, `date_of_birth`, `position`, `custom_fields`, `is_active`, `is_skipped`, `requires_verification`, `roles[]` (`{ role, ownership_percent, voting_percent }`), `kyc_session_id`, `kyc_session_status`, `kyc_session_url`, `kyc_session_deleted`, `kyb_sub_session_id`, `kyb_sub_session_status`, `kyb_sub_session_url`, `kyb_sub_session_deleted`, `verification_workflow_type`, `verification_workflow_id`, `verification_workflow_label`, `verification_workflow_features`, `didit_internal_id`. `kyc_session_deleted` i `kyb_sub_session_deleted` indiquen que una sessió filla s’ha eliminat: el seu estat es manté congelat amb el valor que tenia, el `*_session_url` corresponent torna `null` perquè l’enllaç ja no resol, i la part deixa de bloquejar la sessió pare (la verificació passa a `In Review`). Restableix-lo amb `PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`.	`{ "parties": [...] }`
`ubo_kyc_summary`	objecte	Sí	Recomptes dels UBO actius amb KYC vinculat: `{ total, approved, flagged, pending }`. `null` quan cap UBO actiu no té KYC vinculat.	`{ "total": 2, "approved": 2, "flagged": 0, "pending": 0 }`
`warnings`	matriu	No	Consulta Objecte d’advertència.	`[]`

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

​Visió general

​Camps comuns

​Objecte d’advertència

​Objectes d’informe

​Verificació d’identitat

​Verificació NFC

​Prova de vida

​Coincidència facial

​Cerca facial

​Objecte de coincidència de cerca facial

​Cribratge AML

​Anàlisi d’IP

​Verificació de la ubicació

​Comprovant de domicili

​Verificació de telèfon

​Verificació de correu electrònic

​Validació en bases de dades

​Resposta del qüestionari

​Signatura electrònica

​Estimació d’edat

​Autenticació biomètrica

​Registre KYB

​Objecte d’empresa

​Document KYB

​Objecte d’element d’un document KYB

​Persona clau KYB

​Camps a nivell de decisió

​Consentiment biomètric

​Referència d’enumeració d’estats

​Estats a nivell de funcionalitat

​Estats a nivell de sessió

Visió general

Camps comuns

Objecte d’advertència

Objectes d’informe

Verificació d’identitat

Verificació NFC

Prova de vida

Coincidència facial

Cerca facial

Objecte de coincidència de cerca facial

Cribratge AML

Anàlisi d’IP

Verificació de la ubicació

Comprovant de domicili

Verificació de telèfon

Verificació de correu electrònic

Validació en bases de dades

Resposta del qüestionari

Signatura electrònica

Estimació d’edat

Autenticació biomètrica

Registre KYB

Objecte d’empresa

Document KYB

Objecte d’element d’un document KYB

Persona clau KYB

Camps a nivell de decisió

Consentiment biomètric

Referència d’enumeració d’estats

Estats a nivell de funcionalitat

Estats a nivell de sessió