Saltar al contenido principal
POST
Python
Usa esta guía para elegir la vía de importación adecuada cuando traslades datos de otro proveedor a Didit. Los clientes suelen llamar “importación” a dos tareas distintas:
  • Importar el historial de verificaciones: recrea registros completados de KYC, KYB, monitorización de transacciones o reglas de flujo para que Didit muestre el historial del proveedor anterior. Usa POST /v3/session/imports/.
  • Importar datos operativos: crea usuarios, empresas, rostros de perfil, entradas de lista de bloqueo o entradas de lista de permitidos para que Didit pueda usarlos en verificaciones futuras. Usa las API de entidades, rostros y listas.
Las importaciones de verificaciones crean registros históricos con session_type: "MIGRATED" para KYC y KYB. No envían correos electrónicos al usuario final, no redirigen a los usuarios al flujo alojado y no vuelven a ejecutar la verificación original. Los registros importados aparecen en las listas de sesiones, los perfiles de entidades, las vistas de transacciones y en GET /v3/session/{session_id}/decision/ cuando corresponde.

Qué importación debes usar

Si solo necesitas un perfil de usuario o de empresa para verificaciones futuras, no importes una sesión de verificación histórica. Usa las API de las entidades User o Business. Si necesitas que la decisión, los campos del documento, las advertencias o la evidencia del proveedor anterior aparezcan como historial de cumplimiento en Didit, usa POST /v3/session/imports/.

Qué se puede migrar desde cada proveedor

Didit acepta un archivo CSV o NDJSON canónico, así que puedes migrar desde cualquier proveedor una vez que exportes y transformes los datos. El contrato de importación es siempre el esquema canónico de Didit.

Flujo de migración

  1. Decide si vas a importar historial, perfiles, rostros, listas, transacciones o reglas.
  2. Exporta tú mismo los datos del proveedor anterior. No envíes a Didit las claves de API del proveedor anterior.
  3. Transforma la exportación del proveedor en la plantilla canónica CSV o NDJSON de Didit correspondiente.
  4. Para migraciones grandes, da preferencia a NDJSON y divide los datos en archivos que puedas reintentar de forma independiente.
  5. Crea el trabajo de importación y consulta su progreso.
  6. Obtén los errores por fila, corrige solo las filas fallidas y vuelve a intentarlas. Todos los trabajos de importación son idempotentes respecto a su ID externo natural.

Crear un trabajo de importación

Crea un trabajo de importación con una única solicitud multipart:
Usa CSV para migraciones más pequeñas basadas en hojas de cálculo y NDJSON para migraciones grandes. Para 100k+ filas, NDJSON es más fácil de procesar en streaming, dividir, validar y reintentar. Para importaciones de transacciones, omite workflow_id:

Campos de la solicitud

Cómo se rastrean y deduplican los registros

No existe ningún campo de la solicitud para la fuente de datos: todas las importaciones usan el esquema canónico de Didit. Cada registro importado almacena metadata.imported_from = "generic" para su trazabilidad. Las importaciones user_verification y business_verification deduplican las filas por external_id dentro de la aplicación, por lo que reintentar el mismo archivo no creará duplicados. Las importaciones transactions deduplican por transaction_id en su lugar.

Importar fotos de documentos, videos y evidencia de selfie

Con import_type=user_verification, puedes importar las fotos originales del documento, los videos de captura del documento y de la prueba de vida, y la imagen de la selfie del proveedor anterior. Usa estas columnas canónicas: En migraciones grandes, usa URL HTTPS. Didit descarga cada archivo, comprueba que la URL sea segura, almacena una copia propiedad de Didit y la vincula a la sesión importada. Las imágenes se comprimen; los videos se almacenan tal cual. En importaciones pequeñas se acepta base64 en línea para las imágenes, pero los videos siempre deben proporcionarse como URL: base64 aumentaría el tamaño de cada video en un ~33% y superaría rápidamente el límite de importación por archivo. Ejemplo de fila NDJSON con URLs de archivos multimedia alojados por el proveedor:
Reglas importantes sobre los archivos multimedia:
  • Las URL deben usar https.
  • Las URL no deben resolverse a direcciones IP privadas, localhost, rangos link-local ni hosts internos de metadatos.
  • Las imágenes aceptan una columna de URL o su alternativa *_base64; si se definen ambas, base64 tiene prioridad. Los videos solo admiten URL: no existe ninguna columna *_video_base64.
  • Los videos deben estar en formato mp4, webm o mov, y cada video puede ocupar como máximo 10 MB. Los archivos más grandes o que no sean de video se rechazan como errores de fila.
  • Didit aplica tiempos de espera de conexión y lectura y un tamaño máximo de archivo, y no realiza reintentos infinitos.
  • Los fallos de descarga de archivos multimedia se almacenan como errores de fila para que el resto de la importación pueda continuar.
  • Si no tienes archivos multimedia del proveedor, deja estas columnas vacías. Didit sigue importando la decisión estructurada y los campos del documento.
  • Las imágenes y los videos importados son evidencia para la revisión histórica. De forma predeterminada, Didit no vuelve a ejecutar el OCR, la prueba de vida ni el análisis de fraude documental sobre los medios históricos importados.

