Saltar para o conteúdo principal
POST
Python
Use este guia para escolher o caminho de importação certo quando move dados de outro fornecedor para a Didit. Os clientes costumam chamar “importação” a dois trabalhos diferentes:
  • Importar trabalho de verificação histórico: recriar registos já concluídos de KYC, KYB, monitorização de transações ou regras de fluxo, para que a Didit mostre o histórico do fornecedor antigo. Use POST /v3/session/imports/.
  • Importar dados operacionais: criar Utilizadores, Empresas, faces de perfil, entradas de listas de bloqueio ou de listas de permissões, para que a Didit os possa usar em verificações futuras. Use as APIs de entidades, faces e listas.
As importações de verificação criam registos históricos com session_type: "MIGRATED" para KYC e KYB. Não enviam e-mails aos utilizadores finais, não os encaminham para o fluxo alojado e não repetem a verificação original. Os registos importados aparecem nas listas de sessões, nos perfis de entidades, nas vistas de transações e em GET /v3/session/{session_id}/decision/, quando aplicável.

Qual importação deve usar?

Se só precisa de um perfil de utilizador ou de empresa para verificações futuras, não importe uma sessão de verificação histórica. Use as APIs das entidades Utilizador ou Empresa. Se precisar que a decisão, os campos do documento, os avisos ou as provas do fornecedor antigo apareçam na Didit como histórico de conformidade, use POST /v3/session/imports/.

O que pode ser migrado de cada fornecedor?

A Didit aceita um ficheiro CSV ou NDJSON canónico, pelo que pode migrar de qualquer fornecedor depois de exportar e transformar os dados. O contrato de importação é sempre o esquema canónico da Didit.

Fluxo de migração

  1. Decida se pretende importar histórico, perfis, rostos, listas, transações ou regras.
  2. Exporte os dados do fornecedor antigo por si próprio. Não envie para a Didit as chaves de API do fornecedor antigo.
  3. Transforme a exportação do fornecedor no modelo CSV ou NDJSON canónico da Didit correspondente.
  4. Em migrações grandes, prefira NDJSON e divida os dados em ficheiros cujo processamento possa tentar novamente de forma independente.
  5. Crie a tarefa de importação e acompanhe o progresso.
  6. Obtenha os erros por linha, corrija apenas as linhas com falhas e tente-as novamente. Todas as tarefas de importação são idempotentes na respetiva chave externa natural.

Criar uma tarefa de importação

Crie uma tarefa de importação com um único pedido multipart:
Utilize CSV para migrações mais pequenas, baseadas em folhas de cálculo, e NDJSON para migrações grandes. Para 100k+ linhas, o NDJSON é mais fácil de transmitir em fluxo, dividir, validar e repetir. Uma aplicação pode executar até 4 tarefas de importação em simultâneo, por isso divida uma migração grande em vários ficheiros e inicie uma tarefa para cada um. Cada tarefa descarrega em paralelo os ficheiros multimédia de uma linha. Uma tarefa interrompida por uma implementação ou por um reinício do processo de trabalho continua automaticamente a partir da última linha importada, pelo que não precisa de a reiniciar. Nas importações de transações, omita workflow_id:

Campos do pedido

Como os registos são rastreados e deduplicados

Não existe um campo de pedido para a origem dos dados: todas as importações usam o esquema canónico da Didit. Cada registo importado guarda metadata.imported_from = "generic" para rastreabilidade. As importações de user_verification e business_verification desduplicam linhas com base em external_id dentro da aplicação, pelo que repetir o mesmo ficheiro não cria duplicados. As importações de transactions desduplicam, em vez disso, com base em transaction_id. Uma migração de fornecedor (source=provider) guarda cada registo como <provider>:<id>, por exemplo sumsub:5f8c0e2a9b1d4c3e2f1a0b9c. Uma importação de ficheiro de Verificação de utilizadores que enviou o ID do fornecedor sem prefixo (5f8c0e2a9b1d4c3e2f1a0b9c) é reconhecida como o mesmo registo, nos dois sentidos. Pode, por isso, iniciar uma migração através de ficheiros e concluí-la com uma migração de fornecedor, ou o inverso, sem importar um registo duas vezes.

Importar fotografias de documentos, vídeos e selfies como prova

