¶ Análise da documentação da APIs de Avaliação e Acompanhamento do Gov.br
| Data de elaboração | 10/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 as APIs aconteça, e possibilite o acompanhamento e avaliação dos serviços publicados. |
| 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 integração entre sistemas é um passo essencial para garantir que as informações circulem de forma fluida e segura entre diferentes plataformas do governo Estadual e Federal. No caso do ALPHA, a conexão com as APIs de Avaliação e Acompanhamento do Gov.br pode abrir caminho para um monitoramento mais eficiente e transparente dos serviços públicos oferecidos à população.
Este estudo tem como objetivo entender como essas APIs funcionam, quais são os pré-requisitos técnicos para a integração com o ALPHA e quais limitações ou possibilidades estão envolvidas nesse processo. Além disso, busca responder a algumas dúvidas práticas, como: as avaliações feitas no Gov.br poderão ser exibidas no ALPHA? É possível limitar o acompanhamento apenas aos atendimentos online e presenciais?
A ideia aqui é mapear tudo o que será necessário para que essa integração seja realmente viável e traga benefícios concretos para o acompanhamento e a avaliação dos serviços disponibilizados.
¶ Acompanhamento - Visão Geral
A API de Acompanhamento do Gov.br foi criada para permitir que órgãos públicos registrem e consultem o andamento das etapas de prestação de serviços aos cidadãos, de forma estruturada e padronizada. Essa funcionalidade é essencial para garantir mais transparência e possibilitar que o cidadão acompanhe, de forma simples, o status de solicitações feitas em ambientes digitais ou presenciais.
A integração com o sistema ALPHA permitirá registrar informações como início e conclusão de etapas de um atendimento, bem como consultar os dados de acompanhamento vinculados a um cidadão, protocolo, órgão ou serviço específico.
¶ Acompanhamento - Registro de Etapas
A principal operação da API nesse contexto é o endpoint POST, que aceita o envio dos seguintes dados:
cpfCidadao (opcional): CPF ou CNPJ do cidadão, sem formatação (mínimo 11 e máximo 14 dígitos).
dataEtapa: Data da execução da etapa do serviço.
dataFechamento (opcional): Data em que a etapa foi encerrada.
dataRequisicao (opcional): Data da solicitação do serviço.
dataSituacaoEtapa: Data em que a situação da etapa foi registrada.
etapa: Descrição da etapa realizada (ex: "Solicitação Recebida").
situacaoEtapa: Situação atual da etapa (ex: "Em Andamento", "Concluída").
flBotao (opcional): Indicador de ação (1 = Ver, 2 = Responder).
linkBotao (opcional): URL de redirecionamento para mais detalhes sobre o serviço.
orgao (opcional): Identificador do órgão responsável.
protocolo: Identificador único da solicitação de serviço.
servico: Identificador do serviço vinculado ao órgão.
Esses campos permitem uma ampla personalização e detalhamento do acompanhamento, tornando possível registrar desde a abertura até o encerramento de cada etapa do atendimento, vejamos um exemplo de inserção:{
"cpfCidadao": "99999999999",
"dataEtapa": "10/04/2025 23:23:23",
"dataFechamento": "12/04/2025 23:23:23",
"dataRequisicao": "10/04/2025 23:23:23",
"dataSituacaoEtapa": "10/04/2025 23:23:23",
"etapa": "Em Processamento.",
"flBotao": 1,
"linkBotao": "https://www.gov.br/pt-br/servicos/obter-o-certificado-internacional-de-vacinacao-e-profilaxia",
"orgao": "36802",
"protocolo": "0001AC.20171212",
"servico": "47",
"situacaoEtapa": "Alguma descrição da situação."
}
¶ Acompanhamento - Consultas Disponíveis
A API também permite consultar os registros já inseridos por meio de endpoints GET, incluindo:
/porCidadao: Consultar por CPF/CNPJ.
/porProtocolo: Consultar pelo número de protocolo.
/porServico: Consultar por serviço.
/porOrgao: Consultar por órgão.
/servicosCidadao: Ver todos os serviços associados a um cidadão.
/docsEstaduais: Retornar a documentação dos serviços estaduais.
Essas operações são úteis para reuso de dados em sistemas integrados como o ALPHA, especialmente em interfaces voltadas ao usuário final.
¶ Acompanhamento - Atualização de Situação
Além do registro inicial, é possível também atualizar a situação de um acompanhamento já existente por meio do endpoint PUT /situacao. Os campos aceitos são:
cpfCidadao (opcional)
orgao (opcional)
protocolo (obrigatório)
servico (obrigatório)
situacaoServico (opcional): Situação atual (1 = Em Aberto, 2 = Concluído)
¶ Acompanhamento - Mapeamento das Etapas com o Alpha
No sistema ALPHA, os registros de acompanhamento de um atendimento são classificados por meio do enum TipoDeAcompanhamento, conforme abaixo:
public enum TipoDeAcompanhamento
{
AcompanhamentoDoAtendente = 0,
AcompanhamentoDoSolicitante = 1,
Conclusao = 2,
ReprovacaoDaConclusao = 3,
AprovacaoDaConclusao = 4
}Cada valor do enum representa uma etapa ou ação significativa no fluxo do atendimento, tanto do ponto de vista do cidadão quanto do atendente. Para registrar essas ações na API do Gov.br, é necessário realizar um mapeamento para os campos etapa e situacaoEtapa, que são exigidos no endpoint POST
Mapeamento Sugerido
| Tipo acompanhamento (Alpha) | Etapa (Gov.br) | Situação (Gov.br) | Observações |
|---|---|---|---|
| AcompanhamentoDoAtendente (0) | "Atendimento Interno" | "Em Andamento" | Pode ser usado para registrar atividades internas realizadas pelo servidor. |
| AcompanhamentoDoSolicitante (1) | "Resposta ao Cidadão" | "Aguardando Retorno" | Representa momentos em que o cidadão participa ou é notificado. |
| Conclusao (2) | "Encerramento do Atendimento" | "Concluído" | Equivale ao fechamento de um atendimento. Pode incluir dataFechamento. |
| ReprovacaoDaConclusao (3) | "Avaliação Negativa da Conclusão" | "Reaberto" | Pode requerer uso da API PUT /situacao para reabrir o atendimento. |
| AprovacaoDaConclusao (4) | "Avaliação Positiva da Conclusão" | "Concluído" | Semelhante à Conclusao, mas pode ser usada para confirmar encerramento após validação. |
¶ Acompanhamento - Viabilidade da Integração da Avaliação com o Alpha
De forma geral, todos os tipos definidos em TipoDeAcompanhamento do ALPHA podem ser sincronizados com o modelo da API de Acompanhamento do Gov.br. Isso é possível graças à flexibilidade dos campos etapa e situacaoEtapa, que aceitam valores descritivos de livre preenchimento, permitindo que o ALPHA defina padrões próprios de nomenclatura, desde que coerentes e padronizados internamente.
A principal atenção deve ser dada ao controle da situação final do serviço (aberto ou concluído), que poderá ser manipulado tanto no momento da etapa quanto via atualização posterior com o endpoint PUT /situacao.
¶ Avaliação - Resumo das Possibilidades da Avaliação de Serviço
A funcionalidade de avaliação permite que o cidadão diga como foi a experiência com um serviço público. Funciona assim:
Criar avaliação: primeiro, a avaliação é registrada com status “Novo”, com dados como CPF, órgão, serviço, etapa do atendimento, canal de prestação (ex: presencial ou online).
Avaliação completa: depois, o cidadão pode dar uma nota de 1 a 5, deixar comentários, escolher critérios (como agilidade e qualidade), e até dizer o que gostou ou o que pode melhorar.
Link de formulário: é possível gerar um link direto para o formulário, que pode ser enviado ao cidadão.
Consultas: dá pra consultar avaliações por CPF, por órgão, por serviço ou ver tudo junto.
¶ Avaliação - Criar Avaliação
POST /
Cria uma avaliação com status "Novo", permitindo que o cidadão avalie posteriormente.
Corpo da requisição:{
"canalAvaliacao": "1 - Formulário da plataforma",
"canalPrestacao": "8 - Web",
"comentario": "Serviço rápido e eficiente.",
"cpfCidadao": "12345678900",
"etapa": "Envio de documentos",
"orgao": "orgao-xyz",
"protocolo": "PROTOCOLO-123",
"servico": "servico-abc"
}
¶ Avaliação - Registrar Avaliação
PUT /
Registra a avaliação efetiva com nota e critérios escolhidos pelo cidadão.{
"avaliacao": {
"canalAvaliacao": "1 - Formulário da plataforma",
"canalPrestacao": "5 - Presencial",
"comentario": "Atendimento cordial.",
"cpfCidadao": "12345678900",
"etapa": "Atendimento presencial",
"orgao": "orgao-xyz",
"protocolo": "PROTOCOLO-123",
"servico": "servico-abc"
},
"avaliarComoAnonimo": "false",
"comentarioAvaliacao": "Gostei bastante da agilidade.",
"criteriosAvaliados": ["AGILIDADE", "CORDIALIDADE"],
"emailUsuario": "usuario@email.com",
"flagTipo": "G",
"nomeUsuario": "João da Silva",
"outroCriterio": "Horário estendido",
"tipoAvaliacao": "2 - Avaliar",
"tipoNota": "5"
}
¶ Avaliação - Obter Link para Formulário de Avaliação
POST /formulario
Gera um link público de acesso ao formulário de avaliação.
Corpo da requisição:{
"canalAvaliacao": "1 - Formulário da plataforma",
"canalPrestacao": "8 - Web",
"comentario": "Gerando link para avaliação.",
"cpfCidadao": "12345678900",
"etapa": "Entrega do documento",
"orgao": "orgao-xyz",
"protocolo": "PROTOCOLO-123",
"servico": "servico-abc"
}
Resposta esperada:{
"location": "https://avaliacao.plataforma.gov.br/formulario/abc123"
}
O link após gerado vai ficar desta forma:
¶ Avaliação - Consultas Disponíveis na Avaliação de Serviço
A API permite buscar avaliações já registradas de algumas formas:
Consulta geral (GET /)
Lista avaliações de forma ampla, sem filtros específicos.
Por cidadão (GET /porCidadao)
Traz todas as avaliações feitas por um determinado CPF.
Por órgão e cidadão (GET /porOrgao)
Filtra as avaliações feitas por um cidadão dentro de um órgão específico.
Por serviço (GET /porServico)
Mostra todas as avaliações feitas para um serviço específico.
Essas rotas ajudam a visualizar o que já foi avaliado, entender padrões e facilitar relatórios.
¶ Fluxo de Acompanhamento e Avaliação:
A avaliação de serviços permite que o cidadão registre sua experiência após utilizar um serviço público. O processo envolve a liberação da avaliação, o preenchimento pelo usuário e, por fim, a consulta dos dados registrados. Abaixo, o fluxo completo dessas etapas:
¶ 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 e tem base nesse enum a seguir:
public enum StatusSolicitacao
{
[Description("Aguardando Análise")]
AguardandoAnalise = 0,
[Description("Em Atendimento")]
EmAtendimento = 1,
[Description("Reprovada")]
Reprovada = 2,
[Description("Pendente de Assinatura")]
PendenteDeAssinatura = 3,
[Description("Concluído")]
Concluido = 4,
[Description("Em Análise")]
EmAnalise = 5,
[Description("Aguardando avaliação do solicitante")]
AguardandoAvaliacaoDoSolicitante = 6,
[Description("Aguardando novo Atendimento")]
AguardandoNovoAtendimento = 7,
[Description("Solicitação Cancelada")]
Cancelada = 8,
[Description("Aguardando ciência do chefe imediato")]
AguardandoCienciaDoChefeImediato = 9,
[Description("Solicitação Cancelada pelo chefe imediato")]
CanceladaPeloChefeImediato = 10
}
¶ História de Usuário 1 — Registrar Acompanhamento no envio para análise do servidor
Eu, servidor estadual,
Quero que, ao iniciar a análise de uma solicitação de serviço, o sistema envie um registro de acompanhamento ao Governo Federal,
Para que o cidadão possa acompanhar o status da sua solicitação diretamente pelo gov.br.
Regras e Validações
O envio deve acontecer automaticamente quando o status mudar para "Em Análise do Servidor".
O texto enviado para o campo de acompanhamento será:
“Sua solicitação está em análise pelo órgão responsável.”
O envio será feito via API de acompanhamento do Governo Federal.
Cenário
Dado que o servidor muda o status da solicitação para “Em Análise do Servidor”,
Quando o status for salvo,
Então o Alpha deve enviar o acompanhamento correspondente ao gov.br.
¶ História de Usuário 2 — Registrar Acompanhamento ao aprovar solicitação
Eu, servidor estadual,
Quero que, ao aprovar uma solicitação, o sistema envie um acompanhamento indicando que ela foi aprovada e entrou em fase de atendimento,
Para que o cidadão saiba que seu pedido foi aceito e está sendo tratado.
Regras e Validações
A mudança de status para “Em Atendimento” (após “Aprovado”) dispara o envio automático.
O texto do acompanhamento será:
“Solicitação aprovada. Em breve você será atendido.”
O acompanhamento será enviado pela API federal.
Cenário
Dado que o servidor aprova a solicitação,
Quando o status muda para “Em Atendimento”,
Então o Alpha envia o acompanhamento informando a aprovação.
¶ História de Usuário 3 — Enviar solicitação de avaliação ao cidadão
Eu, sistema Alpha,
Quero que, ao concluir um atendimento, seja disparada uma solicitação de avaliação para o cidadão por meio do gov.br,
Para que ele possa avaliar a qualidade do serviço recebido.
Regras e Validações
A mudança de status para “Aguardando avaliação do cidadão” deve disparar a API de avaliação.
O sistema deve enviar:
CPF do cidadão;
Identificador do serviço;
Código do atendimento ou protocolo;
Data da conclusão.
Cenário
Dado que o atendimento foi concluído,
Quando o status muda para “Aguardando avaliação do cidadão”,
Então o Alpha solicita que o gov.br envie a avaliação ao cidadão por e-mail.
¶ História de Usuário 4 — Cidadão reprovou o atendimento
Eu, sistema Alpha,
Quero receber e processar a reprovação feita pelo cidadão no gov.br,
Para que possamos registrar e reencaminhar a solicitação para novo atendimento.
Regras e Validações
Ao receber a reprovação, o status da solicitação deve mudar para:
“Aguardando novo Atendimento”
E depois para “Em Atendimento” quando um novo atendimento for iniciado.
A reprovação deve ser registrada junto com a justificativa do cidadão.
Cenário
Dado que o cidadão reprovou o atendimento via gov.br,
Quando a reprovação for recebida,
Então o sistema muda para “Aguardando novo Atendimento”.
¶ História de Usuário 5 — Cidadão aprovou o atendimento
Eu, sistema Alpha,
Quero registrar que o cidadão aprovou o atendimento,
Para que a solicitação seja encerrada oficialmente.
Regras e Validações
O status da solicitação deve mudar para “Concluído”.
Nenhuma nova ação é permitida após essa etapa.
A aprovação é considerada como encerramento definitivo do ciclo.
Cenário
Dado que o cidadão aprovou o atendimento via gov.br,
Quando essa informação for recebida,
Então o sistema muda o status para “Concluído” e finaliza o processo.
¶ Conclusão
Com base na análise realizada sobre a integração entre o sistema Alpha (Portal do Cidadão do Governo do Estado de Rondônia) e as APIs do Governo Federal, foi possível identificar pontos viáveis e estratégicos para garantir que os atendimentos e os acompanhamentos realizados pelo Estado possam refletir de forma integrada e automatizada na base federal.
A classe Atendimento, que centraliza o fluxo de atendimentos realizados no Alpha, permite que ações como confirmação de atendimento, não atendimento, justificativas e avaliação interna sejam tratadas localmente. A partir disso, foi possível mapear histórias de usuário que conectam esses eventos às APIs federais, especialmente nos momentos de registro de acompanhamento e disparo de avaliação federal.
A principal proposta da integração é garantir que, ao final de um atendimento realizado no Alpha, os dados de acompanhamento sejam enviados ao Governo Federal, permitindo que o cidadão acompanhe o andamento do seu serviço em plataformas unificadas. Além disso, o sistema estadual passa a notificar o Governo Federal para que este envie a avaliação por e-mail ao cidadão, sem necessidade de duplicação de lógica ou coleta paralela de dados.
Essa abordagem mantém o Alpha como sistema central de operação, evitando retrabalho e permitindo uma experiência fluida tanto para os gestores quanto para os cidadãos. As funcionalidades de cadastro, edição, publicação, despublicação e exclusão dos serviços já previstas continuam sendo executadas no mesmo ambiente, agora complementadas com as novas ações de registro de acompanhamento e avaliação pós-atendimento.
Em resumo, a integração entre Alpha e o Governo Federal avança para um novo estágio, ampliando o controle do Estado sobre os serviços prestados e fortalecendo a transparência e centralidade no cidadão. Ao fazer isso de maneira progressiva e bem estruturada, o Estado de Rondônia garante uma solução escalável, coerente com os padrões federais e com potencial de servir como modelo para outras esferas estaduais.