Criar uma pessoa 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>",
  "externalId": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "attributes": {}
}
'

{
  "success": true,
  "data": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

POST

entities

automatic

Criar uma pessoa 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>",
  "externalId": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "operationalHours": {},
  "depth": 123,
  "autoExecuteIntegrations": {},
  "autoExecuteIntegrationsShareholders": {},
  "customData": {},
  "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 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 | 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).

riskMatrixIds

string[]

Preferido para várias matrizes: lista ordenada de UUIDs. Tem precedência sobre riskMatrixId quando informado e não vazio.

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

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.

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
enrichments (array, opcional, padrão: []) - Array de códigos de provedores de enriquecimento específicos 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.

{
  executeAllActiveEnrichments?: boolean; // padrão: false
  enrichments?: ValidProviderCodesEnum[]; // padrão: []
  enrichmentGroupRefs?: string[];
}

Exemplo:

{
  "executeAllActiveEnrichments": false,
  "enrichments": ["br_bdc_basic_data_enrichment"],
  "enrichmentGroupRefs": ["my_marketplace_group_slug"],
}

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
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
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.

{
  executeAllActiveEnrichments?: boolean;
  enrichments?: {
    company?: ValidProviderCodesEnum[];
    person?: ValidProviderCodesEnum[];
  };
  enrichmentGroupRefs?: string[];
}

Exemplo:

{
  "enrichments": {
    "person": ["br_cpfcnpj_complete_person_enrichment"],
    "company": ["br_cpfcnpj_complete_company_enrichment"]
  },
  "enrichmentGroupRefs": ["related_entities_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 pessoa nos registros oficiais e a requisição falhará.

Brasil (BR)

Cenário	Código(s) de Enrichment Obrigatório(s)	Descrição
Entidade principal	`br_bdc_basic_data_enrichment`	Busca 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_enrichment`	Ambos 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ário	Código de Enrichment Obrigatório	Descrição
Entidade principal	`ar_nosis_extended_verification_enrichment`	Busca dados da pessoa do Nosis

Argentina não suporta criação automática de relacionamentos ainda. O parâmetro depth deve ser 0.

customData

object

Opcional — Dados do cliente para a pessoa principal que não devem ser substituídos pelos enrichments. Referência completa: Criação automática de entidades.Campos: name, email, phone, birthDate → entityData.person.dateOfBirth, address → entityData.person.address, gender (enum: M | F | male | female | other | unknown — use other para não binário; ver Criar entidade).Exemplo:

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

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

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

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

Próximos Passos

Obter Pessoa - Recuperar detalhes da pessoa
Criar Pessoa Manualmente - Criar pessoas com seus próprios dados
Criar Validação KYC - Iniciar verificação de identidade

Criar uma entidade pessoa Obter uma pessoa por ID

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Corpo da Requisição

​Códigos de Enrichment Obrigatórios por País

​Brasil (BR)

​Argentina (AR)

​Resposta

​Exemplos

​Criar Pessoa com Todas as Integrações Ativas

​Criar Pessoa com Integrações Específicas

​Exemplo de Resposta

​Respostas de Erro

​400 Bad Request - Tax ID Inválido

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

​409 Conflict - Pessoa Já Existe

​Melhores Práticas

​Próximos Passos

Visão Geral

Endpoint

Autenticação

Corpo da Requisição

Códigos de Enrichment Obrigatórios por País

Brasil (BR)

Argentina (AR)

Resposta

Exemplos

Criar Pessoa com Todas as Integrações Ativas

Criar Pessoa com Integrações Específicas

Exemplo de Resposta

Respostas de Erro

400 Bad Request - Tax ID Inválido

404 Not Found - Pessoa Não Encontrada no Registro

409 Conflict - Pessoa Já Existe

Melhores Práticas

Próximos Passos