Para import_type=user_verification, pode importar as fotografias originais do documento, os vídeos de captura do documento e de prova de vida, e a imagem de selfie do fornecedor anterior. Utilize estas colunas canónicas: Para migrações de grande dimensão, utilize URLs HTTPS. O Didit transfere cada ficheiro, valida que o URL é seguro, guarda uma cópia de propriedade do Didit e associa-a à sessão importada. As imagens são comprimidas; os vídeos são guardados tal como estão. O base64 inline é aceite para imagens em importações pequenas, mas os vídeos têm de ser sempre fornecidos como URL, pois o base64 aumentaria cada vídeo em cerca de 33% e excederia rapidamente o limite de importação por ficheiro. Exemplo de linha NDJSON com URLs de multimédia alojada pelo fornecedor:
Regras importantes sobre multimédia:
  • Os URLs têm de usar https.
  • Os URLs não podem resolver para IPs privados, localhost, intervalos link-local ou hosts de metadados internos.
  • As imagens aceitam uma coluna de URL ou a respetiva alternativa *_base64; o base64 tem prioridade quando ambos estão preenchidos. Os vídeos só podem ser fornecidos através de URL: não existe coluna *_video_base64.
  • Os vídeos têm de ser mp4, webm ou mov, e cada vídeo pode ter no máximo 10 MB. Ficheiros maiores ou que não sejam vídeos são rejeitados como erros de linha.
  • O Didit impõe timeouts de ligação e de leitura, um tamanho máximo de ficheiro e não faz tentativas infinitas.
  • As falhas de transferência de multimédia são guardadas como erros de linha, para que o restante da importação possa continuar.
  • Se não tiver multimédia do fornecedor, deixe estas colunas vazias. O Didit continua a importar 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 predefinição, o Didit não volta a executar OCR, prova de vida nem análise de fraude documental sobre o material histórico importado.

Consultar o progresso

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

Transferir erros de linha

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

Proteção contra abuso

As tarefas de importação históricas através de POST /v3/session/imports/ estão desativadas por predefinição. O Didit ativa esta capacidade por organização, após análise, porque estas tarefas podem processar milhões de linhas e transferir multimédia. As importações normais de dados operacionais descritas neste guia (criar Utilizadores, criar Empresas, carregar faces de perfil, carregar listas de bloqueio de faces ou adicionar entradas a listas) não requerem uma ativação especial para migração, além das permissões normais da chave de API, da disponibilidade do produto e dos limites de pedidos desses endpoints. As tarefas de importação históricas também são executadas em processos de trabalho isolados, com limites de tamanho de ficheiro, quotas de linhas, URLs de multimédia apenas em HTTPS, bloqueio de URLs de rede privada, um limite de 4 tarefas de importação ativas por aplicação e captura de erros por linha.

Estados canónicos

Idempotência

O Didit utiliza external_id como chave de idempotência das importações de Verificação de utilizadores e de Verificação de empresas, com âmbito ao nível da aplicação. As importações de transações utilizam transaction_id por aplicação. Repetir a importação do mesmo ficheiro ignora as linhas já importadas e cria as linhas que ainda não foram processadas.

Importar utilizadores, rostos de perfil e listas de bloqueio

Use estes caminhos quando não estiver a recriar uma sessão de verificação concluída.

Importar perfis de utilizador

Crie utilizadores com POST /v3/users/create/ ou com a importação CSV da Business Console em Importar e exportar utilizadores. Isto cria ou atualiza apenas o perfil VendorUser. Não cria uma sessão de verificação, uma decisão KYC, um relatório do documento, um aviso nem um histórico de webhooks. Use isto quando quiser que a Didit saiba que o cliente existe antes das verificações futuras, ou quando precisar de preencher retroativamente campos do tipo CRM, como display_name, etiquetas ou metadados.

Carregar rostos de perfil fidedignos

Depois de existir um utilizador, carregue um rosto de perfil fidedigno com POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/. Isto associa a prova biométrica ao perfil do utilizador e indexa-a para deteção de duplicados e pesquisa facial. Isto não coloca o rosto na lista de bloqueio. É útil quando tem uma imagem de perfil de confiança de um fornecedor de KYC anterior e quer que as verificações futuras da Didit a comparem com ela.

Importar listas de bloqueio e de permissões de rostos

