Pular para o conteúdo principal
POST
Python
Use este guia para escolher o caminho de importação certo ao migrar dados de outro provedor para a Didit. Existem dois tipos diferentes de tarefas que os clientes costumam chamar de “importação”:
  • Importar o histórico de verificações: recria registros concluídos de KYC, KYB, monitoramento de transações ou regras de fluxo para que a Didit exiba o histórico do provedor anterior. Use POST /v3/session/imports/.
  • Importar dados operacionais: cria Usuários, Empresas, rostos de perfil, entradas de lista de bloqueio ou entradas de lista de permissão para que a Didit possa usá-los em verificações futuras. Use as APIs de entidades, rostos e listas.
As importações de verificações criam registros históricos com session_type: "MIGRATED" para KYC e KYB. Elas não enviam e-mails ao usuário final, não redirecionam os usuários para o fluxo hospedado e não executam novamente a verificação original. Os registros importados aparecem nas listas de sessões, nos perfis de entidades, nas visualizações de transações e em GET /v3/session/{session_id}/decision/, quando aplicável.

Qual importação usar

Se você só precisa de um perfil de usuário ou de empresa para verificações futuras, não importe uma sessão de verificação histórica. Use as APIs de entidades de Usuário ou de Empresa. Se você precisa que a decisão, os campos do documento, os avisos ou as evidências do provedor anterior apareçam como histórico de conformidade na Didit, use POST /v3/session/imports/.

O que pode ser migrado de cada fornecedor?

O Didit aceita um arquivo CSV ou NDJSON canônico, então você pode migrar de qualquer fornecedor depois de exportar e transformar os dados. O contrato de importação é sempre o esquema canônico do Didit.

Fluxo de migração

  1. Decida se você vai importar histórico, perfis, rostos, listas, transações ou regras.
  2. Exporte você mesmo os dados do fornecedor antigo. Não envie chaves de API do fornecedor antigo ao Didit.
  3. Transforme a exportação do fornecedor no modelo canônico CSV ou NDJSON correspondente do Didit.
  4. Em migrações grandes, prefira NDJSON e divida os dados em arquivos que possam ser reenviados de forma independente.
  5. Crie o job de importação e consulte o progresso.
  6. Obtenha os erros por linha, corrija apenas as linhas com falha e tente importá-las novamente. Todos os jobs de importação são idempotentes com base no seu ID externo natural.

Criar um job de importação

Crie um job de importação com uma única requisição multipart:
Use CSV em migrações menores baseadas em planilhas e NDJSON em migrações grandes. Com 100k linhas ou mais, o NDJSON é mais fácil de transmitir, dividir, validar e tentar novamente. Em importações de transações, omita workflow_id:

Campos da requisição

Como os registros são rastreados e deduplicados

Não existe um campo na requisição para a origem dos dados: toda importação usa o esquema canônico do Didit. Cada registro importado armazena metadata.imported_from = "generic" para fins de rastreabilidade. Importações user_verification e business_verification deduplicam as linhas pelo external_id dentro da aplicação, então tentar novamente com o mesmo arquivo não cria duplicatas. Já as importações transactions deduplicam pelo transaction_id.

Importar fotos de documentos, vídeos e evidências de selfie

Para import_type=user_verification, você pode importar as fotos originais dos documentos, os vídeos de captura do documento/prova de vida e a imagem da selfie do provedor anterior. Use estas colunas canônicas: Para migrações grandes, use URLs HTTPS. A Didit baixa cada arquivo, valida se a URL é segura, armazena uma cópia de propriedade da Didit e a vincula à sessão importada. As imagens são comprimidas; os vídeos são armazenados como estão. Base64 inline é aceito para imagens em importações pequenas, mas os vídeos devem sempre ser fornecidos como URL: o base64 aumentaria cada vídeo em ~33% e logo ultrapassaria o limite de importação por arquivo. Exemplo de linha NDJSON com URLs de mídia hospedadas pelo provedor:
Regras importantes para mídia:
  • As URLs devem usar https.
  • As URLs não podem resolver para IPs privados, localhost, faixas link-local ou hosts internos de metadados.
  • As imagens aceitam uma coluna de URL ou sua alternativa *_base64; o base64 tem precedência quando ambos estão definidos. Os vídeos são somente por URL: não existe coluna *_video_base64.
  • Os vídeos devem estar em mp4, webm ou mov, e cada vídeo pode ter no máximo 10 MB. Arquivos maiores ou que não sejam vídeo são rejeitados como erros de linha.
  • A Didit aplica timeouts de conexão/leitura, tamanho máximo de arquivo e não tenta novamente indefinidamente.
  • Falhas no download de mídia são armazenadas como erros de linha, para que o restante da importação possa continuar.
  • Se você não tiver mídia do provedor, deixe essas colunas vazias. A Didit ainda importa a decisão estruturada e os campos do documento.
  • As imagens e os vídeos importados são evidências para revisão histórica. Por padrão, a Didit não executa novamente OCR, prova de vida ou análise de fraude documental na mídia histórica importada.

