13. Integração de Outros Sistemas com o Fala.BR

Me-OUV é a API REST do Fala.BR.

Em linguagem bem simples, API é um conjunto de rotinas e padrões de programação para acesso a um aplicativo de software ou plataforma baseado na Web.

A sigla API refere-se ao termo em inglês "Application Programming Interface" que significa em tradução para o português "Interface de Programação de Aplicativos".

Por sua vez, Representational State Transfer (REST), que em português se traduz Transferência Representacional de Estado, é um estilo de arquitetura de software que define um conjunto de restrições a serem usados para a criação de web services (serviços Web).

Os Web services que estão em conformidade com o estilo arquitetural REST, denominados Web services RESTful, fornecem interoperabilidade entre sistemas de computadores na Internet.

Este roteiro foi feito para orientar a integração dos sistemas das unidades de ouvidoria dos órgãos (sistemas próprios de ouvidoria; SEI etc) ao sistema Fala.BR.

Foram utilizados como exemplo requisições ao ambiente de treinamento.

Para executar requisições da API utilizaremos a ferramenta Postman, cuja versão gratuita pode ser baixada e instalada em [1].

IMPORTANTE A documentação detalhada de cada requisição está disponível em [2] e [3].

3.1 Usuário de Aplicação

O primeiro passo para utilizar a API é obter um usuário para a aplicação.

Para isto deve-se solicitar acesso ao administrador do Fala.BR: OGU/CGOUV - Coordenação-Geral de Orientação e Acompanhamento de Ouvidorias, por meio do e-mail: suporte.e-ouv@cgu.gov.br.

Os perfis possíveis para usuários de sistema são:

3.1.1 Web service Atendente

Realiza ações para outros usuários, podendo registar manifestações para estes. É possível consultar o andamento destas manifestações, dentre outras ações do usuário manifestante como a ação de complementá-las.

O perfil não está vinculado a nenhum órgão nem limitado a nenhum tipo de formulário. (Antigo perfil web service terceiro).

3.1.2 Web service Respondente

Realiza ações para um determinado órgão. Pode realizar todas as ações do órgão sobre as manifestações que estão no órgão vinculado a este perfil.

As ações possíveis ao órgão são as mesmas do perfil Respondente, como responder e encaminhar.

Também é possível atualizar dados destas manifestações como assunto, subassunto e responsável pela análise.

O perfil sempre está vinculado a um órgão, podendo estar limitado a um tipo de formulário. (Antigo perfil web service ouvidoria)

3.1.3 Web service observador

Consulta e detalha manifestações do órgão vinculado ao perfil.

Se o perfil não estiver vinculado a nenhum órgão, pode consultar todas as manifestações.

Pode estar limitado a um tipo formulário. (Antigo perfil web service gestor)

Após o administrador criar o usuário sistema com um dos perfis acima, um e-mail a este usuário é enviado com as credenciais de acesso ao site web do Fala.BR e à API Me-OUV.

Exemplo:

   PREZADO(A) SR(A) APPORGAOX.

   SEU CADASTRO FOI REALIZADO COM SUCESSO NO "FALA.BR". 
   PARA ACESSAR, UTILIZAR OS DADOS ABAIXO. 

   USUÁRIO: APPORGAOX
   SENHA: XXXXXXXX

   NO PRIMEIRO ACESSO COM ESSES DADOS, O SISTEMA SOLICITARÁ A ALTERAÇÃO DA SENHA. 
   A NOVA SENHA DEVE TER 8 DÍGITOS, CONTENDO LETRAS E NÚMEROS. 

   A AUTORIZAÇÃO À API ME-OUV SEGUE O PADRÃO OAUTH 2.0.
   PARA OBTER TOKEN DE ACESSO UTILIZE OS DADOS ABAIXO.

   ID DA APLICAÇÃO CLIENTE (CLIENTID): 1053
   SENHA (CLIENT SECRET): XXXXXXXX

IMPORTANTE:

Antes de utilizar a API é necessário ativar o usuário;

Para isto basta acessar ao site web do Fala.BR com o usuário e a senha recebidos no e-mail;

No primeiro acesso será exigido troca de senha;

Ainda, será necessário gerar uma nova senha para aplicação (client secret);

   Para isso, deve-se entrar na tela "Meu Usuário" e acionar "Gerar nova senha" na seção "Aplicação".
   Uma nova senha de aplicação é enviada ao e-mail do usuário.