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": {}
}
'
{
  "success": true,
  "entity": {},
  "rulesResult": {},
  "rulesExecutionSummary": {}
}

​
Visão Geral

Cria uma nova entidade com o tipo e atributos especificados. Entidades representam os objetos de dados principais que você deseja analisar para risco e conformidade.

​
Endpoint

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

​
Autenticação

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

​
Corpo da Requisição

​
type
string
required
O tipo de entidade a ser criada. Tipos disponíveis:
  • person - Pessoa física/cliente
  • company - Entidade empresarial
​
externalId
string
required
Seu identificador único para esta entidade em seu sistema
​
name
string
required
Nome de exibição para a entidade
​
countryCode
string
required
Código de país ISO 3166-1 alpha-2 (ex: “US”, “BR”, “AR”)
​
taxId
string
Número de identificação fiscal (validado com base no 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 do tipo. Veja exemplos abaixo para cada tipo de entidade.
Quando usar entityData?
  • Opcional para criação básica de entidade - Você pode criar uma entidade apenas com 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 entidade mínima primeiro, depois atualizá-la com dados completos antes de executar a análise de risco
Exemplo Mínimo (Person):
{
  "type": "person",
  "name": "João Silva",
  "taxId": "12345678900",
  "countryCode": "BR"
  // entityData não é necessário para criação básica
}
Exemplo Completo (Person com dados KYC):
{
  "type": "person",
  "name": "João Silva",
  "taxId": "12345678900",
  "countryCode": "BR",
  "entityData": {
    "person": {
      "firstName": "João",
      "lastName": "Silva",
      "dateOfBirth": "1980-01-15",
      "email": "joao@example.com",
      "phone": "+5511912345678"
    }
  }
}

​
Estruturas de Dados de Entidade

​
Entidade Person

{
  "person": {
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "YYYY-MM-DD",
    "nationality": "string",
    "occupation": "string",
    "income": number
  }
}

​
Entidade Company

{
  "company": {
    "legalName": "string",
    "tradeName": "string",
    "incorporationDate": "YYYY-MM-DD",
    "industry": "string",
    "employeeCount": number,
    "revenue": number
  }
}

​
Entidade Alert

{
  "alert": {
    "alertNumber": "string",
    "alertType": "RISK | COMPLIANCE | FRAUD | REGULATORY | SYSTEM",
    "severity": "INFO | WARNING | HIGH | CRITICAL",
    "status": "NEW | ACKNOWLEDGED | INVESTIGATING | RESOLVED | FALSE_POSITIVE",
    "sourceSystem": "string",
    "triggerRuleId": "string",
    "triggerCondition": "string",
    "affectedEntityId": "string",
    "relatedEntityIds": ["string"],
    "alertedAt": "ISO8601 timestamp",
    "acknowledgedAt": "ISO8601 timestamp",
    "acknowledgedBy": "string",
    "resolvedAt": "ISO8601 timestamp",
    "resolvedBy": "string",
    "resolutionNotes": "string",
    "falsePositiveReason": "string"
  }
}

​
Parâmetros de Query

​
refresh
boolean
default:"false"
Força o re-enriquecimento da entidade mesmo que já exista no sistema.Tipo: boolean (query string: "true" ou "false")Comportamento:
  • Quando true: Força o sistema a buscar dados atualizados de provedores de enriquecimento (ex: verificação de antecedentes, dados KYC, registros de empresas)
  • Quando false ou omitido: Utiliza dados de enriquecimento em cache se disponíveis
  • Sobrescreve a configuração da organização enrichmentsConfig.reEnrichExistingEntities
Casos de Uso:
  • Re-validar dados da entidade após um período de tempo significativo
  • Atualizar informações quando se sabe que os dados externos mudaram
  • Atualização manual acionada pela equipe de compliance
  • Auditorias periódicas de qualidade de dados
Exemplo:
POST http://api.gu1.ai/entities?refresh=true
Nota: O re-enriquecimento pode incorrer em custos adicionais de provedores de dados externos.

​
Resposta

​
success
boolean
Indica se a entidade foi criada com sucesso
​
entity
object
O objeto de entidade criado incluindo:
  • id - ID interno do gu1
  • externalId - Seu ID externo
  • organizationId - ID da sua organização
  • type - Tipo de entidade
  • name - Nome da entidade
  • riskScore - Pontuação de risco inicial (0-100)
  • status - Status da entidade
  • entityData - Dados específicos do tipo
  • attributes - Atributos personalizados
  • createdAt - Data/hora de criação
  • updatedAt - Data/hora 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
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 (array de { name?, type?, severity?, description? }), 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 Entidade Person (KYC)

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
      }
    },
    "attributes": {
      "email": "maria.gonzalez@example.com",
      "phone": "+54 11 1234-5678",
      "customerSince": "2024-01-15"
    }
  }'

​
Criar Entidade Company (KYB)

curl -X POST http://api.gu1.ai/entities \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "company",
    "externalId": "company_789",
    "name": "Tech Solutions S.A.",
    "countryCode": "BR",
    "taxId": "12.345.678/0001-90",
    "entityData": {
      "company": {
        "legalName": "Tech Solutions Sociedade Anônima",
        "tradeName": "Tech Solutions",
        "incorporationDate": "2020-06-15",
        "industry": "Software Development",
        "employeeCount": 50,
        "revenue": 5000000
      }
    },
    "attributes": {
      "website": "https://techsolutions.com.br",
      "registeredAddress": "Av. Paulista, 1000, São Paulo",
      "partnershipTier": "gold"
    }
  }'

​
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
      }
    },
    "attributes": {
      "email": "maria.gonzalez@example.com",
      "phone": "+54 11 1234-5678",
      "customerSince": "2024-01-15"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T14:30:00.000Z"
  }
}

​
Respostas de Erro

​
400 Bad Request - ID Fiscal Inválido

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Formato de CUIT inválido. Por favor verifique o formato e tente novamente.",
    "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": "Faltam campos obrigatórios para criação da empresa",
    "details": {
      "missingFields": ["legalName", "industry"],
      "requiredFields": ["legalName", "tradeName", "industry", "incorporationDate"],
      "countryCode": "BR"
    }
  },
  "entity": null
}

​
409 Conflict - Entidade Duplicada

{
  "success": false,
  "error": {
    "code": "DUPLICATE_ENTITY",
    "message": "Entidade com este external_id já existe",
    "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"
}

​
429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Você excedeu o limite de taxa da API. Por favor aguarde antes de fazer mais solicitações.",
  "retryAfter": 3600,
  "limit": 100,
  "remaining": 0,
  "resetAt": "2025-01-15T10:00:00Z"
}

​
500 Internal Server Error

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Ocorreu um erro inesperado ao criar a entidade",
    "details": {
      "message": "Database connection timeout"
    }
  },
  "entity": null
}

​
Próximos Passos

Após criar uma entidade, você pode:
  1. Solicitar Análise de IA - Obter avaliação automatizada de risco
  2. Listar Entidades - Consultar suas entidades
  3. Obter Detalhes da Entidade - Recuperar informações completas da entidade
  4. Aplicar Regras - Executar regras de conformidade e risco