Skip to main content
PATCH
/
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": {}
}
'
{
  "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

ā€‹
id
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
ā€‹
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 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)
:::note 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:
  1. Registra a alteraĆ§Ć£o no log de eventos da entidade com um snapshot antes/depois
  2. Aciona reavaliaĆ§Ć£o para recalcular a pontuaĆ§Ć£o de risco com base nos novos dados
  3. Emite evento em tempo real para notificar clientes conectados sobre a atualizaĆ§Ć£o
  4. 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

  1. AtualizaƧƵes Parciais: Envie apenas os campos que deseja alterar - nĆ£o Ć© necessĆ”rio enviar a entidade inteira
  2. Monitorar ReavaliaƧƵes: Verifique o ID da avaliaĆ§Ć£o retornado para acompanhar o recĆ”lculo da pontuaĆ§Ć£o de risco
  3. Trilha de Auditoria: Use o previousEntity na resposta para manter o histĆ³rico de alteraƧƵes
  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