Atualizar uma entidade por ID

curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "taxId": "<string>",
  "email": {},
  "phone": {},
  "nationality": {},
  "countryCode": "<string>",
  "attributes": {},
  "status": "<string>",
  "reason": "<string>",
  "changeStatusManual": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "entityData": {}
}
'

{
  "entity": {},
  "evaluation": {},
  "previousEntity": {}
}

PATCH

entities

{id}

Atualizar uma entidade por ID

curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "taxId": "<string>",
  "email": {},
  "phone": {},
  "nationality": {},
  "countryCode": "<string>",
  "attributes": {},
  "status": "<string>",
  "reason": "<string>",
  "changeStatusManual": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "entityData": {}
}
'

{
  "entity": {},
  "evaluation": {},
  "previousEntity": {}
}

Visão Geral

Atualiza os atributos e dados de uma entidade existente. Este endpoint aciona automaticamente uma reavaliação da pontuação de risco da entidade e emite eventos de atualização em tempo real.

Endpoint

PATCH http://api.gu1.ai/entities/{id}

Autenticação

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

Authorization: Bearer YOUR_API_KEY

Parâmetros de Caminho

string

required

O ID gu1 da entidade a ser atualizada

Corpo da Requisição

Todos os campos do schema de criação estão disponíveis, exceto type (o tipo de entidade não pode ser alterado). Todos os campos são opcionais - inclua apenas os campos que deseja atualizar.

name

string

Atualizar o nome de exibição da entidade

O ID externo não é atualizado neste endpoint. Use Alterar ID externo (POST /entities/change-external-id) com reason obrigatório (mín. 5 caracteres). As rotas PATCH de atualização ignoram externalId no corpo.

taxId

string

Atualizar número de identificação fiscal

string | null

Atualizar o e-mail de contato na raiz da entidade. Omita o campo para não alterar; envie null para limpar.

phone

string | null

Atualizar o telefone de contato na raiz da entidade. Omita o campo para não alterar; envie null para limpar.

nationality

string | null

Nacionalidade na raiz (ISO 3166-1 alpha-2 ao persistir). Omita para não alterar; null remove. Se atualizar nationality em entityData de pessoa/empresa, a raiz pode ser recalculada quando vier no mesmo request.

countryCode

string

Atualizar código de país ISO 3166-1 alpha-2

attributes

object

Atualizar atributos personalizados (mescla com atributos existentes)

status

string

Status do ciclo de vida (active, inactive, blocked, under_review, suspended, pending_verification, expired, rejected, deleted).Obrigatório com reason: qualquer mudança de status deve incluir reason para auditoria.

reason

string

Motivo da atualização (especialmente ao mudar o status para blocked ou rejected).Obrigatório quando: mudança de status para blocked, rejected ou suspended.

changeStatusManual

boolean

default:"false"

Com true, atualizações automáticas de status são desativadas: regras de matriz de risco e automações como set_entity_status não alteram o status. Atualizações manuais por este endpoint (ou UI) continuam válidas.

Padrão: false.
Enviar false explicitamente remove o bloqueio.
Não desativa cálculo de risco nem outros efeitos de regras; apenas gravações de status por regras/automações.

Obrigatório com reason: se changeStatusManual mudar (ativar ou desativar), enviar reason no mesmo PATCH para auditoria.

Matrizes de risco

Atribuir ou substituir as matrizes de risco da entidade. Mesma semântica de Criar entidade (riskMatrixId / riskMatrixIds).

riskMatrixId

string | string[] | null

Legacy: um UUID, um array de UUIDs ou null para remover todas as matrizes atribuídas. Se riskMatrixIds vier não vazio, tem precedência sobre este campo.

riskMatrixIds

string[]

Forma preferida para várias matrizes: lista ordenada de UUIDs da sua organização. Envie [] (ou riskMatrixId: null) para desatribuir todas. Cada UUID deve existir na org; caso contrário a API retorna 400 com código INVALID_RISK_MATRIX.

Atualizar matrizes apenas persiste a atribuição na entidade. Este endpoint não executa o motor de regras nem retorna rulesExecutionSummary. Para avaliar regras depois, use Analisar entidade ou aguarde triggers de ciclo de vida (entity_created, kyc_approved, etc.) nas matrizes cujo trigger corresponda ao evento.Os mesmos campos se aplicam em Atualizar por ID externo e PATCH /entities/by-tax-id/{taxId}.

entityData

object

Atualizar dados específicos do tipo (mescla com entityData existente)

Resposta

entity

object

O objeto da entidade atualizada com todos os valores atuais

evaluation

object

Avaliação recém-criada acionada pela atualização

id - ID da Avaliação
entityId - ID da Entidade
decision - “PENDING” (aguardando processamento)
evaluationType - “SYSTEM”
reasons - Array com “Re-evaluation triggered by attribute change”

previousEntity

object

O estado da entidade antes da atualização (para auditoria/comparação)

Este endpoint não retorna rulesResult nem rulesExecutionSummary. O motor de regras não é executado na atualização; esses campos são retornados apenas por endpoints que executam regras (criar, criar-automático, enriquecer, refrescar, analisar).

Comportamento

Quando você atualiza uma entidade, o sistema automaticamente:

Registra a alteração no log de eventos da entidade com um snapshot antes/depois
Aciona reavaliação para recalcular a pontuação de risco com base nos novos dados
Emite evento em tempo real para notificar clientes conectados sobre a atualização
Mantém trilha de auditoria para fins de conformidade e revisão

Exemplos

Atualizar Renda de Pessoa

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "person": {
        "income": 95000,
        "occupation": "Senior Software Engineer"
      }
    }
  }'

