> ## Documentation Index > Fetch the complete documentation index at: https://docs.didit.me/llms.txt > Use this file to discover all available pages before exploring further. # Importar dados de outro fornecedor > Escolha no Didit a importação certa para sessões, utilizadores, faces, listas de bloqueio, empresas, transações históricas e estados de fluxo. 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?| Objetivo | Caminho de importação a usar | O que cria | Ideal para | | - | - | - | - | | Recriar sessões KYC históricas | `POST /v3/session/imports/` com `import_type=user_verification` | `Session`, dados de Verificação de identidade, imagens opcionais de documento/selfie, vídeos de documento e de prova de vida, etiquetas, metadados | Migrar candidatos cuja verificação já foi concluída da Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo ou de outro fornecedor de KYC | | Recriar sessões KYB históricas | `POST /v3/session/imports/` com `import_type=business_verification` | `BusinessSession`, dados de registo de empresas, administradores, beneficiários efetivos, etiquetas, metadados | Migrar verificações de empresas concluídas de fornecedores de KYB, fornecedores de registos de empresas ou ferramentas internas de KYB | | Recriar registos históricos de monitorização de transações | `POST /v3/session/imports/` com `import_type=transactions` | `Transaction`, partes associadas ao sujeito/à contraparte, resultados dos fornecedores, dados da Travel Rule, instantâneo da rede, metadados | Migrar o histórico de motores de regras, KYT, triagem de carteiras ou monitorização de transações em moeda fiduciária | | Importar regras personalizadas de estado do fluxo | `POST /v3/session/imports/` com `import_type=status_rules` | `VerificationSettings.feature_status_rules` | Migrar lógica de políticas de outro fornecedor ou de uma folha de cálculo para o motor de fluxos da Didit | | Criar Utilizadores sem sessões históricas | `POST /v3/users/create/` ou importação de CSV na Console | Linhas de perfil de `VendorUser` | Carregar a lista de utilizadores antes de iniciar novas verificações na Didit | | Associar faces de perfil fidedignas a utilizadores | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` | Evidência da face de perfil indexada para deteção de duplicados e pesquisa facial | Migrar imagens faciais de perfil de outro fornecedor de KYC sem recriar sessões completas | | Colocar faces em listas de bloqueio ou de permissões | `POST /v3/lists/{list_uuid}/entries/face-upload/` ou `POST /v3/lists/{list_uuid}/entries/` com `reference_session_id` | Entrada na lista de faces e embedding biométrico | Migrar faces conhecidas por estarem associadas a fraude, faces de confiança para a lista de permissões ou bloquear uma face de uma sessão existente na Didit | | Criar Empresas sem sessões KYB históricas | `POST /v3/businesses/create/` ou importação de CSV na Console | Linhas de perfil de `VendorBusiness` | Carregar a lista de clientes empresariais antes de executar KYB |> [!NOTE] > > 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.| Família de fornecedores | Origens típicas | Normalmente migrável | Notas | | - | - | - | - | | Fornecedores KYC | Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo, HyperVerge, AU10TIX, Mitek, Ondato | ID do candidato, ID de utilizador do fornecedor, estado da decisão, campos do documento, imagens do documento, imagem de selfie/prova de vida, etiquetas de recusa, etiquetas, metadados brutos do fornecedor | Utilize `import_type=user_verification`. Se o fornecedor não conseguir exportar imagens, importe os campos estruturados e deixe vazios os URL das imagens. | | Fornecedores KYB | Fornecedores de registos de empresas, Sumsub KYB, Trulioo KYB, exportações de registos no estilo Creditsafe, ferramentas KYB internas | Nome da empresa, número de registo, país, estado no registo, dirigentes, beneficiários efetivos, nível de risco, payload bruto do registo | Utilize `import_type=business_verification`. Os dirigentes e os UBO são enviados como arrays JSON. | | Fornecedores de monitorização de transações / KYT | Sumsub Transaction Monitoring, exportações KYT no estilo Chainalysis, Crystal, Merkle Science, Sardine, Unit21, Alloy, motores de regras internos | ID da transação, montante, moeda, direção, sujeito/contraparte, ocorrências de regras, resultados do fornecedor, estado da Travel Rule, instantâneo do grafo de rede | Utilize `import_type=transactions`. As transações importadas são registos históricos; por defeito, não voltam a ser analisadas. | | Folhas de cálculo de fluxos e políticas | Exportações de políticas de conformidade, tabelas de regras dos fornecedores, folhas de cálculo internas de risco | Regras de estado por funcionalidade, como "se o país emissor for X, definir Verificação de identidade como Em análise" | Utilize `import_type=status_rules`. As regras são validadas em relação ao catálogo de campos de fluxo da Didit antes de serem guardadas. | | Repositórios de utilizadores/perfis | CRM, base de dados de clientes, exportação de utilizadores do fornecedor, armazém de dados | `vendor_data`, nome de apresentação, metadados, etiquetas, imagens faciais de confiança | Utilize as APIs de utilizadores e o carregamento de imagens faciais de perfil. Não é o mesmo que uma sessão de verificação concluída. | | Dados de lista de bloqueio/permissão | Listas de fraude de fornecedores, folhas internas de operações antifraude, listas de contestações (chargebacks), listas internas relacionadas com sanções | E-mails, telefones, documentos, carteiras, IP, impressões digitais de dispositivos, rostos, países, utilizadores, empresas | Utilize as APIs de listas. Para imagens faciais, utilize o endpoint dedicado de envio de rostos para que a Didit possa extrair o embedding biométrico. |## Fluxo de migração1) 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çãoCrie uma tarefa de importação com um único pedido multipart:```bash theme={null} curl -X POST https://verification.didit.me/v3/session/imports/ \ -H "x-api-key: YOUR_API_KEY" \ -F "import_type=user_verification" \ -F "workflow_id=YOUR_KYC_WORKFLOW_ID" \ -F "file=@didit-import.ndjson" ```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`:```bash theme={null} curl -X POST https://verification.didit.me/v3/session/imports/ \ -H "x-api-key: YOUR_API_KEY" \ -F "import_type=transactions" \ -F "file=@didit-transactions.ndjson" ```### Campos do pedido| Campo | Obrigatório | Descrição | | - | - | - | | `import_type` | Não, o valor por defeito é `user_verification` | Um de `user_verification`, `business_verification`, `status_rules`, `transactions`. | | `workflow_id` | Sim, exceto para `transactions` | UUID do fluxo ao qual os registos importados ficam associados. `user_verification` e `status_rules` requerem um fluxo de Verificação de utilizadores; `business_verification` requer um fluxo de Verificação de empresas (KYB). | | `file` | Um de `file` ou `source_file_url` | O ficheiro CSV ou NDJSON canónico, incluído diretamente no pedido. | | `source_file_url` | Um de `file` ou `source_file_url` | URL HTTPS do qual a Didit descarrega o ficheiro. Os URL de redes privadas são recusados. | | `source_format` | Não | `csv` ou `ndjson`. Inferido pela extensão do ficheiro se for omitido. |### Como os registos são rastreados e deduplicadosNã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 `:`, 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 provaPara `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:| Evidência | Coluna preferencial | Alternativa para importações pequenas | Armazenado no Didit como | | - | - | - | - | | Imagem frontal do documento | `document_front_url` | `document_front_base64` | Imagem frontal de OCR da Verificação de identidade | | Imagem traseira do documento | `document_back_url` | `document_back_base64` | Imagem traseira de OCR da Verificação de identidade | | Selfie / imagem de prova de vida | `selfie_url` | `selfie_base64` | Imagem de referência de face/prova de vida | | Vídeo frontal do documento | `document_front_video_url` | Apenas URL | Vídeo frontal de OCR da Verificação de identidade | | Vídeo traseiro do documento | `document_back_video_url` | Apenas URL | Vídeo traseiro de OCR da Verificação de identidade | | Vídeo de prova de vida | `liveness_video_url` | Apenas URL | Vídeo de captura de face/prova de vida |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:```json theme={null} { "external_id": "applicant-123", "vendor_data": "user-42", "created_at": "2025-01-12T10:30:00Z", "status": "Approved", "email": "user@example.com", "phone": "+34687020083", "first_name": "Jane", "last_name": "Doe", "date_of_birth": "1990-05-15", "document_type": "P", "issuing_state": "USA", "document_number": "123456789", "expiration_date": "2030-01-15", "document_front_url": "https://provider-export.example.com/files/applicant-123-front.jpg", "document_back_url": "https://provider-export.example.com/files/applicant-123-back.jpg", "selfie_url": "https://provider-export.example.com/files/applicant-123-selfie.jpg", "document_front_video_url": "https://provider-export.example.com/files/applicant-123-front.webm", "document_back_video_url": "https://provider-export.example.com/files/applicant-123-back.webm", "liveness_video_url": "https://provider-export.example.com/files/applicant-123-liveness.mp4", "reject_reasons_json": "[]", "provider_metadata_json": "{\"source\":\"sumsub-export\"}" } ```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. Prompt de importação de Verificação de utilizadores Copiar o prompt para a área de transferência \

