Skip to main content
POST
Criar uma entidade automaticamente com enriquecimento

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

Autenticação

Requer uma chave API válida no cabeçalho Authorization:

Corpo da Requisição

string
required
Número de identificação fiscal da entidade (ex: CNPJ para Brasil, RFC para México, CUIT para Argentina).Em uma organização, um taxId ativo (normalizado: apenas letras e dígitos) pode pertencer a apenas uma entidade — seja person ou company. Se o mesmo tipo já existe, a API o reutiliza (alreadyExisted). Se outro tipo já possui esse tax ID, a solicitação falha com 409 e código DUPLICATE_TAX_ID.Tipo: string (comprimento mínimo: 1)
string
required
Código de país ISO 3166-1 alpha-2 (ex: “BR”, “MX”, “AR”, “CL”)Tipo: string (comprimento: 2)
string
required
Tipo de entidade a criar:
  • company - Entidade empresarial
  • person - Pessoa física
Tipo: enum - 'company' | 'person'
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).
object
Opcional. Mesma semântica de Criar entidade, 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": "<uuid>" | null } (boolean legacy também aceito).
string
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-930123456789.A coluna taxId continua salva no formato de exibição do país. Mesmas regras de Criar uma entidade (pessoa ou empresa) quando há taxId.Tipo: string (opcional)
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)
array
Vínculos declarativos a entidades já existentes (relatedEntityId / relatedTaxId / relatedExternalId + relationshipType + role). Independente do depth de enrichment. Máx. 10. Contraparte ausente → RELATED_ENTITY_NOT_FOUND e a entidade não é criada. Mesma semântica que Criar entidade.
boolean
default:"false"
Marcar esta entidade como cliente para fins de rastreamentoTipo: boolean (padrão: false)
string | string[]
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)
string[]
Preferido para várias matrizes: lista ordenada de UUIDs. Tem precedência sobre riskMatrixId quando informado e não vazio.Tipo: string[] (opcional)
boolean
default:"false"
Pular execução automática de regras após criação da entidadeTipo: boolean (opcional, padrão: false)
string
default:"under_review"
Status inicial para a entidade. Opções:
  • active
  • inactive
  • blocked
  • under_review (padrão)
  • pending_verification - Aguardando conclusão de KYC/KYB
  • awaiting_information - Aguardando dados do cliente (p. ex. documentos de onboarding pedidos por e-mail)
  • suspended
  • expired
  • deleted
  • rejected
Tipo: enum - 'active' | 'inactive' | 'blocked' | 'under_review' | 'pending_verification' | 'awaiting_information' | 'suspended' | 'expired' | 'deleted' | 'rejected' | 'not_started' (padrão: ‘under_review’)
object | null
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.
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
  • 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
Exemplo:
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
  • 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
Exemplo:

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

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

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

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.
object
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: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):
Exemplo (empresa):
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:

Parâmetros de Query

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:
Nota de Custo: Pode incorrer em cobranças adicionais de provedores de dados terceirizados.
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:
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.
boolean
Indica se a entidade foi criada com sucesso
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
object
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.
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.

entity:creation-completed

Emitido quando a entidade e todos os relacionamentos foram criados.

entity:creation-failed

Emitido se o processo de criação falhar.

Monitoramento de sanções Gu1 na criação automática

No POST /entities/automatic: 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.
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)

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

Retornado quando o taxId normalizado já é usado por uma entidade ativa de um tipo diferente na mesma organização (pessoa vs empresa). Matches do mesmo tipo são reutilizados em vez de falhar.

500 Internal Server Error

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