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

# Cambiar ID externo de una persona

> Asigna un nuevo identificador externo a una persona en gu1 con motivo de auditoría obligatorio; actualiza referencias desnormalizadas en eventos.

## Descripción

Este endpoint cambia el **external ID** de una entidad. No es posible hacerlo con `PATCH /entities/:id`, `PATCH /entities/by-external-id/:externalId` ni `PATCH /entities/by-tax-id/:taxId` (esos cuerpos **ignoran** `externalId`).

* Comprueba unicidad del nuevo ID en la organización.
* Actualiza la fila de la entidad.
* Si el ID anterior no estaba vacío y cambia, actualiza referencias en **transacciones** y **user events** en la misma transacción de base de datos.

El campo **reason** es obligatorio (mínimo 5 caracteres). El cambio se audita (metadatos: `externalIdChangeReason`, `source: change_external_id_endpoint`).

## Endpoint

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

## Cuerpo de la petición

Indica **exactamente uno** de los campos de búsqueda, más el nuevo valor y el motivo.

<ParamField body="entityId" type="string (uuid)">
  UUID interno de la entidad en gu1.
</ParamField>

<ParamField body="externalId" type="string">
  **Solo búsqueda**: el ID externo **actual** de la entidad (no el nuevo).
</ParamField>

<ParamField body="taxId" type="string">
  **Solo búsqueda**: tax ID de una entidad que ya tenga tax ID guardado y no vacío. Si hay varias coincidencias → `409` `AMBIGUOUS_TAX_ID_LOOKUP`; usar `entityId` o `externalId`.
</ParamField>

<ParamField body="newExternalId" type="string" required>
  Nuevo identificador externo (se recorta en servidor). No puede estar en uso por otra entidad.
</ParamField>

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

## Respuesta

* `success`: boolean
* `changed`: `false` si el nuevo valor es igual al actual (sin cambios)
* `entity`: objeto entidad actualizado

## Ejemplo

```json theme={null}
{
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "newExternalId": "crm_cliente_8842",
  "reason": "Migración CRM — alinear con ID del sistema origen"
}
```