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
 
(9 revisões intermediárias pelo mesmo usuário 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:


[[http://wiki.cgu.gov.br/wiki/images/4/4b/Como_utilizar_a_API_do_Fala.BR_%28Me-OUV%29.pdf|Sunflowers]]
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.




[[Media:Como_utilizar_a_API_do_Fala.BR_(Me-OUV).pdf|Sunflowers]]
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.


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"'''.
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]].
 
 
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 [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)
       
[[Arquivo:imgFalaBrwiki117.png|1000px|esquerda|FalaBr]]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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'''
 
 
[[Arquivo:imgFalaBrwiki118.png|900px|esquerda|FalaBr]]
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
[[Arquivo:imgFalaBrwiki116.png|900px|esquerda|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'''==
 
 
Para listar os tipos de formulário, faça uma requisição à coleção de tipos de formulário: GET api/tipos-formulario .
Instruções no Postman:
 
a)     Crie uma nova requisição:
i. Acesse New > Request e preencha:
• Request name: tipos-formulario
• Collection: falabr-demo
• + Create Collection falabr-demo
• Save to falabr-demo
 
b) Preencha os dados na requisição "token" criada:
i) Manter o método GET já selecionado
• Enter request URL: https://treinafalabr.cgu.gov.br/api/tipos-formulario
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*> 
* Obs: importante colocar a palavra “Bearer” seguida de espaço antes do valor do token. Não acrescentar os símbolos < e >.
 
Figura
 
c) Send
A resposta da requisição será um JSON com a lista de tipos de formulários.
 
Figura
 
=='''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:
 
'''3.4.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
 
 
'''3.4.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 entre com o par key value:
                  • Key: Authorization
                  • Value: Bearer <token-obtido-no-passo-acima*>
        '''iv.''' Na aba Body selecione:
                  • o radio "raw"
                  • em Text, a opção JSON
        '''v.''' No editor de texto digitar uma das duas sequências abaixo de forma sumária ou mais completa - de acordo com a necessidade/ disponibilidade de dados:
 
'''3.4.2.1. Se estiver 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.2 Se estiver 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, conforme demonstrado na imagem abaixo:
 
Figura

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”