Skip to main content
POST
Cambiar ID externo de una empresa

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 las referencias en transacciones (origin_external_id / destination_external_id) y user events (entity_external_id, incluidas las filas ligadas por entity_id). La ficha se guarda en el momento. El historial se actualiza por lotes cortos, así un volumen grande no bloquea el request. externalIdPropagation vale done si esa reescritura terminó antes de la respuesta, o running si sigue. Las transacciones nuevas ya usan el ID nuevo. Las filas viejas que todavía tienen el ID anterior se alcanzan mientras el campo está en running.
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
  • externalIdPropagation: solo si changed es true. done si el historial de transacciones y eventos ya usa el ID nuevo. running si la ficha ya cambió y el historial sigue actualizándose. Las transacciones nuevas usan el ID nuevo en ambos casos.

Ejemplo