Importar entidades (CSV)

Endpoint

POST https://api.gu1.ai/batch-import/import/entities

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

Authorization: Bearer SUA_API_KEY

Modos (`entityImportMode`)

Modo	Quando	Comportamento
`manual`	Padrão se omitir o campo	Entidade mínima com `taxId` + `suggested_name` (obrigatório). Sem pipeline de dados básicos (Nosis/CPF). Enrichments opcionais via `autoExecuteIntegrations` no form e/ou colunas CSV por linha. Sem `depth` / acionistas. País: qualquer ISO2 válido da plataforma (`country_code` por linha tem prioridade).
`automatic`	Enviar `entityImportMode=automatic`	Dados básicos por tax ID (AR, BR ou CL) + enrichments (padrão todos ativos se omitir `autoExecuteIntegrations`) + `depth` opcional.

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

curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
  -H 'Authorization: Bearer SUA_API_KEY' \
  -F 'file=@bulk-entities-template.csv'

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

Manual com enrichments escolhidos

Mesma semântica do modo Manual do hub:

curl -X POST 'https://api.gu1.ai/batch-import/import/entities' \
  -H 'Authorization: Bearer SUA_API_KEY' \
  -F 'file=@bulk-entities-template.csv' \
  -F 'entityImportMode=manual' \
  -F 'autoExecuteIntegrations={"executeAllActiveEnrichments":false,"enrichments":["nosis_enrichment"]}' \
  -F 'riskMatrixCompanyId=UUID_DA_MATRIZ'

Modo automático (explícito)

  -F 'entityImportMode=automatic'

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:

Fonte	Quando usar
Campo do form `country`	Passo 2 do hub ou multipart na API. Obrigatório em CSV simples (só `tax_id` + `type`). Obrigatório em linhas sem `country_code`.
Coluna CSV `country_code` (alias `country`)	Por linha. Substitui o `country` do lote quando presente.

Prioridade: country_code na linha → country do lote. Se nenhum estiver definido numa linha, o import falha com missing country antes de enfileirar.

Modo	Países permitidos
Automático	AR, BR, CL
Manual	Qualquer ISO2 válido da plataforma

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_name obrigatório, sem depth.

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.

Coluna CSV	Alias	Campo API / entidade	Notas
`tax_id`	`taxId`	`taxId`	Obrigatório. Normalizado por país.
`type`	`tipo`	`type`	Obrigatório. `person` / `company`.
`country_code`	`country`	`country`	ISO2 por linha. Substitui o `country` do lote. Coluna opcional no CSV quando o lote envia `country` (CSV simples) ou quando cada linha inclui `country_code`. País sempre obrigatório — coluna e/ou campo do lote.
`suggested_name`	`name`, `nombre`	`suggestedName`	Nome para exibição. Obrigatório no manual em cada linha.
`gender`	—	`gender`	Dado de criação. Enum: `M`, `F`, `male`, `female`, `other`, `unknown`. Use `other` para não binário. Ver Criar entidade — Person.
`external_id`	`externalId`	`externalId`	ID externo.
`email`	—	`email`	Email de contato.
`phone`	—	`phone`	Telefone.
`registration_date`	—	`registrationDate`	Data de registro (ISO).
`risk_matrix_id`	—	`riskMatrixId`	UUID da matriz por linha.
`execute_all_active_enrichments`	—	`autoExecuteIntegrations.executeAllActiveEnrichments`	`true` / `false`.
`enrichments`	—	`autoExecuteIntegrations.enrichments`	Códigos separados por `,` ou `;`.
`enrichment_group_refs`	—	`autoExecuteIntegrations.enrichmentGroupRefs`	Slugs de grupos.
`omit_enrichments`	`exclude_enrichments`	`autoExecuteIntegrations.excludeEnrichments`	Códigos a omitir do conjunto final. Funciona com `execute_all_active_enrichments=true`. Se for a única coluna de enrichment na linha, funde com a config do lote.
`create_relationships`	—	`createRelationships`	Só modo automático.
`depth`	—	`depth`	0–5. Só automático (removido no manual).
`status`	—	`status`	Status da entidade.
`attributes.<path>`	—	`attributes`	Dado de negócio aninhado (notação com ponto, como CSV nativo de transações). Ex.: `attributes.segment_tag`.
`entityData.<path>`	—	`entityData.{person\|company}`	Perfil KYC/KYB. Sem `person`/`company` na cabeça → usa o `type` da linha. Ex.: `entityData.income`, `entityData.tradeName`.
`entityData.person.<path>` / `entityData.company.<path>`	—	`entityData.person` / `.company`	Caminhos explícitos.
`metadata.<path>`	—	`attributes` (legacy)	Deprecado; fundido em `attributes`.
Coluna sem prefixo	—	`attributes`	Retrocompat: `segment_tag` → `attributes.segment_tag`.

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_).

