Desenvolver API de Integração Mapa Cultural <> e-Parcerias (CGE)

[Junior-Shyko]

Contexto

Para atender à Lei nº 18.012/2022 e ao Decreto Estadual nº 35.635/2023, é necessário estabelecer uma integração automática entre o Mapa Cultural (SECULT) e o sistema e-Parcerias (CGE). O objetivo é eliminar o reprocessamento manual de dados, garantindo que informações de monitoramento e prestação de contas inseridas no Mapa Cultural sejam espelhadas fielmente no e-Parcerias para fins de fiscalização e transparência.

Objetivo

Como um Desenvolvedor Backend
Quero desenvolver uma API autenticada no Mapa Cultural
Para permitir que o sistema e-Parcerias consulte e espelhe dados de proponentes, documentos de execução e pareceres técnicos de forma automatizada e segura.

Escopo

• Desenvolvimento de Endpoints: Criar endpoints para fornecer os seguintes dados:
  • Dados do Proponente (Nome, CPF) e Município.
  • Documentos de execução física e prestação de contas.
  • Extratos financeiros e pareceres técnicos.
  • Status atual do projeto e da prestação de contas.
• Segurança e Autenticação: Implementar autenticação via Token com controle de acesso rigoroso.
• Rastreabilidade (Logs): Implementar log de importações contendo metadados de origem, data e hora da transação para fins de auditoria.
• Classificação de Instrumentos: Garantir que a API informe o tipo de projeto (ex: Paulo Gustavo, Aldir Blanc) e o tipo de instrumento:
  • Termo de Execução Cultural.
  • Termo de Compromisso Cultural.
  • Termo de Patrocínio Cultural.
  • Termo de Cooperação Financeira.
• Mapeamento de Metadados: Incluir metadados de origem em todos os registros exportados.

Fora de Escopo

• Alterações na interface do sistema e-Parcerias (responsabilidade da CGE).
• Desenvolvimento de fluxos de aprovação de contas dentro da API (a API apenas reporta o status atual).
• Migração de dados históricos anteriores à vigência da lei (a menos que especificado).

Critérios de Aceitação (Gherkin/Cucumber)

1. Autenticação e Segurança

Dado que um sistema externo tenta acessar o endpoint de integração
Quando a requisição não fornece um Token válido ou está sem autenticação
Então o sistema deve retornar um erro 401 Unauthorized
E registrar a tentativa de acesso negado nos logs.

2. Sincronização de Dados de Execução

Dado que o sistema e-Parcerias solicita os dados de um projeto específico via API
Quando o Mapa Cultural processa a requisição
Então ele deve retornar o JSON contendo os documentos de execução física, pareceres técnicos e o status da prestação de contas
E o registro deve incluir a data/hora exata da geração do dado.

3. Classificação Correta do Instrumento

Dado que uma consulta é realizada para um edital da Lei Paulo Gustavo
Quando a API retorna os dados
Então o campo tipo_instrumento deve retornar obrigatoriamente um dos valores padronizados (ex: "Termo de Execução Cultural")
E os dados do proponente (Nome/CPF) devem estar devidamente vinculados.

Observações

• Referência Legal: Lei nº 18012/2022 e Decreto Estadual nº 35.635/2023.
• Integração: Os dados serão exibidos na aba “Instrumentos Simplificados” do e-Parcerias, filtrados por número SACC e tipo de projeto.
• Responsáveis: Kennedy Glauber e Daniel Costa (CECOP/SECULT).
  Link do documento: https://docs.google.com/document/d/14GV5RcK7xrv06ckImDaOFw20JACC5rcnFXYa5CChzl0/edit?usp=sharing
  Formato do json:

{
  "metadata": {
    "origem": "Mapa Cultural do Ceará",
    "timestamp_extracao": "2024-03-15T10:30:00Z",
    "versao_api": "1.0"
  },
  "projeto": {
    "numero_sacc": "123456/2024",
    "tipo_projeto": "Lei Paulo Gustavo",
    "instrumento": {
      "tipo": "Termo de Execução Cultural",
      "data_assinatura": "2024-01-10",
      "valor_total": 50000.00
    },
    "proponente": {
      "nome": "João da Silva",
      "cpf_cnpj": "000.000.000-00",
      "municipio": "Fortaleza",
      "id_agente_mapa": "12345"
    },
    "status": {
      "fase_atual": "Prestação de Contas",
      "situacao": "Em Análise",
      "data_ultima_atualizacao": "2024-03-01T08:00:00Z"
    },
    "execucao_fisica": [
      {
        "id_documento": "doc_001",
        "tipo": "Relatório de Execução do Objeto",
        "url_download": "https://mapacultural.secult.ce.gov.br/files/relatorio_001.pdf",
        "data_envio": "2024-02-15"
      }
    ],
    "financeiro": {
      "extratos_bancarios": [
        {
          "mes_referencia": "Janeiro/2024",
          "url_arquivo": "https://mapacultural.secult.ce.gov.br/files/extrato_jan.pdf"
        }
      ],
      "comprovantes_despesa": []
    },
    "pareceres_tecnicos": [
      {
        "id_parecer": "par_99",
        "tipo": "Parecer Técnico de Monitoramento",
        "resultado": "Favorável",
        "conteudo_resumo": "Objeto cumprido conforme o plano de trabalho.",
        "autor": "Técnico SECULT 01",
        "data_emissao": "2024-03-10"
      }
    ]
  }
}