Consultar o progresso

A resposta inclui status, import_type, total_rows, processed_rows, created_count, updated_count, skipped_count, failed_count e checkpoint_row.

Baixe os erros por linha

Cada erro inclui row_number, external_id, error e raw_row, para que você possa corrigir apenas as linhas com falha e tentar novamente.

Proteção contra abuso

Os jobs de importação histórica por meio de POST /v3/session/imports/ ficam desativados por padrão. A Didit habilita esse recurso por organização após uma análise, porque esses jobs podem processar milhões de linhas e baixar mídia. As importações normais de dados operacionais deste guia (criar usuários, criar empresas, enviar fotos de perfil, enviar listas de bloqueio de rostos ou adicionar entradas a listas) não exigem nenhuma habilitação especial de migração além das permissões normais da chave de API, da disponibilidade do produto e dos limites de requisições desses endpoints. Os jobs de importação histórica também são executados em workers isolados, com limites de tamanho de arquivo, limites de linhas, URLs de mídia somente HTTPS, bloqueio de URLs de redes privadas, limites de jobs ativos por aplicação e captura de erros por linha.

Status padronizados

Idempotência

A Didit usa external_id como chave de idempotência da importação nas importações de Verificação de usuários e de Verificação de empresas, com escopo por aplicação. As importações de transações usam transaction_id por aplicação. Ao tentar importar novamente o mesmo arquivo, as linhas já importadas são ignoradas e as linhas ainda não processadas são criadas.

Importar usuários, rostos de perfil e listas de bloqueio

Use os seguintes endpoints quando você não estiver recriando uma sessão de verificação concluída:

Importar perfis de usuário

Crie usuários com POST /v3/users/create/ ou pela importação CSV do Business Console em Importar e exportar usuários. Isso cria ou atualiza apenas o perfil VendorUser. Não cria sessão de verificação, decisão de KYC, relatório do documento, aviso nem histórico de webhooks. Use esta opção quando quiser que a Didit saiba que o cliente existe antes de verificações futuras, ou quando precisar preencher retroativamente campos no estilo de um CRM, como display_name, tags ou metadados.

Enviar rostos de perfil confiáveis

Depois que um usuário existir, envie um rosto de perfil confiável com POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/. Isso vincula evidências biométricas ao perfil do usuário e as indexa para detecção de duplicados e busca facial. Isso não adiciona o rosto a uma lista de bloqueio. É útil quando você tem uma imagem de perfil confiável de um provedor de KYC anterior e quer que as verificações futuras da Didit façam a comparação com ela.

Importar listas de bloqueio e listas de permissão de rostos

Para bloquear ou permitir um rosto diretamente, use POST /v3/lists/{list_uuid}/entries/face-upload/ com uma lista do tipo rosto. A Didit extrai o embedding biométrico e armazena uma entrada na lista. Use esta opção para imagens de fraudadores conhecidos, rostos confiáveis de listas de permissão ou migrações de listas de fraude de provedores. Se o rosto vier de uma sessão existente da Didit, prefira POST /v3/lists/{list_uuid}/entries/ com reference_session_id; a Didit extrai o rosto correto da sessão e vincula a entrada à origem.

Importar listas de usuários, empresas, documentos, carteiras, e-mails, telefones, IPs ou dispositivos

Use POST /v3/lists/{list_uuid}/entries/ para valores de lista que não sejam rostos. Este é o caminho certo para listas de bloqueio de provedores, listas de permissão, listas de chargeback, endereços de carteira, IPs sabidamente arriscados, impressões digitais de dispositivos, números de documentos, e-mails, telefones, usuários ou empresas.

Próximos passos

Importar usuários

Carregue perfis de usuário e vincule rostos de perfil confiáveis.

Importar empresas

Carregue perfis de empresa antes de executar o KYB.

Enviar rosto de perfil

Vincule imagens de rosto confiáveis aos usuários importados.

Enviar rosto para lista

Adicione rostos a listas de bloqueio ou listas de permissão.

Criar entrada de lista

Importe telefones, e-mails, carteiras, documentos, IPs, dispositivos, usuários ou empresas para listas.

Limites de requisições

Projete loops de migração e novas tentativas de forma segura.

Autorizações

x-api-key
string
header
obrigatório