\`You are helping migrate historical User Verification (KYC) sessions into Didit.

Goal:
Transform the customer's Sumsub, MetaMap, or provider export into Didit's canonical verification import file, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=user_verification
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- DIDIT_WORKFLOW_ID for a User Verification workflow
\- Provider export file or API output

Canonical columns:
external_id, vendor_data, created_at, status, email, phone, first_name, last_name, date_of_birth, gender, nationality, document_type, issuing_state, document_number, personal_number, expiration_date, document_front_url, document_back_url, selfie_url, document_front_base64, document_back_base64, selfie_base64, document_front_video_url, document_back_video_url, liveness_video_url, is_blocklisted, reject_reasons_json, tags, provider_metadata_json

Rules:
\- phone is optional and accepts international format (for example +34687020083); it is stored on the imported session.
\- external_id must be the provider's unique verification/applicant id.
\- vendor_data must be the customer's stable user id. If absent, use the provider identity/user id.
\- status must be Approved, Declined, In Review, or Expired.
\- date_of_birth and expiration_date must use YYYY-MM-DD.
\- created_at must be ISO 8601.
\- nationality and issuing_state must be ISO-3166 alpha-3, for example USA, ESP, BRA.
\- document_type must use Didit codes: P, ID, DL, RP, SSC, HIC, WP, TC, VISA, PSC, BC, OTHER.
\- reject_reasons_json must be a JSON array. provider_metadata_json must be a JSON object.
\- Use document_front_url, document_back_url, and selfie_url when the provider can export evidence images. Use HTTPS media URLs for large imports. Avoid inline base64 unless the import is small.
\- Use document_front_video_url, document_back_video_url, and liveness_video_url to import capture videos. Videos must be mp4, webm, or mov and at most 10 MB each; otherwise the row is rejected.
\- If only one document side exists, fill document_front_url and leave document_back_url empty.
\- Never call the import API with provider credentials. The customer downloads provider data themselves.
\- The import is idempotent by external_id inside one Didit application, so retries are safe.

Steps:
1\. Inspect the provider export schema.
2\. Map each provider row to the canonical fields.
3\. Write NDJSON for large files; one JSON object per line.
4\. Validate the first 10 rows locally before uploading.
5\. Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=user_verification" \
-F "workflow_id=$DIDIT_WORKFLOW_ID" \
-F "file=@didit-import.ndjson"
6\. Poll until status is COMPLETED or FAILED.
7\. If failed_count is greater than 0, fetch /errors/ and produce a corrected file containing only failed rows.

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A short summary of created, skipped, and failed rows.`

