Skip to main content
POST
Alterar ID externo de uma empresa

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 as referências em transações (origin_external_id / destination_external_id) e user events (entity_external_id, inclusive as linhas ligadas por entity_id). A ficha é gravada na hora. O histórico é atualizado em lotes curtos, então um volume grande não bloqueia o request. externalIdPropagation vale done se essa reescrita terminou antes da resposta, ou running se continua. Transações novas já usam o ID novo. Linhas antigas que ainda têm o ID anterior são alcançadas enquanto o campo está running.
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
  • externalIdPropagation: só quando changed é true. done se o histórico de transações e eventos já usa o ID novo. running se a ficha já mudou e o histórico ainda está sendo atualizado. Transações novas usam o ID novo nos dois casos.

Exemplo