Saltar al contingut principal
POST
curl

Serveis basats en adreces

Per als serveis que validen una adreça de residència o de subministrament, pots enviar una sola address i Didit la dividirà abans de processar la comprovació. Per obtenir la millor taxa de coincidència, envia directament els camps d’adreça estructurats de Didit: Els camps estructurats substitueixen el valor únic de address. postal_code s’accepta com a àlies de address_element_5.

Consentiment

Alguns serveis de bases de dades requereixen el consentiment explícit de l’usuari final abans que el proveïdor es pugui consultar. El catàleg de serveis marca aquestes files amb requires_consent=true. Envia consent=true quan el consentiment de l’usuari s’aplica als serveis seleccionats. Didit rebutja la sol·licitud abans de cap crida al proveïdor o cap esdeveniment de facturació si algun servei seleccionat requereix consentiment i no l’envies.

Càrrega de fitxers

La validació de bases de dades utilitza multipart/form-data. Els serveis biomètrics que requereixen selfie mostren aquest camp com a càrrega de fitxer a l’entorn de proves de l’API, de manera que pots seleccionar una imatge directament en lloc d’enganxar una ruta o una cadena en base64. Al codi, puja el fitxer amb la sintaxi multipart habitual:

Errors de validació

Didit valida els camps obligatoris, l’estructura de l’adreça i els formats específics de cada servei abans de cridar el proveïdor. Per exemple, els serveis de registres xinesos com chn_national_id i chn_passport_verification esperen full_name en l’escriptura xinesa original, i chn_national_id també requereix un número d’identitat nacional xinès vàlid de 15 o 18 caràcters amb una suma de control correcta. Si una sol·licitud no es pot executar, l’API retorna errors explícits per camp i no es factura cap ús. Si un proveïdor falla després de la validació prèvia, la resposta inclou validation_errors, i les sol·licituds d’API desades emmagatzemen aquests errors al resultat de la validació de bases de dades.

Entrada rebutjada i resultats no disponibles

Quan cap servei no retorna un resultat utilitzable, revisa cada entrada de validation_errors abans de decidir si cal reintentar. L’estat HTTP per si sol no determina si és adequat reintentar. Una resposta 400 amb code: "provider_rejected_input" i retryable: false significa que cada intent sense resposta ha rebutjat explícitament l’entrada. Corregeix les dades subministrades abans de tornar-ho a provar. Aquests intents no es facturen. Una resposta 502 amb code: "empty_provider_response" i retryable: true significa que el servei no ha pogut produir un resultat utilitzable per un altre motiu. Això inclou una entrada rebutjada seguida d’una alternativa no disponible o d’una alternativa que no ofereix cap explicació. Torna-ho a intentar més tard; la resposta no demostra que l’entrada sigui incorrecta. Si una base de dades continua fallant, Didit envia un correu electrònic a les organitzacions que l’han utilitzat recentment quan la interrupció es prolonga, i de nou quan les comprovacions reals confirmen que torna a respondre; consulta Notificacions de disponibilitat. Quan només fallen alguns dels serveis seleccionats, la sol·licitud es completa igualment: la resposta és 200 i els serveis que han fallat es mostren a database_validation.errors[], cadascun amb els mateixos camps code i retryable. database_validation.status aleshores segueix els serveis que sí han respost i pot ser Approved, així que revisa errors[] en cada resposta i no només en una resposta 4xx o 5xx. Un servei que apareix allà no apareix a validations ni a services_used, i no es factura; torna a intentar aquest servei per separat. Altres errors 502 poden requerir dades corregides. Per exemple, provider_invalid_input i provider_validation_error descriuen una entrada que la font ha rebutjat i que no s’ha de reintentar sense canvis, fins i tot quan la resposta heretada no inclou retryable. La guia de reintent per a empty_provider_response no s’aplica a aquests codis. Un resultat concloent de no coincidència és una comprovació completada, no un error de disponibilitat.

Autoritzacions

x-api-key
string
header
requerit

La clau d'API de la teva aplicació, des de Developers -> API keys a la Business Console. La clau primària té accés complet. Una clau amb nom pot tenir l'abast limitat: cap, lectura o escriptura per recurs, limitada a determinats fluxos de treball o a sessions aprovades, a una llista d'adreces IP i a una data de caducitat. 401 significa que la clau és incorrecta, revocada o caducada; 403 significa que no s'ha enviat cap clau, que la clau no té accés a aquest recurs o acció, o que la sol·licitud prové d'una adreça fora de la seva llista d'IP; 404 en una ruta de sessió significa que la sessió està fora dels fluxos de treball o estats de la clau. Una clau sense accés a fitxers multimèdia rep els URL d'imatge, vídeo i PDF com a null, i una clau sense permís d'escriptura de sessions rep els enllaços de sessió i els tokens com a null. Consulta https://docs.didit.me/console/api-keys.

