> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
## 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
```bash theme={null}
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
```bash theme={null}
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:
```bash theme={null}
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)
```bash theme={null}
-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)](#país-iso2--sempre-obrigatório) 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**](/files/bulk-imports/bulk-entities-template-automatic.csv) — com **`entityImportMode=automatic`**. Linhas demo AR/BR/CL, `depth`, enrichments.
* [**bulk-entities-template-manual.csv**](/files/bulk-imports/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](/pt/api-reference/entities/create#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). |
| **`related_tax_id`** | — | `relationships[].relatedTaxId` | Contraparte existente por tax ID. **Exatamente um** de `related_tax_id` / `related_external_id` / `related_entity_id` por linha. |
| **`related_external_id`** | — | `relationships[].relatedExternalId` | Contraparte por `externalId`. |
| **`related_entity_id`** | — | `relationships[].relatedEntityId` | Contraparte por UUID. |
| **`relationship_type`** | — | `relationships[].relationshipType` | Default `shareholder` se houver contraparte. Enum do grafo. |
| **`relationship_role`** | — | `relationships[].role` | Papel em `metadata.roles` (ex. `SOCIO`). |
| **`relationship_as_source`** | — | `relationships[].asSource` | Default `true`: a linha criada é **source** e a contraparte (`related_*`) é **target**. Com `relationship_type=shareholder`, a linha é acionista/sócia dessa contraparte. `false` inverte a direção. |
| **`status`** | — | `status` | Status da entidade. |
| **`attributes.`** | — | **`attributes`** | Dado de negócio aninhado (notação com ponto, como CSV nativo de transações). Ex.: `attributes.segment_tag`. |
| **`entityData.`** | — | **`entityData.{person\|company}`** | Perfil KYC/KYB. Sem `person`/`company` na cabeça → usa o **`type`** da linha. Ex.: `entityData.income`, `entityData.tradeName`. |
| **`entityData.person.`** / **`entityData.company.`** | — | **`entityData.person`** / **`.company`** | Caminhos explícitos. |
| **`metadata.`** | — | **`attributes`** (legacy) | Deprecado; fundido em `attributes`. |
| **Coluna sem prefixo** | — | **`attributes`** | Retrocompat: `segment_tag` → `attributes.segment_tag`. |
**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](/pt/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:
```csv theme={null}
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](#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`**.
```bash theme={null}
-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](/pt/api-reference/bulk-imports/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](/pt/api-reference/bulk-imports/overview).