\
Colar em Prompt de importação de Verificação de empresas Copiar o prompt para a área de transferência \

\`You are helping migrate historical Business Verification (KYB) sessions into Didit.

Goal:
Transform the customer's KYB provider export into Didit's canonical business verification import file, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=business_verification
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- DIDIT_WORKFLOW_ID for a Business Verification workflow
\- Provider export file or API output

Canonical business columns:
external_id, vendor_data, created_at, status, company_name, registration_number, country_code, registry_status, verification_status, company_type, tax_number, risk_level, incorporation_date, registered_address, is_from_registry, officers_json, beneficial_owners_json, provider_metadata_json, tags

Rules:
\- external_id must be the provider's unique business verification id.
\- vendor_data must be the customer's stable business id.
\- status must be Approved, Declined, In Review, or Expired.
\- country_code must be ISO-3166 alpha-3.
\- officers_json and beneficial_owners_json must be JSON arrays of objects.
\- provider_metadata_json must be a JSON object.
\- The import is idempotent by external_id inside one Didit application.

Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=business_verification" \
-F "workflow_id=$DIDIT_WORKFLOW_ID" \
-F "file=@didit-business-import.ndjson"

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A short summary of created, skipped, and failed rows.`

\
Colar em Prompt de importação de regras de estado personalizadas Copiar o prompt para a área de transferência \

