Skip to main content
PATCH
http://api.gu1.ai
/
entities
/
{id}
Atualizar
curl --request PATCH \
  --url http://api.gu1.ai/entities/{id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "externalId": "<string>",
  "taxId": "<string>",
  "countryCode": "<string>",
  "attributes": {},
  "entityData": {},
  "status": "<string>",
  "reason": "<string>",
  "riskMatrixId": "<string>"
}
'
{
  "entity": {},
  "evaluation": {},
  "previousEntity": {}
}

​
Visão Geral

Atualiza atributos e dados de uma pessoa existente. Este endpoint aciona automaticamente uma reavaliação da pontuação de risco da pessoa 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 de autorização: 
Authorization: Bearer YOUR_API_KEY

​
Parâmetros de Caminho

​
id
string
required
O ID do gu1 da pessoa a atualizar

​
Corpo da Requisição

Todos os campos são opcionais - inclua apenas os campos que deseja atualizar.
​
name
string
Atualizar o nome de exibição da pessoa
​
externalId
string
Atualizar seu identificador externo
​
taxId
string
Atualizar número de identificação fiscal
​
countryCode
string
Atualizar código de país ISO 3166-1 alpha-2
​
attributes
object
Atualizar atributos personalizados (mescla com atributos existentes)
​
entityData
object
Atualizar dados específicos da pessoa (mescla com entityData existente)
​
status
string
Atualizar status da pessoa. Status disponíveis:
  • pending - Estado inicial, aguardando processamento
  • under_review - Em revisão manual
  • active - Aprovado e ativo
  • suspended - Temporariamente suspenso (requer reason)
  • blocked - Bloqueado permanentemente (requer reason)
  • rejected - Rejeitado durante a integração (requer reason)
Nota: Mudanças de status para suspended, blocked ou rejected requerem um campo reason para fins de auditoria.
​
reason
string
Obrigatório ao alterar o status para suspended, blocked ou rejected. Fornece trilha de auditoria para mudanças de status.
​
riskMatrixId
string
UUID da matriz de risco a ser associada com esta pessoa. Atualiza quais regras são usadas para avaliação de risco.

​
Resposta

​
entity
object
O objeto pessoa atualizado 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 pessoa antes da atualização (para auditoria/comparação)

​
Comportamento

Quando você atualiza uma pessoa, o sistema automaticamente:
  1. Registra a mudança no log de eventos da entidade com um snapshot antes/depois
  2. Aciona reavaliação para recalcular a pontuação de risco com base em novos dados
  3. Emite evento em tempo real para notificar clientes conectados da atualização
  4. Mantém trilha de auditoria para conformidade e fins de revisão

​
Exemplos

​
Atualizar Renda e Ocupação da 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 de Contato

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": {
        "email": "new.email@example.com",
        "phone": "+54 11 9876-5432",
        "address": "Av. Libertador 2500, Buenos Aires"
      }
    }
  }'

​
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 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 '{
    "status": "suspended",
    "reason": "Suspicious activity detected - pending investigation"
  }'

​
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"]
}

​
400 Bad Request - Motivo Ausente para Mudança de Status

{
  "error": "Changing status to 'suspended' requires a reason for audit purposes."
}

​
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 completar a verificação KYC, atualizar a pessoa
const response = await fetch(`http://api.gu1.ai/entities/${personId}`, {
  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(person_id, new_data):
    response = requests.patch(
        f'http://api.gu1.ai/entities/{person_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()

​
Melhores Práticas

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

​
Próximos Passos