Consultar el progreso

La respuesta incluye status, import_type, total_rows, processed_rows, created_count, updated_count, skipped_count, failed_count y checkpoint_row.

Descargar errores de filas

Cada error incluye row_number, external_id, error y raw_row, para que puedas corregir solo las filas fallidas y reintentar.

Protección contra abusos

Los trabajos de importación histórica mediante POST /v3/session/imports/ están desactivados de forma predeterminada. Didit habilita esta capacidad por organización tras una revisión, porque estos trabajos pueden procesar millones de filas y descargar archivos multimedia. Las importaciones normales de datos operativos de esta guía (crear usuarios, crear empresas, subir rostros de perfil, subir listas de bloqueo de rostros o añadir entradas a listas) no requieren ninguna habilitación especial de migración, más allá de los permisos normales de la clave de API, la disponibilidad del producto y los límites de solicitudes de esos endpoints. Además, los trabajos de importación histórica se ejecutan en workers aislados con límites de tamaño de archivo, límites de filas, URL de archivos multimedia que solo usan HTTPS, bloqueo de URL de redes privadas, límites de trabajos activos por aplicación y registro de errores por fila.

Estados canónicos

Idempotencia

Didit usa external_id como clave de idempotencia de importación para las importaciones de verificación de usuarios y verificación de empresas, con alcance por aplicación. Las importaciones de transacciones usan transaction_id por aplicación. Al reintentar el mismo archivo, se omiten las filas que ya se importaron y se crean las que aún no se habían procesado.

Importar usuarios, rostros de perfil y listas de bloqueo

Usa estas vías cuando no estés recreando una sesión de verificación completada:

Importar perfiles de usuario

Crea usuarios con POST /v3/users/create/ o con la importación CSV de Business Console descrita en Importar y exportar usuarios. Esto solo crea o actualiza el perfil VendorUser. No crea una sesión de verificación, una decisión de KYC, un informe de documento, advertencias ni historial de webhooks. Úsalo cuando quieras que Didit sepa que el cliente existe antes de futuras comprobaciones, o cuando necesites completar con datos históricos campos de tipo CRM como display_name, etiquetas o metadatos.

Subir rostros de perfil de confianza

Una vez que exista el usuario, sube un rostro de perfil de confianza con POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/. Esto asocia evidencia biométrica al perfil del usuario y la indexa para la detección de duplicados y la búsqueda facial. Esto no añade el rostro a una lista de bloqueo. Resulta útil cuando tienes una imagen de perfil de confianza de un proveedor de KYC anterior y quieres que las futuras comprobaciones de Didit la usen como referencia.

Importar listas de bloqueo y listas de permitidos de rostros

Para bloquear o permitir un rostro directamente, usa POST /v3/lists/{list_uuid}/entries/face-upload/ con una lista de tipo rostro. Didit extrae el embedding biométrico y almacena una entrada en la lista. Úsalo para imágenes de estafadores conocidos, rostros de confianza de listas de permitidos o migraciones de listas de fraude de un proveedor. Si el rostro procede de una sesión de Didit existente, es preferible usar POST /v3/lists/{list_uuid}/entries/ con reference_session_id; Didit extrae el rostro correcto de la sesión y vincula la entrada con su origen.

Importar listas de usuarios, empresas, documentos, wallets, correos electrónicos, teléfonos, IP o dispositivos

Usa POST /v3/lists/{list_uuid}/entries/ para valores de listas que no sean rostros. Es la vía adecuada para listas de bloqueo de proveedores, listas de permitidos, listas de contracargos, direcciones de wallets, direcciones IP de riesgo conocidas, huellas digitales de dispositivos, números de documento, correos electrónicos, teléfonos, usuarios o empresas.

Próximos pasos

Importar usuarios

Carga perfiles de usuario y asocia rostros de perfil de confianza a ellos.

Importar empresas

Carga perfiles de empresa antes de ejecutar el KYB.

Subir rostro de perfil

Asocia imágenes faciales de confianza a los usuarios importados.

Subir rostro a una lista

Añade rostros a listas de bloqueo o listas de permitidos.

Crear entrada de lista

