Skip to main content
POST
/
entities
Criar
curl --request POST \
  --url http://api.gu1.ai/entities \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "type": "<string>",
  "externalId": "<string>",
  "name": "<string>",
  "countryCode": "<string>",
  "taxId": "<string>",
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": "<string>",
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {}
}
'
{
  "success": true,
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

​
Visão Geral

Cria uma nova entidade de pessoa com os atributos especificados. Entidades de pessoa representam clientes individuais que você deseja analisar para risco e conformidade (KYC).

​
Endpoint

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

​
Autenticação

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

​
Corpo da Requisição

​
type
string
required
Deve ser person para criar uma entidade de pessoa
​
externalId
string
required
Seu identificador único para esta pessoa em seu sistema
​
name
string
required
Nome de exibição da pessoa
​
countryCode
string
required
Código de país ISO 3166-1 alpha-2 (por exemplo, “US”, “BR”, “AR”)
​
taxId
string
Número de identificação fiscal (validado com base no país)
📋 Ver Formatos de Tax ID por País para formatos aceitos e regras de validação para cada país.
​
attributes
object
Opcional - Atributos personalizados como pares chave-valor para metadados flexíveisUse isto para campos personalizados que não se encaixam no esquema padrão (ex: IDs internos, tags, flags)
​
entityData
object
Opcional - Estrutura de dados específica da pessoa (veja abaixo)
Quando usar entityData?
  • Opcional para criação básica de entidade - Você pode criar uma pessoa com apenas type, name, taxId e countryCode
  • Necessário para enriquecimento e análise de risco - Se você quiser executar verificações de conformidade, precisará fornecer campos relevantes
  • Pode ser preenchido depois - Você pode criar uma pessoa mínima primeiro, depois atualizá-la com dados completos antes de executar análise de risco
Exemplo Mínimo:
{
  "type": "person",
  "name": "João Silva",
  "taxId": "12345678901",
  "countryCode": "BR"
  // Não é necessário entityData para criação básica
}
Exemplo Completo (com dados KYC):
{
  "type": "person",
  "name": "João Silva",
  "taxId": "12345678901",
  "countryCode": "BR",
  "entityData": {
    "person": {
      "firstName": "João",
      "lastName": "Silva",
      "dateOfBirth": "1980-01-15",
      "email": "joao@example.com",
      "phone": "+5511987654321"
    }
  }
}
​
registrationDate
string
Data de registro da pessoa em formato ISO 8601 datetime (ex: “2024-01-15T10:30:00Z”)
​
isClient
boolean
default:"false"
Marcar esta pessoa como cliente para fins de rastreamento
​
riskMatrixId
string
UUID da matriz de risco para executar regras automaticamente. Veja a seção Execução de Matriz de Risco abaixo para mais detalhes.
​
skipRulesExecution
boolean
default:"false"
Pular a execução automática de regras após a criação da pessoa. Use isso para criar a entidade primeiro e acionar as regras manualmente depois.
​
status
string
default:"under_review"
Status inicial da pessoa. Opções:
  • active - Pessoa está ativa
  • inactive - Pessoa está inativa
  • blocked - Pessoa está bloqueada
  • under_review - Pessoa está em revisão (padrão)
  • suspended - Pessoa está suspensa
  • expired - Registro da pessoa expirou
  • deleted - Excluído suavemente
  • rejected - Pessoa foi rejeitada
​
autoExecuteIntegrations
object
Configurar a execução automática de integrações (enriquecimentos e verificações) ao criar a pessoa.Estrutura:
{
  "executeAllActiveEnrichments": false,
  "executeAllActiveChecks": false,
  "enrichments": ["NOSIS"],
  "checks": ["COMPLY_ADVANTAGE", "REPET"]
}
Propriedades:
  • executeAllActiveEnrichments (boolean) - Executar todas as integrações de enriquecimento ativas configuradas na sua organização
  • executeAllActiveChecks (boolean) - Executar todas as integrações de verificação ativas configuradas na sua organização
  • enrichments (string[]) - Array de códigos específicos de provedores de enriquecimento para executar
  • checks (string[]) - Array de códigos específicos de provedores de verificação para executar
Códigos de Provedores Comuns:
  • NOSIS - NOSIS Argentina (dados de identidade e crédito de pessoas)
  • REPET - REPET Argentina (triagem de listas de vigilância)
  • COMPLY_ADVANTAGE - ComplyAdvantage (triagem de sanções e PEP)
  • WORLDCHECK - Refinitiv World-Check (triagem de conformidade)
Veja Referência de Códigos de Provedores para lista completa.

​
Estrutura de Dados da Entidade Pessoa

O objeto entityData.person deve conter: 
{
  "person": {
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "YYYY-MM-DD",
    "nationality": "string",
    "occupation": "string",
    "income": number,
    "incomeCurrency": "string",
    "address": "string | object (veja nota sobre Formato de Endereço)",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string",
    "email": "string",
    "phone": "string",
    "alternativePhone": "string",
    "idType": "national_id | passport | drivers_license | tax_id | other",
    "idNumber": "string",
    "isPep": boolean,
    "pepPosition": "string",
    "pepCountry": "string"
  }
}
Formato de Endereço: O campo address suporta ambos os formatos:
  • Formato string (simples): "Av. Paulista, 1000, São Paulo, SP, Brazil"
  • Formato objeto (estruturado): 
    {
  "street": "Av. Paulista",
  "number": "1000",
  "complement": "Suite 200",
  "neighborhood": "Bela Vista",
  "city": "São Paulo",
  "state": "SP",
  "country": "Brazil",
  "postalCode": "01310-100"
}

​
Execução de Matriz de Risco

Você pode executar automaticamente uma matriz de risco (regras de conformidade KYC) ao criar uma pessoa fornecendo o parâmetro riskMatrixId.

​
Como Funciona

  1. Obtenha seu ID de Matriz de Risco no painel do gu1 (formato: UUID)
  2. Inclua riskMatrixId na sua requisição de criação
  3. O sistema automaticamente:
    • Cria a entidade pessoa
    • Executa todas as regras KYC na matriz
    • Calcula a pontuação de risco
    • Gera alertas de conformidade se necessário
    • Atualiza o status da pessoa com base nos resultados

​
Exemplo com Matriz de Risco

{
  "type": "person",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15",
      "occupation": "Software Engineer"
    }
  }
}

