Перейти к основному содержанию
POST
Python
Используйте это руководство, чтобы выбрать подходящий способ импорта, когда вы переносите данные из другого провайдера в Didit. Под словом «импорт» клиенты обычно имеют в виду две разные задачи:
  • Импорт исторических проверок: воссоздайте завершённые записи KYC, KYB, мониторинга транзакций или правил сценариев, чтобы в Didit отображалась прежняя история провайдера. Используйте POST /v3/session/imports/.
  • Импорт операционных данных: создайте User, Business, лица из профилей, записи в списке блокировки или в списке разрешённых, чтобы Didit мог использовать их в будущих проверках. Используйте API сущностей, лиц и списков.
Импорты верификации создают исторические записи с session_type: "MIGRATED" для KYC и KYB. Они не отправляют письма конечным пользователям, не перенаправляют пользователей в размещённый процесс верификации и не запускают исходную верификацию повторно. Импортированные записи появляются в списках сессий, профилях сущностей, представлениях транзакций и в GET /v3/session/{session_id}/decision/, где это применимо.

Какой импорт выбрать?

Если вам нужен только профиль пользователя или бизнеса для будущих проверок, не импортируйте историческую сессию верификации. Используйте API сущностей User или Business. Если же решение прежнего провайдера, поля документа, предупреждения или доказательства должны появиться в Didit как история комплаенса, используйте POST /v3/session/imports/.

Что можно перенести от каждого провайдера?

Didit принимает канонический файл CSV или NDJSON, поэтому перенести данные можно от любого провайдера, если вы самостоятельно выгрузите их и приведёте к нужному формату. Схема импорта всегда соответствует канонической схеме Didit.

Порядок миграции

  1. Решите, что именно вы импортируете: историю, профили, лица, списки, транзакции или правила.
  2. Выгрузите данные из старого провайдера самостоятельно. Не передавайте API-ключи старого провайдера в Didit.
  3. Преобразуйте выгрузку провайдера в соответствующий канонический шаблон Didit CSV или NDJSON.
  4. Для больших миграций предпочтительно использовать NDJSON и разбивать данные на файлы, которые можно повторно загружать независимо друг от друга.
  5. Создайте задание импорта и отслеживайте его прогресс.
  6. Получите ошибки по строкам, исправьте только строки с ошибками и повторите их загрузку. Все задания импорта идемпотентны по их естественному внешнему идентификатору.

Создание задания импорта

Создайте задание импорта одним multipart-запросом:
Для небольших миграций, которые ведутся в таблицах, используйте CSV, а для больших миграций используйте NDJSON. При 100k+ строк NDJSON проще передавать потоком, разбивать на части, проверять и повторять. В одном приложении может одновременно выполняться до 4 заданий импорта, поэтому разбейте большую миграцию на несколько файлов и запустите задание для каждого из них. Каждое задание параллельно загружает медиафайлы для каждой строки. Задание, прерванное развёртыванием или перезапуском воркера, продолжается с последней импортированной строки самостоятельно, поэтому перезапускать его не нужно. Для импорта транзакций не указывайте workflow_id:

Поля запроса

Как отслеживаются и дедуплицируются записи

Поля для указания источника данных нет: любой импорт использует каноническую схему Didit. Каждая импортированная запись сохраняет metadata.imported_from = "generic" для отслеживания происхождения. Импорты user_verification и business_verification исключают дубликаты строк по external_id в пределах приложения, поэтому повторная загрузка того же файла не создаст дубликатов. Импорты transactions исключают дубликаты по transaction_id. Миграция от провайдера (source=provider) сохраняет каждую запись в виде <provider>:<id>, например sumsub:5f8c0e2a9b1d4c3e2f1a0b9c. Запись, которую импорт файла «Проверка пользователей» передал с голым идентификатором провайдера (5f8c0e2a9b1d4c3e2f1a0b9c), распознаётся как та же запись в обоих направлениях. Поэтому вы можете начать миграцию с помощью файлов и завершить её миграцией от провайдера или наоборот, не импортируя запись дважды.

Импорт фото документов, видео и материалов с селфи

Для import_type=user_verification можно импортировать оригинальные фото документов, видео захвата документа и проверки живости, а также изображение селфи от предыдущего провайдера. Используйте эти канонические столбцы: Для больших миграций используйте HTTPS-URL. Didit загружает каждый файл, проверяет, что URL безопасен, сохраняет собственную копию Didit и привязывает её к импортированной сессии. Изображения сжимаются, видео сохраняются без изменений. Встроенный base64 принимается для изображений в небольших импортах, но видео всегда должны передаваться как URL, поскольку base64 увеличивает каждое видео примерно на 33% и быстро превышает лимит импорта на файл. Пример строки NDJSON с URL медиафайлов, размещённых у провайдера:
Важные правила для медиафайлов:
  • URL должны использовать схему https.
  • URL не должны указывать на приватные IP-адреса, localhost, диапазоны link-local или внутренние хосты метаданных.
  • Для изображений допустим либо столбец с URL, либо его резервный вариант *_base64; если заданы оба, приоритет у base64. Для видео поддерживается только URL: столбца *_video_base64 не существует.
  • Видео должны быть в формате mp4, webm или mov, и каждое видео может быть размером не более 10 МБ. Файлы большего размера или файлы не видеоформата отклоняются, а строка помечается как содержащая ошибку.
  • Didit применяет таймауты на подключение и чтение, максимальный размер файла и не выполняет бесконечных повторных попыток.
  • Ошибки загрузки медиафайлов сохраняются как ошибки строк, чтобы остальная часть импорта могла продолжиться.
  • Если у вас нет медиафайлов от провайдера, оставьте эти столбцы пустыми. Didit всё равно импортирует структурированное решение и поля документа.
  • Импортированные изображения и видео служат доказательствами для проверки исторических данных. По умолчанию Didit не запускает повторно OCR, проверку живости или анализ подделки документов для импортированных исторических медиафайлов.

