Manual Avaliacao Servicos Gov BR PT BR Latest

Manual de uso da API de Avaliação e
Acompanhamento
servicos.gov.br
nov. 07, 2022

Introdução
1 Apresentação 1
1.1 Fluxo simplificado para o cidadão . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2 Fluxo simplificado das APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
2 Passo a passo para avaliar um serviço 7

2.1 1. Obtenha as credenciais para usar as APIs de avaliação . . . . . . . . . . . . . . . . . . . . . . . . 7
2.2 2. Descubra o código do órgão e o código dos seus serviços . . . . . . . . . . . . . . . . . . . . . . 7
2.3 3. Envie o(s) acompanhamento(s) durante a execução do serviço . . . . . . . . . . . . . . . . . . . . 8
2.4 4. Obter Link do formulário para avaliação . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
2.5 5. O cidadão preenche a avaliação . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
3 Acesso as APIs de Acompanhamento e Avaliação de Serviços 11

3.1 Testes e homologação . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 Produção . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.3 Ambiente web para desenvolvedores . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4 Exemplos 13
5 Acompanhamento 17
5.1 1. Registrar Acompanhamentos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.2 2. Solicitar Conclusão/Reabertura de uma prestação de serviço . . . . . . . . . . . . . . . . . . . . . 20
6 Avaliação 23
6.1 Obter Link do formulário de avaliação . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
7 FAQ - Perguntas frequentes 27

7.1 O CPF do cidadão é obrigatório? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7.2 Não acho meu serviço na lista de serviços para meu órgão. O que devo fazer? . . . . . . . . . . . . . 27
7.3 Os códigos dos órgãos e serviços são os mesmos em teste/homologação e em produção? . . . . . . . 27
7.4 Para registrar o acompanhamento é necessário enviar o número do protocolo? Esse número possui
um formato específico? Qual seu tamanho mínimo e máximo? . . . . . . . . . . . . . . . . . . . . . 28
7.5 Posso encadear acompanhamento, finalização e obtenção de link numa mesma ação do usuário (clique
único)? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7.6 Pode ser gerado acompanhamento sem finalização? . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
7.7 Quais os passos para o cancelamento de um acompanhamento? . . . . . . . . . . . . . . . . . . . . 28
7.8 Existe algum mecanismo do módulo de avaliação para submeter e-mail/SMS para solicitar avaliação
diretamente ao usuário? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
i
7.9 Existe alguma interface web onde conseguimos consultar os acompanhamentos abertos e avaliações? 28
7.10 Há a possibilidade de gerar a avaliação sem que seja necessário a criação do acompanhamento? . . . 29
7.11 É preciso finalizar o atendimento para gerar o link de avaliação? . . . . . . . . . . . . . . . . . . . . 29
7.12 Há algum ícone padrão para ser usado no link da avaliação? . . . . . . . . . . . . . . . . . . . . . . 29
7.13 Os campos do formulário de avaliação são fixos ou parametrizados? Quem define esses campos? . . 29
7.14 Onde é feito o acompanhamento das avaliações enviadas pelos cidadãos? . . . . . . . . . . . . . . . 29
8 Índices 31
ii
CAPÍTULO 1
Apresentação
O decreto 8936/2016, instituiu a Plataforma de Cidadania Digital e dispôs sobre a oferta dos serviços públicos digitais,
no âmbito dos órgãos e das entidades da administração pública federal direta, autárquica e fundacional.
No seu artigo 3º, incisos IV e V foi instituído a ferramenta de avaliação da satisfação dos usuários em relação aos
serviços públicos prestados e o painel de monitoramento do desempenho dos serviços públicos prestados.
Entre as informações mínimas que deverão estar disponíveis no painel para cada serviço, órgão ou entidade da ad-
ministração pública federal, estão o volume de solicitações, tempo médio de atendimento e o nível de satisfação dos
usuários.
1.1 Fluxo simplificado para o cidadão
O formulário de avaliação deverá ser exibido na própria página do serviço para melhor experiência do cidadão.
1.2 Fluxo simplificado das APIs
Atenção:
• É obrigatório o registro de pelo menos uma etapa de acompanhamento para gerar uma avaliação.
• Cada etapa de acompanhamento poderá ser avaliada.
• Fica a critério do órgão a forma de exibição do formulário de avaliação para o cidadão. Poderá ser um modal
dentro da própria página do serviço/sistema (recomendado), pop-up ou email para o cidadão com o link de
acesso ao formulário.
1
Manual de uso da API de Avaliação e Acompanhamento
Fig. 1: Ao final da prestação do serviço o cidadão recebe o formulário de avaliação
2 Capítulo 1. Apresentação
Fig. 2: O cidadão poderá avaliar até 7 dimensões predeterminadas
1.2. Fluxo simplificado das APIs 3

