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

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 a PATCH /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 operacional
inactive: Entidade está inativa
blocked: Entidade está bloqueada (requer reason)
suspended: Entidade está suspensa (requer reason)
rejected: Entidade foi rejeitada durante o onboarding (requer reason)

Nota: Mudar para 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 nome
lastName: Sobrenome
middleName: Nome do meio
dateOfBirth: Data de nascimento (YYYY-MM-DD)
nationality: Nacionalidade (ISO 3166-1 alpha-2)
email: Endereço de e-mail
phone: Número de telefone
address: Objeto de endereço (street, city, state, country, postalCode)

Campos de empresa:

legalName: Nome legal da empresa
tradingNames: Array de nomes comerciais
registrationNumber: Número de registro da empresa
incorporationDate: Data de constituição (YYYY-MM-DD)
industry: Indústria/setor
employees: Número de funcionários
website: Site da empresa
address: 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 para blocked, 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"]
}

Após atualizar a matriz de risco, você deve acionar uma reanálise usando 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 campo status (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"
}

Nota: Se você atualizar o status junto com outros campos, o webhook NÃO é acionado (assume edição em massa da entidade em vez de mudança de status independente).

Trilha de Auditoria

Cada atualização de entidade cria um evento ATTRIBUTE_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.)

Consultar trilha de auditoria:

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 externalId ao criar entidades via POST /entities para 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/analyze para 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

⌘I

​Visão Geral

​Parâmetros de Rota

​Corpo da Solicitação

​Campos Imutáveis

​Resposta

​Exemplo de Solicitação

​Exemplo de Resposta

​Mudança de Status com Motivo

​Casos de Uso

​1. Atualizar Informações do Cliente

​2. Atribuir Matriz de Risco

​3. Bloquear Entidade Após Investigação

​4. Sincronizar Dados da Empresa

​Eventos e Webhooks

​Eventos em Tempo Real

​Gatilhos de Webhook

​Trilha de Auditoria

​Respostas de Erro

​Melhores Práticas

​Endpoints Relacionados

Visão Geral

Parâmetros de Rota

Corpo da Solicitação

Campos Imutáveis

Resposta

Exemplo de Solicitação

Exemplo de Resposta

Mudança de Status com Motivo

Casos de Uso

1. Atualizar Informações do Cliente

2. Atribuir Matriz de Risco

3. Bloquear Entidade Após Investigação

4. Sincronizar Dados da Empresa

Eventos e Webhooks

Eventos em Tempo Real

Gatilhos de Webhook

Trilha de Auditoria

Respostas de Erro

Melhores Práticas

Endpoints Relacionados