\`You are helping import custom status rules into a Didit workflow.

Goal:
Transform the customer's policy spreadsheet into Didit's feature_status_rules format, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=status_rules
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- DIDIT_WORKFLOW_ID for the workflow to update
\- A policy spreadsheet or JSON policy definition

Canonical status-rule columns:
feature, rules_json, mode

Rules:
\- feature must be a Didit feature key such as OCR, LIVENESS, FACE_MATCH, AML, KYB_REGISTRY, KYB_DOCUMENTS, or KYB_KEY_PEOPLE.
\- rules_json must be a JSON array of rule objects.
\- Each rule needs field, operator, status, and usually value.
\- mode is replace or append. Default is replace.
\- Do not reference status fields such as kyc.status; status rules compute status and must use other report fields.

Example rules_json:
\[{"field":"kyc.issuing_state","operator":"in","value":["VEN","IRN"],"status":"In Review"}]

Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=status_rules" \
-F "workflow_id=$DIDIT_WORKFLOW_ID" \
-F "file=@didit-status-rules.csv"

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A summary of updated and failed rule rows.`

\
Colar em Prompt de importação de transações Copiar o prompt para a área de transferência \

\`You are helping migrate historical transaction monitoring records into Didit.

Goal:
Transform the customer's legacy transaction monitoring export into Didit's canonical transaction import file, then call Didit's import API.

Didit API:
\- Create import job: POST https://verification.didit.me/v3/session/imports/
\- Poll job: GET https://verification.didit.me/v3/session/imports/{import_id}/
\- Read row errors: GET https://verification.didit.me/v3/session/imports/{import_id}/errors/
\- Download template: GET https://verification.didit.me/v3/session/imports/template/?import_type=transactions
\- Authenticate with x-api-key: 

Inputs you need:
\- DIDIT_API_KEY
\- A transaction export file or API output

Canonical transaction columns:
transaction_id, transaction_at, transaction_category, direction, amount, currency, currency_kind, amount_in_default_currency, default_currency, payment_details, payment_reference_id, action_type, status, score, severity, subject_json, counterparty_json, custom_properties_json, provider_results_json, travel_rule_json, network_snapshot_json, metadata_json

Rules:
\- transaction_id is required and is idempotent per Didit application.
\- transaction_category must be one of Didit's transaction categories, for example finance, kyc, travelRule, userPlatformEvent, gamblingBet, gamblingLimitChange, gamblingBonusChange, or auditTrailEvent.
\- direction must be INBOUND or OUTBOUND.
\- status must be APPROVED, IN_REVIEW, DECLINED, or AWAITING_USER.
\- subject_json must include vendor_data and full_name.
\- counterparty_json is optional but should be included when the legacy provider has it.
\- provider_results_json must be a JSON array.
\- travel_rule_json, network_snapshot_json, custom_properties_json, and metadata_json must be JSON objects when present.

Create an import job:
curl -X POST https://verification.didit.me/v3/session/imports/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "import_type=transactions" \
-F "file=@didit-transactions.ndjson"

Output:
\- A canonical CSV or NDJSON file ready for Didit.
\- The curl command used to create the import job.
\- The import_id and polling command.
\- A summary of created, skipped, and failed transaction rows.`

