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

​
externalId
string
required
Seu identificador externo único para a entidade

​
Corpo da Solicitação

​
name
string
Nome da entidade (nome completo da pessoa ou nome da empresa)
​
taxId
string
Número de identificação fiscal (SSN, EIN, VAT, CPF, CNPJ, etc.)
​
email
string | null
E-mail de contato na raiz da entidade. Omita para não alterar; null limpa.
​
phone
string | null
Telefone de contato na raiz da entidade. Omita para não alterar; null limpa.
​
nationality
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.
​
status
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.
​
reason
string
Obrigatório ao mudar o status para blocked, suspended ou rejected. Fornece trilha de auditoria para a mudança de status.
​
changeStatusManual
boolean
default:"false"
Mesma semântica de Atualizar entidade por ID. Com true, regras de matriz e automações não alteram status.
​
riskMatrixId
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.
​
riskMatrixIds
string[]
Forma preferida para várias matrizes: lista ordenada de UUIDs da sua organização. Envie [] para desatribuir todas.
​
entityData
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
​
attributes
object
Atributos personalizados chave-valor para armazenamento flexível de dados
​
metadata
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.
​
entity
object
O objeto de entidade atualizado com todos os valores atuais
​
evaluation
object | null
Objeto de avaliação (atualmente null - recurso de reavaliação temporariamente desabilitado)
​
previousEntity
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

​
404 Not Found
error
Entidade com o externalId especificado não encontrada em sua organização
{
  "error": "Entity not found"
}
​
400 Bad Request
error
Dados de solicitação inválidos ou erro de validação
{
  "error": "Changing status to 'blocked' requires a reason for audit purposes."
}
​
400 Bad Request
error
Tentando alterar campos imutáveis
{
  "error": "Field 'type' cannot be changed after entity creation"
}

​
Melhores Práticas

  1. Sempre Defina ID Externo na Criação: Defina externalId ao criar entidades via POST /entities para habilitar atualizações por ID externo.
  2. 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.
  3. 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.
  4. 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.
  5. Trate 404 com Cuidado: Se a entidade não for encontrada por ID externo, você pode precisar criá-la primeiro usando POST /entities.
  6. Atualizações em Lote: Para atualizar múltiplas entidades, chame este endpoint concorrentemente com diferentes IDs externos para melhor desempenho.

​
Endpoints Relacionados