Criar uma entidade pessoa

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>",
  "operationalHours": {},
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "monitoring": {}
}
'

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

POST

entities

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>",
  "operationalHours": {},
  "attributes": {},
  "entityData": {},
  "registrationDate": "<string>",
  "isClient": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "skipRulesExecution": true,
  "status": "<string>",
  "autoExecuteIntegrations": {},
  "monitoring": {}
}
'

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

operationalHours

object | null

Horário operacional opcional na raiz para regras KYT. Mesma forma que em Criar entidade. Valores de timezone: Enum fuso horário.

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 | string[]

Um ou mais UUIDs de matrizes de risco (legacy: um único UUID). Se informados, após a criação o sistema avalia a pessoa somente contra regras ativas dessas matrizes (salvo skipRulesExecution: true). Mesma semântica que riskMatrixIds quando você envia um único id como string. Veja Execução de Matriz de Risco abaixo.

riskMatrixIds

string[]

Forma preferida para várias matrizes: lista ordenada de UUIDs da sua organização. Quando presente e não vazia, tem precedência sobre riskMatrixId.

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 enriquecimentos ao criar a pessoa.Estrutura:

{
  "executeAllActiveEnrichments": false,
  "enrichments": [
    "ar_renaper_data_enrichment",
    "ar_repet_person_enrichment",
    "global_gueno_sanctions_enrichment"
  ],
  "excludeEnrichments": []
}

Propriedades:

executeAllActiveEnrichments (boolean) - Executar todos os enriquecimentos ativos da org
enrichments (string[]) - Códigos a executar após criar a entidade
enrichmentGroupRefs (string[], opcional) - Slugs de grupos do Marketplace
excludeEnrichments (string[], opcional) - Códigos a omitir do conjunto final

Códigos *_check não fazem mais parte do contrato de criação; payloads legacy que os enviem são ignorados no parse.Veja Códigos de provedores e Criar entidade.

monitoring

object

Opcional. Só afeta enriquecimentos com monitoramento contínuo (hoje: global_gueno_sanctions_enrichment). Mesma semântica em Criar entidade — monitoramento: monitoring.main[código] com { "watchlist": true } (ou true legacy), o código em enrichments e monitoramento ON no Marketplace.

Monitoramento de sanções Gu1 (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,
    "enrichments": ["global_gueno_sanctions_enrichment"],
  }
}

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 ou mais matrizes de risco (regras de conformidade KYC) ao criar uma pessoa fornecendo riskMatrixId ou riskMatrixIds.

Como Funciona

Obtenha seu(s) ID(s) de Matriz de Risco no painel do gu1 (formato: UUID)
Inclua riskMatrixId ou riskMatrixIds 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"
    }
  }
}

Exemplo com várias matrizes de risco

{
  "type": "person",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixIds": [
    "550e8400-e29b-41d4-a716-446655440000",
    "660e8400-e29b-41d4-a716-446655440001"
  ],
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15"
    }
  }
}

Combinado com enriquecimentos e monitoramento Gu1

{
  "type": "person",
  "name": "María González",
  "taxId": "20-12345678-9",
  "countryCode": "AR",
  "riskMatrixId": "550e8400-e29b-41d4-a716-446655440000",
  "autoExecuteIntegrations": {
    "executeAllActiveEnrichments": false,
    "enrichments": [
      "ar_renaper_data_enrichment",
      "ar_repet_person_enrichment",
      "global_gueno_sanctions_enrichment"
    ]
  },
  "monitoring": {
    "main": {
      "global_gueno_sanctions_enrichment": {
        "watchlist": true
      }
    }
  },
  "entityData": {
    "person": {
      "firstName": "María",
      "lastName": "González",
      "dateOfBirth": "1985-03-15"
    }
  }
}

Ver Criar entidade — monitoramento.

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

Formatos de Tax ID por País Criar uma pessoa automaticamente com enriquecimento

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Corpo da Requisição

​Monitoramento de sanções Gu1 (pessoa)

​Estrutura de Dados da Entidade Pessoa

​Execução de Matriz de Risco

​Como Funciona

​Exemplo com Matriz de Risco

​Exemplo com várias matrizes de risco

​Combinado com enriquecimentos e monitoramento Gu1

​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 Gu1 (pessoa)

Estrutura de Dados da Entidade Pessoa

Execução de Matriz de Risco

Como Funciona

Exemplo com Matriz de Risco

Exemplo com várias matrizes de risco

Combinado com enriquecimentos e monitoramento Gu1

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