--- title: "POST | Criar agente do Network Connector" slug: "api-v2-post-create-network-connector-agent" updated: 2026-11-03T14:47:50Z published: 2026-11-03T14:47:50Z canonical: "docs.senhasegura.io/api-v2-post-create-network-connector-agent" --- > ## 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. # POST | Criar agente do Network Connector ## Descrição Crie um agente do Network Connector enviando apenas o nome. O Segura™ define a porta e retorna o fingerprint usado para instalar o agente. O novo agente é criado ativo. Use o `id` dele no campo `network_connector_id` para vincular um dispositivo ao agente. Cada requisição cria um novo agente. O endpoint não aceita o cabeçalho `Idempotency-Key`, então reenviar a mesma requisição cria outro agente. --- ## Pré-requisitos - Uma aplicação com a **Permissão do recurso PAM** definida como **Leitura e escrita**, concedida pelo administrador no A2A. Para mais informações, acesse [Como gerenciar autorizações no A2A API v2](/v4-2/docs/pt/api-v2-how-to-manage-authorizations-in-a2a). - Um token de acesso OAuth 2.0 válido. Para mais informações, acesse [Como autenticar uma aplicação A2A](/v4-2/docs/pt/how-to-authenticate-an-application-in-a2a). --- ## Requisição `POST` `/api/v2/platform/network-connector/agents` ### Cabeçalhos | Cabeçalho | Obrigatório | Valor | | --- | --- | --- | | `Content-Type` | Sim | `application/json` | ### Corpo da requisição | Campo | Tipo | Obrigatório | Descrição | | --- | --- | --- | --- | | `name` | string | Sim | Nome do agente. Os espaços no início e no fim são removidos. Máximo: 255 caracteres. Precisa ser único entre os agentes do Network Connector, incluindo os desativados. | Envie apenas `name`. O Segura™ define `id`, `port`, `active` e `fingerprint`: enviar qualquer um deles retorna `422`. --- ### Exemplo de requisição `POST` `{{url}}/api/v2/platform/network-connector/agents` ``` { "name": "agent-rj-02" } ``` --- ## Resposta ``` HTTP/1.1 201 Created ``` A resposta inclui estes cabeçalhos: - `Location`: caminho do novo agente. - `ETag`: versão do estado atual do agente. Envie-o no cabeçalho `If-Match` de [PUT | Atualizar agente do Network Connector](/v4-2/docs/pt/api-v2-put-update-network-connector-agent) ou de [PATCH | Atualizar agente do Network Connector](/v4-2/docs/pt/api-v2-patch-update-network-connector-agent). ### Exemplo de corpo da resposta ``` { "data": { "id": "12", "network_connector_agent": { "name": "agent-rj-02", "port": "30003", "active": true, "fingerprint": "EXAMPLE-FINGERPRINT-0003" } }, "meta": { "links": { "self": "/api/v2/platform/network-connector/agents/12" }, "actions": { "deactivate": "/api/v2/platform/network-connector/agents/12/deactivate" } } } ``` --- ## Campos do corpo da resposta | Campo | Tipo | Descrição | | --- | --- | --- | | `data` | object | O agente criado. | | `data.id` | string | Código de identificação único do agente, retornado como string. Use-o no caminho dos outros endpoints de agente. Para vincular um dispositivo, envie-o como número inteiro no campo `network_connector_id` do dispositivo. | | `data.network_connector_agent` | object | Atributos do agente. | | `data.network_connector_agent.name` | string | Nome do agente, sem os espaços no início e no fim. | | `data.network_connector_agent.port` | string | Porta definida pelo Segura™ para o agente, retornada como string. | | `data.network_connector_agent.active` | boolean | Sempre `true` para um novo agente. | | `data.network_connector_agent.fingerprint` | string | Valor usado para instalar o agente. Guarde-o com segurança e compartilhe-o apenas com quem vai instalar o agente. | | `meta` | object | Links de navegação e ações disponíveis. | | `meta.links.self` | string | Caminho do agente criado. | | `meta.actions.deactivate` | string | Caminho para desativar o agente. Para mais informações, acesse [POST \| Desativar agente do Network Connector](/v4-2/docs/pt/api-v2-post-deactivate-network-connector-agent). | --- ## Erros | Código HTTP | Mensagem | Causa possível | Solução | | --- | --- | --- | --- | | `400` | `api.request.bad_request` | O corpo não é um JSON válido. | Confira a sintaxe do payload. | | `403` | `api.auth.insufficient_permission` | A **Permissão do recurso PAM** da aplicação é **Apenas leitura**. | Peça ao administrador para definir a **Permissão do recurso PAM** como **Leitura e escrita** no A2A. | | `404` | `api.resource.not_found` | O Network Connector não existe no ambiente. | Verifique se o Network Connector está configurado no Segura™. | | `415` | `api.request.unsupported_media_type` | O cabeçalho `Content-Type` não é `application/json`. | Envie `Content-Type: application/json`. | | `422` | `api.validation.required_field` | `name` está ausente, vazio ou contém apenas espaços. | Envie um nome para o agente. | | `422` | `api.validation.invalid_type` | `name` não é uma string. | Envie `name` como string. | | `422` | `api.validation.invalid_value` | `name` tem mais de 255 caracteres. | Envie um nome com até 255 caracteres. | | `422` | `api.validation.duplicate` | Outro agente, ativo ou desativado, já usa o nome. | Escolha outro nome. Para ver os nomes em uso, acesse [GET \| Listar todos os agentes do Network Connector](/v4-2/docs/pt/api-v2-get-list-all-network-connector-agents) com `active=true` e com `active=false`. | | `422` | `patch.field.not_allowed` | O corpo contém `id`, `port`, `active` ou `fingerprint`. | Envie apenas `name`. | | `422` | `api.validation.unknown_field` | O corpo contém um campo que não faz parte do contrato. | Envie apenas `name`. | | `503` | `network_connector.port_allocation_failed` | O Segura™ não conseguiu definir uma porta para o agente. O agente não é criado. | Aguarde o número de segundos indicado no cabeçalho `Retry-After` e reenvie a requisição. | | `503` | `network_connector.broker_unavailable` | O serviço do Network Connector está temporariamente indisponível. O agente não é criado. | Aguarde o número de segundos indicado no cabeçalho `Retry-After` e reenvie a requisição. Se o erro persistir, entre em contato com o time de suporte do Segura™. | | `503` | `network_connector.credential_unavailable` | O Segura™ não conseguiu concluir a criação. O agente não é criado. | Aguarde o número de segundos indicado no cabeçalho `Retry-After` e reenvie a requisição. Se o erro persistir, entre em contato com o time de suporte do Segura™. | Para erros de autenticação, limites de requisição e o formato da resposta de erro, acesse [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/pt/api-v2-conventions-and-shared-behaviors). ### Exemplo de resposta de erro `422` outro agente já usa o nome: ``` { "code": "api.validation.duplicate", "message": "A network connector agent with this name already exists.", "details": [ { "field": "name", "code": "api.validation.duplicate" } ] } ``` --- ## Documentos relacionados - [GET | Listar todos os agentes do Network Connector](/v4-2/docs/pt/api-v2-get-list-all-network-connector-agents) - [GET | Listar um agente do Network Connector por [id]](/v4-2/docs/pt/api-v2-get-list-a-network-connector-agent) - [PATCH | Atualizar agente do Network Connector](/v4-2/docs/pt/api-v2-patch-update-network-connector-agent) - [POST | Desativar agente do Network Connector](/v4-2/docs/pt/api-v2-post-deactivate-network-connector-agent) - [API v2 - Convenções e comportamentos compartilhados](/v4-2/docs/pt/api-v2-conventions-and-shared-behaviors) - [Como gerenciar autorizações no A2A API v2](/v4-2/docs/pt/api-v2-how-to-manage-authorizations-in-a2a)