Skip to main content
POST
/
entities
/
automatic
Criar Automaticamente
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>",
  "externalId": "<string>",
  "isClient": true,
  "riskMatrixId": "<string>",
  "skipRulesExecution": true,
  "status": "<string>",
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "attributes": {}
}
'
{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

​
Visão Geral

O endpoint de criação automática de pessoa permite que você crie pessoas fornecendo informações mínimas (ID fiscal e país). O sistema automaticamente:
  • Busca dados da pessoa de registros oficiais
  • Enriquece a pessoa com informações adicionais
  • Executa integrações (verificações e enriquecimentos) automaticamente
Isso é ideal para processos de KYC (Conheça Seu Cliente) onde você deseja integrar clientes com informações completas automaticamente.

​
Endpoint

POST http://api.gu1.ai/entities/automatic

​
Autenticação

Requer uma chave de API válida no cabeçalho de autorização: 
Authorization: Bearer YOUR_API_KEY

​
Corpo da Requisição

​
taxId
string
required
Número de identificação fiscal da pessoa (por exemplo, CPF para Brasil, CURP para México, CUIT para Argentina)
📋 Ver Formatos de Tax ID por País para formatos aceitos e regras de validação para cada país.
​
country
string
required
Código de país ISO 3166-1 alpha-2 (por exemplo, “BR”, “MX”, “AR”, “CL”)
​
type
string
required
Deve ser definido como person
​
externalId
string
Seu identificador único para esta pessoa (opcional, será gerado automaticamente se não fornecido)
​
isClient
boolean
default:"false"
Marcar esta pessoa como cliente para fins de rastreamento
​
riskMatrixId
string
UUID da matriz de risco para executar regras automaticamente
​
skipRulesExecution
boolean
default:"false"
Pular a execução automática de regras após a criação da pessoa
​
status
string
default:"under_review"
Status inicial da pessoa
​
depth
number
default:"0"
Profundidade da extração de relacionamentos (0-5). Controla quantos níveis de relacionamentos buscar e criar automaticamente.
  • 0: Sem relacionamentos (apenas entidade principal)
  • 1: Apenas relacionamentos diretos
  • 2: Relacionamentos + seus relacionamentos
  • 3-5: Níveis adicionais (use com cautela - pode criar muitas entidades)
​
autoExecuteIntegrations
object
Configurar a execução automática de integrações para a entidade pessoa 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 de provedores de enriquecimento específicos para executar
  • checks (array, opcional, padrão: []) - Array de códigos de provedores de verificação específicos 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_bdc_basic_data_enrichment"],
  "checks": ["pep_check", "sanctions_check"]
}
​
autoExecuteIntegrationsShareholders
object
Configurar a execução automática de integrações para relacionamentos descobertos. Útil ao usar depth > 0. Veja Referência de Códigos de Provedores para códigos disponíveis.Tipo: object (opcional)Propriedades:
  • executeAllActiveEnrichments (boolean, opcional, padrão: false) - Executar todos os enriquecimentos ativos em entidades relacionadas
  • executeAllActiveChecks (boolean, opcional, padrão: false) - Executar todas as verificações ativas em entidades relacionadas
  • enrichments (object, opcional) - Enriquecimentos específicos por tipo de entidade
    • company (array, padrão: []) - Enriquecimentos para relacionamentos de empresa
    • person (array, padrão: []) - Enriquecimentos para relacionamentos de pessoa
  • checks (object, opcional) - Verificações específicas por tipo de entidade
    • company (array, padrão: []) - Verificações para relacionamentos de empresa
    • person (array, padrão: []) - Verificações para relacionamentos de pessoa
{
  executeAllActiveEnrichments?: boolean;
  executeAllActiveChecks?: boolean;
  enrichments?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
  checks?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
}
Exemplo:
{
  "enrichments": {
    "person": ["br_cpfcnpj_complete_person_enrichment"],
    "company": ["br_cpfcnpj_complete_company_enrichment"]
  }
}

​
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 pessoa nos registros oficiais e a requisição falhará.

​
Brasil (BR)

CenárioCódigo(s) de Enrichment Obrigatório(s)Descrição
Entidade principalbr_bdc_basic_data_enrichmentBusca dados da pessoa via BDC/CPF (nome completo, data de nascimento, endereço, etc.)
Relacionados (depth > 0)br_bdc_related_companies_enrichment E br_bdc_related_persons_enrichmentAmbos obrigatórios em autoExecuteIntegrations.enrichments. Busca empresas e pessoas relacionadas ao indivíduo
Os enrichments de relacionamentos devem ser incluídos no array autoExecuteIntegrations.enrichments da entidade principal (não em autoExecuteIntegrationsShareholders), pois o sistema precisa executá-los na pessoa principal para descobrir os relacionamentos. O campo autoExecuteIntegrationsShareholders controla quais enrichments executar em cada entidade relacionada após serem criados.

​
Argentina (AR)

CenárioCódigo de Enrichment ObrigatórioDescrição
Entidade principalar_nosis_extended_verification_enrichmentBusca dados da pessoa do Nosis
Argentina não suporta criação automática de relacionamentos ainda. O parâmetro depth deve ser 0.
​
attributes
object
Opcional - Atributos personalizados como pares chave-valor para a entidade criada.Aplicam-se apenas à entidade principal (a pessoa criada), não a relacionamentos/acionistas. Ú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"]
}

​
Resposta

​
success
boolean
Indica se a pessoa foi criada com sucesso
​
data
object
Informações completas sobre a criação:
  • entity (object) - A pessoa criada com todos os dados
  • summary (object) - Resumo da criação
  • errors (object, opcional) - Detalhes de quaisquer erros
​
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, 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.

​
Exemplos

​
Criar Pessoa com Todas as Integrações Ativas

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",
    "isClient": true,
    "autoExecuteIntegrations": {
      "executeAllActiveEnrichments": true,
      "executeAllActiveChecks": true
    }
  }'

​
Criar Pessoa 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",
    "autoExecuteIntegrations": {
      "enrichments": ["br_bdc_basic_data_enrichment"]
    }
  }'

​
Exemplo de Resposta

{
  "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",
          "nationality": "BR"
        }
      },
      "createdAt": "2024-12-23T10:30:00.000Z",
      "updatedAt": "2024-12-23T10:30:00.000Z"
    },
    "summary": {
      "entitiesCreated": 1,
      "relationshipsCreated": 0,
      "errorsCount": 0
    }
  },
  "rulesResult": null
}

​
Respostas de Erro

​
400 Bad Request - Tax ID Inválido

{
  "success": false,
  "error": "Invalid CPF format for Brazil"
}

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

{
  "success": false,
  "error": "Entity not found in official registry",
  "details": {
    "taxId": "123.456.789-00",
    "country": "BR",
    "registry": "Receita Federal"
  }
}

​
409 Conflict - Pessoa Já Existe

{
  "success": false,
  "error": "Entity with this tax ID already exists",
  "details": {
    "existingEntityId": "uuid",
    "taxId": "123.456.789-00"
  }
}

​
Melhores Práticas

  1. Tratamento de erros: Sempre verifique o campo success na resposta
  2. Limitação de taxa: Seja consciente dos limites de taxa ao criar múltiplas pessoas
  3. Seleção de integração: Escolha integrações específicas para melhor controle sobre custo e desempenho

​
Próximos Passos