Skip to main content
POST
Importar entidades (CSV)

Endpoint

Visão geral

Content-Type: multipart/form-data. Enfileira o mesmo job bulk do hub Importações em lote. Exige entities:bulk_import e importação em massa automática na org. Resposta 202 com jobId e importMode efetivo.

Autenticação

Modos (entityImportMode)

Valores legacy manual_no_enrichment e automatic_enriched ainda são aceitos no request e normalizados para manual / automatic. A resposta usa os nomes canônicos.

Se um enrichment falhar (por linha)

Cada linha do CSV é processada à parte. Padrão: a linha fica failed e o job segue para a próxima. Com stopOnFirstError=true o lote para no primeiro erro (as linhas já criadas permanecem). Em automatic, enrichments extras (BCRA na Argentina, etc.) só correm depois que dados básicos deram certo. Um erro de BCRA não aborta uma alta cujo passo de dados básicos já teve sucesso.

Padrão enviando só o CSV

importMode: manual — entidade mínima, sem enrichments salvo envio explícito.

Manual com enrichments escolhidos

Mesma semântica do modo Manual do hub:

Modo automático (explícito)

Sem autoExecuteIntegrations no automático → todos os enrichments ativos da org.

Ação de matriz após a conclusão

O campo multipart opcional postImportActions aceita um array JSON. A ação run_risk_matrix_filtered enfileira uma execução em massa da matriz de risco quando o job chega a completed:
Com relatedEntitiesOfCreatedEntitiesOnly=true, a Gu1 avalia somente entidades vinculadas diretamente —como origem ou destino— a linhas cujo resultado neste arquivo foi created. filters.type define se as relacionadas devem ser company ou person, e a matriz correspondente é obrigatória. Linhas com skipped_existing ou failed são excluídas. Sem esse flag, filters é aplicado à lista completa de entidades da organização. Como alternativa, envie sourceImportJobId com o ID de uma importação de entidades anterior e concluída. A Gu1 executa a matriz somente nas linhas created desse lote que correspondam a filters.type, inclusive entidades sem vínculo com as linhas do arquivo atual. sourceImportJobId e relatedEntitiesOfCreatedEntitiesOnly=true são mutuamente exclusivos. A importação anterior deve pertencer à mesma organização e ter seu relatório completo disponível. Você também pode enviar onlyWithoutRiskMatrixExecution=true para avaliar todas as entidades de filters.type que ainda não tenham uma auditoria de execução de matriz. Depois que uma entidade é processada com sucesso, importações posteriores não voltam a incluí-la. Os três escopos (sourceImportJobId, entidades relacionadas e sem execução anterior) são mutuamente exclusivos.

CSV plataforma

Cabeçalhos mínimos: tax_id, type. Recomendado: suggested_name (obrigatório no manual). Ver País (ISO2) para country_code.

País (ISO2) — sempre obrigatório

Cada linha precisa de um país para criar a entidade (manual e automático). Informe em um ou ambos os lugares: Prioridade: country_code na linha → country do lote. Se nenhum estiver definido numa linha, o import falha com missing country antes de enfileirar. Modelos de referência — download (tax IDs de demo fixos; substitua antes de importar em produção) ou gere IDs novos no hub do painel (Entidades → importação em massa): Fonte canônica (manter alinhada se as colunas mudarem): apps/web/src/lib/bulk-automatic-entity-import-parse.ts.

Referência de colunas (CSV plataforma)

Cabeçalhos case-insensitive; espaços → _. Aliases entre parênteses.
Mesma entidade, vários vínculos (CSV): o CSV da plataforma admite uma relação por linha. Se a mesma pessoa/empresa aparecer em várias linhas com related_* distintos, a Gu1 não recria a entidade (skip por tax_id duplicado), mas aplica o vínculo daquela linha. Se o edge (source → target + tipo) já existir, esse vínculo é omitido (idempotente). Alternativa em API/JSON: um único create com até 10 itens em relationships[].
Removido (2026-06-04): as colunas CSV execute_all_active_checks e checks não fazem mais parte do contrato de importação. Use enrichments, enrichment_group_refs e execute_all_active_enrichments. Ver Changelog.
Notação com ponto: cabeçalhos com . geram objetos aninhados. Enrichments podem sobrescrever entityData; valores do CSV são reaplicados no fim (CSV prevalece em conflitos). attributes: colunas attributes.*, metadata.* (legacy) ou sem prefixo. Form attributes (JSON) do lote funde com os da linha (linha prevalece). Colunas de enrichment por linha aplicam em ambos modos; depth só em automatic.

Enrichments em relacionadas por linha (CSV plataforma)

Opcional — só modo automatic. Prefixo relationship_ (alias plural relationships_). Lotes com política custom (ex. Paytime): omita relationship_execute_all_active_enrichments do CSV para aplicar a política do formulário. Use relationship_omit_enrichments por linha só para exceções. Exemplo omit em acionistas:
CSV simples (só tax_id + type): envie country (ISO2) no form do lote — obrigatório.

Campos do formulário

Enrichments nos filhos e monitoramento

Com entityImportMode=automatic e depth > 0 são criados acionistas (raiz empresa) ou entidades relacionadas (raiz pessoa): monitoringApplyToRelationships: com false, o JSON monitoring vale só para a entidade principal. Recomendado false com by_root_type.
Um autoExecuteIntegrationsShareholders por linha no bulk JSON ou colunas relationship_* no CSV ainda prevalece sobre a política do lote para esse item.

Manual vs automático

Limites

Ver Importações em lote.