Importar entidades (CSV)
Referência API
Importar entidades (CSV)
Envia CSV e enfileira import bulk — formato plataforma sem mappingId ou colunas custom com mappingId. Manual por padrão; automático explícito.
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.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)
autoExecuteIntegrations no automático → todos os enrichments ativos da org.
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):
- bulk-entities-template-automatic.csv — com
entityImportMode=automatic. Linhas demo AR/BR/CL,depth, enrichments. - bulk-entities-template-manual.csv — com
entityImportMode=manual(padrão). Linhas demo AR/MX/BR,suggested_nameobrigatório, semdepth.
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.. 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ó modoautomatic. 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:
tax_id + type): envie country (ISO2) no form do lote — obrigatório.
Campos do formulário
Enrichments nos filhos e monitoramento
ComentityImportMode=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.
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.