¶ Integração por Eventos entre o Alpha Solicitações e Outros Sistemas
| Data de elaboração | 24/08/2025 |
|---|---|
| Responsável pelo estudo | José Lucas da Silva Costa (Analista) |
| Equipe do estudo |
|
| Alvo | Alpha |
| Origem | Alpha Solicitações |
| Objetivo | Implementar um mecanismo que, a cada etapa concluída em um serviço, o sistema Alpha Solicitações envie mensagens que possam ser consumidos por outros sistemas interessados, permitindo que eles tomem decisões de forma independentes com a informação que esta ouvindo. |
| Documentação correlata (opcional) |
https://alphasolicitacoesapi.production.local/index.html https://wiki.setic.ro.gov.br/pt-br/home/spaces/code/gc/padroes |
| Observações | Nenhuma |
¶ Introdução
A SETIC-RO mantém o Alpha Solicitações (Back-end) como base para o Portal do Cidadão, sistema usado hoje para agendamentos de serviços e atendimentos públicos. Apesar da importância, o Alpha ainda funciona de forma isolada: quando uma etapa é concluída, a informação não chega automaticamente a outros sistemas do governo que poderiam utilizá-la.
O pedido feito é justamente para mudar isso:
“Implementar um mecanismo que, a cada etapa concluída em um serviço, o sistema Alpha Solicitações envie mensagens que possam ser consumidas por outros sistemas interessados, permitindo que eles tomem decisões de forma independentes com a informação que estão ouvindo.”
Ou seja, sempre que uma etapa for concluída, o Alpha deve emitir uma notificação ou evento, e outros sistemas podem reagir de forma independente, sem depender de chamadas diretas.
¶ Contexto e necessidade
Hoje, o Alpha Solicitações guarda as informações apenas para si. Se outro sistema quiser saber o que aconteceu, precisa consultar o Alpha por meio de APIs ou relatórios. Isso gera dependência, acoplamento e lentidão.
A proposta é mudar para um modelo assíncrono, em que:
- Sistemas externos possam reagir sozinhos aos eventos;
- Cada etapa concluída gere um evento auditável e monitorável;
- A comunicação seja fluida, sem necessidade de acoplamento direto via API síncrona.
¶ Caminhos possíveis
1. Webhook
No modelo Webhook, o próprio Alpha Solicitações envia uma requisição HTTP (POST) para os sistemas cadastrados sempre que uma etapa for concluída.
Por exemplo: se um cidadão confirmar um agendamento, o Alpha dispara uma notificação automática para o sistema de auditoria ou estatísticas.
Pontos fortes: simples de implementar, comunicação quase em tempo real.
Pontos fracos: se o sistema de destino estiver fora do ar, a mensagem pode se perder, a não ser que exista um mecanismo de reenvio (retry).
Observação vinda da liderança técnica: embora pareça simples, um webhook exige cuidados adicionais, como manter um gerenciamento mínimo para registrar e controlar as rotas configuradas, além de garantir resiliência no tratamento de falhas de envio, evitando a perda de mensagens. Esse ponto já havia sido levantado anteriormente, mas foi reforçado novamente para destacar a importância prática.
2. Fila de Mensagens
No modelo com Fila de Mensagens (ex.: RabbitMQ ou Kafka), o Alpha Solicitações não chama diretamente nenhum sistema. Ele apenas publica o evento em uma fila, e cada sistema interessado consome a informação no seu tempo.
Pontos fortes: garante que nenhum evento se perca, permite que novos sistemas passem a consumir os eventos sem alterar o Alpha e traz maior robustez e escalabilidade.
Pontos fracos: exige mais infraestrutura e conhecimento técnico para manter a fila funcionando.
Observação (conforme apontado pela liderança técnica): esse modelo é o mais recomendado sob o ponto de vista arquitetural. Contudo, sua aplicação prática depende do controle da infraestrutura, já que a fila não pode ser disponibilizada diretamente na internet para sistemas externos, o que limita sua adoção quando os consumidores não fazem parte do ambiente interno.
¶ Implementação do Webhook
Como sistema Alpha, quero enviar notificações para sistemas externos cadastrados (via Webhook) sempre que determinadas ações ocorrerem, para que os demais sistemas do governo possam acompanhar, auditar e reagir de forma independente e assíncrona.
O Alpha deve enviar uma requisição HTTP POST para os sistemas externos sempre que eventos-chave ocorrerem. O corpo da requisição deve conter: CPF do cidadão (quando aplicável), identificador da solicitação ou atendimento, serviço relacionado, tipo de evento (Cancelamento, Aprovação, Reprovação, Conclusão, Avaliação, etc.) e data e hora da ação. O sistema deve registrar logs das notificações enviadas para fins de auditoria. Em caso de falha no envio, devem ser feitas pelo menos 3 tentativas de reenvio. Vejamos o diagrama os cenários:
1. Cancelamento:
Dado que uma solicitação ou agendamento foi cancelado no Alpha,
Quando os endpoints /api/Solicitacao/Cancelar/{solicitacaoId} ou /api/Atendimento/ConfirmarNaoAtendimento/{id}/{justificativa} forem acionados,
Então o sistema envia um Webhook informando que o atendimento/solicitação foi cancelado com status "Cancelado".
2. Conclusão:
Dado que uma solicitação foi concluída,
Quando os endpoints /api/Solicitacao/ConcluirSolicitacao/{id} ou /api/Solicitacao/ConcluirEtapaDaSolicitacao/{etapaDaSolicitacaoId} forem acionados,
Então o sistema envia um Webhook informando que a solicitação/etapa foi concluída.
3. Aprovação/Reprovação:
Dado que uma solicitação foi aprovada ou reprovada,
Quando os endpoints /api/Solicitacao/AprovarSolicitacao, /api/Solicitacao/ReprovarSolicitacao, /api/Solicitacao/AprovarSolicitacaoDeServico/{id} ou /api/Solicitacao/ReprovarSolicitacaoDeServico/id/{id}/motivo/{motivo} forem acionados,
Então o sistema envia um Webhook notificando a decisão tomada, incluindo o motivo, se houver.
4. Avaliação:
Dado que o cidadão avaliou um atendimento,
Quando o endpoint /api/Atendimento/AvaliarAtendimento for acionado,
Então o sistema envia um Webhook contendo a nota, comentário e dados do serviço/atendimento avaliado.
¶ Implementação da Fila de Mensagens
Como sistema Alpha, quero enviar eventos para sistemas externos cadastrados via fila de mensagens (Kafka ou RabbitMQ) sempre que determinadas ações ocorrerem, para que os demais sistemas do governo possam acompanhar, auditar e reagir de forma independente e assíncrona.
O Alpha deve publicar uma mensagem na fila sempre que eventos-chave ocorrerem. O conteúdo da mensagem deve conter: CPF do cidadão (quando aplicável), identificador da solicitação ou atendimento, serviço relacionado, tipo de evento (Cancelamento, Aprovação, Reprovação, Conclusão, Avaliação, etc.) e data e hora da ação. O sistema deve registrar logs das mensagens publicadas para fins de auditoria. Em caso de falha no envio, devem ser feitas pelo menos 3 tentativas de reenvio. Vejamos o diagrama e os cenários:
1. Cancelamento:
Dado que uma solicitação ou agendamento foi cancelado no Alpha,
Quando os endpoints /api/Solicitacao/Cancelar/{solicitacaoId} ou /api/Atendimento/ConfirmarNaoAtendimento/{id}/{justificativa} forem acionados,
Então o sistema publica uma mensagem na fila informando que o atendimento/solicitação foi cancelado com status "Cancelado".
2. Conclusão:
Dado que uma solicitação foi concluída,
Quando os endpoints /api/Solicitacao/ConcluirSolicitacao/{id} ou /api/Solicitacao/ConcluirEtapaDaSolicitacao/{etapaDaSolicitacaoId} forem acionados,
Então o sistema publica uma mensagem na fila informando que a solicitação/etapa foi concluída.
3. Aprovação/Reprovação:
Dado que uma solicitação foi aprovada ou reprovada,
Quando os endpoints /api/Solicitacao/AprovarSolicitacao, /api/Solicitacao/ReprovarSolicitacao, /api/Solicitacao/AprovarSolicitacaoDeServico/{id} ou /api/Solicitacao/ReprovarSolicitacaoDeServico/id/{id}/motivo/{motivo} forem acionados,
Então o sistema publica uma mensagem na fila notificando a decisão tomada, incluindo o motivo, se houver.
4. Avaliação:
Dado que o cidadão avaliou um atendimento,
Quando o endpoint /api/Atendimento/AvaliarAtendimento for acionado,
Então o sistema publica uma mensagem na fila contendo a nota, comentário e dados do serviço/atendimento avaliado.
¶ Monitoria e Auditoria de Eventos
Além da forma de comunicação (Webhook ou Fila de Mensagens), é essencial que o Alpha Solicitações possua um mecanismo interno de monitoria dos eventos gerados.
A cada etapa concluída, quando um evento for disparado, o sistema deve registrar internamente:
Data e hora em que o evento foi gerado.
Tipo de evento (ex.: criação, cancelamento, conclusão, avaliação).
Destino (qual sistema ou fila deveria receber a informação).
Status do envio (enviado com sucesso, falha, pendente de reenvio).
Identificador único do evento, para rastreabilidade.
Esse registro cumpre dois papéis principais:
Auditoria: permite verificar posteriormente quais eventos foram gerados, garantindo transparência e confiabilidade.
Monitoramento: facilita identificar falhas no fluxo de comunicação e agir rapidamente em caso de perda ou erro no envio.
Observação da liderança técnica: a monitoria não depende da escolha entre Webhook ou Fila. Ela deve existir de forma central no Alpha, funcionando como um log interno e auditável de todos os eventos disparados.
¶ Conclusão
A modernização do Alpha Solicitações passa pela capacidade de se comunicar automaticamente com outros sistemas do governo. Tanto os Webhooks quanto as Filas de Mensagens atendem ao pedido inicial, com diferentes níveis de complexidade.
- O Webhook é mais rápido de implantar e pode ser o primeiro passo.
- A Fila de Mensagens é mais robusta e preparada para crescer, sendo a solução ideal a médio e longo prazo.
De qualquer forma, o importante é que cada etapa concluída no Alpha deixe de ser um dado isolado e passe a ser um evento útil para outros sistemas, trazendo mais integração, eficiência e benefícios ao cidadão.