Chave de API da sua aplicação, em Developers -> API keys no Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter escopo restrito: nenhum acesso, leitura ou escrita por recurso, limitada a alguns fluxos ou a sessões aprovadas, a uma lista de endereços IP e a uma data de validade. 401 significa que a chave está errada, revogada ou expirada; 403 significa que nenhuma chave foi enviada, que a chave não tem acesso a este recurso ou ação, ou que a requisição veio de um endereço fora da sua lista de IPs; 404 em uma rota de sessão significa que a sessão está fora dos fluxos ou status da chave. Uma chave sem acesso a mídia recebe URLs de imagem, vídeo e PDF como null, e uma chave sem permissão de escrita em sessões recebe links e tokens de sessão como null. Consulte https://docs.didit.me/console/api-keys.

Corpo

import_type
enum<string>
padrão:user_verification

O que importar: sessões históricas de Verificação de usuários, sessões históricas de Verificação de empresas, regras de status personalizados do fluxo de verificação (workflow) ou registros históricos de monitoramento de transações.

Opções disponíveis:
user_verification,
business_verification,
status_rules,
transactions
workflow_id
string<uuid>

UUID do fluxo de verificação (workflow) ao qual as sessões ou regras de status importadas devem ser vinculadas. Obrigatório para user_verification, business_verification e status_rules. Omita para transactions.

source_format
enum<string>

Opcional. Inferido a partir da extensão do arquivo enviado quando omitido.

Opções disponíveis:
csv,
ndjson
file
file

Arquivo CSV ou NDJSON canônico. Use NDJSON para importações grandes. Tamanho máximo de upload de 25 MB (use source_file_url para arquivos maiores). Mutuamente exclusivo com source_file_url.

source_file_url
string<uri>

Alternativa ao upload de arquivo. Deve ser uma URL HTTPS que resolva para um endereço público (redes privadas/loopback são rejeitadas). Mutuamente exclusivo com file.

source
enum<string>

provider torna esta importação uma migração de outro provedor de verificação de identidade. Omita para uma importação de arquivo.

Opções disponíveis:
file,
provider
provider
enum<string>

Origem da migração, obtida de GET /v3/session/imports/providers/. Obrigatório quando source é provider.

Opções disponíveis:
sumsub,
jumio,
veriff,
onfido,
persona,
metamap,
socure,
idnow,
shufti,
idenfy,
ondato,
trulioo,
au10tix,
complycube,
other
credentials
object

A chave somente leitura do provedor, com os nomes de campo listados em credential_fields. Criptografada em repouso, nunca retornada e apagada quando a importação termina. Envie-a como uma string JSON no multipart.

options
object
status_mapping
object

Alterações no mapeamento de status padrão do provedor: status de origem para status da Didit. Not Finished e Abandoned são ignorados e contabilizados, nunca importados.

dry_run
boolean
padrão:false

Conta o que a migração importaria (por status, já existente na Didit, mesma pessoa, não concluído) e não grava nada. O job termina em READY. Inicie-o com POST /v3/session/imports/{importId}/start/.

face_templates
boolean
padrão:false

Gera templates faciais a partir das selfies importadas e os busca entre os rostos e a lista de bloqueio da aplicação. As correspondências são apenas sinalizadas para revisão. Requer lawful_basis_confirmed.

lawful_basis_confirmed
boolean
padrão:false

Confirma que você tem uma base legal para compartilhar essas selfies com a Didit, na qualidade de operadora.

Resposta

Tarefa de importação aceita. Consulte o uuid retornado até que status seja COMPLETED ou FAILED.

uuid
string<uuid>
obrigatório

ID da tarefa de importação. Use este valor para consultar o progresso e obter os erros das linhas.

status
enum<string>
obrigatório
Opções disponíveis:
PENDING,
PROCESSING,
COMPLETED,
FAILED,
PAUSED,
CANCELLED,
READY
import_type
enum<string>
obrigatório
Opções disponíveis:
user_verification,
business_verification,
status_rules,
transactions
source_format
enum<string>
obrigatório
Opções disponíveis:
csv,
ndjson
source_filename
string
obrigatório
total_rows
integer<int64>
obrigatório
processed_rows
integer<int64>
obrigatório
created_count
integer<int64>
obrigatório
updated_count
integer<int64>
obrigatório
skipped_count
integer<int64>
obrigatório
failed_count
integer<int64>
obrigatório
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>

O estado da tarefa conforme exibido no console; errors é uma tarefa concluída com linhas rejeitadas.

Opções disponíveis:
ready,
queued,
running,
paused,
completed,
errors,
failed,
cancelled
source
enum<string>
Opções disponíveis:
file,
api,
provider
provider
string

Origem da migração; vazio para importação por arquivo ou API.

provider_options
object
credential_hint
string

Os primeiros caracteres da chave que a migração guarda. A chave em si nunca é retornada.

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

Quando um job pausado pelo limite de requisições do provedor é retomado automaticamente.

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

O que uma simulação (dry run) encontrou: 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 modificação em 1 de novembro de 2026