Coluna	Descrição
`relationship_execute_all_active_enrichments`	`true` = todos os enrichments ativos; `false` = só dados básicos. Substitui a política do lote (`childEnrichmentPolicy`) nessa linha.
`relationship_enrichments_company`	Códigos de provedor para filhos tipo empresa (separados por `,` ou `;`)
`relationship_enrichments_person`	Códigos para filhos tipo pessoa
`relationship_enrichment_group_refs`	Grupos do marketplace (opcional)
`relationship_omit_enrichments`	Alias de `relationship_exclude_enrichments`. Códigos a omitir (também com `execute_all_active=true`). Se for a única coluna `relationship_` na linha, funde* com a política do lote.
`relationship_exclude_enrichments`	Igual a `relationship_omit_enrichments` (nome legado).

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,country_code,depth,relationship_omit_enrichments
67250861000107,company,BR,1,global_gueno_sanctions_enrichment

CSV simples (só tax_id + type): envie country (ISO2) no form do lote — obrigatório.

Campos do formulário

Campo	Obrigatório	Descrição
`file`	Sim	CSV
`country`	Condicional (obrigatório na prática)	ISO2 do lote. Obrigatório se o CSV não traz `country_code` numa linha. Fallback opcional se todas as linhas incluem `country_code`.
`autoExecuteIntegrations`	Não	JSON — manual: opcional; automático: padrão todos ativos
`riskMatrixPersonId` / `CompanyId`	Não	UUID — ambos modos
`monitoring`	Não	JSON — ambos modos
`autoExecuteIntegrationsShareholders`	Não	JSON no lote — automático + `depth` > 0. Por linha: colunas `relationship_*` no CSV ou campo no bulk JSON.
`childEnrichmentPolicy`	Não	`all_active` (padrão), `by_root_type` ou `basic_only` — ver Enrichments nos filhos e monitoramento.
`monitoringApplyToRelationships`	Não	`true` / `false` — se `false`, `monitoring` só nas entidades principais. Padrão `true` com `depth` > 0 se omitido.
`depth`	Não	0–5 — só automático
`monitoring`	Não	JSON — ambos modos

Enrichments nos filhos e monitoramento

Com entityImportMode=automatic e depth > 0 são criados acionistas (raiz empresa) ou entidades relacionadas (raiz pessoa):

`childEnrichmentPolicy`	Entidade principal	Empresa → acionistas	Pessoa → relacionadas
`all_active` (padrão)	Conforme config	Todos os enrichments ativos do tipo do filho	Igual
`by_root_type`	Conforme config	Todos os ativos exceto `global_gueno_sanctions_enrichment`	Só dados básicos do snapshot do provedor da raiz
`basic_only`	Conforme config	Só dados básicos	Só dados básicos

monitoringApplyToRelationships: com false, o JSON monitoring vale só para a entidade principal. Recomendado false com by_root_type.

-F 'entityImportMode=automatic' \
-F 'depth=1' \
-F 'childEnrichmentPolicy=by_root_type' \
-F 'monitoringApplyToRelationships=false' \
-F 'monitoring={"main":{"global_gueno_sanctions_enrichment":{"watchlist":true}}}'

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

	Manual	Automático
Dados básicos Nosis/CPF	Não	Sim
`suggested_name`	Obrigatório	Recomendado
País (ISO2)	Obrigatório — `country` do lote e/ou `country_code` por linha (linha prevalece)	Igual (automático: só AR, BR, CL)
Enrichments	Opcionais	Padrão todos ativos
`depth`	Não	Sim (0–5)
Países	Qualquer ISO2 válido	AR, BR, CL

Limites

	Valor
Arquivos por request	1 CSV (campo `file`)
Máx. linhas por import	Conforme plano (overview — Limites por plano): Freemium 4.000 → Enterprise 100.000
Teto servidor (opcional)	`BULK_AUTOMATIC_ENTITY_MAX_ITEMS`
Acima do limite	`400` `TOO_MANY_ITEMS`

Ver Importações em lote.

​Endpoint

​Visão geral

​Autenticação

​Modos (entityImportMode)

​Padrão enviando só o CSV

​Manual com enrichments escolhidos

​Modo automático (explícito)

​CSV plataforma

​País (ISO2) — sempre obrigatório

​Referência de colunas (CSV plataforma)

​Enrichments em relacionadas por linha (CSV plataforma)

​Campos do formulário

​Enrichments nos filhos e monitoramento

​Manual vs automático

​Limites

Endpoint

Visão geral

Autenticação

Modos (`entityImportMode`)

Padrão enviando só o CSV

Manual com enrichments escolhidos

Modo automático (explícito)

CSV plataforma

País (ISO2) — sempre obrigatório

Referência de colunas (CSV plataforma)

Enrichments em relacionadas por linha (CSV plataforma)

Campos do formulário

Enrichments nos filhos e monitoramento

Manual vs automático

Limites