Skip to main content
POST
Cambiar ID externo

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

Cuerpo de la petición

Indica exactamente uno de los campos de búsqueda, más el nuevo valor y el motivo.
string (uuid)
UUID interno de la entidad en gu1.
string
Solo búsqueda: el ID externo actual de la entidad (no el nuevo).
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.
string
required
Nuevo identificador externo (se recorta en servidor). No puede estar en uso por otra entidad.
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