¶ Realizar uma análise da documentação da API Acompanhamento e Avaliação de Serviços do Gov.br
| Data de elaboração | 17/03/2025 |
|---|---|
| Responsável pelo estudo | José Lucas da Silva Costa (Analista) |
| Equipe do estudo |
|
| Alvo | Portal do Cidadão |
| Origem | Integração com os serviços do Gov.Br |
| Objetivo | Este estudo tem por objetivo realizar uma análise da documentação de integração da API de acompanhamento e avaliação |
| Documentação correlata (opcional) |
https://wiki.setic.ro.gov.br/pt-br/home/spaces/code/gc/estudos/0 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
A ideia desse estudo é entender como fazer a integração do Portal do Cidadão de Rondônia com as APIs do Governo Federal. Com essa integração, quando o estado cadastrar um serviço no Portal do Cidadão, ele já vai aparecer automaticamente no página de serviços do Governo Federal, sem precisar cadastrar de novo lá.
As APIs que vamos usar são:
Serviços API: é a principal. Com ela se consegue cadastrar, alterar, excluir, despublicar ou publicar os serviços. Tudo o que for feito no Portal do Cidadão vai ser enviado para o gov.br por meio dessa API.
Acompanhamento API: serve para acompanhar o status dos serviços que foram enviados. Por exemplo, depois que o serviço é cadastrado, dá pra ver se ele já foi iniciado, se ainda está em análise, ou se precisa de alguma coisa.
Avaliação API: com essa API, é possível ver o que os cidadãos estão achando dos serviços. Dá pra pegar as notas e comentários que eles deixam. Assim, o estado pode melhorar os serviços com base nesse feedback.
¶ Serviços API: Proposta de integração com o Alpha
A proposta é usar o próprio sistema Alpha, que já é o sistema oficial de cadastro de serviços do Estado de Rondônia, para também enviar essas informações automaticamente para o gov.br.
Assim, ao cadastrar ou atualizar um serviço no Alpha, o sistema vai gerar a publicação no Governo Federal, garantindo que o serviço (e suas informações completas, como etapas) integre sem necessidade de duplicar o trabalho.
Na tela de detalhes de cada serviço no Alpha, será criada uma nova aba chamada "Governo Federal", e dentro dessa aba o servidor vai conseguir realizar o envio das informações do serviço:
Publicar ou Despublicar o serviço no gov.br:
- Sempre que o serviço for atualizado no Alpha, o sistema vai automaticamente gerar uma publicação.
- A publicação levará todas as informações atualizadas do serviço, incluindo as etapas necessárias para o cidadão acessar o serviço.
- O botão Despublicar vai remover o serviço do ar no Governo Federal, mas ele continuará disponível no Alpha.
Excluir o serviço do Governo Federal:
- A exclusão será uma opção junto com "Publicar" e "Despublicar", e será obrigatória a inserção de uma justificativa explicando o motivo da exclusão.
- Após excluir o serviço do Governo Federal, os botões "Despublicar" e "Excluir" não estarão mais visíveis, pois o serviço deixará de existir lá.
- A exclusão será sempre confirmada com o servidor para evitar erros.
Importante: As etapas do serviço também serão enviadas junto com o serviço, garantindo que o cidadão consiga visualizar como acessar, quais documentos levar, prazos, e demais informações necessárias.
¶ Acompanhamento e Avaliação API: Proposta de integração
Em relação à integração com as APIs de Acompanhamento e Avaliação, entendemos que essas funcionalidades representam uma camada importante para o ciclo completo de oferta de serviços ao cidadão, garantindo não apenas o acesso, mas também o monitoramento e a melhoria contínua da qualidade desses serviços. Vejamos o fluxo:
Porém, por se tratarem de funcionalidades que envolvem fluxos distintos — como o acompanhamento de solicitações feitas pelo cidadão e a coleta de feedbacks sobre o serviço —, acreditamos que a abordagem para essas integrações deva ser pensada com o devido cuidado, respeitando o momento ideal dentro do cronograma do projeto. Vejamos a tela de feedback também:
Neste primeiro momento, o foco está concentrado na integração para o cadastro e publicação dos serviços estaduais, visando garantir que o Alpha e o Portal do Cidadão estejam devidamente alinhados com o Governo Federal na oferta e exibição dos serviços. A partir do momento em que esses fluxos principais estiverem estáveis e homologados, a integração com as APIs de Acompanhamento e Avaliação poderá vir de forma mais estruturada, permitindo uma abordagem mais estratégica e menos corrida.
Além disso, é importante considerar que a integração com Acompanhamento e Avaliação exige uma série de definições adicionais, como:
- Quais serviços serão passíveis de acompanhamento?
- Quais etapas ou status de atendimento serão compartilhados com o cidadão via Governo Federal?
- Como será feito o retorno das avaliações ao Alpha? Essas avaliações terão impacto na gestão do serviço?
- Quais papéis e permissões os servidores estaduais terão na gestão desses feedbacks?
Por serem questões sensíveis e que impactam diretamente a experiência do cidadão, acreditamos que é prudente reservar um estudo específico e mais aprofundado para essa etapa.
Portanto, reforçamos que a integração com Acompanhamento e Avaliação deve fazer parte de uma segunda fase do projeto, a ser discutida em um estudo dedicado, com o envolvimento do time Vingadores, garantindo uma visão completa do processo.
Dessa forma, asseguramos que a solução entregue seja eficiente, segura e, principalmente, útil tanto para o cidadão quanto para a gestão pública.
¶ Sugestões de Histórias de Usuário
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.
¶ História de Usuário 1 — Publicar Serviço no Governo Federal
Eu, gestor de serviços, Quero que o botão "Publicar" esteja disponível na aba "Governo Federal" dos detalhes de um serviço cadastrado no Alpha
Por quê?
Para que eu consiga disponibilizar o serviço diretamente no Governo Federal, de forma prática, e que o sistema registre quem realizou a ação e quando.
¶ Regras e Validações
- O botão "Publicar" deve estar visível apenas quando o serviço ainda não estiver publicado no Governo Federal.
- Ao clicar em "Publicar", o sistema Alpha deve tentar realizar a publicação direta no Governo Federal.
- Se a publicação for bem-sucedida, o Alpha deve:
- Registrar um histórico, contendo:
- CPF do usuário que realizou a ação;
- Data e hora da ação;
- Resultado: "Publicação realizada com sucesso no Governo Federal".
- Exibir ao usuário uma mensagem de sucesso: "Serviço publicado com sucesso no Governo Federal"
- Registrar um histórico, contendo:
- Se a publicação falhar, o sistema deve:
- Registrar uma pendência de publicação no banco de dados.
- Registrar no histórico:
- CPF do usuário;
- Data e hora;
- Resultado: "Falha na publicação no gov.br. Motivo: [erro retornado]".
- Exibir ao usuário uma mensagem de erro: "Não foi possível publicar o serviço. Por favor, tente novamente mais tarde."
- Enquanto o serviço estiver publicado, o botão "Publicar" não deve aparecer (deve ser substituído pelo botão "Despublicar").
- A ação de publicar deve sempre exigir confirmação: "Deseja realmente publicar este serviço no gov.br?"
¶ Cenários
Dado que o gestor acessa os detalhes de um serviço,
Quando o serviço não estiver publicado,
Então o botão "Publicar" deve estar visível e ativo.
Dado que o gestor clica em "Publicar",
Quando confirma a ação,
Então o Alpha tenta publicar o serviço no Governo Federal
Dado que a publicação ocorre com sucesso,
Então o sistema registra o histórico completo e exibe a mensagem de sucesso.
Dado que a publicação falha,
Então o sistema registra a pendência e o histórico completo, e exibe a mensagem de erro.
¶ História de Usuário 2 — Despublicar Serviço do Governo Federal
Eu, gestor de serviços, Quero que o botão "Despublicar" esteja disponível na aba "Governo Federal" dos detalhes de um serviço publicado no Alpha
Por quê?
Para que eu possa remover o serviço do Governo Federal, quando necessário, e o sistema registre quem realizou a ação e quando.
¶ Regras e Validações
- O botão "Despublicar" deve estar visível apenas quando o serviço já estiver publicado no Governo Federal
- Ao clicar em "Despublicar", o sistema Alpha deve tentar realizar a despublicação direta no Governo Federal
- Se a despublicação for bem-sucedida, o Alpha deve:
- Registrar um histórico, contendo:
- CPF do usuário que realizou a ação;
- Data e hora da ação;
- Resultado: "Despublicação realizada com sucesso no Governo Federal".
- Exibir ao usuário uma mensagem de sucesso: "Serviço despublicado com sucesso do Governo Federal"
- Registrar um histórico, contendo:
- Se a despublicação falhar, o sistema deve:
- Registrar uma pendência de despublicação no banco de dados.
- Registrar no histórico:
- CPF do usuário;
- Data e hora;
- Resultado: "Falha na despublicação no Governo Federal. Motivo: [erro retornado]".
- Exibir ao usuário uma mensagem de erro: "Não foi possível despublicar o serviço. Por favor, tente novamente mais tarde."
- Após a despublicação, o botão "Despublicar" deixa de ser exibido, e o botão "Publicar" volta a aparecer.
- A ação de despublicar deve sempre exigir confirmação: "Deseja realmente despublicar este serviço do Governo Federal?"
¶ Cenários
Dado que o gestor acessa os detalhes de um serviço publicado,
Quando acessar a aba "Governo Federal",
Então o botão "Despublicar" deve estar visível.
Dado que o gestor clica em "Despublicar",
Quando confirma a ação,
Então o Alpha tenta despublicar o serviço no Governo Federal
Dado que a despublicação ocorre com sucesso,
Então o sistema registra o histórico completo e exibe a mensagem de sucesso.
Dado que a despublicação falha,
Então o sistema registra a pendência e o histórico completo, e exibe a mensagem de erro.
¶ História de Usuário 3 — Excluir Serviço do Alpha e do Governo Federal
Eu, gestor de serviços, Quero que o botão "Excluir" esteja disponível na aba "Governo Federal" dos detalhes de um serviço publicado no Governo Federal.
Por quê?
Para que eu possa remover o serviço do Governo Federal (se já estiver publicado), quando ele não for mais necessário, e o sistema registre quem fez a ação, quando foi feita, e o motivo da exclusão.
¶ Regras e Validações
- O botão "Excluir" deve estar visível apenas quando o serviço estiver publicado.
- Antes de excluir, o sistema deve solicitar uma justificativa obrigatória ao usuário, por meio de um campo de texto.
- A ação de excluir deve sempre exigir confirmação adicional, com a pergunta:
"Deseja realmente excluir este serviço do Governo Federal?" - Ao confirmar a exclusão:
- O serviço deve ser removido da base do Governo Federal (poderá ficar registrado apenas como histórico).
- Registrar no histórico, contendo:
- CPF do usuário que realizou a ação;
- Data e hora da ação;
- Justificativa preenchida;
- Resultado: "Serviço excluído com sucesso do Governo Federal".
- Após a exclusão, o serviço não poderá mais ser listado ou acessado pelo usuário no Governo Federal.
- Os botões "Despublicar" e "Excluir" não devem mais ser exibidos após a exclusão.
- Caso a exclusão falhe em alguma etapa (ex.: falha ao despublicar no gov.br), o sistema deve:
- Registrar um histórico de tentativa de exclusão no banco de dados, especificando o motivo da falha.
- Registrar no histórico:
- CPF do usuário;
- Data e hora;
- Justificativa;
- Resultado: "Falha na exclusão. Motivo: [erro retornado]".
- Exibir ao usuário uma mensagem de erro: "Não foi possível excluir o serviço no Governo Federal. Por favor, tente novamente mais tarde."
¶ Cenários
Dado que o gestor acessa os detalhes de um serviço,
Quando acessar a aba "Governo Federal",
Então o botão "Excluir" deve estar visível (se o serviço ainda não foi excluído).
Dado que o gestor clica em "Excluir",
Quando insere a justificativa e confirma a exclusão,
Então o Alpha exclui o serviço e registra o histórico completo.
Dado que a exclusão ocorre com sucesso,
Então o sistema exibe a mensagem: "Serviço excluído com sucesso."
E o serviço não aparece mais em listas ou buscas do Governo Federal.
Dado que a exclusão falha (ex.: falha ao excluir no Governo Federal),
Então o sistema registra a pendência e o histórico completo,
E exibe a mensagem de erro: "Não foi possível excluir o serviço no Governo Federal. Por favor, tente novamente mais tarde."
¶ Conclusão
Com base na análise realizada sobre a integração do Portal do Cidadão do Governo do Estado de Rondônia (Alpha) com as APIs do Governo Federal, foi possível identificar caminhos viáveis para garantir que os serviços estaduais sejam disponibilizados de forma automatizada e integrada ao gov.br, proporcionando uma experiência unificada e simplificada ao cidadão.
Foi possível compreender que a integração inicial deve focar no cadastro, edição, publicação, despublicação e exclusão dos serviços estaduais, de modo que o Alpha passe a ser o sistema central de gestão desses serviços, sem a necessidade de plataformas ou telas adicionais. Com isso, todas as ações relativas aos serviços estaduais poderão ser feitas diretamente no Alpha, com a possibilidade de refletir essas ações automaticamente na base do Governo Federal, respeitando o controle e gestão do próprio Estado.
A solução pensada prioriza a simplicidade e o controle centralizado, permitindo que o gestor estadual, a partir de um único ambiente, possa:
- Cadastrar e editar os serviços;
- Publicar ou despublicar no gov.br conforme a necessidade;
- Excluir serviços com registro de justificativa, data e CPF do responsável;
Além disso, o estudo também deixou claro que a integração com as APIs de Acompanhamento e Avaliação será um passo importante, mas que deverá acontecer em uma segunda fase do projeto, mediante um novo levantamento de requisitos e análise técnica mais profunda. Essa decisão visa garantir que a primeira fase seja finalizada com qualidade, e que o ciclo completo (cadastro, publicação, acompanhamento e avaliação) seja construído com a atenção e estrutura necessárias.
Em resumo, o caminho proposto oferece ao Estado de Rondônia uma solução segura, integrada e em conformidade com as exigências do Governo Federal, ao mesmo tempo que mantém a autonomia e o controle dos serviços estaduais, permitindo uma gestão eficiente, transparente e centrada no cidadão.