> ## 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.
# Criar uma entidade automaticamente com enriquecimento
> Cria automaticamente com dados enriquecidos de registros oficiais — no modelo universal de entidades gu1 para KYC, KYB e análise de risco.
## Visão Geral
O endpoint de criação automática de entidades permite criar entidades fornecendo informações mínimas (ID fiscal e país). O sistema automaticamente:
* Busca dados de empresa/pessoa de registros oficiais
* Enriquece a entidade com informações adicionais
* Cria entidades relacionadas (sócios, diretores) baseado na profundidade especificada
* Executa enriquecimentos automaticamente
Isso é ideal para processos KYB (Know Your Business) e KYC (Know Your Customer) onde você deseja integrar entidades com informações completas automaticamente.
## Endpoint
```
POST http://api.gu1.ai/entities/automatic
```
## Autenticação
Requer uma chave API válida no cabeçalho Authorization:
```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```
## Corpo da Requisição
Número de identificação fiscal da entidade (ex: CNPJ para Brasil, RFC para México, CUIT para Argentina)
**Tipo**: `string` (comprimento mínimo: 1)
Código de país ISO 3166-1 alpha-2 (ex: "BR", "MX", "AR", "CL")
**Tipo**: `string` (comprimento: 2)
Tipo de entidade a criar:
* `company` - Entidade empresarial
* `person` - Pessoa física
**Tipo**: `enum` - `'company' | 'person'`
Opcional. ISO 3166-1 alpha-2 ou rótulo mapeável; gravado na linha da **entidade principal** (mesma validação que [Criar entidade](/pt/api-reference/entities/create)).
Opcional. Mesma semântica de [Criar entidade](/pt/api-reference/entities/create#exemplo-monitoramento-de-sancoes-gu1-na-criacao), com dois mapas:
* **`main`**: watchlist da **entidade raiz** quando enrichments rodam via `autoExecuteIntegrations`.
* **`relationships`**: watchlist de **sócios/relacionadas** com `depth` > 0 via `autoExecuteIntegrationsShareholders` (por `company` / `person`).
**Hoje só** `global_gueno_sanctions_enrichment`. Valor recomendado: `{ "watchlist": true }` ou `{ "watchlist": true, "riskMatrixId": "" | null }` (`boolean` legacy também aceito).
Seu identificador único para esta entidade no seu sistema. **Opcional.**
Se omitido, `externalId` é definido com o **tax ID normalizado** a partir do **`taxId` obrigatório**: apenas letras e dígitos, maiúsculas (sem pontos, traços ou espaços). Exemplo: `30-12345678-9` → `30123456789`.
A coluna **`taxId`** continua salva no [formato de exibição do país](/pt/api-reference/entities/tax-id-formats). Mesmas regras de [Criar uma entidade (pessoa ou empresa)](/pt/api-reference/entities/create) quando há `taxId`.
**Tipo**: `string` (opcional)
Quantos níveis de sócios/relacionamentos criar automaticamente:
* `0` - Criar apenas a entidade principal (sem relacionamentos)
* `1` - Criar sócios/diretores diretos
* `2` - Criar sócios e seus sócios
* Máximo: `5`
**Tipo**: `number` (mín: 0, máx: 5, padrão: 0)
Marcar esta entidade como cliente para fins de rastreamento
**Tipo**: `boolean` (padrão: false)
Um ou mais UUIDs de matrizes de risco (legacy: um único UUID). Após a criação, regras ativas dessas matrizes são executadas (salvo `skipRulesExecution: true`).
**Tipo**: `string | string[] | null` (opcional)
Preferido para **várias** matrizes: lista ordenada de UUIDs. Tem precedência sobre `riskMatrixId` quando informado e não vazio.
**Tipo**: `string[]` (opcional)
Pular execução automática de regras após criação da entidade
**Tipo**: `boolean` (opcional, padrão: false)
Status inicial para a entidade. Opções:
* `active`
* `inactive`
* `blocked`
* `under_review` (padrão)
* `suspended`
* `expired`
* `deleted`
* `rejected`
**Tipo**: `enum` - `'active' | 'inactive' | 'blocked' | 'under_review' | 'suspended' | 'expired' | 'deleted' | 'rejected'` (padrão: 'under\_review')
Horário operacional opcional da **entidade principal** (`timezone` + `weekly`). Persistido na criação automática como na criação manual de entidades. Não se aplica a acionistas/relacionamentos criados por `depth`.
Configurar execução automática de integrações para a entidade principal. Veja [Referência de Códigos de Provedores](/pt/api-reference/integrations/provider-codes) para códigos disponíveis.
**Tipo**: `object` (opcional)
**Propriedades:**
* `executeAllActiveEnrichments` (boolean, opcional, padrão: `false`) - Executar todas as integrações de enriquecimento ativas
* `enrichments` (array, opcional, padrão: `[]`) - Array de códigos específicos de provedores de enriquecimento para executar
* `enrichmentGroupRefs` (array de strings, opcional) — Slugs de **grupos de enriquecimento** do Marketplace (somente enriquecimentos). Com `executeAllActiveEnrichments: false`, os grupos são resolvidos e mesclados com `enrichments` explícitos. Com `executeAllActiveEnrichments: true`, os refs de grupo são ignorados; `enrichments` explícitos ainda podem acrescentar códigos após o conjunto ativo.
* `excludeEnrichments` (array, opcional, padrão: `[]`) — Códigos de provedor omitidos do conjunto final resolvido
```typescript theme={null}
{
executeAllActiveEnrichments?: boolean; // padrão: false
enrichments?: ValidProviderCodesEnum[]; // padrão: []
enrichmentGroupRefs?: string[];
excludeEnrichments?: ValidProviderCodesEnum[]; // padrão: []
}
```
**Exemplo:**
```json theme={null}
{
"executeAllActiveEnrichments": true,
"excludeEnrichments": ["br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["my_marketplace_group_slug"]
}
```
Configurar execução automática de integrações para sócios e entidades relacionadas criadas durante a travessia da hierarquia. Isso permite especificar diferentes integrações para empresas vs pessoas. Veja [Referência de Códigos de Provedores](/pt/api-reference/integrations/provider-codes) para códigos disponíveis.
**Tipo**: `object` (opcional)
**Propriedades:**
* `executeAllActiveEnrichments` (boolean, opcional, padrão: `false`) - Executar todas as integrações de enriquecimento ativas para todos os sócios
* `enrichments` (object, opcional) - Códigos específicos de provedores de enriquecimento por tipo de entidade:
* `company` (array, opcional, padrão: `[]`) - Enriquecimentos para sócios empresas
* `person` (array, opcional, padrão: `[]`) - Enriquecimentos para sócios pessoas
* `enrichmentGroupRefs` (array de strings, opcional) — Mesmos slugs do objeto principal; com `executeAllActiveEnrichments: false` aplicam-se **a `company` e a `person`**. Com `executeAllActiveEnrichments: true` neste objeto, os refs de grupo são ignorados; `enrichments` explícitos por tipo ainda podem acrescentar códigos após o ativo de cada lado.
* `excludeEnrichments` (array, opcional, padrão: `[]`) — Códigos omitidos nas listas `company` e `person` após o merge
```typescript theme={null}
{
executeAllActiveEnrichments?: boolean; // padrão: false
enrichments?: {
company?: ValidProviderCodesEnum[]; // padrão: []
person?: ValidProviderCodesEnum[]; // padrão: []
};
enrichmentGroupRefs?: string[];
excludeEnrichments?: ValidProviderCodesEnum[]; // padrão: []
}
```
**Exemplo:**
```json theme={null}
{
"executeAllActiveEnrichments": true,
"excludeEnrichments": ["br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["shareholder_pipeline_group_slug"]
}
```
## Códigos de Enrichment Obrigatórios por País
Ao usar códigos de enrichment específicos (não `executeAllActiveEnrichments: true`), certos enrichments são **obrigatórios** para que a criação automática funcione. Sem eles, o sistema não consegue buscar os dados básicos da entidade nos registros oficiais e a requisição falhará.
### Brasil (BR)
#### Entidade Principal
| Tipo de Entidade | Código de Enrichment Obrigatório | Descrição |
| ---------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **Company** | `br_cpfcnpj_complete_company_enrichment` | Busca dados da empresa do CNPJ/Receita Federal (razão social, nome fantasia, endereço, setor, etc.) |
| **Person** | `br_bdc_basic_data_enrichment` | Busca dados da pessoa via BDC/CPF (nome completo, data de nascimento, endereço, etc.) |
#### Sócios / Entidades Relacionadas (apenas quando `depth > 0`)
| Tipo da Entidade Principal | Código(s) de Enrichment Obrigatório(s) | Descrição |
| -------------------------- | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| **Company** | `br_bdc_shareholders_enrichment` | Busca o QSA (Quadro Societário e de Administradores) para descobrir sócios e diretores da empresa |
| **Person** | `br_bdc_related_companies_enrichment` **E** `br_bdc_related_persons_enrichment` | Ambos são obrigatórios. Busca empresas e pessoas relacionadas ao indivíduo |
Os enrichments de sócios devem ser incluídos no array `autoExecuteIntegrations.enrichments` da **entidade principal** (não em `autoExecuteIntegrationsShareholders`), pois o sistema precisa executá-los na entidade principal para descobrir quem são os sócios. O campo `autoExecuteIntegrationsShareholders` controla quais enrichments executar **em cada sócio** após serem criados.
### Argentina (AR)
#### Entidade Principal
| Tipo de Entidade | Código de Enrichment Obrigatório | Descrição |
| ---------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Company** | `ar_nosis_extended_verification_enrichment` | Busca dados da empresa do Nosis (razão social, situação CUIT, endereço, atividades, etc.) |
| **Person** | `ar_nosis_extended_verification_enrichment` | Mesmo provedor para ambos os tipos de entidade |
#### Sócios / Entidades Relacionadas
Argentina **não suporta** criação automática de sócios/relacionamentos ainda. O parâmetro `depth` deve ser `0`. Se `depth > 0` for fornecido, a requisição falhará com um erro.
**Opcional** — Dados enviados pelo cliente para a **entidade principal** que **não** devem ser substituídos pelos enrichments do registro. Não se aplica a sócios nem entidades relacionadas (`depth > 0`).
Após os enrichments, a API **reaplica** `customData` para preservar os valores (ex.: sincronização automática de nome).
**Persistência:**
| Campo em `customData` | Coluna raiz (`entities`) | `entityData` | |
| --------------------- | ------------------------ | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `name` | `name` | — | |
| `email` | `email` | `person.email` / `company.email` | |
| `phone` | `phone` | `person.phone` / `company.phone` | |
| `birthDate` | — | Apenas `person.dateOfBirth` (pessoa) | |
| `address` | — | `person.address` ou `company.address` | |
| `gender` | — | `person.gender` | Opcional. Enum fechado: `M`, `F`, `male`, `female`, `other`, `unknown`. Use **`other`** para identidade não binária. Valores como `X` ou `non_binary` são rejeitados. Em **AR**, apenas `M`/`F` (ou `male`/`female`) se aplicam à derivação de CUIL e RENAPER. Ver [Criar entidade — Person](/pt/api-reference/entities/create#entidade-person). |
**Propriedades documentadas:** `name`, `email`, `phone`, `birthDate` (pessoa), `address` (string ou objeto com `fullAddress`, `street`, `city`, …), `gender` (enum opcional — `other` para não binário).
**Chaves adicionais (somente API):** qualquer outra chave em `customData` é aceita e gravada em `entityData.person` ou `entityData.company` (mesma proteção contra enrichments). Ex.: `firstName`, `occupation`, `tradeName`. O dashboard envia só os campos do formulário; integrações via API podem estender o objeto.
**Exemplo (pessoa):**
```json theme={null}
{
"taxId": "12345678901",
"country": "BR",
"type": "person",
"customData": {
"name": "MARIA SILVA",
"email": "cliente@empresa.com",
"phone": "+5511988888888",
"birthDate": "1990-05-15",
"address": "Rua Exemplo 100, São Paulo"
}
}
```
**Exemplo (empresa):**
```json theme={null}
{
"taxId": "12345678000199",
"country": "BR",
"type": "company",
"customData": {
"name": "Acme Brasil Ltda (nome fantasia)",
"email": "contato@acme.com",
"phone": "+5511400000000",
"address": {
"fullAddress": "Av. Paulista 1000, São Paulo",
"city": "São Paulo"
}
}
}
```
**Opcional** - Atributos personalizados como pares chave-valor para a entidade criada.
Aplicam-se apenas à entidade principal (pessoa ou empresa criada), não a acionistas/relacionamentos. Útil para segmentos de negócio, etiquetas, IDs internos ou qualquer metadado que queira associar no momento da criação.
**Estrutura:** objeto com chaves string e valores de qualquer tipo (string, number, boolean, array, etc.).
**Exemplo:**
```json theme={null}
{
"businessSegments": ["retail", "fintech"],
"source": "onboarding_web",
"tags": ["vip", "high_volume"]
}
```
## Parâmetros de Query
Força o re-enriquecimento da entidade principal mesmo que já exista no sistema.
**Tipo**: `boolean` (query string: `"true"` ou `"false"`)
**Comportamento**:
* Quando `true`: Força busca de dados atualizados de registros oficiais e provedores de enriquecimento
* Quando `false` ou omitido: Utiliza dados de enriquecimento em cache se disponíveis
* Sobrescreve a configuração da organização `enrichmentsConfig.reEnrichExistingEntities`
**Casos de Uso**:
* Revisões periódicas de compliance exigindo informações atualizadas
* Re-validar dados da entidade após mudanças regulatórias
* Atualizar estrutura empresarial após mudanças corporativas conhecidas
* Atualização manual acionada por oficiais de compliance
**Exemplo**:
```bash theme={null}
POST http://api.gu1.ai/entities/automatic?refresh=true
```
**Nota de Custo**: Pode incorrer em cobranças adicionais de provedores de dados terceirizados.
Força o re-enriquecimento de TODOS os sócios e entidades relacionadas na estrutura corporativa.
**Tipo**: `boolean` (query string: `"true"` ou `"false"`)
**Comportamento**:
* Quando `true`: Força busca de dados atualizados para a entidade principal E todos os sócios em todos os níveis (até `depth`)
* Quando `false` ou omitido: Atualiza apenas a entidade principal se `refresh=true`, sócios usam dados em cache
* Funciona em combinação com o parâmetro `depth` para determinar quão profundo atualizar
* Sobrescreve configuração da organização para todas as entidades relacionadas
**Casos de Uso**:
* Auditoria completa de estrutura corporativa
* Due diligence exigindo cadeia de propriedade atualizada
* Revisões anuais de compliance de toda a árvore corporativa
* Investigação de estruturas de propriedade complexas
**Exemplo - Atualizar estrutura inteira**:
```bash theme={null}
POST http://api.gu1.ai/entities/automatic?reEnrichExistingChildEntities=true&depth=3
```
Isso atualizará a empresa principal E todos os sócios até 3 níveis de profundidade.
**Nota de Performance**:
* Definir como `true` com valores altos de `depth` (4-5) pode levar vários minutos
* Pode resultar em custos significativos se a estrutura corporativa for complexa
* Considere usar seletivamente apenas para entidades de alto risco
**Melhor Prática**:
* Use `refresh=true` sozinho para atualizações de entidade única
* Use `reEnrichExistingChildEntities=true` apenas quando precisar de validação completa da cadeia de propriedade
## Resposta
O endpoint executa sincronamente e retorna o resultado completo incluindo a entidade principal e todas as entidades relacionadas criadas.
Indica se a entidade foi criada com sucesso
Informações completas sobre a criação:
* `entity` (object) - A entidade principal criada com todos os seus dados
* `shareholders` (array) - Array de entidades de sócios criadas (para empresas)
* `relationships` (array) - Array de entidades relacionadas criadas (para pessoas)
* `summary` (object):
* `entitiesCreated` (number) - Número total de entidades criadas
* `relationshipsCreated` (number) - Número total de relacionamentos criados
* `errorsCount` (number) - Número de erros encontrados
* `errors` (object, opcional) - Detalhes de quaisquer erros que ocorreram:
* `creationFailed` (array) - Criações de entidades que falharam
* `enrichmentFailed` (array) - Execuções de enriquecimento que falharam
Resultado da execução de regras (apenas presente quando as regras foram executadas, ex. quando **skipRulesExecution** é `false` e há matriz configurada via `riskMatrixId` ou `riskMatrixIds`), ou null. Quando presente, inclui:
* **success** (boolean) - Se as regras foram executadas com sucesso
* **rulesTriggered** (number) - Número de regras disparadas
* **alerts** (array) - Alertas gerados pelas regras
* **riskScore** (number) - Pontuação de risco final
* **decision** (string) - Decisão final (APPROVE, REJECT, HOLD, REVIEW\_REQUIRED)
* **rulesExecutionSummary** (object) - Presente quando as regras foram executadas. Ver abaixo a estrutura.
**Na raiz da resposta** (igual à API de transações). Mesmo valor que `rulesResult.rulesExecutionSummary`. **Apenas presente quando as regras foram executadas (ex. skipRulesExecution é false e a matriz de risco foi executada).** Resumo de quais regras deram match (hit) vs não (no hit), ações executadas e pontuação total. Omitido quando as regras não foram executadas. Estrutura completa e exemplo: [Resumo de Execução de Regras](/pt/api-reference/rules-execution-summary).
* **rulesHit** (array) - Regras cujas condições foram atendidas. Cada item: **name**, **description**, **score**, **priority**, **category**, **status** (ex. `active`, `shadow`), **conditions** (array de `{ field, value, operator? }`), **actions** (alerts, suggestion, status, assignedUser).
* **rulesNoHit** (array) - Regras avaliadas mas cujas condições não foram atendidas. Mesma estrutura que rulesHit (inclui ações configuradas, não executadas).
* **actionsExecuted** (object) - Ações executadas agregadas de todas as regras que deram hit: **alerts** (array de `{ name?, type?, severity?, description? }`), **suggestion** (`BLOCK` | `SUSPEND` | `FLAG`, maior peso), **status** (status aplicado à entidade, se houver), **assignedUser** (`{ userId }`, se houver), **customKeys** (array de strings, opcional) — chaves de ações personalizadas das regras que deram match; para integrações/workflows.
* **totalScore** (number) - Soma do **score** de todas as regras que deram hit e não estão em status `shadow`.
## Eventos WebSocket
O sistema emite eventos em tempo real durante o processo de criação:
### `entity:creation-started`
Emitido quando o processo de criação começa.
```json theme={null}
{
"taxId": "12.345.678/0001-90",
"type": "company",
"userId": "user_id"
}
```
### `entity:creation-completed`
Emitido quando a entidade e todos os relacionamentos foram criados.
```json theme={null}
{
"success": true,
"mainEntity": {
"id": "uuid",
"name": "Nome da Empresa",
"taxId": "12.345.678/0001-90"
},
"stats": {
"totalEntitiesCreated": 15,
"companiesCreated": 8,
"peopleCreated": 7,
"relationshipsCreated": 14
}
}
```
### `entity:creation-failed`
Emitido se o processo de criação falhar.
```json theme={null}
{
"success": false,
"error": "Mensagem de erro",
"taxId": "12.345.678/0001-90"
}
```
## Monitoramento de sanções Gu1 na criação automática
No `POST /entities/automatic`:
| Campo | Aplica-se a |
| -------------------------- | ------------------------------------------------------------------------------ |
| `monitoring.main` | Entidade raiz (`taxId` do body) via `autoExecuteIntegrations`. |
| `monitoring.relationships` | Sócios/relacionadas com `depth` > 0 via `autoExecuteIntegrationsShareholders`. |
Hoje só **`global_gueno_sanctions_enrichment`** usa monitoramento no body. O código precisa estar no array de enrichments do nível **e** no mapa com watchlist ativo.
```json theme={null}
{
"taxId": "30-71000001-2",
"country": "AR",
"type": "company",
"depth": 1,
"monitoring": {
"main": {
"global_gueno_sanctions_enrichment": {
"watchlist": true
}
},
"relationships": {
"global_gueno_sanctions_enrichment": {
"watchlist": true,
"riskMatrixId": null
}
}
},
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": false,
"enrichments": [
"ar_afip_registration_enrichment",
"global_gueno_sanctions_enrichment"
]
},
"autoExecuteIntegrationsShareholders": {
"executeAllActiveEnrichments": false,
"enrichments": {
"company": ["global_gueno_sanctions_enrichment"],
"person": ["global_gueno_sanctions_enrichment"]
}
}
}
```
Enrichments de registro (ex.: `ar_afip_registration_enrichment`) ignoram `monitoring`.
Este payload ilustra apenas **`monitoring`** e os códigos Gu1. Um pedido real ainda precisa dos **enriquecimentos obrigatórios de registro** para o `country` e `type` escolhidos (veja a secção de códigos obrigatórios por país acima); caso contrário, a criação automática falha.
## Exemplos
### Criar Empresa com Sócios (Profundidade 1)
```bash cURL theme={null}
curl -X POST http://api.gu1.ai/entities/automatic \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"taxId": "12.345.678/0001-90",
"country": "BR",
"type": "company",
"depth": 1,
"isClient": true,
"autoExecuteIntegrations": {
"executeAllActiveEnrichments": true
}
}'
```
```javascript JavaScript theme={null}
const response = await fetch('http://api.gu1.ai/entities/automatic', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
taxId: '12.345.678/0001-90',
country: 'BR',
type: 'company',
depth: 1,
isClient: true,
autoExecuteIntegrations: {
executeAllActiveEnrichments: true,
}
})
});
const data = await response.json();
console.log(data);
// Escutar eventos WebSocket
socket.on('entity:creation-completed', (result) => {
console.log('Entidade criada:', result.mainEntity);
console.log('Total de entidades criadas:', result.stats.totalEntitiesCreated);
});
```
```python Python theme={null}
import requests
response = requests.post(
'http://api.gu1.ai/entities/automatic',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'taxId': '12.345.678/0001-90',
'country': 'BR',
'type': 'company',
'depth': 1,
'isClient': True,
'autoExecuteIntegrations': {
'executeAllActiveEnrichments': True,
}
}
)
data = response.json()
print(data)
```
### Criar Pessoa (KYC) com Integrações Específicas
```bash cURL theme={null}
curl -X POST http://api.gu1.ai/entities/automatic \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"taxId": "123.456.789-00",
"country": "BR",
"type": "person",
"externalId": "customer_12345",
"depth": 0,
"autoExecuteIntegrations": {
"enrichments": ["br_bdc_basic_data_enrichment"]
}
}'
```
```javascript JavaScript theme={null}
const response = await fetch('http://api.gu1.ai/entities/automatic', {
method: 'POST',
headers: {
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
taxId: '123.456.789-00',
country: 'BR',
type: 'person',
externalId: 'customer_12345',
depth: 0,
autoExecuteIntegrations: {
enrichments: ['br_bdc_basic_data_enrichment']
}
})
});
const data = await response.json();
```
```python Python theme={null}
import requests
response = requests.post(
'http://api.gu1.ai/entities/automatic',
headers={
'Authorization': 'Bearer YOUR_API_KEY',
'Content-Type': 'application/json'
},
json={
'taxId': '123.456.789-00',
'country': 'BR',
'type': 'person',
'externalId': 'customer_12345',
'depth': 0,
'autoExecuteIntegrations': {
'enrichments': ['br_bdc_basic_data_enrichment']
}
}
)
data = response.json()
```
### Criar Empresa Argentina (Sem Suporte a Sócios)
```bash theme={null}
curl -X POST http://api.gu1.ai/entities/automatic \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"taxId": "30-12345678-9",
"country": "AR",
"type": "company",
"depth": 0,
"isClient": true,
"riskMatrixId": "risk_matrix_uuid",
"autoExecuteIntegrations": {
"enrichments": ["ar_nosis_extended_verification_enrichment"]
}
}'
```
### Criar Empresa Brasileira com Sócios e Integrações Seletivas
```bash theme={null}
curl -X POST http://api.gu1.ai/entities/automatic \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"taxId": "12.345.678/0001-90",
"country": "BR",
"type": "company",
"depth": 2,
"isClient": true,
"riskMatrixId": "risk_matrix_uuid",
"autoExecuteIntegrations": {
"enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["main_entity_group_slug"]
},
"autoExecuteIntegrationsShareholders": {
"enrichments": {
"company": ["br_cpfcnpj_complete_company_enrichment"],
"person": ["br_bdc_basic_data_enrichment"]
},
"enrichmentGroupRefs": ["child_entities_group_slug"]
}
}'
```
## Exemplo de Resposta
### Criação Bem-Sucedida de Empresa com Sócios
```json theme={null}
{
"success": true,
"data": {
"entity": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"organizationId": "org_uuid",
"type": "company",
"name": "Tech Solutions LTDA",
"taxId": "12345678000190",
"countryCode": "BR",
"status": "under_review",
"riskScore": null,
"entityData": {
"company": {
"legalName": "Tech Solutions LTDA",
"tradeName": "Tech Solutions",
"incorporationDate": "2020-01-15",
"industry": "Technology"
}
},
"createdAt": "2024-12-23T10:30:00.000Z",
"updatedAt": "2024-12-23T10:30:00.000Z"
},
"shareholders": [
{
"id": "shareholder_1_uuid",
"type": "person",
"name": "João Silva",
"taxId": "12345678900",
"countryCode": "BR",
"entityData": {
"person": {
"firstName": "João",
"lastName": "Silva"
}
},
"shareholderInfo": {
"percentage": 60.0,
"role": "Sócio Administrador"
}
},
{
"id": "shareholder_2_uuid",
"type": "person",
"name": "Maria Santos",
"taxId": "98765432100",
"countryCode": "BR",
"entityData": {
"person": {
"firstName": "Maria",
"lastName": "Santos"
}
},
"shareholderInfo": {
"percentage": 40.0,
"role": "Sócia"
}
}
],
"summary": {
"entitiesCreated": 3,
"relationshipsCreated": 2,
"errorsCount": 0
}
},
"rulesResult": null
}
```
### Criação Bem-Sucedida de Pessoa
```json theme={null}
{
"success": true,
"data": {
"entity": {
"id": "person_uuid",
"organizationId": "org_uuid",
"type": "person",
"name": "João Silva",
"taxId": "12345678900",
"countryCode": "BR",
"status": "under_review",
"entityData": {
"person": {
"firstName": "João",
"lastName": "Silva",
"dateOfBirth": "1985-05-15"
}
},
"createdAt": "2024-12-23T10:30:00.000Z",
"updatedAt": "2024-12-23T10:30:00.000Z"
},
"relationships": [],
"summary": {
"entitiesCreated": 1,
"relationshipsCreated": 0,
"errorsCount": 0
}
},
"rulesResult": null
}
```
## Respostas de Erro
### 400 Bad Request - ID Fiscal Inválido
```json theme={null}
{
"success": false,
"error": "Formato de CNPJ inválido para o Brasil"
}
```
### 404 Not Found - Entidade Não Encontrada no Registro
```json theme={null}
{
"success": false,
"error": "Entidade não encontrada no registro oficial",
"details": {
"taxId": "12.345.678/0001-90",
"country": "BR",
"registry": "Receita Federal"
}
}
```
### 409 Conflict - Entidade Já Existe
```json theme={null}
{
"success": false,
"error": "Entidade com este ID fiscal já existe",
"details": {
"existingEntityId": "uuid",
"taxId": "12.345.678/0001-90"
}
}
```
### 500 Internal Server Error
```json theme={null}
{
"success": false,
"error": "Falha ao criar entidade automaticamente",
"details": {
"message": "Timeout da API externa"
}
}
```
## Melhores Práticas
1. **Use profundidade com sabedoria**: Valores de profundidade mais altos (3-5) podem criar muitas entidades e levar mais tempo para completar. Comece com profundidade 0-1 para testes.
2. **Monitore eventos WebSocket**: Embora a API retorne sincronamente, eventos WebSocket também são emitidos para atualizações de UI em tempo real (`entity:creation-started`, `entity:creation-completed`, `entity:creation-failed`).
3. **Lide com timeouts**: Para hierarquias complexas com alta profundidade, a requisição pode levar vários minutos. Configure valores de timeout HTTP apropriados no seu cliente.
4. **Tratamento de erros**: Sempre verifique o campo `success` e o objeto `errors` na resposta. Algumas entidades podem ser criadas com sucesso enquanto outras falham.
5. **Limitação de taxa**: Tenha cuidado com limites de taxa ao criar múltiplas entidades em rápida sucessão. O endpoint busca dados de APIs externas que podem ter seus próprios limites de taxa.
## Endpoints Relacionados
* [Criar Entidade Manualmente](/pt/api-reference/entities/create) - Criar entidades com seus próprios dados
* [Obter Entidade](/pt/api-reference/entities/get) - Recuperar detalhes da entidade
* [Listar Entidades](/pt/api-reference/entities/list) - Consultar suas entidades