Atualizar uma pessoa por ID externo
curl --request PATCH \
--url http://api.gu1.ai/entities/by-external-id/:externalId \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"taxId": "<string>",
"nationality": {},
"status": "<string>",
"reason": "<string>",
"riskMatrixId": {},
"entityData": {},
"attributes": {},
"metadata": {}
}
'import requests
url = "http://api.gu1.ai/entities/by-external-id/:externalId"
payload = {
"name": "<string>",
"taxId": "<string>",
"nationality": {},
"status": "<string>",
"reason": "<string>",
"riskMatrixId": {},
"entityData": {},
"attributes": {},
"metadata": {}
}
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>',
nationality: {},
status: '<string>',
reason: '<string>',
riskMatrixId: {},
entityData: {},
attributes: {},
metadata: {}
})
};
fetch('http://api.gu1.ai/entities/by-external-id/:externalId', 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/by-external-id/:externalId",
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>',
'nationality' => [
],
'status' => '<string>',
'reason' => '<string>',
'riskMatrixId' => [
],
'entityData' => [
],
'attributes' => [
],
'metadata' => [
]
]),
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/by-external-id/:externalId"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"taxId\": \"<string>\",\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\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/by-external-id/:externalId")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"taxId\": \"<string>\",\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/by-external-id/:externalId")
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 \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"entity": {},
"evaluation": {},
"previousEntity": {},
"404 Not Found": {},
"400 Bad Request": {}
}Referência API
Atualizar uma pessoa por ID externo
Atualiza uma pessoa no gu1 usando seu identificador externo em vez do UUID interno, útil ao integrar bases de clientes existentes e sistemas legados.
PATCH
/
entities
/
by-external-id
/
:externalId
Atualizar uma pessoa por ID externo
curl --request PATCH \
--url http://api.gu1.ai/entities/by-external-id/:externalId \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "<string>",
"taxId": "<string>",
"nationality": {},
"status": "<string>",
"reason": "<string>",
"riskMatrixId": {},
"entityData": {},
"attributes": {},
"metadata": {}
}
'import requests
url = "http://api.gu1.ai/entities/by-external-id/:externalId"
payload = {
"name": "<string>",
"taxId": "<string>",
"nationality": {},
"status": "<string>",
"reason": "<string>",
"riskMatrixId": {},
"entityData": {},
"attributes": {},
"metadata": {}
}
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>',
nationality: {},
status: '<string>',
reason: '<string>',
riskMatrixId: {},
entityData: {},
attributes: {},
metadata: {}
})
};
fetch('http://api.gu1.ai/entities/by-external-id/:externalId', 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/by-external-id/:externalId",
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>',
'nationality' => [
],
'status' => '<string>',
'reason' => '<string>',
'riskMatrixId' => [
],
'entityData' => [
],
'attributes' => [
],
'metadata' => [
]
]),
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/by-external-id/:externalId"
payload := strings.NewReader("{\n \"name\": \"<string>\",\n \"taxId\": \"<string>\",\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\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/by-external-id/:externalId")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"name\": \"<string>\",\n \"taxId\": \"<string>\",\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("http://api.gu1.ai/entities/by-external-id/:externalId")
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 \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"riskMatrixId\": {},\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"entity": {},
"evaluation": {},
"previousEntity": {},
"404 Not Found": {},
"400 Bad Request": {}
}Visão Geral
Este endpoint permite atualizar uma entidade usando seu próprio identificador externo em vez de nosso UUID interno. É útil quando você não armazena nossos UUIDs em seu sistema e apenas rastreia seus próprios IDs externos. A funcionalidade é idêntica aPATCH /entities/:id, mas usa externalId como identificador.
Parâmetros de Rota
string
required
Seu identificador externo único para a entidade
Corpo da Solicitação
string
Nome da entidade (nome completo da pessoa ou nome da empresa)
string
Número de identificação fiscal (SSN, EIN, VAT, CPF, CNPJ, etc.)
string | null
Nacionalidade na raiz (ISO 3166-1 alpha-2 ao persistir). Omita para não alterar;
null remove. Se atualizar nationality dentro de entityData no mesmo request, a raiz pode ser recalculada.string
Status da entidade. Valores possíveis:
active: Entidade está ativa e operacionalinactive: Entidade está inativanot_started: Análise ainda não iniciadaunder_review: Em revisão / análise em andamentopending_verification: Aguardando conclusão de KYC/KYBawaiting_information: Aguardando dados do cliente (p. ex. documentos de onboarding pedidos por e-mail)blocked: Entidade está bloqueada (requerreason)suspended: Entidade está suspensa (requerreason)rejected: Entidade foi rejeitada durante o onboarding (requerreason)expired: Dados/documentos vencidosdeleted: Soft-deleted
blocked, suspended ou rejected requer fornecer um reason para auditoria.string
Obrigatório ao mudar o status para
blocked, suspended ou rejected. Fornece trilha de auditoria para a mudança de status.string (uuid)
ID da matriz de risco a ser atribuída a esta entidade. A matriz de risco determina quais regras serão executadas para avaliação de risco.
object
Estrutura de dados específica da entidade. Para entidades de pessoa, use
entityData.person. Para entidades de empresa, use entityData.company.Campos de pessoa:firstName: Primeiro nomelastName: SobrenomemiddleName: Nome do meiodateOfBirth: Data de nascimento (YYYY-MM-DD)nationality: Nacionalidade (ISO 3166-1 alpha-2)email: Endereço de e-mailphone: Número de telefoneaddress: Objeto de endereço (street, city, state, country, postalCode)
legalName: Nome legal da empresatradingNames: Array de nomes comerciaisregistrationNumber: Número de registro da empresaincorporationDate: Data de constituição (YYYY-MM-DD)industry: Indústria/setoremployees: Número de funcionárioswebsite: Site da empresaaddress: Objeto de endereço
object
Atributos personalizados chave-valor para armazenamento flexível de dados
object
Metadados do sistema (geralmente definidos pelo sistema, mas podem ser atualizados)
Campos Imutáveis
Os seguintes campos não podem ser alterados após a criação da entidade:type: Tipo de entidade (person ou company)countryCode: Código do país da entidade (ISO 3166-1 alpha-2)
Resposta
Retorna o objeto de entidade atualizado.object
O objeto de entidade atualizado com todos os valores atuais
object | null
Objeto de avaliação (atualmente null - recurso de reavaliação temporariamente desabilitado)
object
O estado da entidade antes da atualização (para auditoria)
Exemplo de Solicitação
curl -X PATCH https://api.gueno.ai/entities/by-external-id/cliente-12345 \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "João Miguel Silva",
"status": "active",
"entityData": {
"person": {
"firstName": "João",
"middleName": "Miguel",
"lastName": "Silva",
"email": "joao.silva@exemplo.com",
"phone": "+55-11-98765-4321"
}
},
"riskMatrixId": "uuid-matriz-aqui"
}'
Exemplo de Resposta
{
"entity": {
"id": "uuid-entidade",
"organizationId": "uuid-org",
"externalId": "cliente-12345",
"type": "person",
"name": "João Miguel Silva",
"taxId": "123.456.789-00",
"countryCode": "BR",
"nationality": "BR",
"status": "active",
"riskScore": "35.00",
"riskMatrixId": "uuid-matriz-aqui",
"entityData": {
"person": {
"firstName": "João",
"middleName": "Miguel",
"lastName": "Silva",
"email": "joao.silva@exemplo.com",
"phone": "+55-11-98765-4321"
}
},
"createdAt": "2025-12-20T10:00:00Z",
"updatedAt": "2025-12-24T15:30:00Z"
},
"evaluation": null,
"previousEntity": {
"id": "uuid-entidade",
"name": "João Silva",
"status": "pending",
...
}
}
Mudança de Status com Motivo
Ao mudar o status parablocked, suspended ou rejected, você deve fornecer um motivo:
curl -X PATCH https://api.gueno.ai/entities/by-external-id/cliente-12345 \
-H "Authorization: Bearer SUA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "blocked",
"reason": "Falhou na triagem de sanções - correspondência detectada na lista OFAC"
}'
Casos de Uso
1. Atualizar Informações do Cliente
Atualizar dados do cliente do seu CRM ou sistema de gerenciamento de usuários:{
"name": "Maria Santos Oliveira",
"entityData": {
"person": {
"lastName": "Santos Oliveira",
"email": "maria.santosoliveira@exemplo.com",
"address": {
"street": "Av. Paulista, 1000",
"city": "São Paulo",
"state": "SP",
"country": "BR",
"postalCode": "01310-100"
}
}
}
}
2. Atribuir Matriz de Risco
Atribuir ou alterar a matriz de risco para uma entidade:{
"riskMatrixId": "uuid-matriz-alto-risco"
}
POST /entities/:entityId/analyze para reavaliar a entidade com as novas regras.
3. Bloquear Entidade Após Investigação
Bloquear uma entidade após investigação de conformidade:{
"status": "blocked",
"reason": "Investigação revelou conexões com entidades sancionadas"
}
4. Sincronizar Dados da Empresa
Atualizar informações da empresa do registro empresarial:{
"entityData": {
"company": {
"employees": 250,
"revenue": 50000000,
"website": "https://empresa-novo-dominio.com.br"
}
}
}
Eventos e Webhooks
Eventos em Tempo Real
Após uma atualização bem-sucedida, o seguinte evento em tempo real é emitido via WebSocket:{
"event": "entity.updated",
"entityId": "uuid-entidade",
"externalId": "cliente-12345",
"updatedFields": ["name", "entityData"],
"previousValues": {...},
"newValues": {...}
}
Gatilhos de Webhook
Se você mudar apenas o campostatus (sem outras mudanças de campo), um webhook é acionado:
Evento: entity.status_changed
{
"event": "entity.status_changed",
"entityId": "uuid-entidade",
"externalId": "cliente-12345",
"oldStatus": "active",
"newStatus": "blocked",
"reason": "Falhou na triagem de sanções",
"changedBy": "uuid-usuario",
"timestamp": "2025-12-24T15:30:00Z"
}
Trilha de Auditoria
Cada atualização de entidade cria um eventoATTRIBUTE_CHANGED no registro de eventos da entidade com:
- Estado anterior (todos os campos alterados)
- Estado posterior (todos os campos alterados)
- Usuário que fez a mudança
- Timestamp
- Fonte (API, dashboard, etc.)
GET /entity-events?entityId=:entityId&eventType=ATTRIBUTE_CHANGED
Respostas de Erro
error
Entidade com o
externalId especificado não encontrada em sua organização{
"error": "Entity not found"
}
error
Dados de solicitação inválidos ou erro de validação
{
"error": "Changing status to 'blocked' requires a reason for audit purposes."
}
error
Tentando alterar campos imutáveis
{
"error": "Field 'type' cannot be changed after entity creation"
}
Melhores Práticas
-
Sempre Defina ID Externo na Criação: Defina
externalIdao criar entidades viaPOST /entitiespara habilitar atualizações por ID externo. - Use para Integração de Sistemas: Este endpoint é ideal para integrações onde você sincroniza dados de sistemas externos (CRM, ERP, etc.) usando seus próprios IDs.
- Forneça Motivos para Mudanças de Status: Sempre inclua motivos significativos ao bloquear, suspender ou rejeitar entidades para a trilha de auditoria de conformidade.
-
Reanalise Após Mudança de Matriz de Risco: Após atribuir uma nova matriz de risco, acione
POST /entities/:entityId/analyzepara reavaliar com as novas regras. -
Trate 404 com Cuidado: Se a entidade não for encontrada por ID externo, você pode precisar criá-la primeiro usando
POST /entities. - Atualizações em Lote: Para atualizar múltiplas entidades, chame este endpoint concorrentemente com diferentes IDs externos para melhor desempenho.
Endpoints Relacionados
- Criar Entidade - Criar nova entidade
- Atualizar Entidade por UUID - Atualizar usando UUID interno
- Obter Entidade - Recuperar detalhes da entidade
- Analisar Entidade - Acionar análise de risco
Was this page helpful?