Exibir código-fonte para 3.1 Como utilizar a API do Fala.br (Me-Ouv)

'''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 [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:

'''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: