Requisitos para Relacionamentos

gistfile1.txt

# Requisitos para Relacionamentos com Orgaos Publicos

Este documento consolida os requisitos necessarios para a aplicacao LYS se relacionar com orgaos publicos, plataformas governamentais e entidades de controle. O foco e orientar produto, desenvolvimento, QA, implantacao e operacao na configuracao de integracoes, envio/consulta de dados, auditoria e conformidade.

Documento complementar:

- `docs/refinamento-fase-final-integracoes-governo.md`
- `docs/referencia-aplicacao.md`
- `docs/referencia-banco-dados.md`

## Escopo

Abrange os relacionamentos ja previstos na Central de Integracoes Governamentais (`/integracoes-governo`) e nos modulos municipais que trocam dados com sistemas externos:

- previdencia e RPPS;
- RH, folha e eventos trabalhistas;
- contabilidade, orcamento e prestacao de contas;
- compras e contratacoes publicas;
- convenios e transferencias;
- fiscal, identidade e cadastro;
- saude;
- educacao;
- transparencia, ouvidoria e LAI;
- migracao e interoperabilidade com sistemas legados.

Fora do escopo deste documento: regras juridicas especificas de cada municipio, parametrizacoes contratuais com fornecedores externos e manuais tecnicos detalhados de cada API. Esses itens devem ser validados na implantacao com os manuais oficiais vigentes e com as credenciais reais do ente.

## Requisitos Transversais

### RT-01 - Cadastro do relacionamento

Todo orgao/provedor deve existir no catalogo `integracoes_governo_catalogo` com:

- codigo unico;
- nome oficial ou nome operacional usado pela equipe;
- categoria;
- descricao;
- URL de homologacao, quando existir;
- URL de producao, quando existir;
- indicador de certificado digital;
- indicador de OAuth/JWT/token;
- link de documentacao, quando disponivel.

### RT-02 - Configuracao por ambiente

Cada relacionamento configurado em `integracoes_governo` deve manter uma instancia por par `(codigo, ambiente)`, usando os ambientes:

- `desconectado`;
- `homologacao`;
- `producao`.

A passagem para producao deve exigir:

- teste de conexao bem-sucedido;
- credenciais/certificado validados;
- autorizacao formal do administrador do ente;
- registro em log com data, responsavel e observacao.

### RT-03 - Credenciais, tokens e certificados

O relacionamento deve suportar, conforme o orgao:

- `client_id`;
- `client_secret`;
- token de acesso;
- data/hora de expiracao do token;
- certificado digital A1 (`.pfx`/`.p12`) ou certificados em `.cer`, `.crt`, `.pem`;
- senha e validade do certificado;
- URL de webhook e segredo de webhook.

Segredos nunca devem aparecer em claro na UI ou em consultas comuns. A leitura deve usar a view `v_integracoes_governo`, que mascara `client_secret`, `token`, `certificado_senha` e `webhook_secret`.

### RT-04 - Armazenamento seguro

Certificados e arquivos sensiveis devem ficar no bucket privado `integracoes-governo-certs`, com acesso restrito a administradores e service role. Arquivos recebidos devem ser:

- nomeados com padrao previsivel por provedor e ambiente;
- substituiveis apenas por administradores;
- removidos quando a integracao for desativada definitivamente;
- verificados quanto a extensao, tamanho e validade.

### RT-05 - Auditoria e rastreabilidade

Toda operacao relevante deve gerar registro em `integracoes_governo_logs`, incluindo:

- tipo: teste de conexao, autenticacao, sincronizacao, webhook de entrada, webhook de saida ou acao manual;
- status: sucesso, aviso ou erro;
- HTTP status, quando houver;
- duracao em ms;
- mensagem operacional;
- resumo sanitizado da requisicao;
- resumo sanitizado da resposta;
- usuario responsavel;
- data/hora.

Nenhum log deve armazenar segredo, senha, token completo, certificado ou payload com dado pessoal desnecessario.

### RT-06 - LGPD e minimizacao de dados

Todo relacionamento deve enviar somente os dados exigidos pelo orgao. Antes de habilitar sincronizacao, a equipe deve classificar:

- base legal;
- finalidade;
- categorias de titulares;
- dados pessoais enviados;
- dados sensiveis enviados;
- prazo de retencao;
- perfis internos autorizados a consultar logs e respostas;
- estrategia de anonimizacao/mascaramento em telas, exports e logs.

### RT-07 - Operacao resiliente

Toda integracao deve respeitar:

- timeout configuravel entre 1 segundo e 5 minutos;
- numero maximo de tentativas entre 0 e 10;
- idempotencia para reenvio de eventos;
- fila ou outbox para eventos assincronos;
- conciliacao entre registros locais e protocolo/recibo externo;
- reprocessamento manual controlado;
- status operacional visivel ao admin: ocioso, sincronizando, erro ou ativo.

### RT-08 - Homologacao e evidencia

Antes da ativacao em producao, deve existir evidencia de homologacao:

- URL usada;
- credencial usada ou tipo de credencial;
- certificado usado, quando aplicavel;
- payloads de teste sanitizados;
- retorno esperado;
- retorno obtido;
- data e responsavel;
- pendencias conhecidas.

### RT-09 - Contratos de dados

Cada relacionamento deve possuir mapeamento entre campos locais e campos externos:

- origem local;
- nome do campo externo;
- tipo;
- obrigatoriedade;
- regra de transformacao;
- validacoes;
- tratamento de erro;
- comportamento em retificacao/cancelamento/exclusao.

### RT-10 - Responsabilidade operacional

Cada orgao/provedor deve ter dono interno definido:

- area responsavel;
- perfil minimo necessario;
- rotina de acompanhamento;
- frequencia de sincronizacao;
- SLA interno para erros;
- canal oficial de suporte do orgao;
- procedimento de contingencia quando o sistema externo estiver indisponivel.

## Matriz de Orgaos e Provedores

| Codigo | Orgao/provedor | Categoria | Relacionamento principal | Certificado | OAuth/token |
| --- | --- | --- | --- | --- | --- |
| `DATAPREV` | DATAPREV / CNIS | Previdenciario | Consulta/validacao de dados previdenciarios e CNIS | Sim | Sim |
| `COMPREV` | COMPREV | Previdenciario | Compensacao previdenciaria entre RGPS e RPPS | Sim | Sim |
| `CADPREV` | CADPREV / SPPS | Previdenciario | Cadastro e regularidade de RPPS junto a SPREV | Sim | Nao |
| `ESOCIAL` | eSocial | RH / Trabalhista | Eventos trabalhistas, previdenciarios e de folha | Sim | Nao |
| `SIAFI` | SIAFI / Tesouro Nacional | Financeiro | Administracao financeira federal e consultas correlatas | Sim | Sim |
| `AUDESP` | AUDESP / TCE-SP | Contabil | Prestacao de contas e dados contabeis ao tribunal | Sim | Nao |
| `PNCP` | Portal Nacional de Contratacoes Publicas | Compras | Publicacao e consulta de contratacoes publicas | Nao | Sim |
| `COMPRASNET` | ComprasNet / Compras.gov.br | Compras | Compras federais, catalogos e processos de contratacao | Nao | Sim |
| `TRANSFEREGOV` | TransfereGov | Convenios | Convenios, parcerias e transferencias voluntarias | Nao | Sim |
| `RFB` | Receita Federal | Fiscal | Consulta e validacao de CPF/CNPJ e situacao fiscal | Sim | Nao |
| `GOVBR` | gov.br SSO OAuth2 | Identidade | Login unico e identificacao do cidadao | Nao | Sim |
| `DATASUS` | DATASUS / RNDS | Saude | Interoperabilidade com sistemas do SUS | Sim | Sim |
| `MEC` | MEC / EducaCenso | Educacao | Censo Escolar e sistemas do MEC | Nao | Sim |
| `INEP` | INEP | Educacao | Estatisticas, indicadores e bases educacionais | Nao | Nao |

## Requisitos por Orgao ou Provedor

### DATAPREV / CNIS

Descricao: relacionamento previdenciario para consulta, validacao e conciliacao de informacoes vinculadas ao Cadastro Nacional de Informacoes Sociais e servicos operados pela DATAPREV.

Requisitos:

