Criar Automaticamente

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 integrações (verificações e 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:

Authorization: Bearer YOUR_API_KEY

Corpo da Requisição

taxId

string

required

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)

country

string

required

Código de país ISO 3166-1 alpha-2 (ex: “BR”, “MX”, “AR”, “CL”)Tipo: string (comprimento: 2)

type

string

required

Tipo de entidade a criar:

company - Entidade empresarial
person - Pessoa física

Tipo: enum - 'company' | 'person'

nationality

string | null

Opcional. ISO 3166-1 alpha-2 ou rótulo mapeável; gravado na linha da entidade principal (mesma validação que Criar entidade).

monitoring

object

Opcional: flags de watchlist para enriquecimentos neste fluxo.

main — mapa código da integração → boolean para o lote da entidade principal.
relationships — mesma forma para sócios/relacionadas quando depth > 0 e recebem enriquecimentos.

Exige monitoramento ativado no Marketplace para essa integração; caso contrário, apenas a consulta normal é executada.

externalId

string

Seu identificador único para esta entidade no seu sistema (opcional, será gerado automaticamente se não fornecido)Tipo: string (opcional)

depth

number

default:"0"

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)

isClient

boolean

default:"false"

Marcar esta entidade como cliente para fins de rastreamentoTipo: boolean (padrão: false)

riskMatrixId

string

UUID da matriz de risco para executar regras automaticamenteTipo: string | null (opcional)

skipRulesExecution

boolean

default:"false"

Pular execução automática de regras após criação da entidadeTipo: boolean (opcional, padrão: false)

status

string

default:"under_review"

Status inicial para a entidade. Opções:

active
inactive
blocked
under_review (padrão)
suspended
expired
deleted
rejected

autoExecuteIntegrations

object

Configurar execução automática de integrações para a entidade principal. Veja Referência de Códigos de Provedores para códigos disponíveis.Tipo: object (opcional)Propriedades:

executeAllActiveEnrichments (boolean, opcional, padrão: false) - Executar todas as integrações de enriquecimento ativas
executeAllActiveChecks (boolean, opcional, padrão: false) - Executar todas as integrações de verificação ativas
enrichments (array, opcional, padrão: []) - Array de códigos específicos de provedores de enriquecimento para executar
checks (array, opcional, padrão: []) - Array de códigos específicos de provedores de verificação para executar

{
  executeAllActiveEnrichments?: boolean; // padrão: false
  executeAllActiveChecks?: boolean; // padrão: false
  enrichments?: ValidProviderCodesEnum[]; // padrão: []
  checks?: ValidProviderCodesEnum[]; // padrão: []
}

Exemplo:

{
  "executeAllActiveEnrichments": false,
  "enrichments": ["br_cpfcnpj_complete_company_enrichment", "br_bdc_shareholders_enrichment"],
  "checks": ["pep_check", "sanctions_check"]
}

autoExecuteIntegrationsShareholders

object

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 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
executeAllActiveChecks (boolean, opcional, padrão: false) - Executar todas as integrações de verificação 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
checks (object, opcional) - Códigos específicos de provedores de verificação por tipo de entidade:
- company (array, opcional, padrão: []) - Verificações para sócios empresas
- person (array, opcional, padrão: []) - Verificações para sócios pessoas

{
  executeAllActiveEnrichments?: boolean; // padrão: false
  executeAllActiveChecks?: boolean; // padrão: false
  enrichments?: {
    company?: ValidProviderCodesEnum[]; // padrão: []
    person?: ValidProviderCodesEnum[]; // padrão: []
  };
  checks?: {
    company?: ValidProviderCodesEnum[]; // padrão: []
    person?: ValidProviderCodesEnum[]; // padrão: []
  };
}

Exemplo:

{
  "executeAllActiveEnrichments": false,
  "executeAllActiveChecks": false,
  "enrichments": {
    "company": ["br_cpfcnpj_complete_company_enrichment"],
    "person": ["br_bdc_basic_data_enrichment"]
  },
  "checks": {
    "company": ["sanctions_check"],
    "person": ["pep_check", "sanctions_check"]
  }
}

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.

customData

object

Opcional - Sobrescritas de campos apenas para a entidade principal (não para sócios ou entidades relacionadas criadas com depth > 0).Se customData.name for enviado como string não vazia, esse valor é gravado como name da entidade e não é substituído pelo nome retornado pelo enrichment de dados básicos nem pela sincronização automática de nome após enrichments adicionais. Se você omitir customData ou o campo name, o comportamento permanece o de sempre: o nome vem do provedor/registro.Tipo: object (opcional)Propriedades:

name (string, opcional) - Nome de exibição da entidade principal. Se enviado, deve ser uma string não vazia (validação da API).

Exemplo:

{
  "name": "Acme Corp (nome fantasia)"
}

attributes

object

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:

{
  "businessSegments": ["retail", "fintech"],
  "source": "onboarding_web",
  "tags": ["vip", "high_volume"]
}