Fig. 3: Após a avaliação, o cidadão será encaminhado para uma tela de sucesso
Fig. 4: Fluxo da API de avaliação
1.2. Fluxo simplificado das APIs 5

CAPÍTULO 2
Passo a passo para avaliar um serviço
2.1 1. Obtenha as credenciais para usar as APIs de avaliação
Os métodos das APIs de avaliação necessitam de autenticação para uso (usuário e senha).
Para solicitar sua credencial, basta acessar a página temática https://www.gov.br/pt-br/temas/
pagina-de-apoio-a-avaliacao-de-servicos-publicos-digitais.
2.2 2. Descubra o código do órgão e o código dos seus serviços
Para a correta utilização da API de Avaliação é preciso obter os códigos válidos do órgão e dos serviços na API de
Serviços.
Siga os seguintes passos:
1- Descubra o ID do seu órgão no SIORG https://siorg.gov.br/siorg-cidadao-webapp/resources/app/
consulta-estrutura.html
Fig. 1: O código SIORG está destacado em amarelo
2- Com o código SIORG obtido, descubra o código do órgão para ser utilizado na API de Avaliação. Para isso,
utilize o endereço https://servicos.gov.br/api/v1/orgao/ inserindo o código SIORG no final da URL.
7
Exemplo: https://servicos.gov.br/api/v1/orgao/235876
Fig. 2: O código do órgão está destacado na imagem acima. É esse código que deverá ser utilizado nas chamadas aos
métodos da API de Avaliação.
3- Por último, descubra o código do seu serviço. Utilize a URL https://servicos.gov.br/api/v1/servicos/orgao/ inse-
rindo o código SIORG no final.
Exemplo: https://servicos.gov.br/api/v1/servicos/orgao/235876
Essa chamada retorna todos os serviços cadastrados para órgão. Caso seu serviço não esteja listado (tanto em produção
quanto em homologação), procure o representante do seu órgão responsável pelo cadastro de serviços no Portal
Gov.br.
Atenção: O código do SIORG não deverá ser utilizado nas chamadas aos métodos da API de Avaliação.
Importante: Todos os passos desse tópico estão relacionados ao ambiente da API de Serviços de produção. Para
ambiente de teste substitua servicos.gov.br por servicos.treina.nuvem.gov.br.
2.3 3. Envie o(s) acompanhamento(s) durante a execução do serviço
É obrigatório o registro de pelo menos uma etapa de acompanhamento para gerar uma avaliação. Cada etapa de
acompanhamento poderá ser avaliada (esse procedimento é opcional).
Como fazer: Para Registrar Acompanhamentos utilize o endpoint específico para isso. Acesse o manual em Acom-
panhamento para maiores informações.
8 Capítulo 2. Passo a passo para avaliar um serviço

Fig. 3: O código do serviço está destacado na imagem acima. É esse código que será usado nas chamadas aos métodos
da API de avaliação
2.4 4. Obter Link do formulário para avaliação
Fica a critério do órgão a forma de exibição do formulário de avaliação para o cidadão. Poderá ser um modal dentro da
própria página do serviço/sistema (recomendado), pop-up ou email para o cidadão com o link de acesso ao formulário.
Como fazer: Para Obter Link do formulário de avaliação, utilize o endpoint de avaliação. Acesse o manual em
Avaliação para maiores informações.
2.5 5. O cidadão preenche a avaliação
O cidadão preenche o formulário de avaliação relacionado ao serviço prestado.
2.4. 4. Obter Link do formulário para avaliação 9

10 Capítulo 2. Passo a passo para avaliar um serviço

