Fala.BR - API Faq

Perguntas Frequentes sobre Integração API do Fala.BR: Guia de Referência

Este documento aborda dúvidas comuns sobre a integração de sistemas internos com a Plataforma Fala.BR por meio de sua API (Application Programming Interface), consolidando informações importantes para equipes técnicas e gestores.

0. O que é a integração API do Fala.BR? Qual seu objetivo?

Trata-se de uma Interface de Programação de Aplicações (traduzindo de Application Programming Interface - API) baseada em WebServices do tipo Representational State Transfer – REST. Por meio da API é possível realizar diversas ações semelhantes ao acesso do Fala.BR via web, tais como registrar, consultar manifestações, consultar dados de domínio e recuperar recursos LAI. Dessa forma, as ouvidorias podem utilizar a API para registrar e tratar as manifestações sem atuar diretamente no Fala.BR ou então tratar em sistemas próprios e sincronizar as informações entre os sistemas. Pode ainda utilizar para baixar suas manifestações em detalhes para compor uma base de dados própria e então produzir relatórios e painéis de acordo com sua necessidade.

1. É possível ter um contato técnico individualizado para esclarecimento de dúvidas durante o processo de integração?

A Ouvidoria-Geral da União (OGU) não disponibiliza um contato técnico individualizado para cada órgão devido ao volume de demandas e à necessidade de padronização. O canal oficial e mais eficaz para tirar dúvidas e obter suporte técnico é por meio da assistente virtual Fabi, e caso não consiga esclarecer suas dúvidas, podem ser enviadas para a equipe de suporte por meio do formulário de suporte técnico (https://formularios.cgu.gov.br/index.php/679625). Ao utilizá-lo, é recomendado fornecer o máximo de detalhes técnicos, como ambiente, contas utilizadas, logs e requisições realizadas (preferencialmente utilizando ferramentas como o Postman, conforme sugerido no "Roteiro Como utilizar a API da Plataforma Fala.BR", referido na API Fala.BR Documentação).

2. Existe documentação sobre os requisitos de cibersegurança da aplicação Fala.BR?

A área de negócio da CGU não possui um documento único e dedicado exclusivamente a requisitos de cibersegurança da aplicação em si. No entanto, as diretrizes e responsabilidades relacionadas à segurança da informação estão detalhadas em outros documentos essenciais para o uso da plataforma e da API. Os principais materiais que abordam esses requisitos são: • Termos de Uso e Aviso de Privacidade do Fala.BR: Disponíveis em https://falabr.cgu.gov.br/publico/TermosDeUso/TermosDeUso.aspx, estes documentos detalham como o sistema funciona, as leis aplicáveis e como os dados dos usuários são tratados, incluindo aspectos de segurança da informação e coleta de IP. • Política de Uso da API do Fala.BR: Este documento estabelece as diretrizes relacionadas às atividades de gestão e do uso da API, incluindo as responsabilidades do órgão integrador na observância da legislação de proteção de dados (LGPD - Lei nº 13.709/2018) e o controle de acesso (login, senhas). A política enfatiza que o controle de acesso e o uso dos dados obtidos via API são de inteira responsabilidade do órgão integrador. Estes materiais fornecem a base para os requisitos de cibersegurança e as responsabilidades de ambas as partes na proteção dos dados.

3. Como lidar com a diferença na funcionalidade de reabertura de manifestações entre um sistema externo e o Fala.BR?

Na API do Fala.BR, é possível utilizar o endpoint POST api/manifestacoes/{id}/reabrir para reabrir uma manifestação concluída ou arquivada. Se seu sistema externo não possui uma funcionalidade equivalente de reabertura, a abordagem recomendada é que: • Sincronização de Status: Seu sistema esteja preparado para receber atualizações de status do Fala.BR. Se uma manifestação for reaberta no Fala.BR, seu sistema deve refletir essa mudança de status. • Ações Exclusivas no Fala.BR: As reaberturas seriam realizadas exclusivamente no Fala.BR. Seu sistema precisaria consultar o status atualizado da manifestação via API (GET api/manifestacoes/{id}) para identificar se ela foi reaberta e gerenciar o fluxo internamente.

4. O Fala.BR permite que a tramitação interna de demandas seja realizada em sistema externo, utilizando o Fala.BR apenas para recebimento e resposta final?

Sim, é possível usar seu sistema próprio para a gestão do tratamento interno das manifestações. Nesse cenário, o Fala.BR funcionará principalmente como um canal de entrada e saída das manifestações. É crucial, porém, que a resposta final e as mudanças de status (como complementação solicitada, prorrogada ou concluída) sejam devidamente registradas e atualizadas no Fala.BR via API. Seu sistema pode inclusive anexar os registros de tratamento (e-mails, documentos) como evidências à manifestação no Fala.BR ao enviar a resposta final, utilizando o endpoint POST api/manifestacoes/{id}/respostas, que permite a inclusão de anexos.

5. Quando uma manifestação é registrada no sistema externo e enviada ao Fala.BR via API, o participante receberá um protocolo do Fala.BR?

Por padrão, não. A fim de se evitar a duplicação de notificações, o padrão do Fala.BR ao registrar uma manifestação via API é não enviar notificação ao manifestante. Contudo, caso deseje o envio pelo Fala.BR, basta indicar o parâmetro “IndEnviarEmailCidadao” com o valor “True”. Dessa forma, o manifestante receberá um e-mail com informações da demanda registrada, quis sejam: o Número Único de Protocolo (NUP) do Fala.BR e o Código de Acesso, desde que um e-mail seja fornecido na requisição API. O Fala.BR, por padrão, não enviará notificações por e-mail ao participante sobre o status da manifestação (registro, complementação, resposta etc.). Caso deseje que o Fala.BR envie e-mails, deve especificar o parâmetro "INDENVIAREMAILCIDADAO: TRUE" na requisição API de registro e de atualizações da manifestação.

6. É obrigatório que as tramitações internas (entre áreas ou usuários) ocorram dentro do próprio sistema Fala.BR?

Não, não é obrigatório que as tramitações internas ocorram dentro do próprio sistema Fala.BR. A integração via API oferece flexibilidade, permitindo que você continue a usar seu sistema externo para a gestão do tratamento da manifestação. O Fala.BR, através da API, pode ser utilizado para o recebimento da manifestação e para o registro da resposta final e do status da manifestação. É possível anexar os registros de tratamento como evidências à manifestação no Fala.BR antes de enviar a resposta final, garantindo que o histórico completo esteja no sistema oficial.

7. Em um fluxo bidirecional, onde manifestações são trocadas entre sistemas, qual número de protocolo prevalece?

Em um cenário bidirecional: • Manifestações do Fala.BR para seu sistema: Manifestações registradas diretamente no portal Fala.BR receberão um NUP e um ID gerados pelo Fala.BR. Seu sistema precisaria usar a API (GET api/manifestacoes) para buscar essas manifestações e inseri-las, usando o ID e o NUP do Fala.BR como identificadores principais. Note que, para operações via API, a chave será o ID, enquanto em operações no Fala.BR a chave será o NUP. • Manifestações do seu sistema para o Fala.BR: Se recebidas pelo seu sistema e enviadas para o Fala.BR via API (POST api/manifestacoes), o Fala.BR gerará um ID e NUP próprios e novos. Seu sistema precisará armazenar esses para referência. O Número Único de Protocolo (NUP) do Fala.BR é o que prevalece como identificador oficial no Fala.BR para o cidadão e para a ouvidoria, enquanto para operações via API, a chave será o ID. Seu sistema deve estabelecer um mecanismo de correlação entre seus protocolos internos e os Ids e NUPs do Fala.BR.

8. O manifestante deve receber respostas por um único canal para evitar duplicidade e confusão?

Idealmente, sim, é interessante que o manifestante receba a resposta por um único canal para evitar duplicidade e confusão. A gestão da comunicação deve ser centralizada. Sua Ouvidoria pode optar por enviar a resposta final pelo seu sistema externo, mantendo o controle da comunicação. No entanto, é fundamental que a resposta final e o status "Concluída" sejam atualizados no Fala.BR via API (POST api/manifestacoes/{id}/respostas). Por padrão, as atualizações das manifestações registradas via API não enviarão notificações ao manifestante. Para que o Fala.BR envie uma notificação ao cidadão, a requisição da resposta via API deve incluir o parâmetro EnviarEmail: TRUE.

9. Mesmo em denúncias registradas como "Identificadas sem Restrição", por que os dados de identificação do manifestante (Nome, Email, etc.) não são retornados pela API ou aparecem como pseudonimizados?

A Plataforma Fala.BR aplica um processo de pseudonimização aos dados do denunciante para garantir sua proteção, conforme regra de negócio estabelecida e em atenção ao Decreto nº 10.153/2019. Mesmo que a manifestação seja classificada como "Identificada sem Restrição" no objeto TipoIdentificacaoManifestante da API, os detalhes diretos do manifestante (como Nome e E-mail) são inibidos na consulta via API. No sistema web, a visualização desses dados exige uma justificativa do servidor, funcionalidade que não está disponível para chamadas via API.

10. Existe alguma forma de obter os dados de identificação completos do manifestante via API para denúncias registradas de forma identificada ("Identificadas sem Restrição")?

Atualmente, a API do Fala.BR não permite a recuperação dos dados de identificação completos do manifestante para denúncias, mesmo quando registradas como "Identificadas sem Restrição". Essa restrição é uma regra de negócio para proteger o denunciante, e a API não possui o mecanismo de "justificativa" que o sistema web exige para exibir tais dados. Este funcionamento, estabelecido como regra de negócio em atenção à proteção ao denunciante, está amparado pelo Decreto nº 10.153/2019 (que trata das salvaguardas de proteção à identidade) e pela Lei nº 13.709/2018 (LGPD). No sistema web, a visualização dos dados exige justificativa, funcionalidade que não está presente na API. Uma eventual revisão dessa regra dependeria de confirmação da OGU, considerando o arcabouço normativo vigente.

11. Quais são os perfis de usuário disponíveis para integração via API e suas respectivas permissões?

Existem dois perfis principais para integração via API, ambos do tipo "Sistema": • WebService Respondente: Este perfil permite realizar todas as ações do órgão sobre as manifestações vinculadas a ele, como registrar, responder e encaminhar. Também é possível atualizar dados das manifestações como assunto, subassunto, tags, serviço e responsável pela análise. • WebService Observador: Este perfil permite apenas consultar e detalhar manifestações do órgão. É ideal para consumo de dados para a montagem de relatórios e painéis próprios.

12. Como solicitar a criação de um usuário para integração via API e quais informações são necessárias?

A solicitação de um usuário para a API deve ser feita pelo Ouvidor do órgão. Para órgãos federais, o contato é com a CGOUV (Coordenação-Geral de Orientação e Acompanhamento de Ouvidoria); para os demais órgãos, como a Sanesul, o contato é com a CGART (Coordenação-Geral de Articulação Institucional). Na solicitação, é preciso indicar o perfil desejado (WebService Respondente ou WebService Observador), os tipos de manifestação que se deseja acessar e os dados do responsável de TI (nome, CPF, e-mail corporativo e telefone de contato), que atuará nos trabalhos de integração.

13. Existem ambientes separados para testes e produção na integração via API?

Sim. Inicialmente, o acesso à API é liberado no ambiente de treinamento (treinafalabr.cgu.gov.br), especialmente para o perfil respondente, para que a equipe possa realizar testes e se familiarizar. Somente após a comprovação da execução da integração com sucesso neste ambiente, o usuário será criado no ambiente de produção (falabr.cgu.gov.br). É necessário criar um usuário webservice para cada um dos ambientes separadamente.

14. Como obter o token de acesso para a API e qual a sua validade?

A API utiliza o padrão OAuth 2.0 para autenticação. Após a criação do usuário webservice, um e-mail é enviado com as credenciais de acesso à API. O próprio usuário API deve, então, acessar o sistema pela opção API (ou usuário e senha no ambiente de treinamento), atualizar a senha no primeiro acesso. Em seguida, deve gerar o token de acesso, preferencialmente por meio da ferramenta Postman. O passo a passo está descrito no documento “Roteiro Como utilizar a API da Plataforma Fala.BR.pdf”. O token de acesso expira regularmente e deverá ser atualizado a partir da geração de uma nova senha da aplicação (client_secret) no cadastro do usuário no sistema, para então gerar um novo token.

15. Os endpoints da API utilizam diversos parâmetros para completar a ação. Como consultar esses parâmetros?

O manual com os endpoints lista uma série de comandos auxiliares para ajudar a compor os comandos, por exemplo, lista de assuntos (GET api/assuntos), lista de subassuntos (GET api/subassuntos?idOrgao={idOrgao}), lista de tags da ouvidoria (GET api/tags?idOrgao={idOrgao}), tipos de formulários (GET api/tipos-formulario), entre outros tantos.

16. Quais são as recomendações para o tipo de consulta para evitar sobrecarga na base de dados?

Para evitar sobrecarga na base de dados do Fala.BR, é altamente recomendável realizar consultas incrementais. Isso significa buscar apenas as atualizações diárias ou por hora, em vez de reler todos os dados a cada consulta. Consultas mal formuladas ou excessivas podem impactar a performance do sistema e, se detectadas, podem ser bloqueadas, conforme previsto na Política de Uso da API.

17. Há um limite de registros por consulta na API? Como lidar com grandes volumes de dados?

Sim, há um limite de 1000 registros por consulta. Se a sua requisição necessitar de mais de 1000 registros, é obrigatório limitar os parâmetros de data de cadastro que limitem a consulta a, no máximo, 5 dias. Não há uma função de "count" na API, pois essa operação onera excessivamente o banco de dados. Para lidar com grandes volumes, utilize a estratégia de consultas incrementais e paginação (MaxResultados e PosInicioPagina) conforme a documentação da API.

18. Quais são os requisitos técnicos para o envio de anexos via API?

Ao enviar anexos por meio da API, eles devem estar no formato base64 e previamente compactados (gzipados). O documento “Roteiro Como utilizar a API da Plataforma Fala.BR.pdf” fornece exemplos de como realizar esse procedimento.

19. É possível incluir subassuntos e tags diretamente no registro de uma manifestação via API?

Atualmente, a API do Fala.BR não disponibiliza parâmetros para inclusão direta de subassuntos e/ou tags no momento do cadastro inicial de uma manifestação (via POST api/manifestacoes). No registro inicial, é possível incluir apenas o assunto principal. No entanto, tanto o subassunto (IdSubassunto) quanto as tags (IdsTags) podem ser atualizados ou adicionados posteriormente a uma manifestação existente utilizando o endpoint POST api/manifestacoes/{id}/atualizar.

20. Qual valor deve ser passado para o parâmetro "Resposta conclusiva" na API e onde encontrar a documentação específica?

Para o parâmetro "Resposta conclusiva" na API, você deve utilizar o endpoint POST api/manifestacoes/{id}/respostas com o campo IdTipoRespostaManifestacao definido como 3 (três) para resposta conclusiva. Os valores disponíveis para tipos de resposta podem ser consultados através do endpoint GET api/tipos-resposta da documentação da API.

21. Como acessar respostas das manifestações através da API?

Use o endpoint GET api/manifestacoes/{id} para obter detalhes completos de uma manifestação, incluindo o teor e todas as respostas associadas. Este endpoint retorna informações detalhadas da manifestação, inclusive o histórico de respostas no campo correspondente.

22. Como redefinir senha para usuário webservice?

Usuários webservice devem usar a opção de recuperação de senha disponível na tela de login do sistema. Clique em "Esqueci minha senha" na tela de login para perfis webservice e siga as instruções enviadas por e-mail. Para atualizar o cliente_id utilizado para geração do token, acesse a funcionalidade "Meu Usuário" no sistema web e utilize a opção "Gerar nova senha" na seção "Aplicação".

23. Como saber se uma manifestação foi efetivamente resolvida através da API?

Verifique o parâmetro IndDemandaResolvida = 1 no retorno do endpoint GET api/manifestacoes/{id}. Este campo indica se a demanda foi efetivamente resolvida pelo órgão, independentemente do status "Concluída". É importante não confundir a situação da manifestação "Concluída" (IdSituacaoManifestacao = 6) com a indicação de resolutividade. Uma manifestação pode estar concluída mas com resolutividade "não resolvida" (IndDemandaResolvida = 0). A situação concluída de uma manifestação sinaliza a inclusão de uma resposta conclusiva na manifestação pela ouvidoria. Enquanto a resolutividade sinaliza o posicionamento final do órgão sobre a demanda. Por exemplo, após a resposta conclusiva da ouvidoria indicando a aptidão de uma denúncia (lembrando que a ouvidoria apenas aprecia a existência dos elementos mínimos de autoria e materialidade), esta será encaminhada para a área apuratória, por exemplo, a corregedoria do órgão que se debruçará mais detidamente sobre a questão e se posicionará mais à frente quanto à admissibilidade, que poderá no futuro se desdobrar em diversos instrumentos apuratórios no âmbito da corregedoria. A resolutividade tem a ver com o posicionamento final sobre a admissibilidade na área apuratória. Mais detalhes estão no manual do sistema.

24. Como obter informações sobre avaliação do cidadão (satisfação) através da API?

Utilize o endpoint GET api/respostaspesquisasatisfacao para acessar as respostas às pesquisas de satisfação das manifestações. Este endpoint retorna informações sobre a avaliação do cidadão quanto ao atendimento recebido, incluindo notas de satisfação e comentários quando disponíveis.

25. Como identificar o responsável atual pela análise de uma manifestação?

Utilize o endpoint GET api/manifestacoes/{id} que retorna informações sobre a quem a manifestação está tramitada atualmente no campo correspondente ao responsável pela análise. Esta é uma "fotografia" do momento da consulta - se a tramitação for modificada posteriormente, a informação será alterada. Para manter dados atualizados, recomenda-se utilizar consultas incrementais pela data de atualização.

26. A API suporta consulta de manifestações encaminhadas para outros órgãos?

As manifestações encaminhadas não estão mais no domínio da ouvidoria, então não é possível acompanhar as atualizações depois que a ouvidoria encaminha uma manifestação para outra ouvidoria. A API, assim como o sistema, permite consultar manifestações encaminhadas para outras ouvidorias por meio do endpoint GET api/reencaminhamentosmanifestacoes.

27. Como consultar dados de usuário através da API?

Utilize o endpoint GET api/usuarios?cpf={cpf} para retornar dados do usuário a partir do CPF. Note que este endpoint está disponível apenas para usuários vinculados ao seu perfil de acesso e segue as restrições de privacidade estabelecidas pela LGPD.

28. É possível cadastrar um usuário cidadão através da API?

Sim, utilize o endpoint POST api/usuarios para cadastrar um usuário cidadão. Este endpoint permite a criação de novos usuários no sistema, respeitando os campos obrigatórios e as validações estabelecidas.

29. Como consultar unidades vinculadas a uma ouvidoria?

Utilize o endpoint GET api/unidades?idOuvidoria={idOuvidoria} para consultar e listar as unidades vinculadas a uma ouvidoria específica. Este endpoint retorna informações sobre a estrutura organizacional interna do órgão cadastrada no sistema.

30. Como monitorar o status de funcionamento da API?

Utilize o endpoint GET api/monitoramento/status para verificar o status de funcionamento da API. Este endpoint fornece informações sobre a disponibilidade e o estado operacional dos serviços da API.

31. Quais são os pré-requisitos para a integração do Fala.BR com o sistema ePAD via API?

Para que a integração do Fala.BR com o ePAD ocorra via API, alguns critérios devem ser atendidos: 1. A corregedoria responsável deve estar informada no cadastro do órgão no Fala.BR. 2. A denúncia deve ser considerada apta e haver indicação de agente público ou empresa envolvidos na manifestação. 3. A integração é acionada apenas na primeira resposta conclusiva da manifestação. 4. O envio para a corregedoria deve ser confirmado na área de integração com o ePAD no momento da resposta.

32. Como o Número Único de Protocolo (NUP) da manifestação é tratado durante a integração com o ePAD via API?

Se disponível no ePAD, o processo de admissibilidade será aberto com o mesmo NUP da denúncia do Fala.BR. O NUP da manifestação original do Fala.BR também é enviado em um anexo junto com os metadados da manifestação, garantindo que a referência seja mantida.

33. É recomendado importar manifestações antigas via API para o Fala.BR?

Embora seja tecnicamente possível registrar manifestações antigas via API em duas etapas (primeiro cadastrando a manifestação e depois atualizando a resposta para concluí-la), essa prática não é recomendada, especialmente porque com o registro das manifestações antigas no Fala.BR, estas receberão a data de registro do dia do cadastro. Não é possível registrar com data anterior. Isso pode afetar a precisão do painel geral de estatísticas devido à diferença nas datas de registro e conclusão. A CGU não oferece suporte para análise de sistemas legados com o objetivo de importar manifestações, e o ideal é que as manifestações sejam registradas no momento de sua ocorrência.

34. O que significa o erro "Token inválido, obtenha novo Token" na integração via API e como devo proceder?

A mensagem refere-se ao token utilizado ter expirado. Para continuar a utilizar deverá ser atualizado.

35. A API do sistema possui uma rota específica que retorne os feriados cadastrados no Fala.BR para efeitos de contagem de prazos?

Não há, na API do sistema, rota específica que retorne os feriados cadastrados. Essa função é restrita a administradores da plataforma. Contudo, o parâmetro "PrazoAtendimento" retornado no JSON do endpoint GET api/manifestacoes/{id} já indica o prazo de atendimento da manifestação no formato DD/MM/YYYY, considerando todos os feriados nacionais cadastrados em ambiente de produção. Para testes, o ambiente de Treinamento também considera esses feriados.

36. É possível extrair uma base de dados com o teor completo das manifestações desde uma determinada data?

A extração completa dos campos das manifestações, incluindo o teor, deve ser realizada por intermédio da API (consultar o tópico "Integração via API - Application Programming Interface" do manual do Fala.BR), pois o sistema não gera relatórios com essa informação.

37. Há previsão de bloqueio ou suspensão das APIs para interação com o Fala.BR a partir de um sistema próprio de uma empresa, especialmente para manifestações de ouvidoria?

Não há informações sobre bloqueio de uso da API para pedidos de acesso à informação ou manifestações de ouvidoria. Assim, não há que se falar em bloqueio.

38. Há alguma iniciativa para disponibilizar webhooks (envio de informações) para endpoints externos, sem a necessidade de realizar consultas periódicas?

No momento, não há iniciativas a respeito desse tema. A integração é realizada apenas via API para unidades de ouvidoria, exigindo consultas.

39. É possível obter uma lista de mensagens de erro para os endpoints da API?

A equipe de tecnologia informou que não é possível fornecer uma lista exata de mensagens de erro. As mensagens podem advir tanto da aplicação quanto de diversos elementos de infraestrutura e serviços utilizados pelo sistema.

40. A API traz informações sobre unidade e departamentos na manifestação? Como consigo essas informações?

A API não exibe as informações de unidade e departamentos da mesma forma que aparecem no sistema para cada manifestação. Para identificar tramitações para unidades internas poderá rastrear no histórico da manifestação. As tramitações ficam registradas como uma ação do tipo “Tramitação” e o detalhamento da ação contêm a string “Manifestacao tramitada para a unidade ....”. Caso a tramitação seja para agente pessoa física, a string da mesma ação será “Manifestacao tramitada para o(s) usuário(s)...” Para consultar as unidades internas da ouvidoria utilize: endpoint GET api/unidades?idOuvidoria={idOuvidoria}.

41. A API do Fala.BR disponibiliza a lista de IDs dos motivos para os respectivos tipos de manifestações no momento da resposta conclusiva (Reclamação, Solicitação, Denúncia, Comunicação e Sugestão)?

Para consultar os tipos de resposta existe a rota

GET api/tipos-resposta?idTipoManifestacao={idTipoManifestacao}	=

que consulta os tipos de resposta, permitindo filtrar pelo tipo da manifestação.

42. Assuntos inativados na plataforma são retornados como "true" na requisição da API?

Conforme o manual do Fala.BR, a tela de gerenciamento de assuntos apenas favorita os assuntos a serem sugeridos ao cidadão no momento do registro da manifestação. Mesmo que não estejam favoritados, poderão ser indicados. Não existe exclusão de assuntos pelos órgãos; a gestão de assuntos é competência da CGU para garantir uniformidade. Portanto, se um assunto está inativado no contexto de sugestão, ele ainda pode existir e ser retornado em outras consultas se for considerado ativo pela CGU. A rota GET api/assuntos?indApenasAtivos={indApenasAtivos}&idOuvidoria={idOuvidoria}&verificarEstruturaAExibir={verificarEstruturaAExibir}&idManifestacao={idManifestacao} permite consultar assuntos ativos e favoritados na ouvidoria.

43. Existe alguma forma de buscar manifestações via API sem os registros migrados?

Não. A API considera todos os pedidos cadastrados ou encaminhados para a ouvidoria, e isso inclui os registros migrados, que são entendidos como um encaminhamento. Não há como realizar requisições via API sem incluir os pedidos migrados. No máximo, poderia filtrar por algum critério como data de registro. Supondo que as manifestações até 31/12/2022 tenham sido migradas para uma nova ouvidoria criada em 2023, poderia puxar apenas as posteriores a essa data de registro.

44. Ao tentar responder uma manifestação via integração (POST api/manifestacoes/{id}/respostas), recebo o erro 403 – Forbidden. Qual pode ser o motivo?

Este problema pode ocorrer se o sistema externo estiver utilizando tags HTML no corpo da resposta, o que não é permitido pela API do Fala.BR. Além disso, certifique-se de que o protocolo da manifestação que você está tentando responder realmente pertence ao órgão ao qual o perfil webservice está vinculado. Um perfil só pode realizar ações sobre as manifestações que estão sob a tutela do órgão a ele associado. Erros do tipo 40X dizem respeito a autorização de acesso. Pode ser por exemplo, a tentativa de registro de uma resposta em nome de outra ouvidoria. Note que registrar uma manifestação para outra ouvidoria é possível, assim como o atendente faz no sistema.

45. A API do Fala.BR permite a inclusão de chatbots na interface do sistema?

É possível criar chatbots para interagir com os cidadãos, coletar dados e depois registrar manifestação, caso do Mauá, do Ministério do Transporte e de chatbot criado pela CGU, em princípio, para a COP30.

46. É possível alterar o motivo da demanda resolvida após a manifestação já estar concluída via API?

Não há parâmetro via API para indicação do motivo da resolutividade. É possível atualizar a opção "Demanda Resolvida" (de Sim para Não e vice-versa) e o texto de observação, mas não o motivo. Esta funcionalidade foi registrada como solicitação de implementação à tecnologia, mas sem prazo definido, pois depende de priorização frente a outras demandas.

47. O Fala.BR ainda suporta integração via API SOAP, ou apenas REST?

A equipe de TI da CGU desenvolveu uma Interface de Programação de Aplicações (API) baseada em WebServices do tipo Representational State Transfer - REST. É importante destacar que a API via SOAP do antigo sistema e-Ouv foi desativada, e a OGU não fornece mais suporte para ela. A integração atual é exclusivamente via API REST

48. Qual é a recomendação da CGU para a ferramenta a ser utilizada na integração com a API do Fala.BR e para o reporte de bugs?

A CGU recomenda a utilização da ferramenta Postman, disponível gratuitamente em https://www.postman.com, para auxiliar na utilização e testes da API. Além disso, solicitações de suporte ou reporte de bugs devem ser necessariamente acompanhados da requisição realizada no Postman para facilitar a investigação e solução dos problemas.

49. Quais cuidados devem ser tomados com os textos enviados via API para evitar erros na visualização do sistema?

Os textos enviados no registro de manifestação via API devem ser tratados pelo órgão antes de serem submetidos. Devem ser excluídos caracteres especiais que possam sinalizar codificação HTML, que causará erro na visualização dos dados no sistema. Dessa forma, é necessário excluir caracteres como "<" e ">", além de combinações que possam ser interpretadas como formatação de texto web, como "\n" (quebra de linha), entre outros.

50. Qual o fluxo recomendado para formar uma base de dados local para criação de painéis e relatórios próprios a partir da API do Fala.BR?

Para montar uma base de dados local e criar painéis/relatórios próprios, o fluxo recomendado é:

a) Montagem da base inicial: Obter a lista de manifestações com GET api/manifestacoes utilizando parâmetros como data de registro ou data de atualização (melhor). A partir dessa lista, realizar um segundo comando para detalhes de cada manifestação com GET api/manifestacoes/{id}.

