Skip to main content
POST
/
entities
/
change-external-id
Alterar 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>"
}
'

​
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

POST https://api.gu1.ai/entities/change-external-id

​
Corpo da requisição

Envie exatamente um campo de localização, mais o novo valor e o motivo.
​
entityId
string (uuid)
UUID interno da entidade na gu1.
​
externalId
string
Apenas busca: o ID externo atual da entidade (não o novo).
​
taxId
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.
​
newExternalId
string
required
Novo identificador externo (trim no servidor). Não pode estar em uso por outra entidade.
​
reason
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

{
  "entityId": "550e8400-e29b-41d4-a716-446655440000",
  "newExternalId": "crm_cliente_8842",
  "reason": "Migração CRM — alinhar com ID do sistema de origem"
}