Criar - gu1

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": [
    "ar_renaper_data_enrichment",
    "ar_repet_person_enrichment"
  ],
  "checks": [
    "ar_repet_person_check",
    "global_complyadvantage_person_search_check",
    "global_gueno_sanctions_check"
  ]
}

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

Exemplos de códigos válidos (pessoa AR — devem coincidir com ValidProviderCodesEnum):

ar_renaper_data_enrichment — dados RENAPER
ar_repet_person_enrichment — REPET (pessoa)
ar_repet_person_check — verificação REPET pessoa
global_complyadvantage_person_search_check — busca ComplyAdvantage (pessoa)
global_complyadvantage_pep_check — PEP ComplyAdvantage
global_gueno_sanctions_check — sanções Güeno (quando configurado)

Veja Códigos de provedores e provider-codes.

monitoring

object

Opcional. Quando o enriquecimento de sanções globais Gueno for executado via autoExecuteIntegrations, defina monitoring.main["global_gueno_sanctions_enrichment"]: true para solicitar modo watchlist (inscrição no screening diário). Hoje esta é a única chave suportada. O mesmo código deve estar em autoExecuteIntegrations.enrichments (ou ativo via execute-all) e o monitoramento deve estar habilitado no Marketplace. Veja exemplos completos em Criar entidade.

Monitoramento de sanções Gueno (pessoa)

{
  "type": "person",
  "externalId": "cust_screening_001",
  "name": "María González",
  "countryCode": "AR",
  "taxId": "27-12345678-1",
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15",
      "nationality": "AR"
    }
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": true
    }
  },
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "executeAllActiveChecks": false,
    "enrichments": ["global_gueno_sanctions_enrichment"],
    "checks": []
  }
}

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

Obtenha seu ID de Matriz de Risco no painel do gu1 (formato: UUID)
Inclua riskMatrixId na sua requisição de criação
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": [
      "ar_renaper_data_enrichment",
      "ar_repet_person_enrichment"
    ],
    "checks": [
      "ar_repet_person_check",
      "global_complyadvantage_person_search_check"
    ]
  },
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15"
    }
  }
}

Fluxo de Execução:

Entidade pessoa criada
Enriquecimentos configurados são executados (ex.: ar_renaper_data_enrichment, ar_repet_person_enrichment)
Verificações configuradas são executadas (ex.: ar_repet_person_check, global_complyadvantage_person_search_check)
Regras da matriz de risco avaliam os dados coletados
Pontuação de risco final calculada
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:

Obter Detalhes da Pessoa - Recuperar informações completas da pessoa
Listar Pessoas - Consultar suas pessoas
Atualizar Pessoa - Modificar dados da pessoa
Criar Validação KYC - Iniciar processo de verificação KYC

Começando

Casos de Uso

Webhooks

Workflows

Monitoramento (entidades)

Pessoa

Mensagens

Empresa

Dispositivos

Eventos

Conheça Seu Cliente (KYC)

Transações

Métodos de Pagamento

Regras

Matriz de Risco

Alertas

Investigações

Ingestão de Dados

Enriquecimento

Integrações

Tutoriais Interativos

Documentation Index

​Visão Geral

​Endpoint

​Autenticação

​Corpo da Requisição

​Monitoramento de sanções Gueno (pessoa)

​Estrutura de Dados da Entidade Pessoa

​Execução de Matriz de Risco

​Como Funciona

​Exemplo com Matriz de Risco

​Combinado com Enriquecimentos

​Resposta

​Exemplo de Requisição

​Exemplo de Resposta

​Respostas de Erro

​400 Bad Request - Tax ID Inválido

​400 Bad Request - Campos Obrigatórios Ausentes

​409 Conflict - Entidade Duplicada

​401 Unauthorized

​Próximos Passos

Visão Geral

Endpoint

Autenticação

Corpo da Requisição

Monitoramento de sanções Gueno (pessoa)

Estrutura de Dados da Entidade Pessoa

Execução de Matriz de Risco

Como Funciona

Exemplo com Matriz de Risco

Combinado com Enriquecimentos

Resposta

Exemplo de Requisição

Exemplo de Resposta

Respostas de Erro

400 Bad Request - Tax ID Inválido

400 Bad Request - Campos Obrigatórios Ausentes

409 Conflict - Entidade Duplicada

401 Unauthorized

Próximos Passos