- manter certificado digital valido quando exigido pelo convenio/API;
- armazenar credenciais OAuth/token com mascaramento;
- vincular consultas a pessoa/servidor/beneficiario local;
- registrar finalidade da consulta e usuario responsavel;
- armazenar apenas resumo operacional da resposta quando houver dados previdenciarios sensiveis;
- permitir conciliacao entre dados locais e retorno externo;
- registrar protocolo, recibo ou identificador externo da consulta, quando fornecido;
- bloquear consulta por usuario sem permissao de modulo previdenciario ou perfil administrativo autorizado.

Dados minimos esperados:

- CPF/NIS/PIS/PASEP quando exigido;
- identificadores de segurado, servidor, aposentado ou pensionista;
- periodo de consulta;
- motivo/finalidade da operacao;
- vinculo ao processo administrativo, quando houver.

### COMPREV

Descricao: relacionamento para compensacao previdenciaria entre regimes, especialmente entre RGPS e RPPS.

Requisitos:

- suportar certificado digital e autenticacao por token, conforme ambiente;
- manter relacao entre processo local e processo COMPREV;
- controlar estados: preparado, enviado, em analise, exigencia, deferido, indeferido, cancelado e pago, quando aplicavel ao fluxo contratado;
- anexar ou referenciar documentos comprobatarios;
- registrar recibos, protocolos e historico de exigencias;
- permitir retificacao e reenvio com rastreabilidade;
- preservar historico imutavel de alteracoes em dados criticos.

Dados minimos esperados:

- segurado/beneficiario;
- regime de origem e destino;
- vinculos e tempos de contribuicao;
- ato concessorio;
- dados de beneficio;
- documentos comprobatarios;
- protocolo externo.

### CADPREV / SPPS

Descricao: relacionamento com o cadastro e acompanhamento de informacoes do RPPS junto a Secretaria de Regime Proprio e Complementar.

Requisitos:

- suportar certificado digital quando exigido;
- manter dados cadastrais do ente, unidade gestora e RPPS;
- controlar envio/acompanhamento de demonstrativos, declaracoes e informacoes de regularidade;
- registrar situacao de cada envio e pendencias de validacao;
- permitir anexacao de comprovantes e relatorios;
- conciliar informacoes de regularidade previdenciaria com os registros locais;
- indicar pendencias que possam afetar CRP, repasses, compensacao ou conformidade.

Dados minimos esperados:

- CNPJ do ente e da unidade gestora;
- dados do RPPS;
- responsaveis legais;
- demonstrativos exigidos;
- competencias;
- comprovantes e recibos.

### eSocial

Descricao: relacionamento para transmissao e consulta de eventos trabalhistas, previdenciarios e de seguranca/saude do trabalho.

Requisitos:

- usar certificado digital valido;
- transmitir eventos conforme leiaute vigente;
- validar XML/XSD antes do envio;
- controlar recibos de lote e resultado de processamento;
- separar ambientes de producao restrita e producao;
- controlar ciclo de vida dos eventos: gerado, validado, enviado, recebido, processado, rejeitado, retificado e excluido;
- manter dependencia entre eventos de tabela, nao periodicos e periodicos;
- registrar retorno completo em area segura, com exibicao resumida na UI;
- permitir reprocessamento sem duplicidade;
- bloquear alteracoes locais que quebrem eventos ja transmitidos sem fluxo de retificacao.

Dados minimos esperados:

- empregador/ente;
- estabelecimento/lotacao;
- trabalhador/servidor;
- cargo, rubrica, folha, afastamento, ferias, vinculo e desligamento;
- eventos periodicos de remuneracao;
- identificadores de lote, recibo e evento.

Observacao operacional: a documentacao tecnica eSocial deve ser verificada antes de cada implantacao, pois leiautes, notas tecnicas e regras de validacao podem mudar.

### SIAFI / Tesouro Nacional

Descricao: relacionamento financeiro com sistemas do Tesouro Nacional, quando o ente possuir autorizacao e necessidade de consulta/integracao.

Requisitos:

- suportar certificado digital e OAuth/token, conforme credenciamento;
- manter segregacao entre dados municipais locais e dados federais consultados;
- registrar finalidade de consulta e responsavel;
- conciliar registros financeiros com exercicio, unidade gestora, fonte, natureza e classificacao orcamentaria;
- armazenar protocolos ou identificadores de transacao;
- impedir envio/alteracao sem autorizacao formal do perfil financeiro competente;
- validar compatibilidade com PCASP, Lei 4.320/64 e regras locais de execucao.

