> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Alterar ID externo de uma pessoa

> Define um novo identificador externo para uma pessoa no gu1 com motivo obrigatório de auditoria; atualiza referências desnormalizadas em eventos.

## Visão geral

Use este endpoint para alterar o **external ID** de uma entidade. Não é possível fazer isso via `PATCH /entities/:id`, `PATCH /entities/by-external-id/:externalId` ou `PATCH /entities/by-tax-id/:taxId` — essas rotas **ignoram** `externalId` no corpo.

* Valida unicidade do novo ID na organização.
* Atualiza a entidade.
* Se o ID anterior não era vazio e mudou, reescreve referências em **transações** e **user events** na mesma transação do banco.

O campo **reason** é obrigatório (mínimo 5 caracteres). A alteração é auditada (`externalIdChangeReason`, `source: change_external_id_endpoint`).

## Endpoint

```
POST https://api.gu1.ai/entities/change-external-id
```

## Corpo da requisição

Envie **exatamente um** campo de localização, mais o novo valor e o motivo.

<ParamField body="entityId" type="string (uuid)">
  UUID interno da entidade na gu1.
</ParamField>

<ParamField body="externalId" type="string">
  **Apenas busca**: o ID externo **atual** da entidade (não o novo).
</ParamField>

<ParamField body="taxId" type="string">
  **Apenas busca**: tax ID de uma entidade que já tenha tax ID salvo e não vazio. Várias correspondências → `409` `AMBIGUOUS_TAX_ID_LOOKUP`; use `entityId` ou `externalId`.
</ParamField>

<ParamField body="newExternalId" type="string" required>
  Novo identificador externo (trim no servidor). Não pode estar em uso por outra entidade.
</ParamField>

<ParamField body="reason" type="string" required>
  Motivo de auditoria: mínimo 5 caracteres, máximo 4000.
</ParamField>

## Resposta

* `success`: boolean
* `changed`: `false` se o novo valor for igual ao atual
* `entity`: objeto da entidade após a operação

## Exemplo

```json theme={null}
{
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "newExternalId": "crm_cliente_8842",
  "reason": "Migração CRM — alinhar com ID do sistema de origem"
}
```