¶ Análise da API de Acompanhamento do Gov.br para o fluxo de agendamento do Alpha
| Data de elaboração | 27/04/2025 |
|---|---|
| Responsável pelo estudo | José Lucas da Silva Costa (Analista) |
| Equipe do estudo |
|
| Alvo | Alpha |
| Origem | Integração com os serviços do Gov.Br |
| Objetivo | Entender o que será necessário para que a integração entre ALPHA e o Governo Federal ocorra, e possibilite o acompanhamento do fluxo de agendamento. |
| Documentação correlata (opcional) |
https://wiki.setic.ro.gov.br/pt-br/home/spaces/code/gc/estudos/ving7 (documentação complementar) https://h-api-servicos.estaleiro.serpro.gov.br/api/v1/docs https://h-acompanhamento-govbrapi.estaleiro.serpro.gov.br/api/acompanhamento/swagger-ui.html |
| Observações | Ao final o estudo já irá abordar uma prévia das histórias a serem desenvolvidas |
¶ Introdução
O objetivo deste estudo é integrar o fluxo de agendamento do sistema Alpha com a API de Acompanhamento do Gov.br. A ideia é que, a cada mudança no status do agendamento — como criação, cancelamento, conclusão automática ou atendimento confirmado — o sistema envie essas informações para o Gov.br. Com isso, o cidadão poderá acompanhar o andamento da sua solicitação diretamente pelo portal, de forma mais prática e transparente.
¶ Fluxo de agendamento no Alpha para o Governo Federal
Quando um cidadão faz uma solicitação para um serviço público, diversas etapas precisam ser seguidas até que a solicitação seja atendida, e cada uma dessas etapas deve ser registrada adequadamente. No contexto da API gov.br, o fluxo do agendamento passa por diversas fases, e é preciso garantir que cada transição de estado seja registrada corretamente para que a plataforma de acompanhamento possa refletir essas mudanças de forma precisa.
Dentro do fluxo de agendamento do sistema Alpha, cada alteração de status representa uma nova etapa que precisa ser registrada no Gov.br. Por isso, foi feito um mapeamento para entender em quais momentos o Alpha deve se comunicar com a API de Acompanhamento.
Quando o agendamento é criado, automaticamente já se cria também o atendimento, e nesse momento o sistema deve registrar uma nova etapa na API informando que o agendamento foi realizado e que está aguardando atendimento. Se o usuário decidir cancelar o agendamento, o Alpha precisa atualizar o registro na API para informar que o agendamento foi cancelado.
Caso o cidadão não cancele e o dia e horário do agendamento passem sem uma confirmação, o próprio sistema executa um processo automático (o job de conclusão de agendamentos), encerrando a solicitação e também atualizando a situação no Gov.br para indicar que o atendimento foi finalizado.
Depois disso, o usuário ainda pode acessar o portal para informar se foi atendido ou não. Se ele confirmar o atendimento, é enviado um novo registro para a API marcando a etapa como “Atendimento Realizado” e concluída. Se, por outro lado, ele indicar que não foi atendido, o sistema registra essa informação na API como “Atendimento Não Realizado”.
Cada um desses eventos gera uma chamada específica para a API de Acompanhamento, sempre atualizando a etapa e a situação do serviço no portal federal, garantindo que o acompanhamento do cidadão esteja sempre atualizado conforme o que realmente aconteceu no Alpha. Vejamos fluxo a seguir resumido.
¶ Padrão sugerido de implementação
Devido a forma de implementação da API de acompanhamento já ter sido abordada neste estudo:
https://wiki.setic.ro.gov.br/pt-br/home/spaces/code/gc/estudos/ving7
Então neste irá abordar apenas os exemplos que são compatíveis com o objeto deste estudo, vejamos:
Para Agendamento:
{
"cpfCidadao": "12345678900",
"protocolo": "AGENDAMENTO-001",
"servico": "SERVICO-123",
"orgao": "36802",
"etapa": "Agendamento realizado",
"situacaoEtapa": "Em andamento",
"dataEtapa": "27/04/2025 09:00:00",
"dataSituacaoEtapa": "27/04/2025 09:00:00",
"dataRequisicao": "27/04/2025 08:00:00"
}Para Cancelamento:
{
"cpfCidadao": "12345678900",
"protocolo": "AGENDAMENTO-001",
"servico": "SERVICO-123",
"orgao": "36802",
"etapa": "Agendamento cancelado",
"situacaoEtapa": "Concluído",
"dataEtapa": "27/04/2025 10:00:00",
"dataSituacaoEtapa": "27/04/2025 10:00:00"
}
¶ Desafios da Integração entre Sistemas
Integrar o sistema Alpha com a API do gov.br envolve desafios técnicos e operacionais. É necessário garantir que os dados sejam transmitidos de forma segura, precisa e eficiente, respeitando todas as exigências legais, como a LGPD (Lei Geral de Proteção de Dados). Além disso, a sincronização entre os sistemas e o tratamento adequado de erros ou falhas são questões importantes a serem superadas durante a implementação.
¶ Impacto na Experiência do Cidadão
A integração entre o sistema Alpha e a API do gov.br também tem um impacto positivo na experiência do cidadão. Com o acompanhamento em tempo real, os cidadãos poderão acompanhar o status de seus agendamentos e atendimentos, desde a criação até a avaliação final. Isso oferece maior controle sobre o processo e facilita o acesso a informações essenciais, como horários de atendimento e possibilidade de cancelamento, tornando o processo mais intuitivo e eficiente.
¶ Padrões RESTful na Integração com a API gov.br
Na integração entre o sistema Alpha e a API gov.br, será adotada a arquitetura RESTful para garantir que as comunicações entre os sistemas sejam eficientes e padronizadas. Isso significa que todas as interações, como o registro de agendamentos, atualizações de status e confirmação de atendimentos, seguirão os princípios e práticas dessa abordagem.
Ao usar os métodos HTTP adequados, como GET, POST, PUT e DELETE, e garantir que as URLs sejam claras e descritivas, a integração será simples e fácil de entender. Além disso, o uso de códigos de status HTTP permitirá uma comunicação eficiente sobre o sucesso ou falha de cada operação.
Essa escolha pelo padrão RESTful assegura que o processo de acompanhamento de agendamentos e atendimentos seja realizado de forma consistente, escalável e de acordo com as melhores práticas de desenvolvimento de APIs, tornando a integração entre o sistema Alpha e a API gov.br mais robusta e confiável.
¶ Implementação da Integração com a API do Governo Federal: Camada Repository e Service
A integração de sistemas com APIs externas, como a API do governo federal, exige um planejamento cuidadoso para garantir uma comunicação eficiente e garantir que o sistema seja fácil de manter e escalar. Em C#, uma abordagem comum para essa integração é a utilização da arquitetura em camadas, que divide a aplicação em diferentes responsabilidades. No caso de integrar com a API gov.br, duas camadas principais entram em cena: Repository e Service. Essas camadas interagem de forma que permitem um fluxo claro e organizado de dados, garantindo que a comunicação com a API seja realizada de forma eficaz e sem a necessidade de o sistema principal se preocupar com detalhes técnicos da integração. Vejamos:
A camada Repository tem a responsabilidade de mapear todas as interações com fontes de dados externas, ou seja, ela realiza as chamadas para a API gov.br. O papel dessa camada é isolar a lógica de comunicação com a API, permitindo que o restante da aplicação não precise se preocupar com detalhes da implementação da API. Por exemplo, quando um agendamento precisa ser registrado, o Repository é quem vai definir o método que irá construir a requisição HTTP e enviá-la para a API gov.br. Com isso, toda a lógica relacionada à interação com a API fica encapsulada no Repository, enquanto outras partes do sistema não precisam saber como a requisição é formada ou como a API responde.
Além disso, o Repository é também responsável por tratar as respostas da API, transformando-as em objetos que o sistema pode manipular com facilidade. Isso é feito através de DTOs (Data Transfer Objects), que são objetos simples usados para transferir dados entre as camadas. Dessa forma, a resposta da API é convertida para um formato que o sistema entende, sem a necessidade de se preocupar com os detalhes específicos da resposta que a API fornece.
Por outro lado, a camada Service é onde reside a lógica de negócios do sistema. Sua principal responsabilidade é coordenar o fluxo de dados entre o Repository e outras partes do sistema, como os controladores. O Service aplica a lógica de negócios e decide quando e como chamar os métodos do Repository para realizar as operações necessárias. Por exemplo, antes de registrar um agendamento, o Service pode verificar se a data do agendamento é válida ou se o cidadão já tem algum agendamento no mesmo período. Isso garante que o sistema tome decisões de negócios antes de realizar chamadas externas à API, assegurando que os dados tratados estejam corretos.
O Service também pode orquestrar chamadas para múltiplos Repositories, caso seja necessário. Imagine um cenário onde, após o agendamento ser registrado, o sistema precisa atualizar o status de um atendimento. O Service pode chamar métodos de outro Repository para registrar essa atualização, garantindo que todas as operações necessárias para o fluxo de trabalho sejam realizadas de maneira ordenada e sem complicações.
Quando falamos do fluxo de trabalho no sistema, ele pode ser bem ilustrado em um exemplo prático. Quando um usuário solicita um agendamento para um serviço, o processo começa com o controlador do sistema chamando o Service para criar o agendamento. O Service realiza as validações necessárias, como garantir que o cidadão tem os dados corretos e que o horário do agendamento está disponível. Após as validações, o Service chama o Repository para registrar o agendamento na API gov.br.
Depois que o agendamento é registrado, a API retorna uma resposta que pode incluir o status do agendamento ou algum erro, dependendo da interação. O Service, então, verifica essa resposta e toma as ações necessárias. Caso o agendamento seja bem-sucedido, o Service pode prosseguir com outras etapas, como notificar o cidadão ou registrar mais informações. E se algo der errado, o Service pode decidir como tratar o erro ou o problema, garantindo que o fluxo do processo continue funcionando corretamente.
Com essa separação clara entre Repository e Service, o código fica mais modular e fácil de entender. Se alguma parte do sistema precisar ser alterada, como por exemplo a forma de comunicação com a API gov.br, você pode fazer as modificações dentro do Repository sem impactar as outras partes do sistema. Isso traz maior flexibilidade e facilita a manutenção do código, especialmente quando se trata de mudanças futuras ou novos requisitos. Além disso, essa abordagem torna o sistema mais escalável, pois a lógica de comunicação com a API é isolada em uma camada específica e pode ser expandida conforme necessário sem comprometer a estrutura do restante do sistema.
Ao isolar a lógica de comunicação com a API no Repository, o código se torna mais fácil de testar. Por exemplo, é possível escrever testes unitários para o Service sem precisar se preocupar com as interações reais com a API. Para testar o Repository, você pode usar mockups para simular as respostas da API e garantir que o Repository esteja funcionando corretamente. Isso torna a aplicação mais robusta, pois é possível testar as partes do sistema de forma independente, sem depender de chamadas externas reais durante o desenvolvimento e a fase de testes.
Essa arquitetura de camadas também traz uma série de benefícios em termos de organização e legibilidade do código. Como cada camada tem uma responsabilidade bem definida, o código fica mais organizado, e qualquer parte do sistema pode ser modificada ou corrigida sem grandes impactos nas demais. Quando algo der errado, o desenvolvimento fica mais fácil, pois é possível identificar rapidamente a origem do problema, seja na comunicação com a API (Repository) ou na lógica de negócios (Service). Além disso, a separação de responsabilidades permite que diferentes equipes possam trabalhar em diferentes partes do sistema, o que facilita a colaboração e aumenta a produtividade.
No fim das contas, a implementação dessa arquitetura de camadas, com as responsabilidades bem divididas entre Repository e Service, resulta em uma integração eficiente e escalável com a API do governo federal. A camada Repository cuida da comunicação com a API e do tratamento das respostas, enquanto o Service aplica a lógica de negócios e valida os dados. Isso torna o código mais modular, flexível e fácil de testar, além de garantir que a integração com a API gov.br seja robusta e eficaz a longo prazo. Essa estrutura bem definida permite que o sistema se adapte às mudanças de forma eficiente e que novos recursos sejam adicionados sem complicar a manutenção.
¶ Sugestões de História
Essas histórias de usuário são uma sugestão para o(a) PO (Product Owner), visando garantir clareza e rastreabilidade completa das ações no Alpha em integração com o Governo Federal e tem base nesse enum a seguir:
public enum StatusDoAgendamento
{
Agendado = 0,
Cancelado = 1,
Concluido = 2
}
¶ História de Usuário 1 — Registrar Criação de Agendamento
Eu, sistema Alpha,
Quero registrar a criação de um agendamento na API de acompanhamento do gov.br,
Para que o agendamento seja monitorado pelo sistema de acompanhamento do governo federal desde sua criação.
¶ Regras e Validações
O sistema deve registrar o agendamento com os status "Agendado" e "Aguardando Atendimento" na API de acompanhamento do gov.br assim que o agendamento for criado.
Os dados registrados devem incluir: CPF do cidadão, identificador do serviço, código do agendamento e data de agendamento.
¶ Cenário
Dado que um agendamento foi criado no sistema Alpha,
Quando o agendamento for registrado,
Então o sistema deve enviar uma solicitação para a API do gov.br, informando que o agendamento foi criado com os status "Agendado" e "Aguardando Atendimento".
¶ História de Usuário 2 — Registrar Cancelamento de Agendamento
Eu, sistema Alpha,
Quero registrar o cancelamento de um agendamento na API de acompanhamento do gov.br,
Para que o cancelamento seja acompanhado e monitorado pelo governo federal.
¶ Regras e Validações
O sistema deve registrar o cancelamento do agendamento na API de acompanhamento do gov.br com o status "Cancelado".
Os dados registrados devem incluir: CPF do cidadão, identificador do serviço, código do agendamento e motivo do cancelamento, se disponível.
¶ Cenário
Dado que um agendamento foi cancelado no sistema Alpha,
Quando o agendamento for cancelado,
Então o sistema deve enviar uma solicitação para a API do gov.br, informando que o agendamento foi cancelado e alterando seu status para "Cancelado".
¶ História de Usuário 3 — Registrar Conclusão do Agendamento
Eu, sistema Alpha,
Quero registrar a conclusão do agendamento na API de acompanhamento do gov.br,
Para que o governo federal possa acompanhar a conclusão do agendamento.
¶ Regras e Validações
O sistema deve registrar a conclusão do agendamento na API de acompanhamento do gov.br, alterando o status para "Concluído" após a execução do Job de conclusão.
Os dados registrados devem incluir: CPF do cidadão, identificador do serviço, código do agendamento, e a data e hora da conclusão.
¶ Cenário
Dado que um agendamento foi concluído no sistema Alpha,
Quando o agendamento for concluído,
Então o sistema deve enviar uma solicitação para a API do gov.br, informando que o agendamento foi concluído e alterando seu status para "Concluído".
¶ História de Usuário 4 — Registrar Confirmação de Atendimento
Eu, sistema Alpha,
Quero registrar a confirmação de atendimento ou não atendimento na API de acompanhamento do gov.br,
Para que o governo federal tenha o acompanhamento da resposta do cidadão quanto ao atendimento recebido.
¶ Regras e Validações
O sistema deve registrar a confirmação ou negação de atendimento na API de acompanhamento do gov.br com o status "Atendido" ou "Não Atendido", conforme a resposta do cidadão.
Os dados registrados devem incluir: CPF do cidadão, identificador do serviço, código do atendimento, e a confirmação de atendimento (sim ou não).
¶ Cenário
Dado que o cidadão confirmou ou negou o atendimento,
Quando o cidadão responder ao questionário de atendimento,
Então o sistema deve enviar uma solicitação para a API do gov.br, informando o status do atendimento como "Atendido" ou "Não Atendido".
¶ Conclusão
Este estudo teve como objetivo integrar o sistema Alpha com a API de acompanhamento do governo federal (gov.br), garantindo que cada etapa do agendamento e atendimento seja registrada de forma eficiente e transparente.
Através das histórias de usuário, foi possível definir claramente os processos de criação, cancelamento, conclusão, confirmação de atendimento e solicitação de avaliação, com a devida comunicação entre o sistema e a API do gov.br. Isso permitirá o acompanhamento em tempo real das ações realizadas, oferecendo mais controle e confiabilidade nos dados dos atendimentos.
Essa integração traz benefícios importantes para o sistema Alpha, como maior transparência, cumprimento das exigências legais e facilidade no monitoramento e fiscalização. No fim, o processo será mais ágil e acessível, tanto para os cidadãos quanto para as autoridades responsáveis.
Em resumo, a implementação dessas etapas vai garantir que o sistema Alpha esteja alinhado com as normas do gov.br, melhorando a gestão dos serviços prestados e a experiência para todos os envolvidos.