Dados minimos esperados:

- exercicio;
- unidade gestora;
- classificacao orcamentaria;
- fonte/destinacao de recurso;
- empenho/liquidacao/pagamento, quando aplicavel;
- identificador externo.

### AUDESP / TCE-SP

Descricao: relacionamento com o sistema AUDESP do Tribunal de Contas do Estado de Sao Paulo para prestacao de contas e envio de dados contabeis/orcamentarios.

Requisitos:

- usar certificado digital quando exigido pelo TCE-SP;
- gerar arquivos/pacotes nos leiautes oficiais;
- validar estrutura antes do envio;
- manter historico por competencia, lote e tipo de demonstrativo;
- registrar recibos, rejeicoes e alertas;
- permitir correcao e reenvio sem perder versoes anteriores;
- relacionar cada envio aos registros contabeis locais;
- manter trilha de auditoria com responsavel e data.

Dados minimos esperados:

- ente/unidade gestora;
- exercicio e competencia;
- plano de contas;
- receitas, despesas, empenhos, liquidacoes e pagamentos;
- balancetes/demonstrativos;
- recibos e mensagens de validacao.

### PNCP

Descricao: relacionamento com o Portal Nacional de Contratacoes Publicas para publicacao, consulta, retificacao e manutencao de dados de contratacoes.

Requisitos:

- credenciar a plataforma/ente antes de publicar dados;
- autenticar com usuario/senha ou mecanismo equivalente para obter token JWT;
- manter associacao entre usuario da API e CNPJs autorizados;
- enviar contratacoes, atas, contratos, empenhos e documentos conforme APIs aplicaveis;
- armazenar sequenciais e identificadores retornados pelo PNCP;
- permitir retificacao, atualizacao e exclusao quando a API permitir;
- garantir que anexos estejam no formato aceito;
- validar CNPJ do orgao, unidade compradora, modalidade, fundamentos legais, datas e valores antes do envio;
- manter consulta publica desacoplada da operacao autenticada de manutencao.

Dados minimos esperados:

- CNPJ do orgao;
- unidade compradora;
- processo/ano/sequencial;
- modalidade e criterio;
- objeto;
- itens;
- fornecedores;
- contratos/atas;
- documentos;
- identificadores PNCP.

### ComprasNet / Compras.gov.br

Descricao: relacionamento com a plataforma federal de compras para consultas, apoio a processos e possiveis integracoes de compras publicas.

Requisitos:

- usar OAuth/token quando exigido;
- separar consulta publica de operacoes autenticadas;
- mapear unidades compradoras e perfis autorizados;
- conciliar itens, catalogos, fornecedores e processos locais;
- registrar origem de dados importados;
- preservar historico de alteracoes em processos licitatorios;
- impedir publicacao ou sincronizacao com dados incompletos de unidade, modalidade, objeto, datas e valores.

Dados minimos esperados:

- unidade compradora;
- processo de compra;
- itens e catalogos;
- fornecedor;
- situacao;
- documentos;
- identificador externo.

### TransfereGov

Descricao: relacionamento com a plataforma federal de transferencias, convenios, parcerias e instrumentos similares.

Requisitos:

- usar OAuth/token conforme credenciamento;
- controlar instrumentos por numero, ano, concedente, convenente, objeto e situacao;
- conciliar repasses, etapas, planos de trabalho, metas e prestacoes de contas;
- registrar documentos enviados e retornos de validacao;
- diferenciar consulta, importacao e manutencao de dados;
- manter alertas de prazo e pendencias;
- relacionar transferencias a receitas, despesas, obras, projetos ou assistencia social quando aplicavel.

Dados minimos esperados:

- CNPJ do convenente;
- orgao concedente;
- instrumento;
- plano de trabalho;
- metas/etapas;
- valores;
- cronograma;
- prestacao de contas;
- situacao externa.

### Receita Federal

Descricao: relacionamento fiscal para consulta/validacao de CPF, CNPJ e situacoes cadastrais/fiscais conforme autorizacao disponivel.

