Criar uma entidade automaticamente com enriquecimento
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.
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
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 empresarialperson- Pessoa física
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 viaautoExecuteIntegrations.relationships: watchlist de sócios/relacionadas comdepth> 0 viaautoExecuteIntegrationsShareholders(porcompany/person).
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-9 → 30123456789.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 diretos2- Criar sócios e seus sócios- Máximo:
5
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:
activeinactiveblockedunder_review(padrão)pending_verification- Aguardando conclusão de KYC/KYBawaiting_information- Aguardando dados do cliente (p. ex. documentos de onboarding pedidos por e-mail)suspendedexpireddeletedrejected
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: Exemplo:
object (opcional)Propriedades:executeAllActiveEnrichments(boolean, opcional, padrão:false) - Executar todas as integrações de enriquecimento ativasenrichments(array, opcional, padrão:[]) - Array de códigos específicos de provedores de enriquecimento para executarenrichmentGroupRefs(array de strings, opcional) — Slugs de grupos de enriquecimento do Marketplace (somente enriquecimentos). ComexecuteAllActiveEnrichments: false, os grupos são resolvidos e mesclados comenrichmentsexplícitos. ComexecuteAllActiveEnrichments: true, os refs de grupo são ignorados;enrichmentsexplí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
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: Exemplo:
object (opcional)Propriedades:executeAllActiveEnrichments(boolean, opcional, padrão:false) - Executar todas as integrações de enriquecimento ativas para todos os sóciosenrichments(object, opcional) - Códigos específicos de provedores de enriquecimento por tipo de entidade:company(array, opcional, padrão:[]) - Enriquecimentos para sócios empresasperson(array, opcional, padrão:[]) - Enriquecimentos para sócios pessoas
enrichmentGroupRefs(array de strings, opcional) — Mesmos slugs do objeto principal; comexecuteAllActiveEnrichments: falseaplicam-se acompanye aperson. ComexecuteAllActiveEnrichments: trueneste objeto, os refs de grupo são ignorados;enrichmentsexplícitos por tipo ainda podem acrescentar códigos após o ativo de cada lado.excludeEnrichments(array, opcional, padrão:[]) — Códigos omitidos nas listascompanyepersonapós o merge
Códigos de Enrichment Obrigatórios por País
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
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 (Exemplo (empresa):
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):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: Nota de Custo: Pode incorrer em cobranças adicionais de provedores de dados terceirizados.
boolean (query string: "true" ou "false")Comportamento:- Quando
true: Força busca de dados atualizados de registros oficiais e provedores de enriquecimento - Quando
falseou omitido: Utiliza dados de enriquecimento em cache se disponíveis - Sobrescreve a configuração da organização
enrichmentsConfig.reEnrichExistingEntities
- 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
boolean
default:"false"
Força o re-enriquecimento de TODOS os sócios e entidades relacionadas na estrutura corporativa.Tipo: Isso atualizará a empresa principal E todos os sócios até 3 níveis de profundidade.Nota de Performance:
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
falseou omitido: Atualiza apenas a entidade principal serefresh=true, sócios usam dados em cache - Funciona em combinação com o parâmetro
depthpara determinar quão profundo atualizar - Sobrescreve configuração da organização para todas as entidades relacionadas
- 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
- Definir como
truecom valores altos dedepth(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
- Use
refresh=truesozinho para atualizações de entidade única - Use
reEnrichExistingChildEntities=trueapenas 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 dadosshareholders(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 criadasrelationshipsCreated(number) - Número total de relacionamentos criadoserrorsCount(number) - Número de erros encontrados
errors(object, opcional) - Detalhes de quaisquer erros que ocorreram:creationFailed(array) - Criações de entidades que falharamenrichmentFailed(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
NoPOST /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.
ar_afip_registration_enrichment) ignoram monitoring.
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 otaxId 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
- 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
successe o objetoerrorsna 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