Mudanças entre as edições de "13. Integração de Outros Sistemas com o Fala.BR"

De Wiki CGU
Ir para navegação Ir para pesquisar
 
(32 revisões intermediárias por 2 usuários não estão sendo mostradas)
Linha 1: Linha 1:
'''Me-OUV é a API REST do Fala.BR.'''
O Decreto 9.494/18, que dispõe sobre o Sistema de Ouvidoria do Poder Executivo Federal, pontuou em seu art. 16 o seguinte:


Art. 16.  As manifestações serão apresentadas, preferencialmente, em meio eletrônico, por meio do Sistema Nacional Informatizado de Ouvidorias - e-Ouv, de uso obrigatório pelos órgãos e pelas entidades da administração pública federal a que se refere o art. 2º, e disponibilizadas na Plataforma Integrada de Ouvidoria e Acesso à Informação - 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"'''.
Desta forma, apenas as ouvidorias federais são obrigadas a utilizarem o Fala.BR para recebimento e tratamento das manifestações recebidas. Todavia, nada impede que a ouvidoria que já possua algum sistema próprio possa realizar a integração com o Fala.BR. Assim, ouvidoria recebe as manifestações pelo Fala.Br, faz o tratamento em seu sistema próprio de ouvidoria e faz a transposição das ações executadas na manifestação para o Fala.BR.




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).
Para permitir tal integração, a equipe de TI da CGU desenvolveu uma Interface de Programação de Aplicações (traduzindo de ''Application Programming Interface'' - API) baseada em WebServices do tipo Representational State Transfer - REST,. Para maiores detalhes em como utilizá-la, basta acessar o roteiro disponível em [[Media:Como_utilizar_a_API_do_Fala.BR.pdf|Como utilizar a API do Fala.BR]].
 
'''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 [https://www.getpostman.com/downloads/].
 
 
'''IMPORTANTE''' A documentação detalhada de cada requisição está disponível em [https://treinafalabr.cgu.gov.br/help] e [https://falabr.cgu.gov.br/help].
 
 
=='''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.
 
[[Arquivo:imgFalaBrwiki116.png|900px|centro|FalaBr]]
 
''imgFalaBrwiki116: Geração de Nova senha Client Secret''
 
 
=='''3.2 Obtendo token de acesso'''==
 
Para autorização às requisições da API utiliza-se o padrão '''OAuth 2.0.'''
 
Assim, antes de realizar as requisições é necessário ter um token.
 
Seguem as instruções de como obter um token para a API com o Postman.
 
 
'''3.2.1 Obter um novo token'''
 
3.2.1.1 Crie uma nova requisição:
 
Passo 1 Acesse New > Request e preencha:
 
      • Request name: token
      • Collection: falabr-demo
      • + Create Collection falabr-demo
      • Save to falabr-demo
 
=='''3.3 Consultando um dado de domínio: tipos-formulario'''==
 
 
=='''3.4 Criando uma nova manifestação'''==
 
Para registrar uma nova manifestação, faça uma requisição à coleção de manifestações: POST api/manifestacoes.
 
Instruções no Postman:
 
'''Passo 1:''' Crie uma nova requisição:
 
        '''i.''' Acesse New > Request e preencha:
        • Request name: elogio
        • Collection: falabr-demo
        • + Create Collection falabr-demo
        • Save to falabr-demo
 
 
'''Passo 2:''' Preencha os dados na requisição "token" criada:
 
        '''i.''' Alterar o método para POST
        • Enter request URL: https://treinafalabr.cgu.gov.br/api/manifestacoes
        '''ii.''' Na aba Authorization
        • Type: No Auth
        '''iii.''' Na aba Headers
                '''(1)''' Entre com o par key value :
                  '''(a)''' Key: Authorization
                  '''(b)''' Value: Bearer <token-obtido-no-passo-acima*>
        '''iv.''' Na aba Body
                '''(1)''' Selecionar o radio "raw"
                '''(2)''' Selecionar em Text, a opção JSON
                '''(3)''' No editor de texto digitar:
 
 
'''3.4.1 Criando uma nova manifestação informando poucos campos'''
 
                {
                  "IdTipoFormulario": 1,
                  "IdTipoManifestacao": 3,
                  "IdOuvidoriaDestino": 6,
                  "TextoManifestacao": "Teste de registro de manifestação informando poucos campos",
                  "IdTipoIdentificacaoManifestante": 4,
                  "Manifestante": {
                    "Nome": "Usuário teste",
                    "Email": "meu@email.com"
                  },
                  "IndEnviarEmailCidadao": false,
                  "IndEnviarEmailOuvidoria": false
                }
 
 
'''3.4.2 Criando uma nova manifestação informando muitos campos'''
 
 
                {
                "IdTipoFormulario": 1,
                "IdTipoManifestacao": 3,
                "IdOuvidoriaDestino": 6,
                "TextoManifestacao": "Testando a orientação do Alexandre com outros detalhes",
                "IdTipoIdentificacaoManifestante": 4,
                "Manifestante": {
                "Nome": "Marcos Chiclete",
                "Email": "marcoschiclete@gmail.com",
                "DataNascimento": "2019-09-19T10:34:33.6516589-03:00",
                "Telefone": {
                "Numero": "1",
                "ddd": "2"
                },
                "Numero": "7",
                "Complemento": "sample string 8",
                "Bairro": "sample string 9",
                "IdRacaCor": 1,
                "IdProfissao": 1,
                "IdEscolaridade": 1,
                "RazaoSocial": "sample string 11",
                "IdTipoInstituicao": 1,
                "IdAreaAtuacao": 1,
                "NomeRepresentante": "sample string 12",
                "CargoRepresentante": "sample string 13",
                "EmailRepresentante": "sample string 14"
                },
                "IndEnviarEmailCidadao": false,
                "IndEnviarEmailOuvidoria": false
                }
 
A resposta será um JSON com o id da manifestação criada mais um link para ela:

Edição atual tal como às 00h34min de 3 de abril de 2020

O Decreto 9.494/18, que dispõe sobre o Sistema de Ouvidoria do Poder Executivo Federal, pontuou em seu art. 16 o seguinte: 

Art. 16.  As manifestações serão apresentadas, preferencialmente, em meio eletrônico, por meio do Sistema Nacional Informatizado de Ouvidorias - e-Ouv, de uso obrigatório pelos órgãos e pelas entidades da administração pública federal a que se refere o art. 2º, e disponibilizadas na Plataforma Integrada de Ouvidoria e Acesso à Informação - Fala.BR.


Desta forma, apenas as ouvidorias federais são obrigadas a utilizarem o Fala.BR para recebimento e tratamento das manifestações recebidas. Todavia, nada impede que a ouvidoria que já possua algum sistema próprio possa realizar a integração com o Fala.BR. Assim, ouvidoria recebe as manifestações pelo Fala.Br, faz o tratamento em seu sistema próprio de ouvidoria e faz a transposição das ações executadas na manifestação para o Fala.BR.


Para permitir tal integração, a equipe de TI da CGU desenvolveu uma Interface de Programação de Aplicações (traduzindo de Application Programming Interface - API) baseada em WebServices do tipo Representational State Transfer - REST,. Para maiores detalhes em como utilizá-la, basta acessar o roteiro disponível em Como utilizar a API do Fala.BR.

Disponível em “https://wiki.cgu.gov.br/index.php?title=13._Integração_de_Outros_Sistemas_com_o_Fala.BR&oldid=2973”