Skip to main content
POST
Alterar ID externo

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

Corpo da requisição

Envie exatamente um campo de localização, mais o novo valor e o motivo.
string (uuid)
UUID interno da entidade na gu1.
string
Apenas busca: o ID externo atual da entidade (não o novo).
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.
string
required
Novo identificador externo (trim no servidor). Não pode estar em uso por outra entidade.
string
required
Motivo de auditoria: mínimo 5 caracteres, máximo 4000.

Resposta

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

Exemplo