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.

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.

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.