Atualizar Informações da Empresa

curl -X PATCH http://api.gu1.ai/entities/660e9511-f39c-52e5-b827-557766551111 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "company": {
        "employeeCount": 75,
        "revenue": 7500000
      }
    },
    "attributes": {
      "partnershipTier": "platinum",
      "monthlyVolume": 500000
    }
  }'

Atualizar Apenas Atributos Personalizados

curl -X PATCH http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "attributes": {
      "accountTier": "premium",
      "loyaltyPoints": 15000,
      "lastLoginDate": "2024-10-03T14:00:00Z"
    }
  }'

Atualizar Status da Transação

curl -X PATCH http://api.gu1.ai/entities/770f0622-g40d-63f6-c938-668877662222 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "entityData": {
      "transaction": {
        "status": "reviewed",
        "flagged": false
      }
    }
  }'

Exemplo de Resposta

{
  "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": 22,
    "riskFactors": [...],
    "status": "active",
    "kycVerified": true,
    "entityData": {
      "person": {
        "firstName": "María",
        "lastName": "González",
        "dateOfBirth": "1985-03-15",
        "nationality": "AR",
        "occupation": "Senior Software Engineer",
        "income": 95000
      }
    },
    "attributes": {
      "email": "maria.gonzalez@example.com",
      "phone": "+54 11 1234-5678",
      "accountTier": "premium"
    },
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T16:45:00.000Z",
    "deletedAt": null
  },
  "evaluation": {
    "id": "eval_new_123",
    "entityId": "550e8400-e29b-41d4-a716-446655440000",
    "decision": "PENDING",
    "evaluationType": "SYSTEM",
    "reasons": ["Re-evaluation triggered by attribute change"],
    "rules": [],
    "entitySnapshot": {...}
  },
  "previousEntity": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "entityData": {
      "person": {
        "occupation": "Software Engineer",
        "income": 85000
      }
    },
    "updatedAt": "2024-10-03T14:35:00.000Z"
  }
}

Respostas de Erro

404 Not Found

{
  "error": "Entity not found"
}

400 Bad Request - Dados Inválidos

{
  "error": "Validation failed",
  "details": ["Invalid country code format"]
}

401 Unauthorized

{
  "error": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Failed to update entity"
}

Casos de Uso

Atualizar Após Verificação KYC

// Após concluir a verificação KYC, atualizar a entidade
const response = await fetch(`http://api.gu1.ai/entities/${entityId}`, {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    attributes: {
      kycVerified: true,
      kycVerificationDate: new Date().toISOString(),
      kycProvider: 'manual_review'
    }
  })
});

Enriquecimento Progressivo de Perfil

# Enriquecer perfil do cliente conforme mais informações ficam disponíveis
def update_customer_info(entity_id, new_data):
    response = requests.patch(
        f'http://api.gu1.ai/entities/{entity_id}',
        headers={
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        json={
            'entityData': {
                'person': new_data
            },
            'attributes': {
                'lastDataUpdate': datetime.now().isoformat(),
                'dataCompleteness': calculate_completeness(new_data)
            }
        }
    )
    return response.json()

Resolução de Transação

// Marcar uma transação sinalizada como resolvida após investigação
async function resolveTransaction(txnId, resolution) {
  const response = await fetch(`http://api.gu1.ai/entities/${txnId}`, {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        transaction: {
          status: 'resolved',
          flagged: false
        }
      },
      attributes: {
        resolutionDate: new Date().toISOString(),
        resolutionNotes: resolution,
        reviewedBy: 'compliance_team'
      }
    })
  });

  return response.json();
}

Melhores Práticas

Atualizações Parciais: Envie apenas os campos que deseja alterar - não é necessário enviar a entidade inteira
Monitorar Reavaliações: Verifique o ID da avaliação retornado para acompanhar o recálculo da pontuação de risco
Trilha de Auditoria: Use o previousEntity na resposta para manter o histórico de alterações
Sincronização em Tempo Real: Atualizações emitem eventos WebSocket para sincronização de UI em tempo real
Idempotência: Seguro para tentar novamente - atualizações com os mesmos dados não criarão eventos duplicados

Próximos Passos

Obter Entidade - Visualizar detalhes da entidade atualizada
Listar Entidades - Consultar entidades com filtros
Upsert Entidade - Criar ou atualizar em uma operação
Solicitar Análise de IA - Obter avaliação de risco atualizada

⌘I

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Caminho

​Corpo da Requisição

​Matrizes de risco

​Resposta

​Comportamento

​Exemplos

​Atualizar Renda de Pessoa

​Atualizar Informações da Empresa

​Atualizar Apenas Atributos Personalizados

​Atualizar Status da Transação

​Exemplo de Resposta

​Respostas de Erro

​404 Not Found

​400 Bad Request - Dados Inválidos

​401 Unauthorized

​500 Internal Server Error

​Casos de Uso

​Atualizar Após Verificação KYC

​Enriquecimento Progressivo de Perfil

​Resolução de Transação

​Melhores Práticas

​Próximos Passos

Visão Geral

Endpoint

Autenticação

Parâmetros de Caminho

Corpo da Requisição

Matrizes de risco

Resposta

Comportamento

Exemplos

Atualizar Renda de Pessoa

Atualizar Informações da Empresa

Atualizar Apenas Atributos Personalizados

Atualizar Status da Transação

Exemplo de Resposta

Respostas de Erro

404 Not Found

400 Bad Request - Dados Inválidos

401 Unauthorized

500 Internal Server Error

Casos de Uso

Atualizar Após Verificação KYC

Enriquecimento Progressivo de Perfil

Resolução de Transação

Melhores Práticas

Próximos Passos