Проверка хода выполнения

Ответ содержит status, import_type, total_rows, processed_rows, created_count, updated_count, skipped_count, failed_count и checkpoint_row.

Загрузка ошибок строк

Каждая ошибка содержит row_number, external_id, error и raw_row, поэтому вы можете исправить только строки с ошибками и повторить импорт для них.

Защита от злоупотреблений

Исторические задания импорта через POST /v3/session/imports/ по умолчанию отключены. Didit включает эту возможность для каждой организации после проверки, поскольку такие задания могут обрабатывать миллионы строк и загружать медиафайлы. Обычные импорты операционных данных, описанные в этом руководстве, например создание пользователей, создание компаний, загрузка лиц для профилей, загрузка списков блокировки лиц или добавление записей в списки, не требуют специального разрешения для миграции, сверх обычных прав API-ключа, доступности продукта и лимитов запросов для этих эндпоинтов. Исторические задания импорта также выполняются на изолированных рабочих узлах с ограничениями на размер файла и количество строк, допустимостью только HTTPS-URL для медиафайлов, блокировкой URL из приватной сети и лимитом в 4 активных задания импорта на приложение, а также с фиксацией ошибок по каждой строке.

Канонические статусы

Идемпотентность

Didit использует external_id в качестве ключа идемпотентности для импортов «Проверка пользователей» и «Верификация бизнеса (KYB)» в пределах каждого приложения. Импорты транзакций используют transaction_id для каждого приложения. Повторный импорт того же файла пропускает строки, которые уже были импортированы, и создаёт строки, которые ещё не были обработаны.

Импорт пользователей, фото профилей лиц и списков блокировки

Используйте эти пути, если вы не воссоздаёте уже завершённую сессию верификации.

Импорт профилей пользователей

Создавайте пользователей с помощью POST /v3/users/create/ или импорта CSV в Business Console из раздела Импорт и экспорт пользователей. Это действие создаёт или обновляет только профиль VendorUser. Оно не создаёт сессию верификации, решение KYC, отчёт по документу, предупреждение или историю webhook. Используйте этот способ, если нужно, чтобы Didit знал о клиенте до будущих проверок, или если требуется заполнить задним числом поля, похожие на CRM, например display_name, теги и метаданные.

Загрузка доверенных фото профилей

После того как пользователь уже существует, загрузите доверенное фото профиля с помощью POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/. Это действие привязывает биометрические данные к профилю пользователя и индексирует их для обнаружения дубликатов и поиска по лицу. Это действие не добавляет лицо в список блокировки. Оно полезно, если у вас есть доверенное фото профиля от предыдущего провайдера KYC и вы хотите, чтобы будущие проверки Didit сравнивали лицо с этим фото.

Импорт списков блокировки и разрешённых лиц

Чтобы заблокировать или разрешить лицо напрямую, используйте POST /v3/lists/{list_uuid}/entries/face-upload/ со списком типа «лицо». Didit извлекает биометрический эмбеддинг и сохраняет запись в списке. Этот способ подходит для изображений известных мошенников, доверенных лиц из списка разрешённых и миграции списков мошенников от провайдеров. Если лицо получено из существующей сессии Didit, предпочтительнее использовать POST /v3/lists/{list_uuid}/entries/ с reference_session_id: Didit извлечёт нужное лицо из сессии и свяжет запись с источником.

Импорт списков пользователей, компаний, документов, кошельков, эл. почты, телефонов, IP-адресов или устройств

Для значений, не связанных с лицами, используйте POST /v3/lists/{list_uuid}/entries/. Этот путь подходит для списков блокировки и списков разрешений провайдеров, списков чарджбэков, адресов кошельков, известных рискованных IP-адресов, отпечатков устройств, номеров документов, адресов электронной почты, телефонов, пользователей или компаний.

Следующие шаги

Импорт пользователей

Загрузите профили пользователей и прикрепите доверенные фото профилей.

Импорт компаний

Загрузите профили компаний перед запуском KYB.

Загрузка фото профиля

Прикрепите доверенные фото лиц к импортированным пользователям.

Загрузка лица в список

Добавляйте лица в списки блокировки или разрешённые списки.

Создание записи в списке

