---
title: "PATCH | Atualizar dispositivo"
slug: "api-v2-patch-update-device"
updated: 2026-11-03T14:47:51Z
published: 2026-11-03T14:47:51Z
canonical: "docs.senhasegura.io/api-v2-patch-update-device"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.senhasegura.io/llms.txt
> Use this file to discover all available pages before exploring further.

# PATCH | Atualizar dispositivo

## Descrição

Atualize campos específicos de um dispositivo cadastrado no PAM Core utilizando a API v2. O endpoint segue a semântica JSON Merge Patch (RFC 7396): apenas os campos enviados são alterados, e os campos omitidos são preservados. Para substituir o dispositivo por completo, acesse [PUT | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-put-update-device).

              Info

              

Este endpoint faz parte da superfície da API v2 do A2A e está disponível a partir da versão 4.2.9 do Segura™. Os dispositivos são servidos pelo caminho base `/api/v2/platform`, e não por `/api/v2/pam` como os demais recursos v2. Não há equivalente v1: a v1 não oferecia atualização parcial.

---

## Pré-requisitos

- Autorização com permissão de **escrita** para o PAM Core, concedida pelo administrador no A2A. Para mais informações, acesse [Como gerenciar autorizações no A2A API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a).
- O `ETag` atual do dispositivo, obrigatório no cabeçalho `If-Match`. Obtenha-o em [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device).
- O dispositivo precisa estar ativo. Operações de escrita em um dispositivo inativo retornam `409`. Para ativá-lo, acesse [POST | Ativar dispositivo (v2)](/v4-2/docs/api-v2-post-activate-device).

---

## Requisição

`PATCH` `/api/v2/platform/devices/{id}`

### Parâmetros de caminho

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `id` | integer | Sim | Código de identificação único do dispositivo. **Nota:** este valor é atribuído pelo Segura™ em [POST \| Criar dispositivo (v2)](/v4-2/docs/api-v2-post-create-device). |

### Cabeçalhos

| Cabeçalho | Obrigatório | Descrição |
| --- | --- | --- |
| `Content-Type` | Sim | Precisa ser `application/merge-patch+json`. Qualquer outro tipo de mídia retorna `415`. |
| `If-Match` | Sim | `ETag` atual do dispositivo, para controle de concorrência otimista. A ausência do cabeçalho retorna `428`; um valor que não corresponde mais ao estado atual retorna `412`. |

### Corpo da requisição

Todos os campos são opcionais. Um campo enviado substitui o valor atual; um campo enviado como `null` remove o valor; um campo omitido permanece inalterado. Os campos de array são substituídos por completo, e não mesclados item a item.

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `name` | string | Nome que identifica o dispositivo. Bloqueado enquanto existir uma sessão ativa do dispositivo no proxy. |
| `address` | string | Endereço IP, hostname ou URL de gerenciamento. Bloqueado enquanto existir uma sessão ativa do dispositivo no proxy. |
| `type` | string | Tipo do dispositivo, por nome. Precisa ser um tipo cadastrado. |
| `vendor` | string | Fabricante do dispositivo, por nome. Precisa ser um fabricante cadastrado. |
| `product` | string | Modelo do dispositivo, por nome. Precisa ser um modelo cadastrado e vinculado ao fabricante. |
| `site` | string | Site onde o dispositivo está localizado, por nome. Precisa ser um site cadastrado. |
| `domain_name` | string | Domínio associado ao dispositivo, por nome. Envie `null` para removê-lo. |
| `tags` | array[string] | Tags associadas ao dispositivo. Substitui a lista completa. |
| `criticality` | string | Nível de criticidade. Valores permitidos: `low`, `medium`, `high`. Envie `null` para removê-lo. |
| `enable_remote_app` | boolean | Habilita o suporte a aplicação remota para o dispositivo. |
| `network_connector_id` | integer | Código de identificação do agent do Network Connector. Envie `null` para remover a associação. A resposta o expande em um objeto. |
| `administrator_group_id` | integer | Código de identificação do grupo administrador. Válido **apenas** quando o modo de política de acesso é estático por dispositivo; enviá-lo no modo de política dinâmica retorna `422`. Envie `null` para removê-lo. |
| `owner` | string | Nome de usuário do usuário cadastrado responsável pelo dispositivo. Envie `null` para removê-lo. |
| `connectivities` | array de objetos | Protocolos de conectividade, no formato `{ protocol, port }`. Substitui a lista completa. Protocolos permitidos: `SSH`, `RDP`, `HTTPS`, `VNC`, `Telnet`, `SQL_Server`. |
| `session_settings` | array de objetos | Configurações de automação de sessão, no formato `{ connectivity, expected_expression, fill_in_value }`. Substitui a lista completa. O `connectivity` precisa corresponder a um protocolo presente em `connectivities`. |

              Atenção

              

Os campos `id` e `active` não podem ser alterados por este endpoint e retornam `422` (`patch.field.not_allowed`). Altere o estado ativo com [POST | Ativar dispositivo (v2)](/v4-2/docs/api-v2-post-activate-device) ou [POST | Desativar dispositivo (v2)](/v4-2/docs/api-v2-post-deactivate-device).

---

### Exemplo de requisição

`PATCH` `{{url}}/api/v2/platform/devices/55`

#### Cabeçalhos

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

#### Corpo

```
{
    "criticality": "low",
    "tags": ["prod", "finance", "critical"],
    "domain_name": null
}
```

---

## Resposta

```
HTTP/1.1 200 OK
ETag: "v4"
```

O cabeçalho `ETag` traz a nova versão do dispositivo. Utilize este valor no cabeçalho `If-Match` da próxima operação de escrita.

### Exemplo de corpo da resposta