Importa teléfonos, correos electrónicos, wallets, documentos, direcciones IP, dispositivos, usuarios o empresas a listas.

Límites de solicitudes

Diseña bucles de migración y reintentos seguros.

Autorizaciones

x-api-key
string
header
requerido

La clave de API de tu aplicación, que encontrarás en Developers -> API keys en la Business Console. La clave principal tiene acceso completo. Una clave con nombre puede tener un alcance limitado: ninguno, lectura o escritura por recurso, limitada a algunos flujos o a sesiones aprobadas, a una lista de direcciones IP y a una fecha de caducidad. 401 significa que la clave es incorrecta, se revocó o expiró; 403 significa que no se envió ninguna clave, que la clave no tiene acceso a este recurso o acción, o que la solicitud provino de una dirección fuera de su lista de IP; 404 en una ruta de sesión significa que la sesión está fuera de los flujos o estados de la clave. Una clave sin acceso a contenido multimedia recibe las URL de imágenes, videos y PDF como null, y una clave sin permiso de escritura en sesiones recibe los enlaces y tokens de sesión como null. Consulta https://docs.didit.me/console/api-keys.

Cuerpo

import_type
enum<string>
predeterminado:user_verification

Qué importar: sesiones históricas de Verificación de usuarios, sesiones históricas de Verificación de empresas, reglas de estado personalizadas del flujo o registros históricos de monitorización de transacciones.

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

UUID del flujo al que deben asociarse las sesiones importadas o las reglas de estado. Obligatorio para user_verification, business_verification y status_rules. Omítelo para transactions.

source_format
enum<string>

Opcional. Si se omite, se deduce de la extensión del archivo subido.

Opciones disponibles:
csv,
ndjson
file
file

Archivo CSV o NDJSON canónico. Usa NDJSON para importaciones grandes. Tamaño máximo de subida: 25 MB (usa source_file_url para archivos más grandes). Mutuamente excluyente con source_file_url.

source_file_url
string<uri>

Alternativa a la subida de un archivo. Debe ser una URL HTTPS que resuelva a una dirección pública (se rechazan las redes privadas y de loopback). Es mutuamente excluyente con file.

source
enum<string>

provider convierte esto en una migración desde otro proveedor de verificación de identidad. Omítelo para importar un archivo.

Opciones disponibles:
file,
provider
provider
enum<string>

Origen de la migración, obtenido de GET /v3/session/imports/providers/. Obligatorio cuando source es provider.

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

La clave de solo lectura del proveedor, con los nombres de campo que indica credential_fields. Se cifra en reposo, nunca se devuelve y se borra cuando termina la importación. Envíala como cadena JSON en multipart.

options
object
status_mapping
object

Cambios en la correspondencia de estados predeterminada del proveedor: del estado de origen al estado de Didit. Not Finished y Abandoned se omiten y se contabilizan, pero nunca se importan.

dry_run
boolean
predeterminado:false

Cuenta lo que importaría la migración (por estado, ya en Didit, misma persona, sin finalizar) sin escribir nada. El trabajo termina en READY. Inícialo con POST /v3/session/imports/{importId}/start/.

face_templates
boolean
predeterminado:false

Genera plantillas faciales a partir de las selfies importadas y búscalas entre los rostros y la lista de bloqueo de la aplicación. Las coincidencias solo se marcan para revisión. Requiere lawful_basis_confirmed.

lawful_basis_confirmed
boolean
predeterminado:false

Confirma que tienes una base legal para compartir estas selfies con Didit como encargado del tratamiento.

Respuesta

Trabajo de importación aceptado. Consulta el uuid devuelto hasta que status sea COMPLETED o FAILED.

uuid
string<uuid>
requerido

Id del trabajo de importación. Usa este valor para consultar el progreso y obtener los errores de las filas.

status
enum<string>
requerido
Opciones disponibles:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
requerido
Opciones disponibles:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
requerido
Opciones disponibles:
csv,
ndjson
source_filename
string
requerido
total_rows
integer<int64>
requerido
processed_rows
integer<int64>
requerido
created_count
integer<int64>
requerido
updated_count
integer<int64>
requerido
skipped_count
integer<int64>
requerido
failed_count
integer<int64>
requerido
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>

El estado del trabajo tal como lo muestra la consola; errors es un trabajo completado con filas rechazadas.

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

Origen de la migración; vacío en una importación desde archivo o API.

provider_options
object
credential_hint
string

Los primeros caracteres de la clave que contiene la migración. La clave en sí nunca se devuelve.

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

Cuándo se reanuda por sí solo un trabajo pausado por el límite de solicitudes del proveedor.

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

Qué encontró una ejecución de prueba: 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
Última modificación el 1 de noviembre de 2026