Saltar al contingut principal
POST
Python
Fes servir aquesta guia per triar el camí d’importació adequat quan migris dades d’un altre proveïdor a Didit. Els clients sovint anomenen “importació” dues feines diferents:
  • Importar treball de verificació històric: recrear registres completats de KYC, KYB, monitoratge de transaccions o regles de flux de treball perquè Didit mostri l’historial de l’antic proveïdor. Utilitza POST /v3/session/imports/.
  • Importar dades operatives: crear Users, Businesses, rostres de perfil, entrades de la llista de bloqueig o de la llista de permesos perquè Didit les pugui utilitzar en futures comprovacions. Utilitza les APIs d’entitats, de rostres i de llistes.
Les importacions de verificació creen registres històrics amb session_type: "MIGRATED" per a KYC i KYB. No envien correus electrònics als usuaris finals, no redirigeixen els usuaris al flux allotjat i no tornen a executar la verificació original. Els registres importats apareixen a les llistes de sessions, als perfils d’entitats, a les vistes de transaccions i a GET /v3/session/{session_id}/decision/ quan sigui aplicable.

Quina importació has d’utilitzar?

Si només necessites un perfil d’usuari o d’empresa per a futures comprovacions, no importis una sessió de verificació històrica. Utilitza les APIs d’entitats User o Business. Si necessites que la decisió, els camps del document, les advertències o les evidències de l’antic proveïdor apareguin com a historial de compliment a Didit, utilitza POST /v3/session/imports/.

Quins elements es poden migrar de cada proveïdor?

Didit accepta un fitxer CSV o NDJSON canònic, de manera que pots migrar des de qualsevol proveïdor després d’exportar i transformar les dades. El contracte d’importació és sempre l’esquema canònic de Didit.

Flux de treball de migració

  1. Decideix si vols importar historial, perfils, cares, llistes, transaccions o regles.
  2. Exporta tu mateix les dades del proveïdor antic. No enviïs a Didit les claus d’API del proveïdor antic.
  3. Transforma l’exportació del proveïdor a la plantilla CSV o NDJSON canònica de Didit que correspongui.
  4. Per a migracions grans, prefereix NDJSON i divideix-les en fitxers que puguis reintentar de manera independent.
  5. Crea la tasca d’importació i consulta’n el progrés.
  6. Obtén els errors de fila, corregeix només les files que han fallat i reintenta-les. Totes les tasques d’importació són idempotents respecte del seu identificador extern natural.

Crea una tasca d’importació

Crea una tasca d’importació amb una única sol·licitud multipart:
Utilitza CSV per a migracions més petites basades en fulls de càlcul i NDJSON per a migracions grans. Per a 100k+ files, NDJSON és més fàcil de transmetre en flux, dividir, validar i reintentar. Una aplicació pot executar fins a 4 tasques d’importació alhora, de manera que has de dividir una migració gran en diversos fitxers i iniciar una tasca per a cadascun. Cada tasca descarrega en paral·lel els fitxers multimèdia d’una fila. Una tasca interrompuda per un desplegament o per un reinici del treballador continua des de l’última fila importada sense intervenció, de manera que no cal reiniciar-la. Per a les importacions de transaccions, omet workflow_id:

Camps de la sol·licitud

Com es fan el seguiment i la deduplicació dels registres

No hi ha cap camp de sol·licitud per a l’origen de les dades: totes les importacions utilitzen l’esquema canònic de Didit. Cada registre importat desa metadata.imported_from = "generic" per a la traçabilitat. Les importacions de user_verification i business_verification deduplicen les files segons external_id dins de l’aplicació, de manera que reintentar el mateix fitxer no crea duplicats. Les importacions de transactions deduplicen segons transaction_id. Una migració de proveïdor (source=provider) desa cada registre com a <provider>:<id>, per exemple sumsub:5f8c0e2a9b1d4c3e2f1a0b9c. Una importació de fitxer de Verificació d’usuaris que hagi enviat l’id nu del proveïdor (5f8c0e2a9b1d4c3e2f1a0b9c) es reconeix com el mateix registre en les dues direccions. Per tant, pots començar una migració amb fitxers i acabar-la amb una migració de proveïdor, o a la inversa, sense importar cap registre dues vegades.