Requisitos:

- usar certificado digital quando exigido;
- limitar consultas a finalidades administrativas justificadas;
- registrar usuario, data, finalidade e entidade consultada;
- mascarar dados sensiveis em logs e telas;
- atualizar cadastro local somente com regra de conciliacao e confirmacao;
- armazenar origem da informacao cadastral e data da ultima validacao;
- respeitar politicas de rate limit e disponibilidade da API usada.

Dados minimos esperados:

- CPF ou CNPJ;
- nome/razao social;
- situacao cadastral;
- natureza juridica, CNAE ou endereco quando necessario;
- data da consulta;
- fonte externa.

### gov.br SSO OAuth2

Descricao: relacionamento de identidade para login unico do cidadao no portal publico ou em fluxos autenticados.

Requisitos:

- implementar fluxo OAuth2/OpenID Connect conforme credenciamento;
- configurar redirect URIs por ambiente;
- validar `state`, `nonce`, emissor, audiencia e expiracao de tokens;
- mapear identidade gov.br para pessoa local sem criar duplicidade;
- solicitar apenas escopos necessarios;
- permitir revinculacao controlada quando houver conflito cadastral;
- registrar eventos de login sem armazenar token em claro;
- definir comportamento para logout local e expiracao de sessao.

Dados minimos esperados:

- identificador unico do usuario;
- CPF, quando autorizado;
- nome;
- email, quando autorizado;
- nivel de conta/confiabilidade, quando fornecido;
- data da vinculacao.

### DATASUS / RNDS

Descricao: relacionamento de saude para interoperabilidade com sistemas do SUS, RNDS, CNES, e-SUS e bases relacionadas, conforme escopo contratado.

Requisitos:

- usar certificado digital e OAuth/token quando exigido;
- tratar dados de saude como dados pessoais sensiveis;
- registrar base legal, finalidade assistencial/administrativa e profissional responsavel;
- aplicar controle de acesso por perfil de saude;
- auditar consulta, importacao e envio de informacoes;
- validar estabelecimentos, profissionais, pacientes, atendimentos e documentos clinicos;
- impedir exibicao de dados clinicos em logs gerais;
- manter historico de sincronizacao por paciente, unidade e competencia, quando aplicavel.

Dados minimos esperados:

- CNS/CPF do paciente, quando exigido;
- estabelecimento/CNES;
- profissional/CBO/CNS, quando exigido;
- atendimento;
- vacina, procedimento, prescricao, exame ou documento clinico;
- identificador externo e recibo.

### MEC / EducaCenso

Descricao: relacionamento educacional para Censo Escolar, dados de escolas, turmas, matriculas e informacoes exigidas pelo MEC.

Requisitos:

- usar OAuth/token quando exigido;
- mapear escola, turma, aluno, matricula, etapa, modalidade e turno;
- validar dados obrigatorios antes do envio;
- controlar competencia/ano letivo;
- registrar recibos, pendencias e inconsistencias;
- permitir correcao com historico;
- conciliar dados educacionais com CadUnico/assistencia social somente quando houver base legal e necessidade operacional;
- restringir acesso a dados de menores de idade.

Dados minimos esperados:

- codigo da escola;
- aluno;
- turma;
- matricula;
- etapa/modalidade;
- necessidades educacionais especificas, quando exigido;
- situacao escolar;
- ano letivo.

### INEP

Descricao: relacionamento com bases, indicadores e estatisticas educacionais do INEP para consulta, comparacao e apoio a gestao.

Requisitos:

- identificar se a fonte e API, arquivo aberto ou integracao autenticada;
- registrar versao/ano da base importada;
- preservar metadados de origem;
- separar dado estatistico publico de dado individual;
- evitar sobrescrever cadastros locais com dados agregados;
- permitir reprocessamento de importacoes por ano/base;
- exibir indicadores com data de referencia.

Dados minimos esperados:

- codigo de escola/municipio;
- ano de referencia;
- indicador;
- valor;
- fonte;
- data de importacao.

## Relacionamentos com Orgaos Publicos Municipais

A aplicacao tambem deve representar relacionamentos internos entre orgaos, secretarias, departamentos, setores e divisoes municipais por meio do modulo de organizacao/unidades.

