Atualizar uma entidade pessoa

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

import requests

url = "http://api.gu1.ai/entities/{id}"

payload = {
    "name": "<string>",
    "taxId": "<string>",
    "countryCode": "<string>",
    "attributes": {},
    "entityData": {},
    "status": "<string>",
    "reason": "<string>",
    "riskMatrixId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    taxId: '<string>',
    countryCode: '<string>',
    attributes: {},
    entityData: {},
    status: '<string>',
    reason: '<string>',
    riskMatrixId: '<string>'
  })
};

fetch('http://api.gu1.ai/entities/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'taxId' => '<string>',
    'countryCode' => '<string>',
    'attributes' => [
        
    ],
    'entityData' => [
        
    ],
    'status' => '<string>',
    'reason' => '<string>',
    'riskMatrixId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/{id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("http://api.gu1.ai/entities/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/{id}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

PATCH

entities

{id}

Atualizar uma entidade pessoa

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

import requests

url = "http://api.gu1.ai/entities/{id}"

payload = {
    "name": "<string>",
    "taxId": "<string>",
    "countryCode": "<string>",
    "attributes": {},
    "entityData": {},
    "status": "<string>",
    "reason": "<string>",
    "riskMatrixId": "<string>"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    name: '<string>',
    taxId: '<string>',
    countryCode: '<string>',
    attributes: {},
    entityData: {},
    status: '<string>',
    reason: '<string>',
    riskMatrixId: '<string>'
  })
};

fetch('http://api.gu1.ai/entities/{id}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "http://api.gu1.ai/entities/{id}",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "PATCH",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'taxId' => '<string>',
    'countryCode' => '<string>',
    'attributes' => [
        
    ],
    'entityData' => [
        
    ],
    'status' => '<string>',
    'reason' => '<string>',
    'riskMatrixId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://api.gu1.ai/entities/{id}"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.patch("http://api.gu1.ai/entities/{id}")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://api.gu1.ai/entities/{id}")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Patch.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"taxId\": \"<string>\",\n  \"countryCode\": \"<string>\",\n  \"attributes\": {},\n  \"entityData\": {},\n  \"status\": \"<string>\",\n  \"reason\": \"<string>\",\n  \"riskMatrixId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

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

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.

string

Atualizar o nome de exibição da pessoa

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).

string

Atualizar número de identificação fiscal

string

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

object

Atualizar atributos personalizados (mescla com atributos existentes)

object

Atualizar dados específicos da pessoa (mescla com entityData existente)

string

Atualizar status da pessoa. Valores canônicos (ver Visão geral):

not_started - Cadastrada; análise ainda não iniciada
under_review - Em revisão (também o padrão na criação)
pending_verification - Aguardando conclusão de KYC/KYB
awaiting_information - Aguardando dados do cliente (p. ex. documentos de onboarding pedidos por e-mail)
active - Verificada / operacional (“aprovada”)
inactive - Encerrada ou inativa
suspended - Suspensão temporária
blocked - Bloqueio permanente
rejected - Onboarding negado
expired / deleted - Dados vencidos ou soft delete

Nota: Toda mudança de status requer reason para auditoria. As operações são bloqueadas em suspended, blocked e rejected.

string

Obrigatório ao alterar o status para suspended, blocked ou rejected. Fornece trilha de auditoria para mudanças de status.

string

UUID da matriz de risco a ser associada com esta pessoa. Atualiza quais regras são usadas para avaliação de risco.

Resposta

object

O objeto pessoa atualizado com todos os valores atuais

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”

object

O estado da pessoa 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 pessoa, o sistema automaticamente:

Registra a mudança no log de eventos da entidade com um snapshot antes/depois
Aciona reavaliação para recalcular a pontuação de risco com base em novos dados
Emite evento em tempo real para notificar clientes conectados da atualização
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"
      }
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        person: {
          income: 95000,
          occupation: 'Senior Software Engineer'
        }
      }
    })
  }
);

