PATCH | Atualizar parcialmente grupo de usuários

Descrição

Altere atributos selecionados de um grupo de usuários. O corpo da requisição segue o formato JSON Merge Patch e lista apenas os campos a alterar, então todo campo omitido mantém o valor atual.

A requisição exige o cabeçalho If-Match, que protege o grupo contra alterações concorrentes. Para substituir o recurso completo, acesse PUT | Atualizar grupo de usuários.

Pré-requisitos

Uma aplicação com a autorização Users concedida pelo administrador no A2A. Para mais informações, acesse Como gerenciar autorizações no A2A API v2.
Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação A2A.
A entity tag atual do grupo, retornada no cabeçalho ETag por GET | Consultar um grupo de usuários.
O grupo deve estar ativo. Um grupo inativo é recusado, acesse POST | Ativar grupo de usuários antes.

Requisição

PATCH /api/v2/iam/user-groups/{id}

Parâmetros de path

Parâmetro	Tipo	Obrigatório	Descrição
`id`	integer	Sim	Código de identificação único do grupo de usuários.

Cabeçalhos

Cabeçalho	Obrigatório	Descrição
`Content-Type`	Sim	Deve ser `application/merge-patch+json`. A plataforma retorna `415` para qualquer outro tipo de mídia, inclusive `application/json`.
`If-Match`	Sim	Entity tag do grupo, conforme retornada pela requisição `GET` mais recente. A plataforma retorna `412` quando o valor está desatualizado e `428` quando o cabeçalho está ausente.

Corpo da requisição

Campo	Tipo	Obrigatório	Descrição
`name`	string	Não	Novo nome do grupo de usuários. Limitado a 100 caracteres e deve ser único em toda a plataforma.
`description`	string	Não	Nova descrição do grupo de usuários. Limitada a 512 caracteres.

Atenção

Os campos id, active, external_id, tenant_code, created_at e updated_at são recusados com patch.field.not.allowed. Mudanças de estado passam pelas ações de ativação e desativação, e o external_id é gerenciado pela sincronização LDAP, então enviá-lo quebraria o vínculo com o grupo externo.

Exemplo de requisição

PATCH {{url}}/api/v2/iam/user-groups/7

Cabeçalhos

Content-Type: application/merge-patch+json
If-Match: "v2"

Corpo

{
  "description": "Finance team group, reviewed in April."
}

Resposta

HTTP/1.1 200 OK
ETag: "v3"
X-Request-Id: 7f3c1a90-2c4e-4b1a-9f5e-0a2b7c9d1e34

O cabeçalho ETag carrega a nova entity tag. Use esse valor no cabeçalho If-Match da próxima atualização ou exclusão.

Exemplo de corpo de resposta

{
  "data": {
    "id": "7",
    "user_group": {
      "name": "Payments - Administrators",
      "active": true,
      "description": "Finance team group, reviewed in April.",
      "external_id": null,
      "created_at": "2026-04-01T12:00:00+00:00",
      "updated_at": "2026-04-18T08:20:00+00:00"
    }
  },
  "meta": {
    "links": {
      "self": "/api/v2/iam/user-groups/7"
    },
    "actions": {
      "deactivate": "/api/v2/iam/user-groups/7/deactivate"
    }
  }
}

Campos do corpo de resposta

Campo	Tipo	Descrição
`data`	object	O grupo de usuários atualizado.
`data.id`	string	Código de identificação único do grupo de usuários, atribuído pela Segura™.
`data.user_group`	object	Atributos do grupo de usuários, incluindo os campos não alterados.
`data.user_group.name`	string	Nome do grupo de usuários.
`data.user_group.active`	boolean	Indica se o grupo de usuários está ativo.
`data.user_group.description`	string	Descrição do grupo de usuários.
`data.user_group.external_id`	string	Identificador externo do grupo na origem LDAP ou Active Directory.
`data.user_group.created_at`	datetime	Data e hora de criação do grupo de usuários.
`data.user_group.updated_at`	datetime	Data e hora desta alteração.
`meta`	object	Metadados do recurso.
`meta.links.self`	string	Caminho do grupo de usuários.
`meta.actions`	object	Ações disponíveis para o grupo em seu estado atual.

Erros

Código HTTP	Mensagem	Possível causa	Solução
`400`	`api.request.bad_request`	O corpo da requisição não é um JSON válido.	Verifique a sintaxe do corpo e reenvie a requisição.
`401`	`api.auth.unauthorized`	O token de acesso está ausente, inválido ou expirou.	Solicite um novo token de acesso.
`404`	`api.resource.not_found`	O grupo de usuários não existe, ou está fora do escopo da autorização.	Verifique o código de identificação e o escopo da autorização.
`409`	`api.resource.inactive`	O grupo de usuários está inativo.	Ative o grupo e tente novamente.
`412`	`api.precondition.failed`	O valor de `If-Match` não corresponde à entity tag atual, então outra alteração foi aplicada antes.	Envie uma nova requisição `GET`, obtenha a entity tag atualizada e tente novamente.
`415`	`api.request.unsupported_media_type`	O cabeçalho `Content-Type` não é `application/merge-patch+json`.	Envie o cabeçalho com `application/merge-patch+json` e tente novamente.
`422`	`patch.field.not.allowed`	O corpo contém `id`, `active`, `external_id`, `tenant_code`, `created_at` ou `updated_at`.	Envie apenas `name` ou `description`.
`422`	`api.validation.unknown_field`	O corpo contém um campo que o grupo de usuários não tem.	Envie apenas `name` ou `description`.
`422`	`api.validation.unique`	Outro grupo de usuários já usa esse nome.	Escolha um nome diferente.
`422`	`api.validation.length_exceeded`	O `name` excede 100 caracteres ou a `description` excede 512 caracteres.	Reduza o valor e reenvie a requisição.
`428`	`api.precondition.required`	O cabeçalho `If-Match` não foi enviado.	Envie uma nova requisição `GET`, obtenha a entity tag e tente novamente com o cabeçalho.
`429`	`api.rate_limit_exceeded`	O limite de requisições foi excedido.	Aguarde o número de segundos retornado no cabeçalho `Retry-After` e tente novamente.

Para as mensagens de erro de autenticação e a política de 403 versus 404, acesse API v2 - Convenções e comportamentos compartilhados.