\
Colar em ## Consultar o progresso```bash theme={null} curl https://verification.didit.me/v3/session/imports/IMPORT_ID/ \ -H "x-api-key: YOUR_API_KEY" ```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```bash theme={null} curl https://verification.didit.me/v3/session/imports/IMPORT_ID/errors/ \ -H "x-api-key: YOUR_API_KEY" ```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 abusoAs 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| Resultado do fornecedor | Estado no Didit | | - | - | | Aprovado / Verde / Verificado | `Approved` | | Recusado / Vermelho / Rejeitado | `Declined` | | Análise manual / Pendente / Revisão necessária | `In Review` | | Incompleto / Init / Linha histórica desconhecida | `Expired` |## IdempotênciaO 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 bloqueioUse estes caminhos quando não estiver a recriar uma sessão de verificação concluída.### Importar perfis de utilizadorCrie utilizadores com [`POST /v3/users/create/`](https://docs.didit.me/pt/management-api/users/create) ou com a importação CSV da Business Console em [Importar e exportar utilizadores](https://docs.didit.me/pt/entities/users/import-export.md). 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 fidedignosDepois 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/`](https://docs.didit.me/pt/management-api/users/upload-face). 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 rostosPara bloquear ou permitir um rosto diretamente, use [`POST /v3/lists/{list_uuid}/entries/face-upload/`](https://docs.didit.me/pt/management-api/lists/upload-face) 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/`](https://docs.didit.me/pt/management-api/lists/create-entry) 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 dispositivosUse [`POST /v3/lists/{list_uuid}/entries/`](https://docs.didit.me/pt/management-api/lists/create-entry) 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> [card] [Importar utilizadores](https://docs.didit.me/pt/entities/users/import-export.md) > > Carregue perfis de utilizador e associe rostos de perfil de confiança.> [card] [Importar empresas](https://docs.didit.me/pt/entities/businesses/import-export.md) > > Carregue perfis de empresa antes de executar a KYB.> [card] [Carregar rosto de perfil](https://docs.didit.me/pt/management-api/users/upload-face.md) > > Associe imagens de rosto fidedignas aos utilizadores importados.> [card] [Carregar rosto para lista](https://docs.didit.me/pt/management-api/lists/upload-face.md) > > Adicione rostos a listas de bloqueio ou de permissões.> [card] [Criar entrada de lista](https://docs.didit.me/pt/management-api/lists/create-entry.md) > > Importe telefones, e-mails, carteiras, documentos, IPs, dispositivos, utilizadores ou empresas para listas.> [card] [Limites de pedidos](https://docs.didit.me/pt/integration/rate-limiting.md) > > Conceba ciclos de migração seguros e novas tentativas. ## OpenAPI ````yaml pt/openapi-25.json POST /v3/session/imports/ openapi: 3.0.0 info: version: 3.0.0 title: Didit Verification API description: API de Verificação de identidade. Autentique-se com o cabeçalho x-api-key. servers: - url: https://verification.didit.me security: [] tags: [] paths: /v3/session/imports/: post: tags: - Sessions summary: Criar uma tarefa de importação de verificação description: >- Cria um trabalho de importação assíncrono para sessões históricas de Verificação de utilizadores, sessões de Verificação de empresas (KYB), registos de monitorização de transações ou regras de estado personalizado de fluxos. Defina `source=provider` para migrar a partir de outro fornecedor: a Didit lê Sumsub, Onfido, Persona e ComplyCube com a sua chave só de leitura, lê registos da Veriff, iDenfy e MetaMap através dos IDs que enviar em `file`, e importa um ficheiro de exportação no formato da Didit para os restantes fornecedores. Os IDs dos registos utilizam espaços de nomes por fornecedor (`sumsub:`) para que uma nova execução ignore tudo o que já se encontra na Didit, e um registo importado através de um ficheiro apenas com o ID do fornecedor também é reconhecido, em ambas as direções, para que a alternância entre a importação por ficheiro e a migração por fornecedor nunca importe um registo duas vezes. Uma aplicação pode executar até 4 trabalhos de importação em simultâneo; um trabalho interrompido por uma implementação ou pelo reinício de um processo de trabalho continua autonomamente a partir da última linha importada. As importações estão desativadas por predefinição e têm de ser ativadas por organização pela Didit. operationId: post_v3_session_imports_create requestBody: required: true content: multipart/form-data: schema: type: object properties: import_type: type: string enum: - user_verification - business_verification - status_rules - transactions default: user_verification description: >- 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. workflow_id: type: string format: uuid description: >- 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: type: string enum: - csv - ndjson description: >- Opcional. Deduzido da extensão do ficheiro carregado quando omitido. file: type: string format: binary description: >- 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: type: string format: uri description: >- 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: type: string enum: - file - provider description: >- `provider` torna isto uma migração a partir de outro fornecedor de verificação de identidade. Omita para uma importação de ficheiro. provider: type: string enum: - sumsub - jumio - veriff - onfido - persona - metamap - socure - idnow - shufti - idenfy - ondato - trulioo - au10tix - complycube - other description: >- Origem da migração, de `GET /v3/session/imports/providers/`. Obrigatório quando `source` é `provider`. credentials: type: object additionalProperties: type: string description: >- 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: type: object properties: region: type: string description: >- A região do fornecedor, uma das suas `regions` (Onfido: `eu`, `us`, `ca`). status_mapping: type: object additionalProperties: type: string enum: - Approved - Declined - In Review - Expired - Not Finished - Abandoned description: >- 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: type: boolean default: false description: >- 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: type: boolean default: false description: >- 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: type: boolean default: false description: >- Confirma que tem uma base legal para partilhar estas selfies com a Didit na qualidade de subcontratante. application/json: schema: type: object required: - source_file_url properties: import_type: type: string enum: - user_verification - business_verification - status_rules - transactions default: user_verification description: >- 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. workflow_id: type: string format: uuid description: >- 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: type: string enum: - csv - ndjson description: >- Opcional. Deduzido da extensão de ficheiro do URL quando omitido. source_file_url: type: string format: uri description: >- 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: type: string enum: - file - provider description: >- `provider` torna isto uma migração a partir de outro fornecedor de verificação de identidade. Omita para uma importação de ficheiro. provider: type: string enum: - sumsub - jumio - veriff - onfido - persona - metamap - socure - idnow - shufti - idenfy - ondato - trulioo - au10tix - complycube - other description: >- Origem da migração, de `GET /v3/session/imports/providers/`. Obrigatório quando `source` é `provider`. credentials: type: object additionalProperties: type: string description: >- 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: type: object properties: region: type: string description: >- A região do fornecedor, uma das suas `regions` (Onfido: `eu`, `us`, `ca`). status_mapping: type: object additionalProperties: type: string enum: - Approved - Declined - In Review - Expired - Not Finished - Abandoned description: >- 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: type: boolean default: false description: >- 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: type: boolean default: false description: >- 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: type: boolean default: false description: >- Confirma que tem uma base legal para partilhar estas selfies com a Didit na qualidade de subcontratante. examples: URL-based import: value: import_type: user_verification workflow_id: 9f9b1234-aaaa-bbbb-cccc-1234567890ab source_file_url: https://files.example.com/exports/sessions.ndjson responses: '201': description: >- Tarefa de importação aceite. Consulte periodicamente o `uuid` devolvido até que `status` seja `COMPLETED` ou `FAILED`. content: application/json: schema: $ref: '#/components/schemas/SessionImportJob' examples: Job accepted: value: uuid: 3f9c1a2b-4d5e-4f60-8a7b-9c0d1e2f3a4b status: PENDING import_type: user_verification source_format: ndjson source_filename: sessions.ndjson total_rows: 0 processed_rows: 0 checkpoint_row: 0 created_count: 0 updated_count: 0 skipped_count: 0 failed_count: 0 total_media_bytes: 0 last_error: null created_at: '2026-05-17T08:42:11Z' updated_at: '2026-05-17T08:42:11Z' started_at: null completed_at: null '400': description: >- Fluxo, tipo de ficheiro, tamanho de ficheiro, URL de origem ou combinação de seletores inválidos. Uma migração cuja chave seja recusada pelo fornecedor devolve `code` (`invalid_credentials`, `missing_permission`, `wrong_region`, `provider_unavailable`, `rate_limited`, `ids_required`, `record_not_found`), `missing_permissions` e `suggested_region`. content: application/json: examples: Invalid workflow: value: workflow_id: - Invalid workflow_id. Workflow required: value: workflow_id: - This field is required for this import type. Wrong file type: value: file: - Only CSV and NDJSON files are supported. File too large: value: file: - Import file exceeds the maximum allowed size. No source: value: file: - Upload a file or provide source_file_url. Both sources: value: file: - Use either file or source_file_url, not both. '403': description: >- Importações não ativadas, aplicação de sandbox ou chave de API em falta (uma chave errada, revogada ou expirada recebe `401`). As importações de verificação estão desativadas por predefinição e têm de ser ativadas pela Didit para cada organização. content: application/json: examples: Imports not enabled: value: detail: >- Verification imports are not enabled for this organization. Sandbox: value: detail: >- Verification imports are not enabled for sandbox applications. Bad API key: value: detail: You do not have permission to perform this action. '429': description: >- A aplicação já tem 4 tarefas de importação ativas (PENDING/PROCESSING/PAUSED), o máximo que pode executar em simultâneo. Aguarde que uma termine antes de iniciar outra. content: application/json: examples: Active job: value: detail: >- This application already has 4 active import jobs, the most it can run at once. Wait for one to finish before starting another. security: - ApiKeyAuth: [] x-codeSamples: - lang: python label: Python source: |- from didit import Didit # Reads DIDIT_API_KEY. client = Didit() result = client.sessions.imports.create( import_type="user_verification", workflow_id="9f9b1234-aaaa-bbbb-cccc-1234567890ab", source_file_url="https://files.example.com/exports/sessions.ndjson", ) print(result) - lang: javascript label: Node.js source: |- import Didit from "@didit-protocol/sdk-node"; // Reads DIDIT_API_KEY. const didit = new Didit(); const result = await didit.sessions.imports.create({ import_type: "user_verification", workflow_id: "9f9b1234-aaaa-bbbb-cccc-1234567890ab", source_file_url: "https://files.example.com/exports/sessions.ndjson", }); console.log(result); - lang: go label: Go source: "ctx := context.Background()\n// Reads DIDIT_API_KEY.\nclient := didit.NewClient()\n\nresult, err := client.Sessions.Imports.Create(ctx, didit.SessionsImportsCreateParams{\n\tImportType: didit.Some(didit.SessionsImportsCreateParamsImportType(\"user_verification\")),\n\tWorkflowID: didit.String(\"9f9b1234-aaaa-bbbb-cccc-1234567890ab\"),\n\tSourceFileURL: didit.String(\"https://files.example.com/exports/sessions.ndjson\"),\n})\nif err != nil {\n\tlog.Fatal(err)\n}\nfmt.Printf(\"%+v\\n\", result)" - lang: java label: Java source: >- import me.didit.Didit; import me.didit.types.SessionsImportsCreateParams; // Reads DIDIT_API_KEY. Didit client = new Didit(); var result = client.sessions().imports().create(SessionsImportsCreateParams.builder() .importType(SessionsImportsCreateParams.ImportType.of("user_verification")) .workflowId("9f9b1234-aaaa-bbbb-cccc-1234567890ab") .sourceFileUrl("https://files.example.com/exports/sessions.ndjson") .build()); System.out.println(result); - lang: php label: PHP source: |- sessions->imports->create([ 'import_type' => 'user_verification', 'workflow_id' => '9f9b1234-aaaa-bbbb-cccc-1234567890ab', 'source_file_url' => 'https://files.example.com/exports/sessions.ndjson', ]); print_r($result->toArray()); - lang: ruby label: Ruby source: |- require "didit" # Reads DIDIT_API_KEY. didit = Didit::Client.new result = didit.sessions.imports.create( import_type: "user_verification", workflow_id: "9f9b1234-aaaa-bbbb-cccc-1234567890ab", source_file_url: "https://files.example.com/exports/sessions.ndjson" ) puts result.to_h - lang: csharp label: .NET source: >- using System; using System.Text.Json; using Didit; // Reads DIDIT_API_KEY. using var client = new DiditClient(); var result = await client.Sessions.Imports.CreateAsync(new SessionsImportsCreateParams { ImportType = new SessionsImportsCreateParamsImportType("user_verification"), WorkflowId = "9f9b1234-aaaa-bbbb-cccc-1234567890ab", SourceFileUrl = "https://files.example.com/exports/sessions.ndjson", }); Console.WriteLine(JsonSerializer.Serialize(result)); components: schemas: SessionImportJob: type: object required: - uuid - status - import_type - source_format - source_filename - total_rows - processed_rows - created_count - updated_count - skipped_count - failed_count properties: uuid: type: string format: uuid description: >- ID da tarefa de importação. Utilize este valor para consultar o progresso e obter erros das linhas. status: type: string enum: - PENDING - PROCESSING - COMPLETED - FAILED - PAUSED - CANCELLED - READY import_type: type: string enum: - user_verification - business_verification - status_rules - transactions source_format: type: string enum: - csv - ndjson source_filename: type: string total_rows: type: integer format: int64 processed_rows: type: integer format: int64 checkpoint_row: type: integer format: int64 created_count: type: integer format: int64 updated_count: type: integer format: int64 skipped_count: type: integer format: int64 failed_count: type: integer format: int64 total_media_bytes: type: integer format: int64 last_error: type: string nullable: true created_at: type: string format: date-time updated_at: type: string format: date-time started_at: type: string format: date-time nullable: true completed_at: type: string format: date-time nullable: true state: type: string enum: - ready - queued - running - paused - completed - errors - failed - cancelled description: >- O estado da tarefa tal como apresentado na consola; `errors` corresponde a uma tarefa concluída com linhas rejeitadas. source: type: string enum: - file - api - provider provider: type: string description: Origem da migração; vazio para uma importação por ficheiro ou API. provider_options: type: object credential_hint: type: string description: >- Os primeiros carateres da chave que a migração contém. A chave em si nunca é devolvida. credentials_expires_at: type: string format: date-time nullable: true resumes_at: type: string format: date-time nullable: true description: >- Quando uma tarefa pausada pelo limite de pedidos do fornecedor é retomada autonomamente. status_mapping: type: object additionalProperties: type: string is_dry_run: type: boolean dry_run_summary: type: object description: >- O que uma execução de teste encontrou: `total`, `by_status`, `already_in_didit`, `same_person`, `not_finished`, `failed`, `unmapped_statuses`. face_templates_enabled: type: boolean lawful_basis_confirmed_at: type: string format: date-time nullable: true not_finished_count: type: integer format: int64 same_person_count: type: integer format: int64 face_templates_count: type: integer format: int64 face_duplicates_count: type: integer format: int64 face_blocklist_hits_count: type: integer format: int64 created_by_name: type: string nullable: true created_by_email: type: string nullable: true securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- 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. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.