Cos

issuing_state
string
requerit

Codi de país ISO 3166-1 alfa-3 del registre contra el qual s'ha de validar (p. ex. BRA, ESP, COL). Determina quins serveis estan disponibles. Els codis no admesos retornen 400 amb la llista completa d'opcions vàlides.

Exemple:

"BRA"

services
string[]

service_ids de catàleg que s'han d'executar per a aquest país (p. ex., ["bra_cpf"]). També accepta una sola cadena o una cadena separada per comes / codificada en JSON. Si s'omet o és buit, s'executa exactament un servei per defecte —el servei en producció més consolidat per al país; els serveis més nous, biomètrics i de pagament per ús s'han d'especificar explícitament. Enviar services canvia la resposta a l'estructura ampliada (afegeix services_used i match_score). Cada id ha d'existir i estar actiu per a l'issuing_state; els serveis que requereixen alta retornen 400 fins que s'activin per a la teva organització. Descobreix els serveis disponibles per país mitjançant GET /v1/organization/database-validation-countries/ (un endpoint de catàleg no documentat en aquesta especificació) o l'editor de fluxos de treball de la Business Console.

Exemple:
validation_type
string
obsolet

OBSOLET. S'accepta per compatibilitat amb versions anteriors però s'ignora: el validation_type de la resposta ara es deriva de quants serveis han coincidit completament. Utilitza services per fixar serveis específics.

Estableix-ho a true quan l'usuari final hagi donat el consentiment explícit als serveis de validació seleccionats. Requerit per als serveis marcats amb requires_consent=true al catàleg — sense ell, aquests serveis retornen 400 amb services_requiring_consent.

identification_number
string

Número d'identificació universal — s'assigna automàticament al camp correcte específic de cada país, de manera que pots utilitzar-lo en lloc de personal_number/tax_number/document_number: ARG→document_number (DNI), BOL→document_number (CI), BRA→tax_number (CPF, 11 dígits), CHL→personal_number (RUT), COL→personal_number (Cédula), CRI→personal_number (Cédula), DOM→personal_number (Cédula, 11 dígits), ECU→personal_number (Cédula, 10 dígits), ESP→personal_number (DNI/NIE), GTM→document_number (DPI), HND→document_number (DNI), MEX→personal_number (CURP, 18 caràcters), PAN→personal_number (Cédula), PER→personal_number (DNI, 8 dígits), PRY→document_number (CI), SLV→document_number (DUI), URY→personal_number (CI), VEN→document_number (Cédula). Mai no sobreescriu un camp específic del país proporcionat de manera explícita.

first_name
string

El nom de la persona física. Requerit per alguns serveis/països.

Exemple:

"John"

last_name
string

Els cognoms de la persona física. Requerits per alguns serveis/països.

Exemple:

"Doe"

middle_name
string

Segon nom, utilitzat per serveis d'alguns països (AUS, NZL, …).

full_name
string

Nom complet — alguns serveis l'accepten en lloc del nom/cognoms (p. ex., serveis de CHN, que fan coincidir el nom en el sistema d'escriptura natiu).

date_of_birth
string<date>

Data de naixement, YYYY-MM-DD. Requerida per molts serveis.

Exemple:

"1980-01-01"

personal_number
string

Identificador personal únic emès pel govern. Fes servir: CHL (RUT), COL (Cédula), CRI, DOM, ECU, ESP (DNI/NIE), MEX (CURP), PAN (Cédula), PER (DNI), URY. Considera fer servir identification_number en el seu lloc.

tax_number
string

Identificador fiscal. Utilitzat per: BRA (CPF, 11 dígits). Considera utilitzar identification_number en el seu lloc.

document_number
string

Número de document. Utilitzat per: ARG (DNI), BOL (CI), GTM (DPI), HND (DNI), PRY (CI), SLV (DUI), VEN (Cédula). Considera utilitzar identification_number en el seu lloc.

document_type
enum<string>

Tipus de document que s'està validant: P passaport, DL permís de conduir, ID document nacional d'identitat, RP permís de residència (a més de SSC, HIC, WP, TC, VISA, PSC, BC, OTHER). Requerit per alguns serveis (p. ex., ESP).

Opcions disponibles:
P,
DL,
ID,
RP,
SSC,
HIC,
WP,
TC,
VISA,
PSC,
BC,
OTHER
expiration_date
string<date>

Data de caducitat del document, YYYY-MM-DD. Obligatòria per a la validació d'ESP (Espanya).

Exemple:

"2030-01-15"

date_of_issue
string<date>

Data d'emissió del document, YYYY-MM-DD (fecha de expedición). Obligatòria per a la validació de la cèdula de COL (Colòmbia).

