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>",
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'
{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

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.

​
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. 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, 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
Tipo: enum - 'active' | 'inactive' | 'blocked' | 'under_review' | 'suspended' | 'expired' | 'deleted' | 'rejected' (padrão: ‘under_review’)
​
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
birthDate—Apenas person.dateOfBirth (pessoa)
address—person.address ou company.address
gender—person.gender (AR, derivação CUIL)
Propriedades documentadas: name, email, phone, birthDate (pessoa), address (string ou objeto com fullAddress, street, city, …), gender (opcional, AR).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 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"
}

​
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 monitoreo 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,
    }
  }'

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