---
title: "POST | Criar sincronização de grupo LDAP"
slug: "api-v2-post-create-ldap-group-sync"
updated: 2026-11-03T14:57:58Z
published: 2026-11-03T14:57:58Z
canonical: "docs.senhasegura.io/api-v2-post-create-ldap-group-sync"
---

> ## 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 sincronização de grupo LDAP

## Descrição

Crie uma sincronização de grupo LDAP na plataforma Segura™. Uma única requisição vincula um grupo do Active Directory, identificado por um distinguished name e um filtro LDAP, a um grupo de usuários, atribui as roles de ACL que seus membros recebem e, opcionalmente, configura o bloco Domum.

A sincronização é criada no estado ativo. Criá-la não importa nenhum usuário: execute [POST | Executar sincronização de grupo LDAP](/v4-2/docs/api-v2-post-run-ldap-group-sync) para iniciar a primeira importação.

---

## 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 no A2A](/v4-2/docs/how-to-authenticate-an-application-in-a2a).
- O servidor LDAP, o grupo de usuários e quaisquer roles referenciadas na requisição já devem existir e estar ativos.
- O módulo de licença `cote` deve estar ativo para enviar o bloco `domum`.

              Info

              

Um token de acesso carrega apenas as autorizações que existiam no momento em que foi gerado. Depois que o administrador habilitar a autorização **Users**, gere um novo token para a aplicação — um token existente não passa a ter a nova autorização.

---

## Requisição

`POST` `/api/v2/iam/ldap-group-syncs`

### Cabeçalhos

| Cabeçalho | Obrigatório | Descrição |
| --- | --- | --- |
| `Content-Type` | Sim | Deve ser `application/json`. |

              Atenção

              

Este endpoint não suporta o header `Idempotency-Key`. Reenviar uma requisição cria uma segunda sincronização. Verifique se o recurso já existe com [GET | Listar todas as sincronizações de grupos LDAP](/v4-2/docs/api-v2-get-list-all-ldap-group-syncs) antes de reenviar.

### Corpo da requisição

O corpo carrega dois objetos. `group_sync` contém a sincronização em si, e `domum` contém a integração opcional com o Domum.

#### `group_sync`

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `name` | string | Sim | Nome da sincronização. Máximo de 100 caracteres. |
| `server_id` | int | Sim | Código de identificação do servidor LDAP. O servidor deve existir e estar ativo. |
| `user_group_id` | int | Sim | Código de identificação do grupo de usuários que recebe os usuários sincronizados. O grupo deve existir e estar ativo. |
| `synchronization_enabled` | boolean | Sim | Indica se a sincronização está habilitada para rodar. |
| `overwrite_user_accesses` | boolean | Sim | Indica se a sincronização sobrescreve os acessos já atribuídos a um usuário. Requer que `synchronization_enabled` seja `true`. |
| `force_roles` | boolean | Não | Indica se a sincronização remove do usuário qualquer role que o grupo do Active Directory não concede mais. Padrão: `true`. |
| `automatic_sync` | boolean | Não | Indica se a plataforma executa a sincronização em sua própria agenda. Padrão: `false`. |
| `dn` | string | Sim | Distinguished name base pesquisado no diretório. Máximo de 255 caracteres. |
| `ad_username_attribute` | string | Sim | Atributo do Active Directory lido como o nome de usuário. Máximo de 255 caracteres. |
| `ad_name_attribute` | string | Não | Atributo do Active Directory lido como o nome completo. Valores permitidos: `name`, `displayname`, `samaccountname`, `null`. Os valores são em minúsculas. |
| `department_id` | int | Não | Código de identificação do departamento atribuído aos usuários sincronizados. Aceita `null`. |
| `ad_query` | string | Sim | Filtro LDAP que seleciona os grupos a sincronizar. Máximo de 2048 caracteres. |
| `role_ids` | array de int | Não | Códigos de identificação das roles de ACL atribuídas aos usuários sincronizados. |

#### `domum`

Envie este objeto apenas quando o módulo de licença `cote` estiver ativo. Sem a licença, a requisição retorna `422 api.feature.unavailable`.