Importar fotos de documents, vídeos i evidències de selfie

Per a import_type=user_verification, pots importar les fotos originals dels documents, els vídeos de captura de document i prova de vida, i la imatge de selfie del proveïdor anterior. Fes servir aquestes columnes canòniques: Per a migracions grans, fes servir URL HTTPS. Didit descarrega cada fitxer, valida que la URL sigui segura, emmagatzema una còpia pròpia de Didit i l’enllaça a la sessió importada. Les imatges es comprimeixen; els vídeos s’emmagatzemen tal com són. El base64 en línia és acceptat per a imatges en importacions petites, però els vídeos s’han de proporcionar sempre com a URL, ja que el base64 augmentaria cada vídeo en un ~33 % i superaria ràpidament el límit d’importació per fitxer. Exemple de fila NDJSON amb URL de contingut allotjat pel proveïdor:
Regles importants sobre el contingut multimèdia:
  • Les URL han de fer servir https.
  • Les URL no poden resoldre’s a IP privades, localhost, rangs d’enllaç local ni servidors de metadades internes.
  • Les imatges accepten una columna d’URL o la seva alternativa *_base64; si s’informen les dues, es fa servir base64. Els vídeos només són URL: no hi ha cap columna *_video_base64.
  • Els vídeos han de ser mp4, webm o mov, i cada vídeo pot tenir com a màxim 10 MB. Els fitxers més grans o que no siguin vídeos es rebutgen com a errors de fila.
  • Didit aplica temps d’espera de connexió i de lectura, una mida màxima de fitxer i no fa reintents infinits.
  • Les errades de descàrrega de contingut multimèdia s’emmagatzemen com a errors de fila perquè la resta de la importació pugui continuar.
  • Si no tens contingut multimèdia del proveïdor, deixa buides aquestes columnes. Didit igualment importa la decisió estructurada i els camps del document.
  • Les imatges i els vídeos importats són evidència per a la revisió històrica. Per defecte, Didit no torna a executar l’anàlisi d’OCR, de prova de vida ni de frau documental sobre el contingut històric importat.

Consultar el progrés

La resposta inclou status, import_type, total_rows, processed_rows, created_count, updated_count, skipped_count, failed_count i checkpoint_row.

Descarregar els errors de fila

Cada error inclou row_number, external_id, error i raw_row, de manera que pots corregir només les files que han fallat i reintentar-les.

Protecció contra abusos

Les tasques d’importació històrica mitjançant POST /v3/session/imports/ estan desactivades per defecte. Didit activa aquesta capacitat per organització després de revisar-la, perquè aquestes tasques poden processar milions de files i descarregar contingut multimèdia. Les importacions de dades operatives habituals d’aquesta guia (crear usuaris, crear empreses, pujar cares de perfil, pujar llistes de bloqueig de cares o afegir entrades a llistes) no requereixen cap habilitació especial de migració més enllà dels permisos normals de la clau d’API, la disponibilitat del producte i els límits de freqüència d’aquests endpoints. Les tasques d’importació històrica també s’executen en processos de treball aïllats amb límits de mida de fitxer, límits de files, URL de contingut que només utilitzen HTTPS, bloqueig d’URL de xarxa privada, un límit de 4 tasques d’importació actives per aplicació i captura d’errors per fila.

Estats canònics

Idempotència

Didit fa servir external_id com a clau d’idempotència de les importacions de verificació d’usuaris i de verificació d’empreses, limitada a cada aplicació. Les importacions de transaccions fan servir transaction_id per aplicació. Tornar a importar el mateix fitxer omet les files que ja s’han importat i crea les files que encara no s’han processat.

