🎓 Inscrições

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:

HTTP

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

Bash

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

✅ Exemplo de resposta

JSON

{
  "data": [
    {
      "id": 501,
      "group": {
        "id": 12,
        "name": "Curso Completo de Marketing"
      },
      "user": {
        "id": 9001,
        "first_name": "Ana",
        "last_name": "Silva",
        "email": "[email protected]",
        "phone": "[phone]"
      },
      "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

JSON

{
  "org": 1,
  "email": "[email protected]",
  "group_id": 12,
  "expires_at": "2026-03-01T10:00:00Z"
}

✅ Exemplo de resposta

JSON

{
  "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

JSON

{
  "org": 1,
  "email": "[email protected]",
  "group_id": 12
}

✅ Exemplo de resposta

JSON

{
  "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