You are absolutely right. Looking at the validateUserAndGroupInOrg method in your service, it explicitly calls addGroups and addUsers if they are missing from the Org. This is a side effect that the API consumer must be aware of, as it changes the state of the User/Group relationships, not just the Enrollment.

Here is the updated documentation with a clearer warning about this auto-association behavior.

Esta seção permite inscrever ou remover usuários de grupos (também chamados de turmas ou conteúdos) dentro da plataforma. As inscrições determinam quais usuários têm acesso aos conteúdos da sua escola.

📌 Funcionalidades disponíveis

Método	Endpoint	Descrição
`GET`	`/enrollments`	Lista inscrições existentes com paginação
`POST`	`/enrollments`	Inscreve um usuário em um grupo
`DELETE`	`/enrollments`	Expira (remove) a inscrição de um usuário em um grupo

🔐 Autenticação e Cabeçalhos

Todas as requisições exigem um token de API válido no cabeçalho:

Authorization: Bearer {SEU_TOKEN_AQUI}
X-Requested-With: XMLHttpRequest
Content-Type: application/json

🔒
O token é exclusivo por plataforma e deve ser gerado previamente pelo administrador.

📖 Listar inscrições (`GET /enrollments`)

Retorna uma lista paginada de inscrições existentes, conforme o **recurso InscriptionIndexResource**. Agora inclui dados da organização.

🔍 Parâmetros de Query

Campo	Tipo	Obrigatório	Padrão	Descrição
`org`	integer	❌	-	ID da Organização (filial) para filtrar.
`page`	integer	❌	1	Número da página.
`per_page`	integer	❌	15	Quantidade de itens por página.

💡 Exemplo de requisição

GET https://sua-plataforma.ensinio.cloud/public/api/v1/enrollments?org=1&page=1&per_page=15

✅ Exemplo de resposta

{
  "data": [
    {
      "id": 501,
      "group": {
        "id": 12,
        "name": "Curso Completo de Marketing"
      },
      "user": {
        "id": 9001,
        "first_name": "Ana",
        "last_name": "Silva",
        "email": "ana@example.com",
        "phone": "+55 11 99999-0000"
      },
      "org": {
        "id": 1,
        "name": "Filial São Paulo"
      },
      "completion_rate": 0.92,
      "inscription_date": "2025-03-01",
      "expiration_date": "2026-03-01"
    }
  ],
  "links": { ... },
  "meta": { ... }
}

📝 Criar inscrição (`POST /enrollments`)

Inscreve um usuário já existente em um grupo/turma da plataforma.

⚠️
Atenção ao uso do parâmetro org:
Caso você envie o ID de uma organização e o usuário ou o grupo ainda não pertençam a ela, o sistema irá adicioná-los automaticamente à organização antes de criar a inscrição.

📦 Parâmetros esperados (Body JSON)

Campo	Tipo	Obrigatório	Descrição
`org`	integer	❌ Opcional	ID da Organização (filial/contexto)
`email`	string	✅ Sim	E-mail do usuário já existente no sistema
`group_id`	integer	✅ Sim	ID do grupo para inscrição
`expires_at`	datetime	❌ Opcional	Data de expiração da inscrição (ISO-8601)

💡 Exemplo de requisição

{
  "org": 1,
  "email": "ana@example.com",
  "group_id": 12,
  "expires_at": "2026-03-01T10:00:00Z"
}

✅ Exemplo de resposta

{
  "message": "Usuário inscrito no grupo com sucesso"
}

✉️ Notificação por E-mail

Ao inscrever um usuário com sucesso:

A plataforma envia automaticamente um e-mail informando que o usuário foi adicionado a um grupo.
O envio é automático e não requer nenhuma ação adicional.
O e-mail só será enviado se o usuário possuir um endereço de e-mail válido.

🧹 Expirar inscrição (`DELETE /enrollments`)

Remove uma inscrição existente, revogando imediatamente o acesso do usuário ao conteúdo do grupo.

📦 Parâmetros esperados (Body JSON)

Campo	Tipo	Obrigatório	Descrição
`org`	integer	❌ Opcional	ID da Organização (filial/contexto)
`email`	string	✅ Sim	E-mail do usuário a ser removido
`group_id`	integer	✅ Sim	ID do grupo do qual o usuário será removido

💡 Exemplo de requisição

{
  "org": 1,
  "email": "ana@example.com",
  "group_id": 12
}

✅ Exemplo de resposta

{
  "message": "Inscrição expirada com sucesso"
}

🧠 Observações importantes

O usuário precisa estar previamente criado para ser inscrito.
A expiração da inscrição revoga imediatamente o acesso ao conteúdo.
Vínculo Automático (org): Se um ID de organização for fornecido na criação e o usuário (ou grupo) não fizer parte dela, ele será vinculado automaticamente.
Inscrições criadas via API são marcadas internamente como do tipo "manual".
Se o usuário já estiver inscrito, apenas a data de expiração será atualizada.
Caso nenhuma data de expiração seja informada, a inscrição será considerada vitalícia.

🚫 Códigos de Erro

Código	Descrição
`400`	Erro de validação nos parâmetros enviados
`401`	Token inválido ou ausente
`403`	Recurso não habilitado no plano do tenant
`404`	Usuário, Grupo ou Organização não encontrado
`429`	Limite de requisições excedido (rate limit)
`500`	Erro interno inesperado

🧭 Resumo visual

Ação	Método	Endpoint	Retorno esperado
Listar inscrições	`GET`	`/enrollments`	Lista paginada de inscrições existentes
Criar nova inscrição	`POST`	`/enrollments`	Mensagem de sucesso ou erro
Expirar/remover inscrição	`DELETE`	`/enrollments`	Mensagem de sucesso ou erro

📌 Funcionalidades disponíveis

🔐 Autenticação e Cabeçalhos

O token é exclusivo por plataforma e deve ser gerado previamente pelo administrador.

📖 Listar inscrições (GET /enrollments)

🔍 Parâmetros de Query

💡 Exemplo de requisição

✅ Exemplo de resposta

📝 Criar inscrição (POST /enrollments)

📦 Parâmetros esperados (Body JSON)

💡 Exemplo de requisição

✅ Exemplo de resposta

✉️ Notificação por E-mail

🧹 Expirar inscrição (DELETE /enrollments)

📦 Parâmetros esperados (Body JSON)

💡 Exemplo de requisição

✅ Exemplo de resposta

🧠 Observações importantes

🚫 Códigos de Erro

🧭 Resumo visual

📖 Listar inscrições (`GET /enrollments`)

📝 Criar inscrição (`POST /enrollments`)

🧹 Expirar inscrição (`DELETE /enrollments`)