Skip to main content
PATCH
Atualizar uma pessoa por ID externo

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

Exemplo de Resposta

Mudança de Status com Motivo

Ao mudar o status para blocked, suspended ou rejected, você deve fornecer um motivo:

Casos de Uso

1. Atualizar Informações do Cliente

Atualizar dados do cliente do seu CRM ou sistema de gerenciamento de usuários:

2. Atribuir Matriz de Risco

Atribuir ou alterar a matriz de risco para uma entidade:
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:

4. Sincronizar Dados da Empresa

Atualizar informações da empresa do registro empresarial:

Eventos e Webhooks

Eventos em Tempo Real

Após uma atualização bem-sucedida, o seguinte evento em tempo real é emitido via WebSocket:

Gatilhos de Webhook

Se você mudar apenas o campo status (sem outras mudanças de campo), um webhook é acionado: Evento: entity.status_changed
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:

Respostas de Erro

error
Entidade com o externalId especificado não encontrada em sua organização
error
Dados de solicitação inválidos ou erro de validação
error
Tentando alterar campos imutáveis

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