🏢 API de Instituições e Unidades - Documentação Completa

📋 Visão Geral

A API de Instituições e Unidades é responsável por toda a gestão da estrutura organizacional do sistema CordenaAi, incluindo cadastro, atualização, consulta e exclusão de instituições e suas respectivas unidades. Esta API fornece a base hierárquica para todo o sistema, permitindo a organização de turmas, usuários e recursos por localização e tipo de instituição.

🎯 Endpoints Disponíveis

🏢 Instituições - Gestão de Instituições

1. GET /api/Instituicoes

Listar Todas as Instituições

2. GET /api/Instituicoes/{id}

Obter Instituição por ID

3. POST /api/Instituicoes

Criar Instituição

4. PUT /api/Instituicoes/{id}

Atualizar Instituição

5. DELETE /api/Instituicoes/{id}

Excluir Instituição

🏬 Unidades - Gestão de Unidades

1. GET /api/Unidades

Listar Todas as Unidades

2. GET /api/Unidades/{id}

Obter Unidade por ID

3. GET /api/Unidades/instituicao/{instituicaoId}

Obter Unidades por Instituição

4. POST /api/Unidades

Criar Unidade

5. PUT /api/Unidades/{id}

Atualizar Unidade

6. DELETE /api/Unidades/{id}

Excluir Unidade

🔧 Modelo de Dados

Instituição

{
  "id": 1,
  "descricao": "Projeto Veleiros",
  "local": "São Paulo, SP",
  "tipo": 1,
  "unidades": [
    {
      "id": 1,
      "nome": "Unidade Centro",
      "local": "São Paulo, SP",
      "tipo": 1,
      "instituicaoId": 1
    }
  ],
  "dataCadastro": "2025-01-15T10:30:00Z",
  "dataAtualizacao": null
}

Unidade

{
  "id": 1,
  "nome": "Unidade Centro",
  "local": "São Paulo, SP",
  "tipo": 1,
  "instituicaoId": 1,
  "instituicaoNome": "Projeto Veleiros",
  "turmas": [
    {
      "id": 1,
      "nome": "Futsal Infantil",
      "unidadeId": 1,
      "responsavelId": "user-guid-here",
      "status": 1
    }
  ],
  "dataCadastro": "2025-01-15T10:30:00Z",
  "dataAtualizacao": null
}

Tipos de Instituição

{
  "TipoInstituicao": {
    "Matriz": 1,
    "Filial": 2
  }
}

Tipos de Unidade

{
  "TipoUnidade": {
    "Matriz": 1,
    "Filial": 2
  }
}

🔐 Autenticação e Autorização

Todos os endpoints requerem:

📊 Casos de Uso Principais

1. Cadastro de Instituição

POST /api/Instituicoes
Content-Type: application/json
Authorization: Bearer {token}

{
  "descricao": "Projeto Veleiros",
  "local": "São Paulo, SP",
  "tipo": 1
}

2. Cadastro de Unidade

POST /api/Unidades
Content-Type: application/json
Authorization: Bearer {token}

{
  "nome": "Unidade Centro",
  "local": "São Paulo, SP",
  "tipo": 1,
  "instituicaoId": 1
}

3. Consulta de Unidades por Instituição

GET /api/Unidades/instituicao/1
Authorization: Bearer {token}

4. Atualização de Instituição

PUT /api/Instituicoes/1
Content-Type: application/json
Authorization: Bearer {token}

{
  "descricao": "Projeto Veleiros - Atualizado",
  "local": "São Paulo, SP - Zona Sul",
  "tipo": 1
}

5. Consulta de Instituição com Unidades

GET /api/Instituicoes/1
Authorization: Bearer {token}

6. Consulta de Unidade com Turmas

GET /api/Unidades/1
Authorization: Bearer {token}

⚠️ Validações e Regras de Negócio

Validações Obrigatórias

Instituições:

Unidades:

Regras de Negócio

🚨 Tratamento de Erros

Códigos de Status HTTP

Formato de Erro

{
  "error": "string",
  "message": "string",
  "details": "string",
  "timestamp": "datetime"
}

📈 Performance e Limitações

Limitações

Otimizações

🔄 Integração com Outros Módulos

Módulos Relacionados

📱 Uso em Aplicações

Web App

Mobile App

🛠️ Manutenção e Monitoramento

Logs Importantes

Métricas Monitoradas

📚 Exemplos Práticos

Fluxo Completo de Criação de Estrutura Organizacional

  1. Criar instituição via POST /api/Instituicoes
  2. Criar unidades via POST /api/Unidades
  3. Associar unidades à instituição via GET /api/Unidades/instituicao/{id}
  4. Verificar estrutura via GET /api/Instituicoes/{id}
  5. Criar turmas nas unidades criadas

Fluxo de Consulta Hierárquica

  1. Listar instituições via GET /api/Instituicoes
  2. Para cada instituição, listar unidades via GET /api/Unidades/instituicao/{id}
  3. Para cada unidade, listar turmas via GET /api/Unidades/{id}
  4. Gerar relatório consolidado

Fluxo de Gestão por Localização

  1. Filtrar instituições por local no frontend
  2. Listar unidades da região via GET /api/Unidades
  3. Exibir estrutura organizacional da região
  4. Permitir seleção para cadastros

Versão: 1.0
Última Atualização: Outubro de 2025
Responsável: Equipe de Desenvolvimento CordenaAi