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

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

[[1]]

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 [2].

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

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)

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

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