POST | Testar conexão do servidor LDAP por [id]

Descrição

Inicie um teste de conexão em um servidor LDAP/AD cadastrado na plataforma Segura™. O teste executa um bind real com a credencial PAM do servidor e, em seguida, uma busca na DN base.

O teste sempre roda em segundo plano. A requisição retorna 202 Accepted com um descritor de job, e o resultado é lido por meio de GET | Listar um job do IAM por [id].

Pré-requisitos

Uma aplicação com a autorização Users concedida pelo administrador no A2A, com a permissão do recurso definida como Leitura e escrita. Para mais informações, acesse Como gerenciar autorizações no A2A.
Um token de acesso OAuth 2.0 válido. Para mais informações, acesse Como autenticar uma aplicação A2A.

Requisição

POST /api/v2/iam/ldap-servers/{id}/test-connection

Parâmetros de caminho

Campo	Tipo	Obrigatório	Descrição
`id`	integer	Sim	Código de identificação único do servidor LDAP. Nota: este valor é atribuído pela Segura™ em POST \| Criar servidor LDAP.

A requisição não leva corpo.

Info

O teste também roda em servidores inativos, então a conexão pode ser verificada antes de o servidor voltar para a cadeia de autenticação.

Exemplo de requisição

POST {{url}}/api/v2/iam/ldap-servers/7/test-connection

Resposta

HTTP/1.1 202 Accepted
Location: /api/v2/iam/jobs/019e0a01-b7b8-7062-82dd-43a8aa0ed6f8

O cabeçalho Location contém o caminho do job criado para este teste.

Exemplo de corpo da resposta

{
    "data": {
        "job": {
            "id": "019e0a01-b7b8-7062-82dd-43a8aa0ed6f8",
            "type": "ldap.test_connection",
            "state": "queued",
            "retry_count": 0,
            "created_at": "2026-05-08 23:52:25",
            "started_at": null,
            "finished_at": null
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/ldap-servers/7/test-connection" }
    }
}

Campos do corpo da resposta

Campo	Tipo	Descrição
`data`	object	A requisição aceita.
`data.job`	object	Job criado para o teste.
`data.job.id`	string	Código de identificação único do job, no formato UUID. Use-o para ler o resultado.
`data.job.type`	string	Tipo do job. Retorna `ldap.test_connection`.
`data.job.state`	string	Estado do job. Um teste recém-aceito retorna `queued`.
`data.job.retry_count`	integer	Número de vezes que o job foi reexecutado.
`data.job.created_at`	datetime	Data e hora de criação do job.
`data.job.started_at`	datetime	Data e hora em que um worker começou a processar o job. Retorna `null` até então.
`data.job.finished_at`	datetime	Data e hora de finalização do job. Retorna `null` até então.
`meta`	object	Metadados da resposta.
`meta.links`	object	Links de navegação para a requisição.
`meta.links.self`	string	Caminho da ação de teste de conexão.

Lendo o resultado

Envie uma requisição GET | Listar um job do IAM por [id] para o caminho em Location até que state seja succeeded ou failed.

Um teste bem-sucedido retorna um objeto result:

Campo	Tipo	Descrição
`bind_ok`	boolean	Indica se o bind teve sucesso.
`base_search_ok`	boolean	Indica se a busca na DN base teve sucesso.
`elapsed_ms`	integer	Tempo que o teste levou, em milissegundos.
`translated_host`	string	Host que a plataforma alcançou.
`translated_port`	integer	Porta que a plataforma alcançou.

Um teste que falha retorna um objeto error cujo code é um dos seguintes.

Código	Descrição
`api.ldap.test_connection.server_not_found`	O registro do servidor foi removido enquanto o job estava na fila.
`api.ldap.test_connection.no_credential`	O servidor não tem credencial PAM para fazer o bind.
`api.ldap.test_connection.credential_decrypt_failed`	Não foi possível descriptografar a credencial de bind.
`api.ldap.test_connection.vault_unavailable`	O vault não respondeu a tempo.
`api.ldap.test_connection.network_connector_unsupported`	O servidor é alcançado por um agente de network connector, que esta versão não consegue testar.
`api.ldap.test_connection.dc_unavailable`	O servidor de diretório não respondeu.
`api.ldap.test_connection.bind_failed`	O bind falhou por um motivo diferente de um diretório inacessível, por exemplo uma credencial recusada, um erro de TLS ou um tempo limite esgotado.
`api.ldap.test_connection.search_failed`	O bind teve sucesso, mas a busca na DN base falhou.

Atenção

Um servidor que alcança o diretório por meio de um agente de network connector, ou seja, um servidor com network_connector_id definido, não pode ser testado nesta versão. O job falha com api.ldap.test_connection.network_connector_unsupported. Todas as demais operações no servidor funcionam normalmente.

Erros

Código HTTP	Mensagem	Causa possível	Solução
`401`	`api.auth.unauthorized`	O token de acesso está ausente ou expirou.	Solicite um novo token de acesso.
`404`	`api.resource.not_found`	O servidor não existe.	Verifique o código de identificação enviado no caminho.
`429`	`api.rate_limit.exceeded`	O limite de requisições foi excedido.	Reduza a frequência de requisições e tente novamente.

A plataforma também responde 503 Service Unavailable (api.service.unavailable) quando a fila de workers em segundo plano está cheia e o teste não pode ser enfileirado. O corpo da resposta informa em details.retry_after o número de segundos a aguardar antes de reenviar a requisição. A partir da versão 4.2.15, a plataforma também envia o mesmo valor no cabeçalho Retry-After.

Info

Uma resposta 202 significa que o teste foi enfileirado, não que a conexão funciona. Leia o job para saber o resultado.

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