Exemple:

"2015-06-20"

nationality
string

Nacionalitat en format ISO 3166-1 alpha-3. Requerida per alguns serveis.

gender
enum<string>

Gènere: M, F o X (altre/desconegut). Obligatori per a la validació de RENAPER de l'Argentina (arg_renaper).

Opcions disponibles:
M,
F,
X
address

Adreça de residència. Es recomana l'objecte estructurat {"street_1":"123 Main St","street_2":"Apt 4B","city":"Springfield","region":"IL","postal_code":"62701","country":"US"}; encara s'accepta una cadena completa d'una sola línia. Obligatori per als serveis de verificació d'adreça; quan un servei defineix requisits d'adreça, les parts que faltin retornen 400 amb address_fields_required_by.

address_element_1
string

Adreça que inclou el carrer, el número i el tipus de via. Si s'omet, es dedueix de address.

address_element_2
string

Apartament, unitat, edifici, planta o línia d'adreça addicional. Envia-ho només quan ho tinguis explícitament.

address_element_3
string

Ciutat, suburbi, districte, localitat o barri. Si s'omet, es deriva d'address.

address_element_4
string

Estat, província, regió o població. Si s'omet, es deriva d'address.

address_element_5
string

Codi postal. S'accepta postal_code com a àlies.

postal_code
string

Codi postal per a serveis basats en adreça (àlies de address_element_5).

driver_license_number
string

Número del permís de conduir per a serveis governamentals de verificació de documents (AUS, NZL, IND).

driver_license_card_number
string

Número de la targeta física del permís de conduir, quan es requereix per separat del número de permís (AUS).

driver_license_state
string

Estat o territori d'emissió del permís de conduir (AUS).

driver_license_version
string

Codi de versió del permís de conduir (NZL).

passport_number
string

Número de passaport per als serveis governamentals de verificació de passaports (AUS, NZL, IND, CHN).

passport_expiration_date
string<date>

Data de caducitat del passaport, YYYY-MM-DD, per als serveis de verificació de passaports.

passport_file_number
string

Número de fitxer del passaport (IND).

passport_issue_country
string

País emissor del passaport (ISO 3166-1 alfa-3) per a serveis de verificació de passaport.

medicare_card_number
string

Número de targeta Medicare (AUS).

immi_card_number
string

Número de la ImmiCard australiana.

immi_card_expiry_date
string<date>

Data de caducitat de la ImmiCard australiana.

citizenship_certificate_number
string

Número de certificat de ciutadania (AUS).

birth_registration_number
string

Número de registre del certificat de naixement (AUS).

birth_registration_date
string<date>

Data de registre del certificat de naixement (AUS).

birth_registration_state
string

Estat de registre del certificat de naixement (AUS).

marriage_certificate_number
string

Número del certificat de matrimoni (AUS).

change_of_name_certificate_number
string

Número del certificat de canvi de nom (AUS).

first_partner_name
string

Nom de pila del cònjuge en un certificat de matrimoni (AUS).

last_partner_name
string

Cognom del cònjuge en un certificat de matrimoni (AUS).

voter_id
string

Número d'inscripció electoral (IND EPIC, IRL).

epic_card
string

Número de la targeta d'elector EPIC de l'Índia.

pan
string

PAN (Permanent Account Number) de l'Índia.

national_id
string

Número d'identificació nacional (CHN, MYS, KEN, KHM, NGA, ZAF, …).

cic
string

Codi d'identificació de credencial (CIC) de l'INE/IFE mexicà, 9 dígits. S'utilitza pel servei de validesa de credencials MEX INE (mex_ine_vigencia).

identificador_ciudadano
string

Identificador de ciutadà de l'INE mexicà (9 dígits). S'utilitza amb cic per a models moderns de l'INE (E/F/G/H) a mex_ine_vigencia.

ocr
string

Número OCR de l'INE mexicà (13 dígits, dors de la targeta). S'utilitza amb cic per al Model D a mex_ine_vigencia.

voter_number
string

Clau d'elector de l'INE mexicà (18 caràcters). S'utilitza amb emission_number per a models antics de l'IFE (A/B/C) a mex_ine_vigencia.

emission_number
string

Número d'emissió de l'INE mexicà. S'utilitza amb voter_number per a models antics de l'IFE (A/B/C) a mex_ine_vigencia.

bvn
string

Número de verificació bancària de Nigèria.

bank_card_number
string

Número de targeta bancària (verificació de targeta bancària CHN).

company_registration_number
string

Número de registre de l'empresa tal com l'emet el registre mercantil: el CNPJ al Brasil (p. ex., 11222333000181), el número de registre a Sud-àfrica (p. ex., 1936/007721/06). Requerit pels serveis de registre mercantil i administradors d'empreses (bra_company_registry, bra_company_directors, zaf_company_registry, zaf_company_directors).

