| Data de elaboração | 10/06/2025 |
| Responsável pelo estudo | Moisés Ferreira (Assessor), Equipe do estudo Caveiras |
| Alvo | Alpha e Portal do Servidor |
| Origem | Análise: Avaliação em relação à integração e consumo de informações via API REST. |
| Objetivo | Este estudo visa identificar problemas na sincronização de dados, indisponibilidades na exibição das Cartas de Serviços e erros de comunicação entre o sistema Alpha e o sistema Portal do Servidor. |
| Observações | Atualmente, não há formas de a equipe saber exatamente onde está ocorrendo o problema. No entanto, existem processos dentro do sistema que podem ser otimizados. |
Este estudo visa identificar possíveis pontos sensíveis a falhas na sincronização de dados, indisponibilidades na exibição das Cartas de Serviços e erros de comunicação entre os sistemas. A partir dessa análise, serão propostas soluções para garantir maior estabilidade, confiabilidade e precisão na integração, assegurando que os servidores possam acessar e solicitar serviços administrativos de forma simples e eficiente por meio do Portal do Servidor.
Falhas na integração entre o sistema Alpha e o Portal do Servidor podem comprometer a exibição e a disponibilidade das Cartas de Serviços, dificultando o acesso dos servidores às informações e à solicitação de serviços relacionados à gestão de pessoas, como anexação de atestados médicos, entre outros requerimentos — impactando a eficiência e a usabilidade do sistema.
O consumo de informações da API alphasolicitacoesapi dentro do portal do servidor é feita por meio da implementação de dois serviços: IAgendamentoApi e IApiServicos. Abaixo listo os endpoints utilizados em cada serviço.
IApiServicosObterVideoConferencias
GET api/VideoConferencia/Obter/
CriarAcompanhamentoDoSolicitante
POST api/Solicitacao/CriarAcompanhamentoDoServidor
CancelarSolicitacao
POST api/Solicitacao/Cancelar/
ReprovarSolicitacaoDeServico
POST api/Solicitacao/ReprovarSolicitacaoDeServico/id/{id}/motivo/
AprovarSolicitacaoDeServico
PUT api/Solicitacao/AprovarSolicitacaoDeServico/
InformarSatisfacao
POST api/Solicitacao/InformarSatisfacao
ObterTotalDeNotificacoesDaCartaDeServico
GET api/Solicitacao/ObterTotalDeNotificacoesDaCartaDeServico/
LimparNotificacoesDaSolicitacao
POST api/Solicitacao/LimparNotificacoes/
ObterNotificacoesNaoVisualizadasPorSolicitacao
GET api/Solicitacao/ObterNotificacoesNaoVisualizadasPorSolicitacao/
SalvarAssinatura
POST api/Solicitacao/AdicionarAssinatura
GravarSolicitacaoDeServico
POST api/SolicitacaoDoServidor/Gravar
ObterSolicitacaoPorIdParaAssinar
GET api/Solicitacao/ObterSolicitacaoPorIdParaAssinar/
ObterSolicitacaoPorId
GET api/Solicitacao/ObterSolicitacaoPorId/
ObterPrazoParaSistemaExterno
POST api/Solicitacao/ObterPrazoParaSistemaExterno/
ObterSolicitacoesPorCpf
GET api/SolicitacaoDoServidor/ObterSolicitacoesPorCpf/
ObterDiasDisponiveisParaAgendamento
GET api/Agendamento/ObterDiasDisponiveisParaAgendamento/{servicoId}/{departamentoResponsavelId}/
IAgendamentoApiObterAgendamentosPorCpf
GET api/Agendamento/ObterAgendamentosDoServidorPorCpf/
ObterAgendamentoPorId
GET api/Agendamento/ObterAgendamentoPorId/
VerificarAcessoAgendamento
GET api/Agendamento/VerificarAcesso/
CriarAgendamento
POST api/Agendamento/CadastrarAgendamentoDoServidor
CancelarAgendamento
POST api/Agendamento/CancelarAgendamento/
A seguir, são apresentados pontos de melhoria na implementação e no uso de recursos que acarretam maior instabilidade na comunicação entre os sistemas.
Problema: A implementação do serviço IApiServicos, além de consumir os métodos citados acima, realiza o consumo de outras APIs. Isso faz com que essa classe assuma várias responsabilidades, como agendamentos, notificações, assinaturas, etc.
Melhoria: Podemos separar os métodos da classe ApiServicos por domínio: IAgendamentoService, IAssinaturaService, INotificacaoService, etc., seguindo o princípio SRP (Single Responsibility Principle).
RestClient.Execute (síncrono) com async TaskProblema: A implementação usa client.Execute(…) (síncrono) e depois faz await Task.FromResult(…), o que não é assíncrono de verdade.
Melhoria: Usar await client.ExecuteAsync(…).
A política de retentativa está configurada para lidar com falhas transitórias em requisições HTTP e tentar novamente antes de desistir.
Define que, se uma falha ocorrer, serão feitas até duas retentativa. O tempo entre cada tentativa segue um crescimento exponencial: primeiro 2 segundos, depois 4 segundos.
return HttpPolicyExtensions.
.HandleTransientHttpError()
.OrTransientHttpStatusCode()
.OrResult(result => result.StatusCode.Equals(HttpStatusCode.NotFound))
.WaitAndRetryAsync(2, retryAttempt => TimeSpan.FromSeconds(Math.Pow(2, retryAttempt)));
Problema: Essa implementação não inclui um Circuit Breaker. Ela apenas define uma política de retentativa com espera exponencial, ou seja, tenta novamente em caso de erro transitório ou resposta 404, até o número máximo de tentativas configuradas.
Melhoria: O Circuit Breaker atua como um disjuntor: monitora falhas e, quando identifica que um serviço está consistentemente falhando, abre o circuito e impede novas requisições por um período de tempo. Isso evita sobrecarga em um sistema que já está em dificuldade e melhora a estabilidade geral.
.CircuitBreakerAsync(3, TimeSpan.FromSeconds(30))
Isso impede novas chamadas quando a API está instável por um tempo.
Problema: Atualmente a API não implementa o padrão IETF RFC 7807.
Melhoria: Implementar o padrão conforme documentação da wiki https://wiki.setic.ro.gov.br/home/spaces/code/gc/padroes/developer-guidelines/apis#erros.
O padrão RFC 7807 define o objeto «detalhes do problema» como uma forma de transportar erros legíveis em uma resposta HTTP para evitar a necessidade de definir novos formatos de resposta de erro para APIs HTTP.
Problema: O código oculta falhas ao retornar um valor padrão, como 0, null ou uma string vazia, em vez de comunicar explicitamente que ocorreu um erro. Isso pode parecer conveniente para evitar interrupções no fluxo de execução, mas tem consequências perigosas, como:
Exemplo:
public async Task<int> ObterTotalDeNotificacoesDaCartaDeServico(string cpf)
{
RestClient client = new RestClient(UriAlphaSolicitacoesApi);
var rest = $"api/Solicitacao/ObterTotalDeNotificacoesDaCartaDeServico/{cpf}";
var request = new RestRequest(rest, Method.GET);
var response = client.Execute(request);
if (response.StatusCode == HttpStatusCode.OK)
{
var respostaJson = JsonConvert.DeserializeObject<int>(response.Content);
return await Task.Run(() => respostaJson);
}
return await Task.Run(() => 0);
}
Melhoria: Lançar exceções adequadas ou registrar erros (logs) para rastrear problemas, garantindo que sejam detectados e corrigidos.
Problema: Atualmente, a comunicação do portal do servidor com o Alpha não utiliza uma chave da central do desenvolvedor
Melhoria: Implementar autenticação da PI do alpha por meio do uso de chaves da central do desenvolvedor. Pagina da wiki com instruções de como implementar: https://wiki.setic.ro.gov.br/pt-br/home/spaces/code/migration/Ferramentas/centraldev/manuais
A análise realizada evidencia que há pontos de melhorias na integração entre o sistema Alpha e o Portal do Servidor, principalmente em relação à estabilidade, tratamento de erros, organização do código e ausência de práticas recomendadas de resiliência. A implementação atual, embora funcional, apresenta riscos de falhas silenciosas e dificuldade de manutenção.
Dentre os principais problemas identificados estão: o acoplamento excessivo de responsabilidades em uma única implementação, o uso de chamadas síncronas travestidas de assíncronas, a ausência de mecanismos como Circuit Breaker, o mascaramento de erros e a falta de autenticação por chave via Central do Desenvolvedor.