Importa usuaris, cares de perfil i llistes de bloqueig

Fes servir aquests camins quan no estiguis recreant una sessió de verificació completada.

Importa perfils d’usuari

Crea usuaris amb POST /v3/users/create/ o amb la importació CSV del Business Console a Importar i exportar usuaris. Això crea o actualitza només el perfil VendorUser. No crea cap sessió de verificació, decisió KYC, informe de document, advertència ni historial de webhooks. Fes-ho servir quan vulguis que Didit sàpiga que el client existeix abans de les verificacions futures, o quan necessitis omplir retroactivament camps similars a un CRM com display_name, etiquetes o metadades.

Puja cares de perfil fiables

Quan existeixi un usuari, puja una cara de perfil fiable amb POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/. Això adjunta l’evidència biomètrica al perfil de l’usuari i la indexa per a la detecció de duplicats i la cerca facial. Això no posa la cara a la llista de bloqueig. És útil quan tens una imatge de perfil de confiança d’un proveïdor de KYC anterior i vols que les verificacions futures de Didit la comparin.

Importa llistes de bloqueig i de permesos de cares

Per bloquejar o permetre una cara directament, fes servir POST /v3/lists/{list_uuid}/entries/face-upload/ amb una llista de tipus de cara. Didit extreu l’embedding biomètric i emmagatzema una entrada de la llista. Fes-ho servir per a imatges de defraudadors coneguts, cares de confiança de llistes de permesos o migracions de llistes de frau dels proveïdors. Si la cara prové d’una sessió existent de Didit, és preferible fer servir POST /v3/lists/{list_uuid}/entries/ amb reference_session_id: Didit extreu la cara correcta de la sessió i enllaça l’entrada amb l’origen.

Importa llistes d’usuaris, empreses, documents, carteres, correus electrònics, telèfons, IP o dispositius

Fes servir POST /v3/lists/{list_uuid}/entries/ per als valors de les llistes que no són cares. És el camí adequat per a llistes de bloqueig i de permesos de proveïdors, llistes de contracàrrecs, adreces, adreces de risc conegudes, petjades digitals de dispositius, números de document, correus electrònics, telèfons, usuaris o empreses.

Propers passos

Importar usuaris

Carrega perfils d’usuari i adjunta cares de perfil de confiança.

Importar empreses

Carrega perfils d’empresa abans d’executar el KYB.

Pujar cara de perfil

Adjunta imatges de cara de confiança als usuaris importats.

Pujar cara a una llista

Afegeix cares a llistes de bloqueig o de permesos.

Crear entrada de llista

Importa telèfons, correus electrònics, carteres, documents, adreces, dispositius, usuaris o empreses a llistes.

Límits de freqüència

Dissenya bucles de migració segurs i reintents.

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

import_type
enum<string>
predeterminat:user_verification

Què importar: sessions històriques de Verificació d'usuaris, sessions històriques de Verificació d'empreses, regles d'estat personalitzades del flux de treball o registres històrics de monitoratge de transaccions.

Opcions disponibles:
user_verification,
business_verification,
status_rules,
transactions
workflow_id
string<uuid>

UUID del flux de treball al qual s'han d'adjuntar les sessions o regles d'estat importades. Obligatori per a user_verification, business_verification i status_rules. Omet-ho per a les transaccions.

source_format
enum<string>

Opcional. S'infereix de l'extensió del fitxer penjat quan s'omet.

Opcions disponibles:
csv,
ndjson
file
file

Fitxer canònic en format CSV o NDJSON. Fes servir NDJSON per a importacions grans. Mida màxima de càrrega de 25 MB (fes servir source_file_url per a fitxers més grans). Mútuament excloent amb source_file_url.

source_file_url
string<uri>

