Atualizar uma entidade 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>",
"email": {},
"phone": {},
"nationality": {},
"status": "<string>",
"reason": "<string>",
"changeStatusManual": true,
"riskMatrixId": [
"<string>"
],
"riskMatrixIds": [
"<string>"
],
"entityData": {},
"attributes": {},
"metadata": {}
}
'import requests
url = "http://api.gu1.ai/entities/by-external-id/:externalId"
payload = {
"name": "<string>",
"taxId": "<string>",
"email": {},
"phone": {},
"nationality": {},
"status": "<string>",
"reason": "<string>",
"changeStatusManual": True,
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"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>',
email: {},
phone: {},
nationality: {},
status: '<string>',
reason: '<string>',
changeStatusManual: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
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>',
'email' => [
],
'phone' => [
],
'nationality' => [
],
'status' => '<string>',
'reason' => '<string>',
'changeStatusManual' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'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 \"email\": {},\n \"phone\": {},\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"changeStatusManual\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\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 \"email\": {},\n \"phone\": {},\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"changeStatusManual\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\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 \"email\": {},\n \"phone\": {},\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"changeStatusManual\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\n \"entityData\": {},\n \"attributes\": {},\n \"metadata\": {}\n}"
response = http.request(request)
puts response.read_body{
"entity": {},
"evaluation": {},
"previousEntity": {},
"404 Not Found": {},
"400 Bad Request": {}
}Atualizar uma entidade por ID externo
Atualiza uma entidade do gu1 usando seu identificador externo em vez do UUID interno, cobrindo empresas, pessoas e transações em uma única chamada.
PATCH
/
entities
/
by-external-id
/
:externalId
Atualizar uma entidade 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>",
"email": {},
"phone": {},
"nationality": {},
"status": "<string>",
"reason": "<string>",
"changeStatusManual": true,
"riskMatrixId": [
"<string>"
],
"riskMatrixIds": [
"<string>"
],
"entityData": {},
"attributes": {},
"metadata": {}
}
'import requests
url = "http://api.gu1.ai/entities/by-external-id/:externalId"
payload = {
"name": "<string>",
"taxId": "<string>",
"email": {},
"phone": {},
"nationality": {},
"status": "<string>",
"reason": "<string>",
"changeStatusManual": True,
"riskMatrixId": ["<string>"],
"riskMatrixIds": ["<string>"],
"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>',
email: {},
phone: {},
nationality: {},
status: '<string>',
reason: '<string>',
changeStatusManual: true,
riskMatrixId: ['<string>'],
riskMatrixIds: ['<string>'],
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>',
'email' => [
],
'phone' => [
],
'nationality' => [
],
'status' => '<string>',
'reason' => '<string>',
'changeStatusManual' => true,
'riskMatrixId' => [
'<string>'
],
'riskMatrixIds' => [
'<string>'
],
'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 \"email\": {},\n \"phone\": {},\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"changeStatusManual\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\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 \"email\": {},\n \"phone\": {},\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"changeStatusManual\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\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 \"email\": {},\n \"phone\": {},\n \"nationality\": {},\n \"status\": \"<string>\",\n \"reason\": \"<string>\",\n \"changeStatusManual\": true,\n \"riskMatrixId\": [\n \"<string>\"\n ],\n \"riskMatrixIds\": [\n \"<string>\"\n ],\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
E-mail de contato na raiz da entidade. Omita para não alterar;
null limpa.string | null
Telefone de contato na raiz da entidade. Omita para não alterar;
null limpa.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.boolean
default:"false"
Mesma semântica de Atualizar entidade por ID. Com
true, regras de matriz e automações não alteram status.string | string[] | null
Legacy: um UUID, um array de UUIDs ou
null para remover todas as matrizes. Se riskMatrixIds vier não vazio, tem precedência. Ver Atualizar entidade — Matrizes de risco.string[]
Forma preferida para várias matrizes: lista ordenada de UUIDs da sua organização. Envie
[] para desatribuir todas.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"
}
},
"riskMatrixIds": ["uuid-matriz-onboarding", "uuid-matriz-post-kyc"]
}'
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",
"riskMatrixIds": ["uuid-matriz-onboarding", "uuid-matriz-post-kyc"],
"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:{
"riskMatrixIds": ["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?