company_name
string

Nom de l'empresa registrada, confrontat amb l'entrada del registre. Opcional per a zaf_company_registry.

initials
string

Les inicials de la persona tal com apareixen impreses al document. Requerides per zaf_drivers_license; acceptades per zaf_bank_account_holder.

licence_number
string

Número del permís de conduir tal com apareix imprès a la targeta, per a zaf_drivers_license. Quan s'omet, s'utilitza document_number.

refugee_file_number
string

Número d'expedient de refugiat emès pel Department of Home Affairs de Sud-àfrica. Requerit per a zaf_refugee.

bank_name
string

Nom del banc titular del compte. Requerit per zaf_bank_account_holder.

bank_account_number
string

Número de compte bancari. Obligatori per a zaf_bank_account_holder; admès per zaf_fraud_prevention.

account_type
string

Tipus de compte bancari per a zaf_bank_account_holder: current, savings, transmission, subscriptionShare o notKnown, sense distingir majúscules i minúscules. Qualsevol altre valor retorna 400. Omet-lo si no en saps el tipus: la comprovació creuada del tipus de compte s'informa llavors com a no confirmada.

phone_number
string

Número de telèfon mòbil de contacte, per als serveis que verifiquen de forma creuada la contactabilitat (zaf_bank_account_holder, zaf_fraud_prevention, zaf_refugee).

right_thumb
string

Empremta dactilar del polze dret codificada en base64 per a zaf_dha_fingerprint_match, juntament amb left_thumb o sola.

left_thumb
string

Empremta dactilar del polze esquerre codificada en base64 per a zaf_dha_fingerprint_match, juntament amb right_thumb o sola.

score_level
integer

Nivell mínim de puntuació biomètrica per a zaf_criminal_face_screening. Per defecte és 3.

max_matches
integer

Nombre màxim de coincidències candidates que retorna zaf_criminal_face_screening. Per defecte és 1.

vehicle_register_number
string

Número de registre del vehicle. Obligatori, juntament amb vehicle_licence_plate i vin, per a zaf_vehicle_ownership.

vehicle_licence_plate
string

Número de matrícula del vehicle. Obligatori, juntament amb vehicle_register_number i vin, per a zaf_vehicle_ownership.

vin
string

Número d'identificació del vehicle (VIN o número de bastidor). Obligatori, juntament amb vehicle_register_number i vehicle_licence_plate, per a zaf_vehicle_ownership.

ssn
string

Número de la Seguretat Social (EUA).

phone
string

Número de telèfon per als serveis de verificació de telèfon.

landline
string

Número de telèfon fix per als serveis de verificació de telèfon.

email
string<email>

Adreça de correu electrònic per als serveis de verificació d'identitat.

country_of_residence
string

País de residència ISO 3166-1 alpha-2. Utilitzat pels serveis globals d'enriquiment d'identitat (p. ex., glb_identity_enrichment) per centrar la cerca.

Exemple:

"US"

partial_match_action
enum<string>
predeterminat:NO_ACTION

Quin efecte té un partial_match en database_validation.status. Per defecte és NO_ACTION (l'estat es manté en Approved, amb una advertència).

Opcions disponibles:
DECLINE,
NO_ACTION
no_match_action
enum<string>
predeterminat:DECLINE

Quin efecte té un no_match en database_validation.status. Per defecte és DECLINE.

Opcions disponibles:
DECLINE,
NO_ACTION
save_api_request
boolean
predeterminat:true

Persisteix la validació com una sessió (visibilitat a la consola, endpoint de decisió, webhook status.updated). També canvia l'estructura de resposta de validations: objectes per servei quan és true (per defecte), un mapa de camps fusionat quan és false.

vendor_data
string

El teu identificador per a l'usuari validat; es retorna tal com s'ha enviat i s'emmagatzema amb la sessió.

metadata
object | null

JSON de format lliure emmagatzemat amb la sol·licitud i retornat com a resposta.

Resposta

Validació completada — almenys un dels serveis seleccionats ha retornat un resultat utilitzable. Inspecciona database_validation.match_type per al resultat agregat, validations per a les comparacions de camps per servei i els outcome_codes, i errors (quan n'hi hagi) per als serveis que hagin fallat.

request_id
string<uuid>

ID de sessió persistida quan save_api_request=true (utilitzable amb GET /v3/session/{sessionId}/decision/); en cas contrari, un UUID de correlació transitori.

database_validation
object
vendor_data
string | null

Ressò del vendor_data que has enviat.

metadata
object | null

Ressò de les metadata que has enviat.

created_at
string<date-time>
Darrera modificació el 7 de novembre del 2026