Parâmetros de Query

refresh

boolean

default:"false"

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:

POST http://api.gu1.ai/entities/automatic?refresh=true

Nota de Custo: Pode incorrer em cobranças adicionais de provedores de dados terceirizados.

refreshShareholders

boolean

default:"false"

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:

POST http://api.gu1.ai/entities/automatic?refreshShareholders=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 refreshShareholders=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.

success

boolean

Indica se a entidade foi criada com sucesso

data

object

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

rulesResult

object

Resultado da execução de regras (apenas presente quando as regras foram executadas, ex. quando skipRulesExecution é false e riskMatrixId foi fornecido), 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.

rulesExecutionSummary

object

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.

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.

{
  "taxId": "12.345.678/0001-90",
  "type": "company",
  "userId": "user_id"
}

`entity:creation-completed`

Emitido quando a entidade e todos os relacionamentos foram criados.

{
  "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.

{
  "success": false,
  "error": "Mensagem de erro",
  "taxId": "12.345.678/0001-90"
}

Exemplos

Criar Empresa com Sócios (Profundidade 1)

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,
      "executeAllActiveChecks": true
    }
  }'

Criar Pessoa (KYC) com Integrações Específicas

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"]
    }
  }'

Criar Empresa Argentina (Sem Suporte a Sócios)

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

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"]
    },
    "autoExecuteIntegrationsShareholders": {
      "enrichments": {
        "company": ["br_cpfcnpj_complete_company_enrichment"],
        "person": ["br_bdc_basic_data_enrichment"]
      }
    }
  }'

Exemplo de Resposta

Criação Bem-Sucedida de Empresa com Sócios

{
  "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

{
  "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

{
  "success": false,
  "error": "Formato de CNPJ inválido para o Brasil"
}

404 Not Found - Entidade Não Encontrada no Registro

{
  "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

{
  "success": false,
  "error": "Entidade com este ID fiscal já existe",
  "details": {
    "existingEntityId": "uuid",
    "taxId": "12.345.678/0001-90"
  }
}

500 Internal Server Error

{
  "success": false,
  "error": "Falha ao criar entidade automaticamente",
  "details": {
    "message": "Timeout da API externa"
  }
}

Melhores Práticas

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.
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).
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.
Tratamento de erros: Sempre verifique o campo success e o objeto errors na resposta. Algumas entidades podem ser criadas com sucesso enquanto outras falham.
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 - Criar entidades com seus próprios dados
Obter Entidade - Recuperar detalhes da entidade
Listar Entidades - Consultar suas entidades

Getting Started

Use Cases

Webhooks

Workflows

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Visão Geral

​Endpoint

​Autenticação

​Corpo da Requisição

​Códigos de Enrichment Obrigatórios por País

​Brasil (BR)

​Entidade Principal

​Sócios / Entidades Relacionadas (apenas quando depth > 0)

​Argentina (AR)

​Entidade Principal

​Sócios / Entidades Relacionadas

​Parâmetros de Query

​Resposta

​Eventos WebSocket

​entity:creation-started

​entity:creation-completed

​entity:creation-failed

​Exemplos

​Criar Empresa com Sócios (Profundidade 1)

​Criar Pessoa (KYC) com Integrações Específicas

​Criar Empresa Argentina (Sem Suporte a Sócios)

​Criar Empresa Brasileira com Sócios e Integrações Seletivas

​Exemplo de Resposta

​Criação Bem-Sucedida de Empresa com Sócios

​Criação Bem-Sucedida de Pessoa

​Respostas de Erro

​400 Bad Request - ID Fiscal Inválido

​404 Not Found - Entidade Não Encontrada no Registro

​409 Conflict - Entidade Já Existe

​500 Internal Server Error

​Melhores Práticas

​Endpoints Relacionados

Visão Geral

Endpoint

Autenticação

Corpo da Requisição

Códigos de Enrichment Obrigatórios por País

Brasil (BR)

Entidade Principal

Sócios / Entidades Relacionadas (apenas quando `depth > 0`)

Argentina (AR)

Entidade Principal

Sócios / Entidades Relacionadas

Parâmetros de Query

Resposta

Eventos WebSocket

`entity:creation-started`

`entity:creation-completed`

`entity:creation-failed`

Exemplos

Criar Empresa com Sócios (Profundidade 1)

Criar Pessoa (KYC) com Integrações Específicas

Criar Empresa Argentina (Sem Suporte a Sócios)

Criar Empresa Brasileira com Sócios e Integrações Seletivas

Exemplo de Resposta

Criação Bem-Sucedida de Empresa com Sócios

Criação Bem-Sucedida de Pessoa

Respostas de Erro

400 Bad Request - ID Fiscal Inválido

404 Not Found - Entidade Não Encontrada no Registro

409 Conflict - Entidade Já Existe

500 Internal Server Error

Melhores Práticas

Endpoints Relacionados