--- title: "POST | Testar conexão do servidor LDAP por [id]" slug: "api-v2-post-test-ldap-server-connection" updated: 2026-11-03T14:57:57Z published: 2026-11-03T14:57:57Z canonical: "docs.senhasegura.io/api-v2-post-test-ldap-server-connection" --- > ## 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 | 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]](/v4-2/docs/api-v2-get-list-an-iam-job). --- ## 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](/v4-2/docs/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/how-to-authenticate-an-application-in-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](/v4-2/docs/api-v2-post-create-ldap-server). | 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]](/v4-2/docs/api-v2-get-list-an-iam-job) 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](/v4-2/docs/api-v2-conventions-and-shared-behaviors).