const result = await response.json();
console.log('Updated person:', result.entity);
console.log('Re-evaluation triggered:', result.evaluation.id);

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entityData': {
            'person': {
                'income': 95000,
                'occupation': 'Senior Software Engineer'
            }
        }
    }
)

result = response.json()
print(f"Updated person: {result['entity']['name']}")
print(f"Re-evaluation ID: {result['evaluation']['id']}")

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"
      }
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      entityData: {
        person: {
          email: 'new.email@example.com',
          phone: '+54 11 9876-5432',
          address: 'Av. Libertador 2500, Buenos Aires'
        }
      }
    })
  }
);

const result = await response.json();
console.log('Contact information updated');

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'entityData': {
            'person': {
                'email': 'new.email@example.com',
                'phone': '+54 11 9876-5432',
                'address': 'Av. Libertador 2500, Buenos Aires'
            }
        }
    }
)

result = response.json()
print("Contact information updated")

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"
    }
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      attributes: {
        accountTier: 'premium',
        loyaltyPoints: 15000,
        lastLoginDate: '2024-10-03T14:00:00Z'
      }
    })
  }
);

const result = await response.json();
console.log('Attributes updated:', result.entity.attributes);

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'attributes': {
            'accountTier': 'premium',
            'loyaltyPoints': 15000,
            'lastLoginDate': '2024-10-03T14:00:00Z'
        }
    }
)

result = response.json()
print(f"Attributes updated: {result['entity']['attributes']}")

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"
  }'

const response = await fetch(
  'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
  {
    method: 'PATCH',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      status: 'suspended',
      reason: 'Suspicious activity detected - pending investigation'
    })
  }
);

const result = await response.json();
console.log('Status updated to:', result.entity.status);

import requests

response = requests.patch(
    'http://api.gu1.ai/entities/550e8400-e29b-41d4-a716-446655440000',
    headers={
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
    },
    json={
        'status': 'suspended',
        'reason': 'Suspicious activity detected - pending investigation'
    }
)

result = response.json()
print(f"Status updated to: {result['entity']['status']}")

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

Atualizações Parciais: Envie apenas os campos que deseja alterar - não é necessário enviar a pessoa inteira
Monitorar Reavaliações: Verifique o ID de avaliação retornado para rastrear o recálculo da pontuação de risco
Trilha de Auditoria: Use o previousEntity na resposta para manter o histórico de mudanças
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 Pessoa - Ver detalhes da pessoa atualizada
Listar Pessoas - Consultar pessoas com filtros
Upsert Pessoa - Criar ou atualizar em uma operação

​Visão Geral

​Endpoint

​Autenticação

​Parâmetros de Caminho

​Corpo da Requisição

​Resposta

​Comportamento

​Exemplos

​Atualizar Renda e Ocupação da Pessoa

​Atualizar Informações de Contato

​Atualizar Apenas Atributos Personalizados

​Atualizar Status da Pessoa

​Exemplo de Resposta

​Respostas de Erro

​404 Not Found

​400 Bad Request - Dados Inválidos

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

​401 Unauthorized

​500 Internal Server Error

​Casos de Uso

​Atualizar Após Verificação KYC

​Enriquecimento Progressivo de Perfil

​Melhores Práticas

​Próximos Passos

Visão Geral

Endpoint

Autenticação

Parâmetros de Caminho

Corpo da Requisição

Resposta

Comportamento

Exemplos

Atualizar Renda e Ocupação da Pessoa

Atualizar Informações de Contato

Atualizar Apenas Atributos Personalizados

Atualizar Status da Pessoa

Exemplo de Resposta

Respostas de Erro

404 Not Found

400 Bad Request - Dados Inválidos

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

401 Unauthorized

500 Internal Server Error

Casos de Uso

Atualizar Após Verificação KYC

Enriquecimento Progressivo de Perfil

Melhores Práticas

Próximos Passos