GET | Listar o Network Connector

Descrição

Obtenha a configuração do Network Connector e a lista dos seus agentes ativos.

O Segura® tem um único Network Connector, por isso este endpoint não recebe identificador. A resposta também lista os agentes ativos do connector, com os códigos de identificação e os nomes.

Atenção

O campo network_connector_id de um dispositivo recebe o código de identificação de um agente, não do connector. Use um id de data.network_connector.agents, nunca o data.id. Para listar também a porta de cada agente, acesse GET | Listar todos os agentes do Network Connector.

Pré-requisitos

Uma aplicação com a Permissão do recurso PAM definida como Apenas leitura ou Leitura e escrita, 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.

Requisição

GET /api/v2/platform/network-connector

Parâmetros de query

Este endpoint aceita apenas o parâmetro fields. Ele não tem paginação, filtros, ordenação nem busca. Qualquer outro parâmetro de query retorna 400.

Campo	Tipo	Descrição
`fields`	string	Restringe a resposta aos campos listados. Aceita `id`, `network_connector` para o objeto inteiro ou qualquer campo `network_connector.*` de Campos do corpo da resposta. O campo `id` é sempre retornado. Envie `fields` apenas uma vez por requisição.

Para a sintaxe completa de projeção de campos, acesse API v2 - Convenções e comportamentos compartilhados.

Exemplo de requisição

GET {{url}}/api/v2/platform/network-connector

Resposta

HTTP/1.1 200 OK

O endpoint aceita leituras condicionais. Envie no cabeçalho If-None-Match o valor de ETag de uma resposta anterior. Se o connector não mudou, a resposta é 304 Not Modified, sem corpo.

Exemplo de corpo da resposta

{
    "data": {
        "id": "1",
        "network_connector": {
            "name": "Network Connector",
            "ip": "192.0.2.10",
            "port": "30000",
            "active": true,
            "username": "nc-service",
            "has_password": true,
            "created_at": null,
            "updated_at": "2026-09-15T14:32:10+00:00",
            "agents": [
                {
                    "id": "2",
                    "name": "agent-rj-01"
                },
                {
                    "id": "5",
                    "name": "agent-sp-01"
                }
            ]
        }
    },
    "meta": {
        "links": {
            "self": "/api/v2/platform/network-connector"
        }
    }
}

Campos do corpo da resposta

Campo	Tipo	Descrição
`data`	object	O Network Connector.
`data.id`	string	Código de identificação único do Network Connector, retornado como string. Não é o valor que o campo `network_connector_id` de um dispositivo aceita.
`data.network_connector`	object	Atributos do Network Connector.
`data.network_connector.name`	string	Nome do Network Connector.
`data.network_connector.ip`	string	Endereço IP do Network Connector.
`data.network_connector.port`	string	Porta do Network Connector, retornada como string. Pode ser `null`.
`data.network_connector.active`	boolean	Indica se o Network Connector está ativo.
`data.network_connector.username`	string	Nome de usuário do Network Connector.
`data.network_connector.has_password`	boolean	Retorna `true` quando o Network Connector tem senha cadastrada. A senha nunca é retornada.
`data.network_connector.created_at`	string	Data e hora de criação, no formato ISO 8601 e em UTC. Exemplo: `2026-09-15T14:32:10+00:00`. Pode ser `null`.
`data.network_connector.updated_at`	string	Data e hora da última alteração, no formato ISO 8601 e em UTC. Pode ser `null`.
`data.network_connector.agents`	array de objetos	Agentes ativos do Network Connector, ordenados por nome e depois por código de identificação. Retorna um array vazio quando não há agente ativo, nunca `null`.
`data.network_connector.agents[].id`	string	Código de identificação único do agente, retornado como string. Use este valor no campo `network_connector_id` de um dispositivo.
`data.network_connector.agents[].name`	string	Nome do agente.
`meta`	object	Metadados da resposta.
`meta.links.self`	string	URL da requisição atual.

Erros

Código HTTP	Mensagem	Causa possível	Solução
`400`	`api.request.invalid_param`	A requisição enviou um parâmetro de query diferente de `fields` ou enviou `fields` mais de uma vez.	Remova os parâmetros extras e envie `fields` apenas uma vez.
`403`	`api.fields.sensitive.not_allowed`	O parâmetro `fields` pediu `network_connector.password`, que nunca é retornado.	Remova o campo de `fields`. Para saber se há senha cadastrada, peça `network_connector.has_password`.
`404`	Sem código específico	O Network Connector não existe no ambiente.	Verifique se o Network Connector está configurado no Segura®.
`422`	`api.fields.invalid`	O parâmetro `fields` pediu um campo que não existe.	Confira os nomes dos campos em Campos do corpo da resposta.

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