Requisitos:

- cadastrar unidades com tipo (`orgao`, `secretaria`, `departamento`, `setor`, `divisao`);
- manter hierarquia administrativa;
- vincular usuarios, perfis, permissoes e escopos a unidade correta;
- permitir direcionamento de solicitacoes, ouvidoria e LAI por orgao destino;
- registrar responsavel, prazo e situacao de cada encaminhamento;
- preservar historico de transferencia entre unidades;
- impedir que usuario de uma unidade acesse dados restritos de outra sem permissao explicita;
- publicar no portal somente informacoes classificadas como publicas.

Aplicacao nos modulos:

- Portal do Cidadao: solicitacoes por orgao destino.
- Ouvidoria: denuncias, reclamacoes, sugestoes e elogios direcionados.
- LAI/e-SIC: pedidos de informacao por orgao destino.
- Assistencia Social: encaminhamentos para INSS ou outros orgaos.
- Juridico: orgao julgador e processos.
- RH: lotacoes, estruturas e orgaos vinculados ao servidor.

## Requisitos de UI/UX

A rota `/integracoes-governo` deve permitir que administradores:

- consultem todos os provedores por categoria;
- vejam ambiente, status, ultima sincronizacao e ultima mensagem;
- configurem conexao, autenticacao, certificado e parametros avancados;
- facam upload de certificado;
- testem a conexao real;
- consultem os ultimos logs;
- ativem/desativem uma integracao;
- editem apenas segredos explicitamente preenchidos;
- vejam segredos sempre mascarados;
- filtrem rapidamente provedores com erro ou pendencia.

## Requisitos de QA

Para cada orgao/provedor, os testes devem cobrir:

- cadastro no catalogo;
- criacao de integracao em homologacao;
- validacao de campos obrigatorios por tipo de autenticacao;
- upload de certificado quando `requer_certificado = true`;
- mascaramento de segredos na view e na UI;
- teste de conexao com sucesso;
- teste de conexao com timeout;
- teste de conexao com erro HTTP;
- registro de log sanitizado;
- atualizacao de status da integracao;
- bloqueio para usuario nao admin;
- separacao entre homologacao e producao;
- comportamento de retry;
- preservacao de credenciais quando o formulario for salvo com placeholder `(mantido)`.

## Requisitos de Implantacao

Antes de declarar um relacionamento pronto para uso, a implantacao deve preencher:

- orgao/provedor;
- ambiente;
- URL base confirmada;
- responsavel tecnico do cliente;
- responsavel funcional do cliente;
- credenciais criadas;
- certificado instalado e validade;
- escopos/permissoes externas concedidas;
- payloads ou arquivos de teste;
- resultado da homologacao;
- procedimento de contingencia;
- data prevista de revisao de credenciais;
- data prevista de renovacao de certificado.

## Fontes Oficiais a Validar na Implantacao

As URLs abaixo devem ser usadas como ponto de partida e confirmadas antes da implementacao fina de cada adapter:

- PNCP: https://pncp.gov.br/manual/pt-br/latest/
- PNCP - API de consulta: https://pncp.gov.br/api/consulta
- eSocial: https://www.gov.br/esocial
- TransfereGov: https://www.gov.br/transferegov/pt-br/sobre/apis-integracao
- DATAPREV: https://www.dataprev.gov.br
- gov.br/acesso: https://acesso.gov.br
- Tesouro Nacional: https://www.gov.br/tesouronacional
- Receita Federal: https://www.gov.br/receitafederal
- DATASUS: https://datasus.saude.gov.br
- INEP: https://www.gov.br/inep

## Checklist de Pronto para Producao

Uma integracao so deve ser marcada como pronta para producao quando:

- o catalogo estiver preenchido;
- a instancia de homologacao tiver log de sucesso;
- os segredos estiverem mascarados em leitura;
- os certificados estiverem em storage privado;
- os perfis de acesso estiverem revisados;
- houver dono operacional definido;
- houver mapeamento de campos;
- houver plano de contingencia;
- houver evidencia de homologacao;
- o ambiente de producao tiver URL e credenciais proprias;
- a ativacao tiver sido aprovada por administrador do ente.