b) Sincronização das atualizações: Diariamente, obter a lista de manifestações que foram atualizadas (novas e modificadas) no dia anterior, passando o parâmetro de data de atualização, como em GET api/manifestacoes?dataAtualizacaoInicio=AAAA-MM-DDTHH:MM:SS&dataAtualizacaoFim=AAAA-MM-DDTHH:MM:SS. Em seguida, obter os detalhes dessas manifestações atualizadas com GET api/manifestacoes/{id}. O ciclo se repete diariamente para manter a base atualizada. É crucial que os painéis internos utilizem essa base local e não consultem diretamente a API do Fala.BR para evitar sobrecarga na base de produção do sistema. A OGU não oferece suporte para ferramentas internas dos órgãos.

51. As manifestações registradas via API ficam associadas a usuários existentes no Fala.BR? Como o cidadão deve acompanhar estas manifestações?

Sim, as manifestações registradas via API que preenchem o CPF e o tipo de documento são associadas a um usuário existente no Fala.BR, caso haja uma correspondência. A associação não é feita pelo e-mail no momento do registro. Dessa forma, para acompanhar a manifestação, o cidadão deve utilizar o código gerado e enviado ao endereço de e-mail informado, conforme o procedimento descrito em "Acessando uma Manifestação de Usuário sem Cadastro".

________________________________________

Este documento serve como um guia de referência. Para mais detalhes e informações técnicas, consulte sempre a "Documentação Completa da API do Fala.BR", o "Roteiro Como utilizar a API da Plataforma Fala.BR.pdf" e o "Manual Fala.BR - Módulo Ouvidoria" disponíveis na Wiki CGU.