Импортируйте телефоны, адреса эл. почты, кошельки, документы, IP-адреса, устройства, пользователей или компании в списки.

Лимиты запросов

Настройте безопасные циклы миграции и повторные попытки.

Авторизации

x-api-key
string
header
обязательно

API-ключ вашего приложения из раздела «Разработчикам» -> «API-ключи» в Business Console. Основной ключ имеет полный доступ. Именованный ключ может иметь ограниченную область действия: без доступа, чтение или запись для каждого ресурса, ограничение определенными сценариями или одобренными сессиями, списком IP-адресов и сроком действия. 401 означает, что ключ неверен, отозван или его срок действия истек; 403 означает, что ключ не был передан, у ключа нет доступа к этому ресурсу или действию, либо запрос поступил с адреса вне его списка IP-адресов; 404 на маршруте сессии означает, что сессия не входит в сценарии или статусы ключа. Ключ без доступа к медиа получает URL изображений, видео и PDF как null, а ключ без прав на запись сессий получает ссылки на сессии и токены как null. См. https://docs.didit.me/console/api-keys.

Тело

import_type
enum<string>
по умолчанию:user_verification

Что импортировать: исторические сессии проверки пользователей, исторические сессии верификации бизнеса, пользовательские правила статусов сценария или исторические записи мониторинга транзакций.

Доступные опции:
user_verification,
business_verification,
status_rules,
transactions
workflow_id
string<uuid>

UUID сценария, к которому должны быть привязаны импортированные сессии или правила статуса. Обязательно для user_verification, business_verification и status_rules. Опустите для transactions.

source_format
enum<string>

Необязательно. Если опущено, определяется по расширению загруженного файла.

Доступные опции:
csv,
ndjson
file
file

Канонический файл CSV или NDJSON. Для больших объёмов импорта используйте NDJSON. Максимальный размер загрузки 25 MB (для файлов большего размера используйте source_file_url). Нельзя использовать одновременно с source_file_url.

source_file_url
string<uri>

Альтернатива загрузке файла. Должен быть HTTPS-URL, указывающим на публичный адрес (частные/loopback-сети отклоняются). Взаимоисключающий с file.

source
enum<string>

provider указывает, что это миграция от другого провайдера верификации личности. Опустите для импорта файла.

Доступные опции:
file,
provider
provider
enum<string>

Источник миграции из GET /v3/session/imports/providers/. Обязателен, если source равен provider.

Доступные опции:
sumsub,
jumio,
veriff,
onfido,
persona,
metamap,
socure,
idnow,
shufti,
idenfy,
ondato,
trulioo,
au10tix,
complycube,
other
credentials
object

Ключ провайдера только для чтения с именами полей, указанными в credential_fields. Зашифрован при хранении, никогда не возвращается в ответах и удаляется по завершении импорта. Передавайте его в виде JSON-строки в multipart.

options
object
status_mapping
object

Изменения стандартного сопоставления статусов провайдера: исходный статус в статус Didit. Статусы Not Finished и Abandoned пропускаются и подсчитываются, но никогда не импортируются.

dry_run
boolean
по умолчанию:false

Подсчитать, что импортирует миграция (по статусу, уже в Didit, один и тот же человек, не завершено), не выполняя запись. Задача переходит в статус READY; запустите её с помощью POST /v3/session/imports/{importId}/start/.

face_templates
boolean
по умолчанию:false

Создание биометрических шаблонов лиц из импортированных селфи и поиск их по лицам приложения и списку блокировки. Совпадения помечаются только для проверки. Требуется lawful_basis_confirmed.

lawful_basis_confirmed
boolean
по умолчанию:false

Подтверждает, что у вас есть законные основания передавать эти селфи компании Didit в качестве обработчика.

Ответ

Задание на импорт принято. Опрашивайте возвращённый uuid, пока status не станет COMPLETED или FAILED.

uuid
string<uuid>
обязательно

Идентификатор задания на импорт. Используйте это значение для отслеживания прогресса и получения ошибок по строкам.

status
enum<string>
обязательно
Доступные опции:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
обязательно
Доступные опции:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
обязательно
Доступные опции:
csv,
ndjson
source_filename
string
обязательно
total_rows
integer<int64>
обязательно
processed_rows
integer<int64>
обязательно
created_count
integer<int64>
обязательно
updated_count
integer<int64>
обязательно
skipped_count
integer<int64>
обязательно
failed_count
integer<int64>
обязательно
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>

Состояние задачи, как оно отображается в консоли; errors означает завершенную задачу с отклоненными строками.

Доступные опции:
ready,
queued,
running,
paused,
completed,
errors,
failed,
cancelled
source
enum<string>
Доступные опции:
file,
api,
provider
provider
string

Источник миграции; пусто для импорта из файла или через API.

provider_options
object
credential_hint
string

Первые символы ключа, содержащегося в миграции. Сам ключ никогда не возвращается.

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

Когда задача, приостановленная из-за лимита запросов провайдера, возобновляется автоматически.

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

Результаты тестового прогона: 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
Последнее изменение 7 ноября 2026 г.