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.
Um dispositivo existente com ao menos um protocolo de conectividade configurado. Para configurar conectividades, acesse POST | Criar dispositivo (v2) ou PATCH | Atualizar dispositivo (v2).

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), 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), 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.
`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®.