CAPÍTULO 3
Acesso as APIs de Acompanhamento e Avaliação de Serviços
Há dois ambientes para o uso da API de Avaliação de Serviços Públicos:
3.1 Testes e homologação
• Acompanhamento: https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/api/acompanhamento/
• Avaliação: https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/api/avaliacao/
3.2 Produção
• Acompanhamento: https://acompanhamento.servicos.gov.br/api/acompanhamento/
• Avaliação: https://avaliacao.servicos.gov.br/api/avaliacao/
3.3 Ambiente web para desenvolvedores
Caso necessite, é disponibilizado um Swagger para teste de chamadas aos métodos da API:
3.3.1 Swagger de testes
• Acompanhamento: https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/api/acompanhamento/
swagger-ui.html
• Avaliação: https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/api/avaliacao/swagger-ui.html
11
3.3.2 Swagger de produção
• Acompanhamento: https://acompanhamento.servicos.gov.br/api/acompanhamento/swagger-ui.html
• Avaliação: https://avaliacao.servicos.gov.br/api/avaliacao/swagger-ui.html
Deve-se usar o cabeçalho http Authorization: Basic em Base64 para passar as credenciais de autenticação nas cha-
madas das APIs.
Nota: Lembre-se de informar usuário e senha no formato (login:senha) em Base64 para utilizar os métodos.
Exemplo prático:
Nosso usuário é aladdin e a senha é opensesame. Então temos o formato aladdin:opensesame
Codificamos essa string (aladdin:opensesame) em Basic64 e obtemos o senguinte código: YWxhZGRpbjpvcG-
Vuc2VzYW1l
Agora é só colocar essa informação no header das nossas chamadas aos métodos da API de avaliação
Reultado final fica: Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
Você pode utilizar a página https://www.base64encode.org/ para codificar a string do login e senha em Base64.
12 Capítulo 3. Acesso as APIs de Acompanhamento e Avaliação de Serviços

CAPÍTULO 4
Exemplos
Aqui você encontra as URL e métodos necessários para registrar acompanamentos e gerar o link da avaliação. Com
esse arquivo, será possivel obter todos os códigos exigidos na integração do seu serviço. Preencha corretamente seu
usuário e senha no momento da execução.
Utilizamos Python para exemplificar e elucidar todas as dúuvidas:
import requests
import base64
siorg_orgao = " " #Informe o codigo SIORG do seu órgão
usuario = " " #Email que foi cadastrado para acessar a API
senha = " " #Senha liberada para o acesso a API
url_acompanhamento_testes = "https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/
˓→api/acompanhamento/"
url_acompanhamento_situacao_testes = "https://api-acompanha-avalia-servicos.dev.nuvem.
˓→gov.br/api/acompanhamento/situacao"
url_avaliacao_teste = "https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/api/
˓→avaliacao/formulario"
url_acompanhamento_producao = "https://acompanhamento.servicos.gov.br/api/
˓→acompanhamento/"
url_acompanhamento_situacao_producao = "https://acompanhamento.servicos.gov.br/api/
˓→acompanhamento/situacao"
url_avaliacao_producao = "https://avaliacao.servicos.gov.br/api/avaliacao/formulario?
˓→completo=false"
url_servico_teste = "https://servicos.treina.nuvem.gov.br/api/v1/servicos/orgao/"
url_servico_producao = "https://servicos.gov.br/api/v1/servicos/orgao/"
url_cod_orgao_api_teste = "https://servicos.treina.nuvem.gov.br/api/v1/orgao/"
url_cod_orgao_api_producao = "https://servicos.gov.br/api/v1/orgao/"
(continues on next page)
13
(continuação da página anterior)