Alternativa a la càrrega de fitxers. Ha de ser una URL HTTPS que apunti a una adreça pública (es rebutgen les xarxes privades o de loopback). Mútuament excloent amb file.

source
enum<string>

provider fa que això sigui una migració des d'un altre proveïdor de verificació d'identitat. Omet-ho per a una importació de fitxers.

Opcions disponibles:
file,
provider
provider
enum<string>

Origen de la migració, de GET /v3/session/imports/providers/. Obligatori quan source és provider.

Opcions disponibles:
sumsub,
jumio,
veriff,
onfido,
persona,
metamap,
socure,
idnow,
shufti,
idenfy,
ondato,
trulioo,
au10tix,
complycube,
other
credentials
object

La clau de només lectura del proveïdor, amb els noms de camp que enumera credential_fields. Xifrada en repòs, mai no es retorna i s'elimina quan finalitza la importació. Envia-la com una cadena JSON a multipart.

options
object
status_mapping
object

Modificacions del mapatge d'estats per defecte del proveïdor: de l'estat d'origen a l'estat de Didit. Not Finished i Abandoned s'ometen i es comptabilitzen, mai s'importen.

dry_run
boolean
predeterminat:false

Compta el que importaria la migració (per estat, ja a Didit, mateixa persona, no finalitzat) i no escriu res. La tasca acaba en READY; inicia-la amb POST /v3/session/imports/{importId}/start/.

face_templates
boolean
predeterminat:false

Genera plantilles biomètriques a partir de les selfies importades i cerca-les a les cares i la llista de bloqueig de l'aplicació. Les coincidències només es marquen per a revisió. Requereix lawful_basis_confirmed.

lawful_basis_confirmed
boolean
predeterminat:false

Confirma que disposes d'una base jurídica per compartir aquestes selfies amb Didit com a encarregat del tractament.

Resposta

Tasca d'importació acceptada. Consulta periòdicament l'uuid retornat fins que status sigui COMPLETED o FAILED.

uuid
string<uuid>
requerit

ID de la tasca d'importació. Utilitza aquest valor per fer el seguiment del progrés i obtenir els errors de les files.

status
enum<string>
requerit
Opcions disponibles:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
requerit
Opcions disponibles:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
requerit
Opcions disponibles:
csv,
ndjson
source_filename
string
requerit
total_rows
integer<int64>
requerit
processed_rows
integer<int64>
requerit
created_count
integer<int64>
requerit
updated_count
integer<int64>
requerit
skipped_count
integer<int64>
requerit
failed_count
integer<int64>
requerit
checkpoint_row
integer<int64>
total_media_bytes
integer<int64>
last_error
string | null
created_at
string<date-time>
updated_at
string<date-time>
started_at
string<date-time> | null
completed_at
string<date-time> | null
state
enum<string>

L'estat de la tasca tal com es mostra a la consola; errors és una tasca completada amb files rebutjades.

Opcions disponibles:
ready,
queued,
running,
paused,
completed,
errors,
failed,
cancelled
source
enum<string>
Opcions disponibles:
file,
api,
provider
provider
string

Origen de la migració; buit per a una importació per fitxer o API.

provider_options
object
credential_hint
string

Els primers caràcters de la clau que manté la migració. La clau en si no es retorna mai.

credentials_expires_at
string<date-time> | null
resumes_at
string<date-time> | null

Quan una tasca posada en pausa pel límit de freqüència del proveïdor es reprèn per si mateixa.

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

El que ha trobat una execució en sec: total, by_status, already_in_didit, same_person, not_finished, failed, unmapped_statuses.

face_templates_enabled
boolean
lawful_basis_confirmed_at
string<date-time> | null
not_finished_count
integer<int64>
same_person_count
integer<int64>
face_templates_count
integer<int64>
face_duplicates_count
integer<int64>
face_blocklist_hits_count
integer<int64>
created_by_name
string | null
created_by_email
string | null
Darrera modificació el 7 de novembre del 2026