Skip to main content
POST
/
entities
/
automatic
Criar uma entidade automaticamente com enriquecimento
curl --request POST \
  --url http://api.gu1.ai/entities/automatic \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "taxId": "<string>",
  "country": "<string>",
  "type": "<string>",
  "nationality": {},
  "monitoring": {},
  "externalId": "<string>",
  "depth": 123,
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'
import requests

url = "http://api.gu1.ai/entities/automatic"

payload = {
"taxId": "<string>",
"country": "<string>",
"type": "<string>",
"nationality": {},
"monitoring": {},
"externalId": "<string>",
"depth": 123,
"isClient": True,
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"skipRulesExecution": True,
"status": "<string>",
"operationalHours": {},
"autoExecuteIntegrations": {},
"autoExecuteIntegrationsShareholders": {},
"customData": {},
"attributes": {}
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
taxId: '<string>',
country: '<string>',
type: '<string>',
nationality: {},
monitoring: {},
externalId: '<string>',
depth: 123,
isClient: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
skipRulesExecution: true,
status: '<string>',
operationalHours: {},
autoExecuteIntegrations: {},
autoExecuteIntegrationsShareholders: {},
customData: {},
attributes: {}
})
};

fetch('http://api.gu1.ai/entities/automatic', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "http://api.gu1.ai/entities/automatic",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'taxId' => '<string>',
'country' => '<string>',
'type' => '<string>',
'nationality' => [

],
'monitoring' => [

],
'externalId' => '<string>',
'depth' => 123,
'isClient' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'skipRulesExecution' => true,
'status' => '<string>',
'operationalHours' => [

],
'autoExecuteIntegrations' => [

],
'autoExecuteIntegrationsShareholders' => [

],
'customData' => [

],
'attributes' => [

]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "http://api.gu1.ai/entities/automatic"

payload := strings.NewReader("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("http://api.gu1.ai/entities/automatic")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/automatic")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"taxId\": \"<string>\",\n \"country\": \"<string>\",\n \"type\": \"<string>\",\n \"nationality\": {},\n \"monitoring\": {},\n \"externalId\": \"<string>\",\n \"depth\": 123,\n \"isClient\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"skipRulesExecution\": true,\n \"status\": \"<string>\",\n \"operationalHours\": {},\n \"autoExecuteIntegrations\": {},\n \"autoExecuteIntegrationsShareholders\": {},\n \"customData\": {},\n \"attributes\": {}\n}"

response = http.request(request)
puts response.read_body
{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

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:
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. 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).
externalId
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)
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 | 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)
riskMatrixIds
string[]
Preferido para várias matrizes: lista ordenada de UUIDs. Tem precedência sobre riskMatrixId quando informado e não vazio.Tipo: string[] (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
Tipo: enum - 'active' | 'inactive' | 'blocked' | 'under_review' | 'suspended' | 'expired' | 'deleted' | 'rejected' (padrão: ‘under_review’)
operationalHours
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.
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
  • 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
{
  executeAllActiveEnrichments?: boolean; // padrão: false
  enrichments?: ValidProviderCodesEnum[]; // padrão: []
  enrichmentGroupRefs?: string[];
  excludeEnrichments?: ValidProviderCodesEnum[]; // padrão: []
}
Exemplo:
{
  "executeAllActiveEnrichments": true,
  "excludeEnrichments": ["br_bdc_shareholders_enrichment"],
  "enrichmentGroupRefs": ["my_marketplace_group_slug"]
}
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
  • 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
{
  executeAllActiveEnrichments?: boolean; // padrão: false
  enrichments?: {
    company?: ValidProviderCodesEnum[]; // padrão: []
    person?: ValidProviderCodesEnum[]; // padrão: []
  };
  enrichmentGroupRefs?: string[];
  excludeEnrichments?: ValidProviderCodesEnum[]; // padrão: []
}
Exemplo:
{
  "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 EntidadeCódigo de Enrichment ObrigatórioDescrição
Companybr_cpfcnpj_complete_company_enrichmentBusca dados da empresa do CNPJ/Receita Federal (razão social, nome fantasia, endereço, setor, etc.)
Personbr_bdc_basic_data_enrichmentBusca 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 PrincipalCódigo(s) de Enrichment Obrigatório(s)Descrição
Companybr_bdc_shareholders_enrichmentBusca o QSA (Quadro Societário e de Administradores) para descobrir sócios e diretores da empresa
Personbr_bdc_related_companies_enrichment E br_bdc_related_persons_enrichmentAmbos 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 EntidadeCódigo de Enrichment ObrigatórioDescrição
Companyar_nosis_extended_verification_enrichmentBusca dados da empresa do Nosis (razão social, situação CUIT, endereço, atividades, etc.)
Personar_nosis_extended_verification_enrichmentMesmo 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 — 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 customDataColuna raiz (entities)entityData
namename
emailemailperson.email / company.email
phonephoneperson.phone / company.phone
birthDateApenas person.dateOfBirth (pessoa)
addressperson.address ou company.address
genderperson.genderOpcional. 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.
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):
{
  "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):
{
  "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"
    }
  }
}
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.
reEnrichExistingChildEntities
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?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.
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 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.
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"
}

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

No POST /entities/automatic:
CampoAplica-se a
monitoring.mainEntidade raiz (taxId do body) via autoExecuteIntegrations.
monitoring.relationshipsSó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.
{
  "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)

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
    }
  }'
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);
});
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

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

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"],
      "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

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

  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