| Campo | Tipo | Obrigatório | Descrição |
| --- | --- | --- | --- |
| `enabled` | boolean | Sim | Indica se os usuários sincronizados recebem acesso no Domum. |
| `type` | string | Sim | Perfil de acesso concedido no Domum. Valores permitidos: `full_users`, `limited_users`. |
| `vendor_id` | int | Condicional | Código de identificação do fornecedor ou grupo interno. Obrigatório quando `enabled` é `true`. |

### Exemplo de requisição `POST` `{{url}}/api/v2/iam/ldap-group-syncs`

#### Corpo

```
{
    "group_sync": {
        "name": "Infrastructure operators",
        "server_id": 10,
        "user_group_id": 7,
        "synchronization_enabled": true,
        "overwrite_user_accesses": false,
        "force_roles": true,
        "automatic_sync": false,
        "dn": "OU=Operators,DC=example,DC=com",
        "ad_username_attribute": "sAMAccountName",
        "ad_name_attribute": "displayname",
        "ad_query": "(&(objectClass=group)(cn=ops-*))",
        "role_ids": [1, 3]
    },
    "domum": {
        "enabled": true,
        "type": "limited_users",
        "vendor_id": 22
    }
}
```

---

## Resposta

```
HTTP/1.1 201 Created
Location: /api/v2/iam/ldap-group-syncs/501
ETag: "174f80fa9c3b4d2e"
```

O header `Location` carrega o caminho da sincronização criada e o header `ETag` carrega sua versão atual. Guarde o valor do `ETag`; [PUT | Atualizar sincronização de grupo LDAP por [id]](/v4-2/docs/api-v2-put-update-ldap-group-sync), [PATCH | Atualizar parcialmente sincronização de grupo LDAP por [id]](/v4-2/docs/api-v2-patch-update-ldap-group-sync) e [DELETE | Excluir sincronização de grupo LDAP por [id]](/v4-2/docs/api-v2-delete-ldap-group-sync) o utilizam no header `If-Match` para detectar alterações concorrentes.

### Exemplo de corpo da resposta

```
{
    "data": {
        "id": "501",
        "group_sync": {
            "name": "Infrastructure operators",
            "active": true,
            "server": { "id": "10" },
            "user_group": { "id": "7" },
            "synchronization_enabled": true,
            "overwrite_user_accesses": false,
            "force_roles": true,
            "automatic_sync": false,
            "dn": "OU=Operators,DC=example,DC=com",
            "ad_username_attribute": "sAMAccountName",
            "ad_name_attribute": "displayname",
            "department": null,
            "ad_query": "(&(objectClass=group)(cn=ops-*))",
            "roles": [{ "id": 1 }, { "id": 3 }]
        },
        "domum": {
            "enabled": true,
            "type": "limited_users",
            "vendor": { "id": 22 }
        }
    },
    "meta": {
        "links": { "self": "/api/v2/iam/ldap-group-syncs/501" },
        "actions": {
            "sync": "/api/v2/iam/ldap-group-syncs/501/sync",
            "deactivate": "/api/v2/iam/ldap-group-syncs/501/deactivate"
        }
    }
}
```

## Campos do corpo da resposta

| Campo | Tipo | Descrição |
| --- | --- | --- |
| `data` | object | A sincronização criada. |
| `meta` | object | Links e as ações disponíveis para o recurso em seu estado atual. |

### `data`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| →`id` | string | Código de identificação único da sincronização, atribuído pela Segura™. |
| →`group_sync` | object | As configurações da sincronização. |
| →`domum` | object | As configurações do Domum. Retornado apenas quando o módulo de licença `cote` está ativo. |