def create_session_pesquisar():
sess = requests.Session()
sess.headers.update({
'Accept': 'application/json'
})
return sess
def consultar_cod_orgao_api_teste():
pesq = create_session_pesquisar()
retorno = pesq.get(url=f'{url_cod_orgao_api_teste}{siorg_orgao}')
print(retorno.json()["id"])
pesq.close()
def consultar_cod_orgao_api_producao():
retorno = pesq.get(url=f'{url_cod_orgao_api_producao}{siorg_orgao}')
print(retorno.json()["id"])
pesq.close()
def pesquisar_servicos_teste():
retorno = pesq.get(url=f'{url_servico_teste}{siorg_orgao}')
for aux in retorno.json()['resposta']:
print(f'{aux["idDb"]} - {aux["nome"]}')
pesq.close()
def pesquisar_servicos_producao():
retorno = pesq.get(url=f'{url_servico_producao}{siorg_orgao}')
for aux in retorno.json()['resposta']:
print(f'{(aux["id"]).split("https://servicos.gov.br/api/v1/servicos/
˓→")[1]} - {aux["nome"]}')
pesq.close()
def gerar_base64():
encoded = base64.b64encode(f'{usuario}:{senha}'.encode('ascii'))
return encoded.decode()
def create_session():
sess = requests.Session()
sess.headers.update({
'Content-Type': 'application/json;charset=UTF-8',
'Accept': 'application/json',
'Authorization': f'Basic {gerar_base64()}'
})
return sess
def create_situacao_acompanhamento():
body = {
"cpfCidadao": "41333618069",
"orgao": "36802",
"protocolo": "Teste_125",
"servico": "47",
"situacaoServico": "2" #Situação atual do Serviço. 1 - Em Aberto, 2 -
˓→Concluído.
}
sess = create_session()
14 Capítulo 4. Exemplos

response = sess.put(url=url_acompanhamento_situacao_testes, json=body)
'''
200 Registrado a conclusão/reabertura do serviço informado
400 Erro nos dados enviados ao servidor
'''
print(response.status_code)
print(response.content)
sess.close()
def create_acompanhamento():
body = {
"cpfCidadao": "41333618069",
"dataEtapa": "10/10/2017",
"dataSituacaoEtapa": "10/10/2017",
"etapa": "Em Processamento.",
"orgao": "36802",
"servico": "47",
"situacaoEtapa": "Alguma descrição da situação."
}
response = sess.post(url=url_acompanhamento_testes, json=body)
'''
201 Acompanhamento criado com sucesso
401 Não Autenticado
403 Autenticado sem autorização
404 Recurso não encontrado
500 Erro Interno do Servidor
'''
sess.close()
def create_avaliacao():
body = {
"canalAvaliacao": "4",
"canalPrestacao": "4",
"cpfCidadao": "41333618069",
"orgao": "36802",
"servico": "47"
}
response = sess.post(url=url_avaliacao_teste, json=body)
'''
200 Link para o formulário
'''
sess.close()
def main():
print("Serviços disponíveis no ambiente de testes:")
pesquisar_servicos_teste()
15
print("\nServiços no ambiente de produção:")

pesquisar_servicos_producao()
print("\nCodigo do orgão para ser usado na API de Avaliação (teste):")

consultar_cod_orgao_api_teste()
print("\nCodigo do orgão para ser usado na API de Avaliação (produção):")

consultar_cod_orgao_api_producao()
print("\nUse isto no Authorization da sua requisição (usuario e senha em

˓→ Base64):")
print(f'Basic {gerar_base64()}')
create_acompanhamento()
create_situacao_acompanhamento()
create_avaliacao()
if __name__ == '__main__':
main()
16 Capítulo 4. Exemplos
CAPÍTULO 5
Acompanhamento
O registro de um acompanhamento deve ser enviado a cada etapa da prestação do serviço.
5.1 1. Registrar Acompanhamentos
O método Registrar Acompanhamentos permite que seja registrada informações de acompanhamento do serviço.
Para mais informações, verifique a documentação Swagger.
Atenção: Vale lembrar que a geração do formulário de avaliação está condicionada ao registro de pelo menos
um acompanhamento.
5.1.1 Endpoint de homologação
https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/api/acompanhamento/
5.1.2 Endpoint de produção
https://acompanhamento.servicos.gov.br/api/acompanhamento/
5.1.3 Parâmetros de Entrada
{
"cpfCidadao": "08254631654",
"dataEtapa": "10/10/2017",
"dataSituacaoEtapa": "10/10/2017",
17

"etapa": "Inicial",
"orgao": "36802",
"protocolo": "0001AC.20171212",
"servico": "47",
"situacaoEtapa": "Alguma descrição da situação."
}
cpfCidadao (string, optional) Informe o CPF do cidadão que está executando o serviço. Esse CPF vai ser validado
com 11 dígitos.
dataEtapa (string) Data da etapa que o serviço foi executado no formato “dd/mm/aaaa”.
dataSituacaoEtapa (string) Data da etapa que o situação foi criado/alterado no formato “dd/mm/aaaa”.
etapa (string) Descrição da etapa que o serviço se encontra na dataEtapa.
orgao (string) ID do órgão, caso não saiba qual ID do órgão consulte a API do Portal de Serviços
Atenção: Esse é o código do órgão na API do Portal de Serviços e não o código SIORG do órgão.
protocolo (string) Protocolo interno do órgão referente ao serviço sendo executado. Geralmente é utilizado uma
identificação única do sistema.
servico (string) ID do serviço, caso não saiba qual ID do serviço consulte a API do Portal de Serviços.
situacaoEtapa (string) Descrição da etapa do serviço.
Veja um exemplo de acesso utilizando o cURL
$ curl -v -X POST --header 'Content-Type: application/json;charset=UTF-8' -k \

--header 'Authorization: Basic YWxhZGluQGRpc25leS5jb206b3BlbnNlc2FtZQ==' \
--header 'Accept-Language: pt-br' \
--header 'Accept: application/json' -d '{ \
"cpfCidadao": "08254631654", \
"dataEtapa": "10/10/2017", \
"dataSituacaoEtapa": "10/10/2017", \
"etapa": Final", \
"orgao": "36802", \
"protocolo": "0001AC.20171212", \
"servico": "47", \
"situacaoEtapa": "Alguma descrição da situação." \
}' 'https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/api/acompanhamento/'
Veja um exemplo de acesso utilizando Java
import org.apache.http.HttpHeaders;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.client.methods.HttpPut;
import org.apache.http.entity.ContentType;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import java.io.BufferedReader;
import java.io.IOException;
import java.io.InputStreamReader;
18 Capítulo 5. Acompanhamento
public class Acompanhamento {
private final CloseableHttpClient httpClient = HttpClients.createDefault();
public static void main(String[] args) throws Exception {

Acompanhamento acompanhamento = new Acompanhamento();
try {
acompanhamento.enviarAcompanhamento();
} finally {
acompanhamento.close();
}
}
private void close() throws IOException {

httpClient.close();
}
private void enviarAcompanhamento() throws Exception {

String url = "https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/api/
˓→acompanhamento/";
String payload = "{" +

"\"cpfCidadao\": \"99999999999\", " +
"\"dataEtapa\": \"10/10/2020\", " +
"\"dataSituacaoEtapa\": \"10/10/2020\", " +
"\"etapa\": \"Inicial\", " +
"\"orgao\": \"123\", " +
"\"protocolo\": \"001\", " +
"\"servico\": \"02\", " +
"\"situacaoEtapa\": \"Texto.\"" +
"}";
HttpPost request = new HttpPost(url);
request.addHeader(HttpHeaders.AUTHORIZATION, "Basic " + "ZmFiaW8uZmVybmFuZGV
˓→");
request.addHeader("Content-Type", "application/json;charset=UTF-8");
request.addHeader("Accept-Language", "pt-br");
request.addHeader("Accept", "application/json");
StringEntity entity = new StringEntity(payload, ContentType.APPLICATION_JSON);
request.setEntity(entity);
HttpResponse response = httpClient.execute(request);
BufferedReader reader = new BufferedReader(new InputStreamReader(response.
˓→getEntity().getContent(), "utf-8"), 8);
String line = null;

while ((line = reader.readLine()) != null) // Read line by line
System.out.print(line);
}
}
5.1.4 Parâmetros de Saída
{
"message": "Acompanhamento registrado com sucesso.",
"status": "CREATED"
}
5.1. 1. Registrar Acompanhamentos 19

messagem Mensagem que descreve o status da operação.

status Status final da operação. Pode ser CREATED, BAD REQUEST ou INTERNAL_SERVER_ERROR
Aviso: Para uma listagem completa da saída por favor verifique a documentação Swagger.
5.2 2. Solicitar Conclusão/Reabertura de uma prestação de serviço
Esse método permite registrar a conclusão ou reabertura de uma prestação de serviço de um protocolo já registrado.
Após os registros dos acompanhamentos e encerrada a prestação do serviço, poderá ser informada a conclusão da pres-
tação do serviço utilizando o método Realizar a conclusão ou reabertura de uma prestação de serviço. Contudo,
para gerar o link do formulário de avaliação não é necessário que o atendimento esteja concluído.
Para mais informações, verifique a documentação Swagger.
https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/api/acompanhamento/situacao
https://acompanhamento.servicos.gov.br/api/acompanhamento/situacao
{
"cpfCidadao": "08254631654",
"orgao": "57842",
"protocolo": "0001AC.20171212",
"servico": "12014",
"situacaoServico": "2"
}
cpfCidadao (string, optional) CPF do cidadão sem formatação.

orgao (string) Identificador do Órgão.
protocolo (string) Protocolo para identificar o serviço.
servico (string) Identificador do serviço.
situacaoServico (string, optional) Situação atual do serviço. 1 - Em Aberto, 2 - Concluído. = [‘1’, ‘2’]
Veja um exemplo de acesso utilizando o cURL
$ curl -v -X PUT --header 'Content-Type: application/json;charset=UTF-8' -k \
--header 'Authorization: Basic YWxhZGluQGRpc25leS5jb206b3BlbnNlc2FtZQ==' \
--header 'Accept: application/json' -d '{ \
"cpfCidadao": "08254631654", \
"orgao": "57842", \

"protocolo": "0001AC.20171212", \
"servico": "12014", \
"situacaoServico": "2" \
}' 'https://acompanhamento.servicos.gov.br/api/acompanhamento/situacao'
Veja um exemplo de acesso utilizando Java

import org.apache.http.client.methods.HttpPut;
public class Acompanhamento {
public static void main(String[] args) throws Exception {

Acompanhamento acompanhamento = new Acompanhamento();
try {
acompanhamento.enviarFechamentoReabertura();
} finally {
acompanhamento.close();
}
}

httpClient.close();
}
private void enviarFechamentoReabertura() throws Exception {

˓→acompanhamento/situacao";

"\"cpfCidadao\": \"99999999999\", " +
"\"orgao\": \"123\", " +
"\"protocolo\": \"001\", " +
"\"servico\": \"01\", " +
"\"situacaoServico\": \"Texto\"" +
"}";
HttpPut put = new HttpPut(url);
put.addHeader(HttpHeaders.AUTHORIZATION, "Basic " + "ZmFiaW8uZmVybmFuZGVzQGV
˓→ ");
put.addHeader("Content-Type", "application/json;charset=UTF-8");
put.addHeader("Accept", "application/json");
put.setEntity(entity);
HttpResponse response = httpClient.execute(put);
˓→getEntity().getContent(), "utf-8"), 8); (continues on next page)
5.2. 2. Solicitar Conclusão/Reabertura de uma prestação de serviço 21


String line = null;
}
}
{
"message": "Registrada a conclusão do serviço informado.",
"status": "OK"
}
messagem Mensagem que descreve o status da operação.