A resposta retorna o dispositivo completo, no mesmo formato de [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device), inclusive os campos que a requisição não alterou.

```
{
    "data": {
        "id": "55",
        "device": {
            "name": "db-prod-01",
            "address": "10.10.10.10",
            "active": true,
            "type": "Server",
            "vendor": "Oracle",
            "product": "Oracle Linux VM",
            "site": "SP-DC1",
            "domain_name": null,
            "tags": ["prod", "finance", "critical"],
            "criticality": "low",
            "owner": {
                "name": "John Doe"
            },
            "administrator_group": null,
            "enable_remote_app": true,
            "network_connector": {
                "id": "12",
                "name": "NC-SP-01",
                "port": "50001"
            },
            "connectivities": [
                {
                    "protocol": "SSH",
                    "port": 22,
                    "connectable": true
                }
            ],
            "session_settings": [
                {
                    "connectivity": "SSH",
                    "expected_expression": "$",
                    "fill_in_value": "sudo su"
                }
            ]
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/platform/devices/55"
        },
        "actions": {
            "deactivate": "/api/v2/platform/devices/55/deactivate"
        }
    }
}
```

---

## Campos do corpo da resposta

A resposta retorna o dispositivo atualizado com os mesmos campos de [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device). Acesse esse documento para as tabelas completas de campos.

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `data` | object | O dispositivo atualizado. |
| `data.id` | string | Código de identificação único do dispositivo. |
| `data.device` | object | Atributos canônicos do dispositivo após a atualização. |
| `meta` | object | Links de navegação e ações disponíveis. |
| `meta.links.self` | string | URL do dispositivo. |
| `meta.actions` | object | Ações disponíveis para o dispositivo em seu estado atual. |

---

## Erros

| Código HTTP | Mensagem | Causa possível | Solução |
| --- | --- | --- | --- |
| `400` | `api.request.malformed` | O corpo não é um JSON válido. | Verifique a sintaxe do payload. |
| `401` | `api.auth.token.invalid` | O token de acesso está ausente ou expirou. | Solicite um novo token de acesso. |
| `403` | `api.permission.denied` | A autorização não tem permissão de escrita para os recursos do PAM Core. | Peça ao administrador para verificar as permissões da autorização no A2A e gere um novo token. |
| `404` | `api.resource.not_found` | O dispositivo não existe ou pertence a outro tenant. | Verifique o código de identificação enviado no caminho. |
| `409` | `api.resource.conflict.active_sessions` | Existe uma sessão ativa do dispositivo no proxy, o que bloqueia alterações em `name` e `address`. | Aguarde o encerramento da sessão, ou encerre-a, e reenvie a requisição. |
| `409` | `api.resource.inactive` | O dispositivo está inativo, portanto operações de escrita não são permitidas. | Ative o dispositivo com [POST \| Ativar dispositivo (v2)](/v4-2/docs/api-v2-post-activate-device) e reenvie a requisição. |
| `412` | `api.precondition.failed` | O valor de `If-Match` não corresponde ao `ETag` atual: o dispositivo foi alterado depois da sua leitura. | Consulte o dispositivo novamente para obter o `ETag` atual, reaplique suas alterações e reenvie a requisição. |
| `415` | `Unsupported Media Type` | O cabeçalho `Content-Type` não é `application/merge-patch+json`. | Envie o tipo de mídia correto. |
| `428` | `api.precondition.required` | O cabeçalho `If-Match` está ausente. | Envie o `ETag` atual no cabeçalho `If-Match`. |
| `422` | `patch.field.not_allowed` | O corpo inclui `id` ou `active`. | Remova o campo. Utilize as ações de ativar e desativar para alterar o estado. |
| `422` | `api.validation.invalid_reference` | Um tipo, fabricante, modelo, site, domínio, Network Connector ou usuário referenciado não existe; um protocolo de `session_settings` não está declarado em `connectivities`; ou o `administrator_group_id` foi enviado com o modo de política de acesso dinâmico. | Cadastre o valor antes ou remova o campo. Consulte `error.details` para identificar o campo. |
| `422` | `api.enum.invalid_value` | O `criticality` recebeu um valor fora de `low`, `medium`, `high`. | Envie um dos valores permitidos. |
| `429` | `rate_limit_exceeded` | O limite de requisições foi excedido. | Aguarde o número de segundos indicado no cabeçalho `Retry-After` e tente novamente. |
| `500` | `api.internal.error` | Erro interno do servidor. | Entre em contato com a equipe de suporte da Segura™. |

### Exemplo de resposta de erro

`422` um campo proibido foi enviado no corpo:

```
{
    "error": {
        "code": "patch.field.not_allowed",
        "message": "Field 'active' cannot be modified via PATCH."
    }
}
```

### Erros de autenticação

| Mensagem | Causa possível | Solução |
| --- | --- | --- |
| `Client authentication failed.` | Falha na autenticação da aplicação com o servidor Segura™. | Verifique os parâmetros de autenticação (`Access Token URL`, `Client ID` e `Client secret`) e solicite um novo token de acesso. |
| `Invalid signature` | Falha no reconhecimento da URL da aplicação cliente. | Verifique a URL da aplicação cliente e reenvie a requisição. |
| `No route matched with those values.` | Cabeçalho de autorização ausente na requisição da API. | Solicite um novo token de acesso. |
| `Request timed out.` | A requisição excedeu o limite de tempo. | Verifique a conectividade entre a origem da requisição e o servidor Segura™. |

---

## Documentos relacionados

- [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors)
- [PUT | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-put-update-device)
- [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device)
- [POST | Criar dispositivo (v2)](/v4-2/docs/api-v2-post-create-device)
- [Como gerenciar autorizações no A2A API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)