### `data.group_sync`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| →→`name` | string | Nome da sincronização. |
| →→`active` | boolean | Indica se a sincronização está ativa. Uma nova sincronização é sempre criada como `true`. |
| →→`server` | object | O servidor LDAP, como `{ "id": <string> }`. A requisição envia `server_id`. |
| →→`user_group` | object | O grupo de usuários, como `{ "id": <string> }`. A requisição envia `user_group_id`. |
| →→`synchronization_enabled` | boolean | Indica se a sincronização está habilitada para rodar. |
| →→`overwrite_user_accesses` | boolean | Indica se a sincronização sobrescreve os acessos já atribuídos a um usuário. |
| →→`force_roles` | boolean | Indica se a sincronização remove roles que o grupo do Active Directory não concede mais. |
| →→`automatic_sync` | boolean | Indica se a plataforma executa a sincronização em sua própria agenda. |
| →→`dn` | string | Distinguished name base pesquisado no diretório. |
| →→`ad_username_attribute` | string | Atributo do Active Directory lido como o nome de usuário. |
| →→`ad_name_attribute` | string | Atributo do Active Directory lido como o nome completo. Retorna `null` quando o atributo enviado não é suportado. |
| →→`department` | object | O departamento atribuído aos usuários sincronizados. Retorna `null` quando não definido. |
| →→`ad_query` | string | Filtro LDAP que seleciona os grupos a sincronizar. |
| →→`roles` | array de objetos | As roles de ACL atribuídas, cada uma como `{ "id": <int> }`. A requisição envia `role_ids`. |

### `data.domum`

| Campo | Tipo | Descrição |
| --- | --- | --- |
| →→`enabled` | boolean | Indica se os usuários sincronizados recebem acesso no Domum. |
| →→`type` | string | Perfil de acesso concedido no Domum. Retorna `full_users` ou `limited_users`. |
| →→`vendor` | object | O fornecedor ou grupo interno, como `{ "id": <int> }`. A requisição envia `vendor_id`. |

              Atenção

              

Enviar `ad_name_attribute` com um valor que a plataforma reconhece mas não suporta retorna `201 Created` e armazena `null`. Verifique o valor de `ad_name_attribute` na resposta para confirmar se o atributo foi aceito.

---

## Erros

| Código HTTP | Mensagem | Causa possível | Solução |
| --- | --- | --- | --- |
| `400` | `api.request.malformed` | O corpo não é um JSON válido. | Verifique a sintaxe do JSON e reenvie a requisição. |
| `403` | `api.permission.denied` | A aplicação não tem permissão para este recurso. | Peça ao administrador para verificar a autorização **Users** da aplicação no A2A. |
| `422` | `api.validation.required_field` | Um campo obrigatório está ausente ou é `null`. | Envie todos os campos obrigatórios listados nas tabelas de corpo da requisição. |
| `422` | `api.validation.invalid_type` | Um campo tem o tipo primitivo incorreto. | Verifique a coluna `Tipo` nas tabelas de corpo da requisição. |
| `422` | `api.validation.length_exceeded` | Uma string é mais longa do que a coluna permite. | Reduza o valor ao máximo documentado para o campo. |
| `422` | `api.validation.invalid_reference` | `server_id`, `user_group_id`, `department_id`, uma entrada em `role_ids` ou `domum.vendor_id` não existe. | Confirme que os recursos referenciados existem antes de reenviar a requisição. |
| `422` | `api.validation.server.inactive` | `server_id` aponta para um servidor LDAP inativo. | Ative o servidor, ou referencie um servidor ativo. |
| `422` | `api.validation.user_group.inactive` | `user_group_id` aponta para um grupo de usuários inativo. | Ative o grupo, ou referencie um grupo ativo. |
| `422` | `api.validation.overwrite.requires_sync_enabled` | `overwrite_user_accesses` é `true` enquanto `synchronization_enabled` é `false`. | Defina `synchronization_enabled` como `true`, ou defina `overwrite_user_accesses` como `false`. |
| `422` | `api.validation.unknown_field` | O corpo carrega uma chave que não faz parte do esquema do recurso. | Remova a chave. Verifique se o corpo usa os objetos `group_sync` e `domum`. |
| `422` | `api.enum.invalid_value` | `ad_name_attribute` ou `domum.type` está fora dos valores permitidos. | Envie um dos valores permitidos listados nas tabelas de corpo da requisição. |
| `422` | `api.feature.unavailable` | O bloco `domum` foi enviado sem o módulo de licença `cote`. | Remova o bloco `domum`, ou peça ao administrador para licenciar o módulo. |
| `422` | `ldap_group_sync.domum.vendor_required` | `domum.enabled` é `true` sem `domum.vendor_id`. | Envie `domum.vendor_id`. |
| `429` | `rate_limit_exceeded` | A aplicação excedeu sua cota de requisições. | Aguarde o período indicado no header `Retry-After` e reenvie a requisição. |

### 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.` | Header 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. |