--- title: "PUT | Atualizar dispositivo" slug: "api-v2-put-update-device" updated: 2026-11-03T14:47:51Z published: 2026-11-03T14:47:51Z canonical: "docs.senhasegura.io/api-v2-put-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. # PUT | Atualizar dispositivo ## Descrição Substitua a representação completa de um dispositivo cadastrado no PAM Core utilizando a API v2. Este endpoint sobrescreve todos os campos mutáveis do dispositivo: os campos opcionais omitidos na requisição são redefinidos para o valor padrão ou esvaziados. Para alterar apenas alguns campos, acesse [PATCH | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-patch-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. Na v1, atualizar um dispositivo reutilizava o endpoint de criação; a v2 separa a substituição completa (`PUT`) da atualização parcial (`PATCH`). --- ## 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 `PUT` `/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 | | --- | --- | --- | | `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 O corpo tem o mesmo formato e os mesmos campos obrigatórios de [POST | Criar dispositivo (v2)](/v4-2/docs/api-v2-post-create-device): `name`, `address`, `type`, `vendor`, `product` e `site` são obrigatórios, e os campos opcionais são `domain_name`, `tags`, `criticality`, `enable_remote_app`, `network_connector_id`, `administrator_group_id`, `owner`, `connectivities` e `session_settings`. Acesse esse documento para a tabela completa de campos. Os campos somente leitura são ignorados quando enviados: `id`, `active` e `connectable`. O estado ativo é alterado apenas por [POST | Ativar dispositivo (v2)](/v4-2/docs/api-v2-post-activate-device) e [POST | Desativar dispositivo (v2)](/v4-2/docs/api-v2-post-deactivate-device). Atenção O `PUT` substitui o dispositivo por completo. Todo campo opcional omitido é **redefinido**, e não preservado: `tags` e `connectivities` ficam vazios, `enable_remote_app` volta para `false` e `criticality` volta para `medium`. Envie a representação completa ou utilize [PATCH | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-patch-update-device) para alterar campos individuais. A alteração de `name` ou `address` é bloqueada enquanto existir uma sessão ativa do dispositivo no proxy, retornando `409`. --- ### Exemplo de requisição `PUT` `{{url}}/api/v2/platform/devices/55` #### Cabeçalhos ``` Content-Type: application/json If-Match: "v3" ``` #### Corpo ``` { "name": "db-prod-01", "address": "10.10.10.10", "type": "Server", "vendor": "Oracle", "product": "Oracle Linux VM", "site": "SP-DC1", "domain_name": "CORP", "tags": ["prod", "database"], "criticality": "medium", "enable_remote_app": true, "network_connector_id": 12, "owner": "jdoe", "connectivities": [ { "protocol": "SSH", "port": 22 } ] } ``` --- ## 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). No exemplo a seguir, `session_settings` foi omitido na requisição e, por isso, foi redefinido para um array vazio. ``` { "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": "CORP", "tags": ["prod", "database"], "criticality": "medium", "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": [] } }, "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 e o cabeçalho `Content-Type`. | | `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. | | `409` | `api.resource.conflict.duplicate_address` | Outro dispositivo já utiliza o endereço de gerenciamento enviado em `address`. | Utilize um endereço diferente. | | `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. | | `428` | `api.precondition.required` | O cabeçalho `If-Match` está ausente. | Envie o `ETag` atual no cabeçalho `If-Match`. | | `422` | `api.validation.required_field` | Um campo obrigatório está ausente. | Envie `name`, `address`, `type`, `vendor`, `product` e `site`. | | `422` | `api.validation.invalid_reference` | Um tipo, fabricante, modelo, site, domínio, Network Connector ou usuário referenciado não existe, 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 `412` o dispositivo foi alterado depois da leitura: ``` { "error": { "code": "api.precondition.failed", "message": "The If-Match header does not match the current ETag." } } ``` ### 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) - [PATCH | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-patch-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)