​
Combinado com Enriquecimentos

Para melhores resultados, combine a execução de matriz com enriquecimentos automáticos: 
{
  "type": "person",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "enrichments": ["NOSIS"],
    "checks": ["COMPLY_ADVANTAGE", "REPET"]
  },
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15"
    }
  }
}
Fluxo de Execução:
  1. Entidade pessoa criada
  2. Enriquecimento NOSIS busca dados de identidade e crédito
  3. REPET verifica listas de vigilância
  4. ComplyAdvantage verifica sanções e status PEP
  5. Regras da matriz de risco avaliam todos os dados coletados
  6. Pontuação de risco final calculada
  7. Alertas de conformidade gerados se as regras forem acionadas

​
Resposta

​
success
boolean
Indica se a pessoa foi criada com sucesso
​
entity
object
O objeto pessoa criado incluindo:
  • id - ID interno do gu1
  • externalId - Seu ID externo
  • organizationId - ID da sua organização
  • type - Sempre “person”
  • name - Nome da pessoa
  • riskScore - Pontuação de risco inicial (0-100)
  • status - Status da pessoa
  • entityData - Dados específicos da pessoa
  • attributes - Atributos personalizados
  • createdAt - Timestamp de criação
  • updatedAt - Timestamp da última atualização
​
rulesResult
object
Resultado da execução de regras (apenas presente quando as regras foram executadas, ex. quando skipRulesExecution é false e há matriz de risco configurada), incluindo:
  • 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). 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.
  • 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.

​
Exemplo de Requisição

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "person",
    "externalId": "customer_12345",
    "name": "María González",
    "countryCode": "AR",
    "taxId": "20-12345678-9",
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Software Engineer",
        "income": 85000,
        "incomeCurrency": "USD",
        "email": "maria.gonzalez@example.com",
        "phone": "+54 11 1234-5678",
        "address": "Av. Corrientes 1234",
        "city": "Buenos Aires",
        "state": "CABA",
        "country": "Argentina",
        "postalCode": "C1043"
      }
    },
    "attributes": {
      "customerSince": "2024-01-15",
      "accountType": "premium"
    }
  }'

​
Exemplo de Resposta

{
  "success": true,
  "entity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "customer_12345",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "person",
    "name": "María González",
    "taxId": "20-12345678-9",
    "countryCode": "AR",
    "riskScore": 25,
    "status": "active",
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Software Engineer",
        "income": 85000,
        "incomeCurrency": "USD",
        "email": "maria.gonzalez@example.com",
        "phone": "+54 11 1234-5678",
        "address": "Av. Corrientes 1234",
        "city": "Buenos Aires",
        "state": "CABA",
        "country": "Argentina",
        "postalCode": "C1043"
      }
    },
    "attributes": {
      "customerSince": "2024-01-15",
      "accountType": "premium"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T14:30:00.000Z"
  }
}

​
Respostas de Erro

​
400 Bad Request - Tax ID Inválido

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid CUIT format. Please check the format and try again.",
    "details": {
      "field": "taxId",
      "taxIdName": "CUIT",
      "providedValue": "20-12345678-9"
    }
  },
  "entity": null
}

​
400 Bad Request - Campos Obrigatórios Ausentes

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Missing required fields for person creation",
    "details": {
      "missingFields": ["firstName", "lastName"],
      "requiredFields": ["firstName", "lastName", "dateOfBirth"],
      "countryCode": "AR"
    }
  },
  "entity": null
}

​
409 Conflict - Entidade Duplicada

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Entity with this external_id already exists",
    "details": {
      "field": "external_id",
      "value": "customer_12345",
      "constraint": "entities_organization_external_id_unique"
    }
  },
  "entity": null
}

​
401 Unauthorized

{
  "error": "Invalid or missing API key",
  "code": "INVALID_KEY"
}

​
Próximos Passos

Após criar uma pessoa, você pode:
  1. Obter Detalhes da Pessoa - Recuperar informações completas da pessoa
  2. Listar Pessoas - Consultar suas pessoas
  3. Atualizar Pessoa - Modificar dados da pessoa
  4. Criar Validação KYC - Iniciar processo de verificação KYC