{
  "openapi": "3.1.0",
  "info": {
    "title": "OPACC — Gestão Cadastral API",
    "version": "1.0.0",
    "description": "API REST da Plataforma Autónoma de Gestão e Atualização Cadastral de Membros da OPACC (Ordem Profissional de Auditores e Contabilistas Certificados — Cabo Verde). Preparada para integração futura com o novo site institucional opacc.cv."
  },
  "servers": [
    { "url": "/api/v1", "description": "Servidor Atual" }
  ],
  "components": {
    "securitySchemes": {
      "AdminCookieAuth": { "type": "apiKey", "in": "cookie", "name": "opacc_session" },
      "AdminBearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" },
      "IntegrationApiKey": { "type": "apiKey", "in": "header", "name": "X-API-Key" }
    }
  },
  "paths": {
    "/public/meta": {
      "get": {
        "tags": ["Público"],
        "summary": "Metadados institucionais e esquema dos formulários",
        "description": "Retorna referência da Circular n.º 27/CDIR/2026, prazo institucional, janela de edição, ilhas, regiões e campos oficiais."
      }
    },
    "/public/challenge": {
      "get": {
        "tags": ["Público"],
        "summary": "Emitir desafio anti-bot assinado",
        "description": "Gera um desafio aritmético simples assinado com HMAC para proteção contra spam e bots."
      }
    },
    "/public/check-nif": {
      "post": {
        "tags": ["Público"],
        "summary": "Verificar disponibilidade transversal de NIF",
        "description": "Verifica se o NIF já está registado (singular ou coletivo) sem expor dados pessoais."
      }
    },
    "/public/submissions/singular": {
      "post": {
        "tags": ["Público"],
        "summary": "Submeter atualização cadastral de Membro Singular (26 campos)",
        "description": "Valida todos os 26 campos da ficha MEMBROS SINGULARES, garante unicidade de NIF, gera referência única e código privado de edição."
      }
    },
    "/public/submissions/coletivo": {
      "post": {
        "tags": ["Público"],
        "summary": "Submeter atualização cadastral de Membro Coletivo (15 campos)",
        "description": "Valida todos os 15 campos da ficha MEMBROS COLETIVOS, garante unicidade de NIF transversal, gera referência única e código privado de edição."
      }
    },
    "/public/submissions/access": {
      "post": {
        "tags": ["Público"],
        "summary": "Autenticar edição limitada por Referência + Código Privado",
        "description": "Valida credenciais privadas do membro e informa se a janela de edição (72h / reabertura) está ativa."
      }
    },
    "/public/submissions/edit": {
      "put": {
        "tags": ["Público"],
        "summary": "Guardar edição limitada dentro do prazo",
        "description": "Atualiza a submissão mantendo a referência original e registando todas as diferenças no histórico."
      }
    },
    "/public/submissions/reopen-request": {
      "post": {
        "tags": ["Público"],
        "summary": "Submeter pedido de reabertura excecional",
        "description": "Regista pedido de reabertura após expiração do prazo para aprovação administrativa."
      }
    },
    "/public/receipt/{token}": {
      "get": {
        "tags": ["Público"],
        "summary": "Descarregar Comprovativo PDF da submissão",
        "description": "Gera comprovativo PDF autenticado por token temporário assinado (não expõe o código privado)."
      }
    },
    "/auth/login": {
      "post": {
        "tags": ["Autenticação"],
        "summary": "Autenticação administrativa",
        "description": "Valida email e palavra-passe com scrypt e emite cookie HttpOnly JWT + token CSRF."
      }
    },
    "/auth/me": {
      "get": {
        "tags": ["Autenticação"],
        "summary": "Obter sessão administrativa atual e permissões RBAC"
      }
    },
    "/auth/logout": {
      "post": {
        "tags": ["Autenticação"],
        "summary": "Encerrar sessão administrativa"
      }
    },
    "/admin/dashboard": {
      "get": {
        "tags": ["Administração"],
        "summary": "Indicadores e gráficos estatísticos em tempo real",
        "description": "Totais singulares/coletivos, pendentes, validados, rejeitados, distribuição geográfica, categorias, evolução temporal e taxa de atualização."
      }
    },
    "/admin/submissions": {
      "get": {
        "tags": ["Administração"],
        "summary": "Pesquisa e consulta cadastral combinada",
        "description": "Suporta filtros combinados por nome, denominação, NIF, cédula, registo comercial, categoria, ilha, região, situação, estado e datas."
      }
    },
    "/admin/submissions/{id}": {
      "get": {
        "tags": ["Administração"],
        "summary": "Ficha detalhada da submissão, diff oficial, snapshots e histórico"
      }
    },
    "/admin/submissions/{id}/analyze": {
      "post": {
        "tags": ["Validação"],
        "summary": "Colocar submissão no estado «Em análise»"
      }
    },
    "/admin/submissions/{id}/request-correction": {
      "post": {
        "tags": ["Validação"],
        "summary": "Solicitar correção («Aguarda correção») e desbloquear janela de edição"
      }
    },
    "/admin/submissions/{id}/validate": {
      "post": {
        "tags": ["Validação"],
        "summary": "Validar submissão e integrar no cadastro oficial",
        "description": "Arquiva versão anterior em snapshot imutável e atualiza o cadastro principal oficial."
      }
    },
    "/admin/submissions/{id}/reject": {
      "post": {
        "tags": ["Validação"],
        "summary": "Rejeitar submissão com justificação obrigatória"
      }
    },
    "/admin/submissions/{id}/reopen": {
      "post": {
        "tags": ["Validação"],
        "summary": "Reabrir processo e conceder novo prazo de edição"
      }
    },
    "/admin/submissions/{id}/admin-edit": {
      "put": {
        "tags": ["Validação"],
        "summary": "Efetuar correção administrativa autorizada com registo de histórico"
      }
    },
    "/admin/exports/xlsx": {
      "get": {
        "tags": ["Exportação"],
        "summary": "Exportar livro Excel (.xlsx) multi-folha conforme ficha OPACC"
      }
    },
    "/admin/exports/csv": {
      "get": {
        "tags": ["Exportação"],
        "summary": "Exportar CSV (UTF-8 BOM com proteção anti-formula injection)"
      }
    },
    "/admin/exports/pdf": {
      "get": {
        "tags": ["Exportação"],
        "summary": "Exportar Relatório Consolidado institucional em PDF"
      }
    },
    "/admin/users": {
      "get": { "tags": ["Sistema (Superadmin)"], "summary": "Listar utilizadores administrativos e perfis RBAC" },
      "post": { "tags": ["Sistema (Superadmin)"], "summary": "Criar utilizador administrativo" }
    },
    "/admin/settings": {
      "get": { "tags": ["Sistema (Superadmin)"], "summary": "Consultar configurações da plataforma" },
      "put": { "tags": ["Sistema (Superadmin)"], "summary": "Atualizar prazo de edição, meta e parâmetros institucionais" }
    },
    "/admin/backups": {
      "get": { "tags": ["Sistema (Superadmin)"], "summary": "Listar cópias de segurança da base de dados" },
      "post": { "tags": ["Sistema (Superadmin)"], "summary": "Criar backup consistente instantâneo (VACUUM INTO + SHA-256)" }
    },
    "/admin/api-keys": {
      "get": { "tags": ["Integração Futura"], "summary": "Listar chaves de API externas" },
      "post": { "tags": ["Integração Futura"], "summary": "Gerar nova chave de API autenticada com scopes" }
    },
    "/integration/health": {
      "get": {
        "tags": ["Integração Futura"],
        "summary": "Estado da API de integração (requer X-API-Key)"
      }
    },
    "/integration/members": {
      "get": {
        "tags": ["Integração Futura"],
        "summary": "Consultar membros oficiais validados (scope: members:read)"
      }
    },
    "/integration/members/{id}": {
      "get": {
        "tags": ["Integração Futura"],
        "summary": "Consultar membro validado por identificador permanente UUID (scope: members:read)"
      }
    },
    "/integration/verify/cedula/{cedula}": {
      "get": {
        "tags": ["Integração Futura"],
        "summary": "Verificar validade de cédula profissional no cadastro oficial (scope: verify:read)"
      }
    },
    "/integration/stats": {
      "get": {
        "tags": ["Integração Futura"],
        "summary": "Obter estatísticas agregadas não nominais (scope: stats:read)"
      }
    }
  }
}