Para bloquear ou permitir um rosto diretamente, use POST /v3/lists/{list_uuid}/entries/face-upload/ com uma lista do tipo facial. A Didit extrai o embedding facial e guarda uma entrada na lista. Use isto para imagens de fraudadores conhecidos, rostos fidedignos para listas de permissões ou migrações de listas de fraude de fornecedores. Se o rosto vier de uma sessão da Didit existente, prefira POST /v3/lists/{list_uuid}/entries/ com reference_session_id. A Didit extrai o rosto correto da sessão e liga a entrada à respetiva origem.

Importar listas de utilizadores, empresas, documentos, carteiras, e-mails, telefones, IPs ou dispositivos

Use POST /v3/lists/{list_uuid}/entries/ para valores de listas que não sejam rostos. É o caminho certo para listas de bloqueio e de permissões de fornecedores, listas de chargebacks, endereços, IPs de risco conhecidos, impressões digitais de dispositivos, números de documentos, e-mails, telefones, utilizadores ou empresas.

Próximos passos

Importar utilizadores

Carregue perfis de utilizador e associe rostos de perfil de confiança.

Importar empresas

Carregue perfis de empresa antes de executar a KYB.

Carregar rosto de perfil

Associe imagens de rosto fidedignas aos utilizadores importados.

Carregar rosto para lista

Adicione rostos a listas de bloqueio ou de permissões.

Criar entrada de lista

Importe telefones, e-mails, carteiras, documentos, IPs, dispositivos, utilizadores ou empresas para listas.

Limites de pedidos

Conceba ciclos de migração seguros e novas tentativas.

Autorizações

x-api-key
string
header
obrigatório

A chave de API da sua aplicação, a partir de Programadores -> Chaves de API na Business Console. A chave principal tem acesso total. Uma chave nomeada pode ter o âmbito definido: nenhum, 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á incorreta, 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 o pedido veio de um endereço fora da sua lista de IP; 404 numa rota de sessão significa que a sessão está fora dos fluxos ou estados da chave. Uma chave sem acesso a multimédia recebe URLs de imagens, vídeos e PDFs como nulos, e uma chave sem permissão de escrita em sessões recebe ligações de sessão e tokens como nulos. 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 utilizadores, sessões históricas de Verificação de empresas, regras de estado personalizadas do fluxo ou registos históricos de monitorização de transações.

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

UUID do fluxo ao qual as sessões importadas ou as regras de estado devem ser associadas. Obrigatório para user_verification, business_verification e status_rules. Omitir para transações.

source_format
enum<string>

Opcional. Deduzido da extensão do ficheiro carregado quando omitido.

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

Ficheiro canónico CSV ou NDJSON. Utilize NDJSON para importações grandes. Tamanho máximo de carregamento de 25 MB (utilize source_file_url para ficheiros maiores). Mutuamente exclusivo com source_file_url.

source_file_url
string<uri>

Alternativa ao carregamento de ficheiro. Deve ser um 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 isto uma migração a partir de outro fornecedor de verificação de identidade. Omita para uma importação de ficheiro.

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

Origem da migração, 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 apenas de leitura do fornecedor, com os nomes de campos listados por credential_fields. Encriptada em repouso, nunca devolvida e apagada quando a importação termina. Envie-a como uma string JSON em multipart.

options
object
status_mapping
object

Edições ao mapeamento de estado predefinido do fornecedor: estado de origem para estado 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 estado, já no Didit, mesma pessoa, não finalizada) e não grava nada. A tarefa termina em READY; inicie-a com POST /v3/session/imports/{importId}/start/.

face_templates
boolean
padrão:false

Cria modelos faciais a partir das selfies importadas e pesquisa-os nos rostos e na lista de bloqueio da aplicação. As correspondências são sinalizadas apenas para revisão. Requer lawful_basis_confirmed.

lawful_basis_confirmed
boolean
padrão:false

Confirma que tem uma base legal para partilhar estas selfies com a Didit na qualidade de subcontratante.

Resposta

Tarefa de importação aceite. Consulte periodicamente o uuid devolvido até que status seja COMPLETED ou FAILED.

uuid
string<uuid>
obrigatório

ID da tarefa de importação. Utilize este valor para consultar o progresso e obter 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 tal como apresentado na consola; errors corresponde a 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 uma importação por ficheiro ou API.

provider_options
object
credential_hint
string

Os primeiros carateres da chave que a migração contém. A chave em si nunca é devolvida.

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

Quando uma tarefa pausada pelo limite de pedidos do fornecedor é retomada autonomamente.

status_mapping
object
is_dry_run
boolean
dry_run_summary
object

O que uma execução de teste 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 7 de novembro de 2026