--- title: "GET | Listar status de conexão do dispositivo" slug: "api-v2-get-device-connection-status" updated: 2026-11-03T14:47:51Z published: 2026-11-03T14:47:51Z canonical: "docs.senhasegura.io/api-v2-get-device-connection-status" --- > ## 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. # GET | Listar status de conexão do dispositivo ## Descrição Acesse o resultado do teste de conectividade mais recente de cada protocolo configurado em um dispositivo cadastrado no PAM Core, utilizando a API v2. A resposta informa um resultado por protocolo, incluindo quando o teste foi executado e o motivo de eventual falha. 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: na v1, os resultados de conectividade estavam disponíveis apenas por protocolo, dentro da resposta do dispositivo. --- ## Pré-requisitos - Autorização com permissão de **leitura** 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). - Um dispositivo existente com ao menos um protocolo de conectividade configurado. Para configurar conectividades, acesse [POST | Criar dispositivo (v2)](/v4-2/docs/api-v2-post-create-device) ou [PATCH | Atualizar dispositivo (v2)](/v4-2/docs/api-v2-patch-update-device). --- ## Requisição `GET` `/api/v2/platform/devices/{id}/connection-status` ### 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), que o retorna como string no corpo da resposta. | --- ### Exemplo de requisição `GET` `{{url}}/api/v2/platform/devices/55/connection-status` --- ## Resposta ``` HTTP/1.1 200 OK ``` A resposta traz o cabeçalho `X-Request-Id`, que correlaciona a requisição nos logs do Segura™. ### Exemplo de corpo da resposta ``` { "data": { "id": "55", "results": [ { "protocol": "SSH", "port": 22, "connectable": true, "tested_at": "2026-06-22T10:00:00-03:00", "message": null }, { "protocol": "RDP", "port": 3389, "connectable": false, "tested_at": "2026-06-22T09:55:00-03:00", "message": "Connection refused" } ] }, "meta": { "links": { "self": "/api/v2/platform/devices/55/connection-status" } } } ``` --- ## Campos do corpo da resposta | Campo | Tipo | Descrição | | --- | --- | --- | | `data` | object | Status de conexão do dispositivo. | | `data.id` | string | Código de identificação único do dispositivo. | | `data.results` | array de objetos | Resultado do teste de conectividade mais recente de cada protocolo configurado no dispositivo. | | `data.results[].protocol` | string | Protocolo de conectividade testado. Valores possíveis: `SSH`, `RDP`, `HTTPS`, `VNC`, `Telnet`, `SQL_Server`. | | `data.results[].port` | integer | Porta utilizada pelo protocolo. Retorna `null` quando nenhuma porta foi registrada para o teste. | | `data.results[].connectable` | boolean | Indica se o dispositivo respondeu neste protocolo no teste mais recente. | | `data.results[].tested_at` | string | Data e hora em que o teste foi executado, no formato ISO 8601. Exemplo: `2026-06-22T10:00:00-03:00`. Retorna `null` quando o protocolo nunca foi testado. | | `data.results[].message` | string | Motivo informado quando o teste falhou. Exemplo: `Connection refused`. Retorna `null` quando o teste foi bem-sucedido. | | `meta` | object | Links de navegação. | | `meta.links` | object | Links de navegação da requisição. | | `meta.links.self` | string | URL da requisição atual. | Info Este endpoint informa o resultado do último teste executado; ele não inicia um novo teste. O mesmo valor de `connectable` também está disponível por protocolo em `device.connectivities[].connectable` em [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device), sem o horário e a mensagem de falha. --- ## Erros | Código HTTP | Mensagem | Causa possível | Solução | | --- | --- | --- | --- | | `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 leitura 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 `id`. Para a política de `403` versus `404`, acesse [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/api-v2-conventions-and-shared-behaviors). | | `500` | `api.internal.error` | Erro interno do servidor. | Entre em contato com a equipe de suporte da Segura™. | ### Exemplo de resposta de erro `404` o dispositivo não existe ou está fora do escopo da autorização: ``` { "error": { "code": "api.resource.not_found", "message": "The requested resource does not exist or is not accessible." } } ``` ### 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) - [GET | Listar um dispositivo (v2)](/v4-2/docs/api-v2-get-list-a-device) - [GET | Listar todos os dispositivos (v2)](/v4-2/docs/api-v2-get-list-all-devices) - [Como gerenciar autorizações no A2A API v2](/v4-2/docs/api-v2-how-to-manage-authorizations-in-a2a)