Skip to main content
POST
/
entities
/
change-external-id
Cambiar ID externo
curl --request POST \
  --url http://api.gu1.ai/entities/change-external-id \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "entityId": {},
  "externalId": "<string>",
  "taxId": "<string>",
  "newExternalId": "<string>",
  "reason": "<string>"
}
'

​
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.
​
entityId
string (uuid)
UUID interno de la entidad en gu1.
​
externalId
string
Solo búsqueda: el ID externo actual de la entidad (no el nuevo).
​
taxId
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.
​
newExternalId
string
required
Nuevo identificador externo (se recorta en servidor). No puede estar en uso por otra entidad.
​
reason
string
required
Motivo de auditoría: mínimo 5 caracteres, máximo 4000.

​
Respuesta

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

​
Ejemplo

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