status Status final da operação. Pode ser OK, ERROR ou INTERNAL_SERVER_ERROR
CAPÍTULO 6
Avaliação
O registro da avaliação deve ser utilizada para geração do link de avaliação da prestação do serviço.
6.1 Obter Link do formulário de avaliação
O método Obter Link do formulário de avaliação retorna um link para que o cidadão possa avaliar o serviço, registra
na base as informações da avaliação e, se for o caso, faz o registro de uma manifestação junto à Ouvidoria.
Atenção: É obrigatório o registro de pelo menos uma etapa de acompanhamento para gerar um link do formulário
de avaliação.
https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/api/avaliacao/formulario
https://avaliacao.servicos.gov.br/api/avaliacao/formulario
{
"cpfCidadao": "08254631654",
23

"orgao": "57842",
"protocolo": "0001AC.20171212",
"servico": "12014"
}
canalAvaliacao (string, optional) [1 - Formulário da plataforma, 2 - Formulário próprio, 3 - SMS, 4 - Pesquisa

presencial e 5 - Whatsapp].
canalPrestacao (string,optional) [1 - Aplicativo Móvel, 2 - E-mail, 3 - Fax, 4 - Postal, 5 - Presencial, 6 - SMS, 7 -
Telefone e 8 - Web].
cpfCidadao (string,optional) CPF do cidadão sem formatação.
etapa (string) Descrição da etapa do serviço.
orgao (string) Identificador do órgão.
protocolo (string) Protocolo para identificar o serviço. (O mesmo informado no registro de Acompanhamento!)
servico (string) Identificador do serviço.
Exemplo de acesso utilizando o cURL
curl --location --request POST 'https://avaliacao.servicos.gov.br/api/avaliacao/
˓→formulario' \
--header 'Content-Type: application/json;charset=UTF-8' \

