> ## 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 empresa automaticamente com enriquecimento
> Criar empresa automaticamente com dados enriquecidos de registros — para entidades de empresa na plataforma de risco e compliance gu1.
## Visão Geral
O endpoint de criação automática de empresa permite que você crie empresas fornecendo informações mínimas (tax ID e país). O sistema automaticamente:
* Busca dados da empresa de registros oficiais
* Enriquece a empresa com informações adicionais
* Executa enriquecimentos automaticamente
Isso é ideal para processos KYB (Know Your Business) onde você deseja integrar empresas com informações completas automaticamente.
## Endpoint
```
POST http://api.gu1.ai/entities/automatic
```
## Autenticação
Requer uma chave de 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 empresa (ex: CNPJ para Brasil, RFC para México, CUIT para Argentina)
📋 Ver [Formatos de Tax ID por País](/pt/api-reference/entities/tax-id-formats) para formatos aceitos e regras de validação para cada país.
Código de país ISO 3166-1 alpha-2 (ex: "BR", "MX", "AR", "CL")
Deve ser definido como `company`
Seu identificador único para esta empresa (opcional, será gerado automaticamente se não fornecido)
Marcar esta empresa como cliente/negócio para fins de rastreamento
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`).
Preferido para **várias** matrizes: lista ordenada de UUIDs. Tem precedência sobre `riskMatrixId` quando informado e não vazio.
Pular execução automática de regras após criação da empresa
Status inicial para a empresa
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`.
Profundidade da extração de relacionamento (0-5). Controla quantos níveis de acionistas/relacionamentos buscar e criar automaticamente.
* `0`: Sem relacionamentos (apenas entidade principal)
* `1`: Apenas acionistas diretos
* `2`: Acionistas + seus acionistas
* `3-5`: Níveis adicionais (use com cautela - pode criar muitas entidades)
Configurar execução automática de integrações para a entidade empresa principal. Veja [Referência de Códigos de Provedor](/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 de provedores de enriquecimento específicos 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.
```typescript theme={null}
{
executeAllActiveEnrichments?: boolean; // padrão: false
enrichments?: ValidProviderCodesEnum[]; // padrão: []
enrichmentGroupRefs?: string[];
}
```
**Exemplo:**
```json theme={null}
{
"executeAllActiveEnrichments": false,
"enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
"enrichmentGroupRefs": ["my_marketplace_group_slug"],
}
```
Configurar execução automática de integrações para acionistas/relacionamentos descobertos. Útil ao usar `depth > 0`. Veja [Referência de Códigos de Provedor](/pt/api-reference/integrations/provider-codes) para códigos disponíveis.
**Tipo**: `object` (opcional)
**Propriedades:**
* `executeAllActiveEnrichments` (boolean, opcional, padrão: `false`) - Executar todos os enriquecimentos ativos nos acionistas
* `enrichments` (object, opcional) - Enriquecimentos específicos por tipo de entidade
* `company` (array, padrão: `[]`) - Enriquecimentos para acionistas empresa
* `person` (array, padrão: `[]`) - Enriquecimentos para acionistas pessoa
* `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.
```typescript theme={null}
{
executeAllActiveEnrichments?: boolean;
enrichments?: {
company?: ValidProviderCodesEnum[];
person?: ValidProviderCodesEnum[];
};
enrichmentGroupRefs?: string[];
}
```
**Exemplo:**
```json theme={null}
{
"enrichments": {
"person": [
"br_cpfcnpj_complete_person_enrichment",
"global_complyadvantage_person_search_enrichment"
],
"company": ["br_cpfcnpj_complete_company_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 empresa nos registros oficiais e a requisição falhará.
### Brasil (BR)
| Cenário | Código(s) de Enrichment Obrigatório(s) | Descrição |
| ------------------------ | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Entidade principal** | `br_cpfcnpj_complete_company_enrichment` | Busca dados da empresa do CNPJ/Receita Federal (razão social, nome fantasia, endereço, setor, etc.) |
| **Sócios** (`depth > 0`) | `br_bdc_shareholders_enrichment` | Obrigatório em `autoExecuteIntegrations.enrichments`. Busca o QSA (Quadro Societário e de Administradores) para descobrir sócios e diretores |
O enrichment de sócios deve ser incluído no array `autoExecuteIntegrations.enrichments` da **entidade principal** (não em `autoExecuteIntegrationsShareholders`), pois o sistema precisa executá-lo na empresa principal para descobrir o QSA. O campo `autoExecuteIntegrationsShareholders` controla quais enrichments executar **em cada sócio** após serem criados.
### Argentina (AR)
| Cenário | Código de Enrichment Obrigatório | Descrição |
| ---------------------- | ------------------------------------------- | ----------------------------------------------------------------------------------------- |
| **Entidade principal** | `ar_nosis_extended_verification_enrichment` | Busca dados da empresa do Nosis (razão social, situação CUIT, endereço, atividades, etc.) |
Argentina **não suporta** criação automática de sócios ainda. O parâmetro `depth` deve ser `0`. Se `depth > 0` for fornecido, a requisição falhará com um erro.
**Opcional** — Dados do cliente para a **empresa principal** que não devem ser substituídos pelos enrichments. Referência completa: [Criação automática de entidades](/pt/api-reference/entities/create-automatic).
Campos: `name`, `email`, `phone`, `address` → `entityData.company.address` (`birthDate` não se aplica a empresas).
**Exemplo:**
```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 (a 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"]
}
```
## Resposta
Indica se a empresa foi criada com sucesso
Informações completas sobre a criação:
* `entity` (object) - A empresa criada com todos os dados
* `summary` (object) - Resumo da criação
* `errors` (object, opcional) - Detalhes de quaisquer erros
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**, **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`.
## Exemplos
### Criar Empresa com Todas as Integrações Ativas
```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": "company",
"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: '123.456.789-00',
country: 'BR',
type: 'company',
isClient: true,
autoExecuteIntegrations: {
executeAllActiveEnrichments: true,
}
})
});
const data = await response.json();
console.log('Company created:', data.data.entity);
```
```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': 'company',
'isClient': True,
'autoExecuteIntegrations': {
'executeAllActiveEnrichments': True,
}
}
)
data = response.json()
print('Company created:', data['data']['entity'])
```
### Criar Empresa 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": "company",
"externalId": "business_12345",
"autoExecuteIntegrations": {
"enrichments": ["br_cpfcnpj_complete_company_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: 'company',
externalId: 'business_12345',
autoExecuteIntegrations: {
enrichments: ['br_cpfcnpj_complete_company_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': 'company',
'externalId': 'business_12345',
'autoExecuteIntegrations': {
'enrichments': ['br_cpfcnpj_complete_company_enrichment'],
}
}
)
data = response.json()
```
## Exemplo de Resposta
```json theme={null}
{
"success": true,
"data": {
"entity": {
"id": "company_uuid",
"organizationId": "org_uuid",
"type": "company",
"name": "Tech Solutions LTDA",
"taxId": "12345678900",
"countryCode": "BR",
"status": "under_review",
"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"
},
"summary": {
"entitiesCreated": 1,
"relationshipsCreated": 0,
"errorsCount": 0
}
},
"rulesResult": null
}
```
## Respostas de Erro
### 400 Bad Request - Tax ID Inválido
```json theme={null}
{
"success": false,
"error": "Invalid CPF format for Brazil"
}
```
### 404 Not Found - Empresa Não Encontrada no Registro
```json theme={null}
{
"success": false,
"error": "Entity not found in official registry",
"details": {
"taxId": "123.456.789-00",
"country": "BR",
"registry": "Receita Federal"
}
}
```
### 409 Conflict - Empresa Já Existe
```json theme={null}
{
"success": false,
"error": "Entity with this tax ID already exists",
"details": {
"existingEntityId": "uuid",
"taxId": "123.456.789-00"
}
}
```
## Melhores Práticas
1. **Tratamento de erros**: Sempre verifique o campo `success` na resposta
2. **Limitação de taxa**: Esteja atento aos limites de taxa ao criar múltiplas empresas
3. **Seleção de integração**: Escolha integrações específicas para melhor controle sobre custo e desempenho
## Próximos Passos
* [Obter Empresa](/pt/api-reference/company/get) - Recuperar detalhes da empresa
* [Criar Empresa Manualmente](/pt/api-reference/company/create) - Criar empresas com seus próprios dados
* [Criar Validação KYB](/pt/use-cases/kyc/create-validation) - Iniciar verificação de identidade