--header 'Accept: application/json' \
--header 'Accept-Language: pt-br' \
--header 'Authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l' \
--data-raw '{
"cpfCidadao": "99999999999",
"orgao": "00000",
"protocolo": "0001KK.20171212",
"servico": "00"
}'
Exemplo de acesso utilizando Java

public class Avaliacao {
public static void main(String[] args) throws Exception{

24 Capítulo 6. Avaliação

Avaliacao avaliacao = new Avaliacao();
try {
avaliacao.obterLink();
} finally {
avaliacao.close();
}
}

httpClient.close();
}
private void obterLink() throws Exception{

˓→avaliacao/formulario";

"\"canalAvaliacao\": \"4\", " +
"\"canalPrestacao\": \"4\", " +
"\"cpfCidadao\": \"99999999999\", " +
"\"etapa\": \"Em Processamento.\", " +
"\"orgao\": \"36802\", " +
"\"protocolo\": \"1234567\", " +
"\"servico\": \"47\"" +
"}";
HttpPost request = new HttpPost(url);
request.addHeader(HttpHeaders.AUTHORIZATION, "Basic " +
˓→"ZmFiaW8uZmVybmFuZGVzQGV");
request.addHeader("Content-Type", "application/json;charset=UTF-8");
request.addHeader("Accept-Language", "pt-br");
request.addHeader("Accept", "application/json");
request.setEntity(entity);
HttpResponse response = httpClient.execute(request);
˓→getEntity().getContent(), "utf-8"), 8);
String line = null;

}
}
{
"location": "https://api-acompanha-avalia-servicos.dev.nuvem.gov.br/#/avaliacao/
˓→eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.
˓→eyJzdWIiOiJ7XCJzZXJ2aWNvXCI6XCI0N1wiLFwiY3BmQ2lkYWRhb1wiOlwiOTYyMjA2MjcxNzJcIixcInByb3RvY29sb1wiOlw
˓→gr5QC_zl1dFqPIdK1o2fnO1sfUIcrpVeK4N2pVMTNi-agvxQSR3m-
˓→ez9YYZ0xZK7fRO6b6QCRiqmvNjcCcgAxg"
location (string) URL de acesso ao formulário de avaliação.
6.1. Obter Link do formulário de avaliação 25

26 Capítulo 6. Avaliação
CAPÍTULO 7
FAQ - Perguntas frequentes
Principais dúvidas sobre integração com a API de avaliação.
7.1 O CPF do cidadão é obrigatório?
O CPF não é obrigatório. A API foi projetada para receber avaliações anônimas e não exige a passagem desse parâ-
metro.
7.2 Não acho meu serviço na lista de serviços para meu órgão. O
que devo fazer?
Procure o ponto focal no órgão pela digitalização de serviços. Essa pessoa terá acesso irrestrito a edição de serviços
no órgão (tanto para o ambiente de produção quanto para homologação).
7.3 Os códigos dos órgãos e serviços são os mesmos em

teste/homologação e em produção?
Não necessariamente. Os códigos podem mudar dependendo do ambiente utilizado. É sempre recomendado que o
desenvolvedor verifique os códigos antes de qualquer mudança de ambiente. Mais informações no Passo a Passo a
passo para avaliar um serviço
27
7.4 Para registrar o acompanhamento é necessário enviar o número

do protocolo? Esse número possui um formato específico? Qual
seu tamanho mínimo e máximo?
Mesmo que seu serviço não gere um número de protocolo é necessário passar um número no parâmetro de protocolo
que pode , por exemplo, ser a chave primária que identifique um atendimento. Não existe um formato padrão pré
estabelecido. Cada órgão estabelece seu número/formato de protocolo. Ele deve ter no mínimo 1 caractere e no
máximo 60 (incluídos os numerais e símbolos).
7.5 Posso encadear acompanhamento, finalização e obtenção de link

numa mesma ação do usuário (clique único)?
O desenvolvedor pode, em uma única ação do usuário, gerar um acompanhamento, finalizar o serviço e gerar o link do
formulário. Basta implementar uma rotina em sequência na aplicação com a criação do acompanhamento e geração
do link.
7.6 Pode ser gerado acompanhamento sem finalização?
Sim, o acompanhamento pode ser gerado em qualquer etapa do serviço (etapa inicial, intermediária ou final).
7.7 Quais os passos para o cancelamento de um acompanhamento?
Não há como cancelar um acompanhamento já registrado.
7.8 Existe algum mecanismo do módulo de avaliação para submeter

e-mail/SMS para solicitar avaliação diretamente ao usuário?
Não há suporte ao envio de e-mail/SMS pela API de Avaliação, somente a geração do link do formulário de avaliação.
A forma de exibição do formulário de avaliação fica a critério do órgão que está implementando a integração. A forma
mais indicada de exibir o formulário para o cidadão é utilizando a própria interface do serviço (utilizando modal,
iframe ou pop-up).
7.9 Existe alguma interface web onde conseguimos consultar os

acompanhamentos abertos e avaliações?
Não foi implementada interface web para consultar os acompanhamentos e avaliações. Entretanto há endpoints na
API que permitem a consulta aos acompanhamentos, são eles, porCidadao, porOrgao, porProtocolo e porServico. Para
mais informações, verifique a documentação Swagger de Acompanhamento. E para avaliação, são eles, porCidadao,
porOrgao e porServico. Para mais informações, verifique a documentação Swagger de Avaliação.
28 Capítulo 7. FAQ - Perguntas frequentes

7.10 Há a possibilidade de gerar a avaliação sem que seja necessário

a criação do acompanhamento?
Não é possível obter o link do formulário de avaliação sem ter feito, ao menos, um registro de acompanhamento.
7.11 É preciso finalizar o atendimento para gerar o link de avaliação?
Não. Independente do status do atendimento (1 - Em Aberto ou 2 - Concluído) é possível gerar o link do formulário
de avaliação.
7.12 Há algum ícone padrão para ser usado no link da avaliação?
Não, a respeito das características de design, o desenvolvedor pode consultar o design system para obter alguma
referência gov.br/ds.
7.13 Os campos do formulário de avaliação são fixos ou parametri-

zados? Quem define esses campos?
Os campos são fixos.
7.14 Onde é feito o acompanhamento das avaliações enviadas pelos

cidadãos?
O acompanhamento é feito no gov.br/gestor.
7.10. Há a possibilidade de gerar a avaliação sem que seja necessário a criação do 29

acompanhamento?
30 Capítulo 7. FAQ - Perguntas frequentes

CAPÍTULO 8
Índices
• genindex
• glossario
31

Manual Avaliacao Servicos Gov BR PT BR Latest

Enviado por

Dados do documento

Descrição original:

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Manual Avaliacao Servicos Gov BR PT BR Latest

Enviado por

Direitos autorais:

Formatos disponíveis

Manual de uso da API de Avaliação e

nov. 07, 2022

2 Passo a passo para avaliar um serviço 7

3 Acesso as APIs de Acompanhamento e Avaliação de Serviços 11

7 FAQ - Perguntas frequentes 27

1.1 Fluxo simplificado para o cidadão

1.2 Fluxo simplificado das APIs

Fig. 1: Ao final da prestação do serviço o cidadão recebe o formulário de avaliação

Fig. 2: O cidadão poderá avaliar até 7 dimensões predeterminadas

1.2. Fluxo simplificado das APIs 3

Fig. 4: Fluxo da API de avaliação

1.2. Fluxo simplificado das APIs 5

Passo a passo para avaliar um serviço

2.1 1. Obtenha as credenciais para usar as APIs de avaliação

2.2 2. Descubra o código do órgão e o código dos seus serviços

Fig. 1: O código SIORG está destacado em amarelo

2.3 3. Envie o(s) acompanhamento(s) durante a execução do serviço

8 Capítulo 2. Passo a passo para avaliar um serviço

2.4 4. Obter Link do formulário para avaliação

2.5 5. O cidadão preenche a avaliação

O cidadão preenche o formulário de avaliação relacionado ao serviço prestado.

2.4. 4. Obter Link do formulário para avaliação 9

10 Capítulo 2. Passo a passo para avaliar um serviço

Acesso as APIs de Acompanhamento e Avaliação de Serviços

Há dois ambientes para o uso da API de Avaliação de Serviços Públicos:

3.1 Testes e homologação

3.3 Ambiente web para desenvolvedores

3.3.1 Swagger de testes

3.3.2 Swagger de produção

12 Capítulo 3. Acesso as APIs de Acompanhamento e Avaliação de Serviços

siorg_orgao = " " #Informe o codigo SIORG do seu órgão

(continues on next page)

(continuação da página anterior)

(continuação da página anterior)

(continuação da página anterior)

print("\nServiços no ambiente de produção:")

print("\nCodigo do orgão para ser usado na API de Avaliação (teste):")

print("\nCodigo do orgão para ser usado na API de Avaliação (produção):")

print("\nUse isto no Authorization da sua requisição (usuario e senha em

O registro de um acompanhamento deve ser enviado a cada etapa da prestação do serviço.

5.1 1. Registrar Acompanhamentos

5.1.1 Endpoint de homologação

5.1.2 Endpoint de produção

5.1.3 Parâmetros de Entrada

(continuação da página anterior)

$ curl -v -X POST --header 'Content-Type: application/json;charset=UTF-8' -k \

Veja um exemplo de acesso utilizando Java

(continuação da página anterior)

public class Acompanhamento {

private final CloseableHttpClient httpClient = HttpClients.createDefault();

public static void main(String[] args) throws Exception {

private void close() throws IOException {

private void enviarAcompanhamento() throws Exception {

String payload = "{" +

String line = null;

5.1.4 Parâmetros de Saída

5.1. 1. Registrar Acompanhamentos 19

messagem Mensagem que descreve o status da operação.

5.2 2. Solicitar Conclusão/Reabertura de uma prestação de serviço

5.2.1 Endpoint de homologação

5.2.2 Endpoint de produção

5.2.3 Parâmetros de Entrada