ProJuris 8: Manual de Integração com Provedores de Recortes

Transcrição

1 ProJuris 8: Manual de Integração com Provedores de Recortes Versão 2.0 por Gabriel Cherem agosto/2014

2 Motivação Pelo menos 50% de todas as sociedades de advogados no Brasil utilizam algum software para o controle e acompanhamento de processos judiciais, sem mencionar os departamentos jurídicos corporativos e os advogados autônomos. Destes, grande parte também assina algum serviço de clipagem ou fornecimento eletrônico de recortes ou publicações oficiais. Neste contexto, a integração entre os sistemas de gestão de processos judiciais e o serviço de fornecimento de recortes deixa de ser uma função desejável para te tornar uma exigência, uma vez que o usuário não vê mais sentido em recortar e colar de um sistema para outro. Entendemos que a construção da integração entre o provedor de recortes e o ProJuris, traz benefícios para todos: em primeiro lugar, para o cliente, que contará com um meio automático, livre de erros e intervenções manuais e repetitivas para realizar a carga das publicações no sistema de gestão de processos. Para o ProJuris, que tem como uma de suas metas, ser o software mais completo neste aspecto, oferecendo integração com o maior número possível de provedores de recortes do mercado. Para o provedor de recortes, uma vez que cada usuário do ProJuris passa a ser um potencial cliente, pois a integração com o novo provedor estará disponível nas novas versões do software, liberadas constantemente para uma base de mais de 10 mil usuários do ProJuris. Por considerarmos um benefício mútuo, decidimos envidar esforços na construção de integrações sem custos para os clientes e nem para os nossos parceiros provedores de recortes. Para isto, criamos este manual que estabelece os requisitos necessários para a integração. Como a Integração Acontece no ProJuris O processo de integração é sempre iniciado por uma ação voluntária do usuário. Ao clicar o botão Obter Recortes, o ProJuris apresenta o menu abaixo para que o usuário selecione o provedor. Após a seleção do provedor, o ProJuris acessa o webservice correspondente informando como parâmetro a conta ou chave do usuário informado pelo provedor no momento da contratação e o período inicial da consulta, que será discutido mais tarde. É feito então o recebimento dos dados disponibilizados pelo provedor em formato XML, e os dados são populados na grade apresentada a seguir:

3 Ao mesmo tempo que a grade é populada, o ProJuris faz a associação entre cada publicação recebida e o processo correspondente no banco de dados através do campo NÚMERO (somente podem ser importadas as publicações associadas a processos previamente cadastrados no ProJuris). O usuário pode então selecionar as publicações que deseja importar e finalizar o procedimento. Note que é facultado ao usuário a possibilidade de fechar esta tela sem que nenhuma publicação seja importada no momento, permitindo que ele retorne mais tarde e repita a operação. Isto pode ser necessário quando houverem publicações que não tenham sido associadas tanto pela inexistência do processo correspondente no ProJuris como por um eventual erro de digitação do número do processo. O usuário precisará então corrigir estas situações e repetir o procedimento. O ProJuris sempre busca pelas publicações em um faixa de data compreendida entre uma data inicial e a atual. Na primeira vez que o cliente realizar a carga, a data inicial é arbitrada com um valor padrão. Após uma importação bem sucedida (onde não houve cancelamento do usuário nem erro), o sistema salva a data da importação, que será usada como a data inicial da próxima importação. É permitido ao usuário editar a data inicial da importação manualmente, caso precise repetir a carga das publicações a partir de uma determinada data. O WebService O WebService deverá seguir o padrão REST e único parâmetro obrigatório é a data inicial que deverá ser passada na URL de chamada ao WebService. O sistema deverá então retornar todas as publicações existentes (inéditas ou não) no período compreendido entre a data inicial passada como parâmetro (inclusive) e a data atual (inclusive). A data utilizada para esta seleção é a data da publicação. Caso o WebService tenha sido implementado de forma que necessite também uma data final para delimitar a busca por datas, o ProJuris poderá incluir este parâmetro com a data atual. A identificação do usuário para efeito de autenticação no WebService, controle de uso do provedor e filtragem das publicações que deverão ser enviadas poderá ser tanto através de conta-de-usuário e senha como por um token ou chave fornecido pelo provedor de recortes.

4 Estes parâmetros também são geralmente enviados na URL, mas o ProJuris também suporta autenticação HTTP básica. O ProJuris também oferece suporte à paginação ou segmentação na chamada do WebService. A paginação pode ser útil para evitar time out quando o volume de dados for muito grande. O parâmetro de paginação é do tipo inteiro sequencial para o número da página ou segmento, iniciando em 0 ou 1. O volume de dados retornado em cada segmento fica a critério do provedor. O ProJuris então realizará diversas chamadas consecutivas ao WebService, incrementando o valor do parâmetro de paginação até receber um erro que indique que não existem mais publicações. Caso o Webservice não suporte paginação, será feita uma única chamada. Não há convenção para o nome dos parâmetros nem para o formato de data, sendo estes estipulados pelo provedor. Exemplo de chamada do WebService: enha=12345&datainicial= &pagina=0 O XML O WebService deverá retornar um XML com uma coleção de publicações. Os seguintes campos são esperados para cada publicação: Campo* Descrição Obrigatório NÚMERO DO É o número do processo relacionado com a publicação, que o Obrigatório PROCESSO ProJuris utilizará para fazer o vínculo. DATA Data da Publicação (formato definido pelo provedor). Obrigatório ID Identificador único da publicação no provedor (número inteiro Obrigatório longo), utilizado para prevenir que uma publicação seja importada em duplicidade, mesmo que obtida em filtros diferentes. O ID seria similar à chave primária da publicação no banco de dados do provedor. TEXTO O texto da publicação. Obrigatório OAB Número da OAB do advogado vinculado a publicação Desejável ADVOGADO Nome do advogado ORIGEM Origem da publicação (jornal, caderno, seção, página, etc.) LOCAL Orgão que originou a publicação * Não há convenção para a nomenclatura dos campos, podendo ser livremente estipulada pelo provedor. Tratamento de Erros ou Exceções Ocorrendo qualquer exceção, deverão também retornar em um XML específico de erro no lugar da coleção de publicações, de preferência com algum código que nos permita um tratamento programático. Os erros em geral serão apresentados na tela para o usuário. Importante esclarecer que todos os erros produzidos na camada de negócios do webserver do provedor de recortes, como validações de clientes, data, erros de acesso, ausência de dados deverão retornar como XML transmitido com status 200, reservando-se os demais status de

5 erro como 400, 500 apenas para erros ocorridos no âmbito da camada HTTP ou inferiores, como indisponibilidade da aplicação. Pelo menos os seguintes erros deverão ser implementados: Nenhum registro encontrado Usuário ou senha inválidos / Token inexistente (conforme a estratégia de autenticação) Aqui também há liberdade para que o provedor estabeleça as mensagens de erro da forma que lhe convir, desde que as duas situações acima sejam satisfeitas. Opcionalmente poderão ser implementados erros ou exceções para situações diversas de interesse do provedor como por exemplo para quando o usuário estiver bloqueado no sistema do provedor (exemplo: Sua conta foi está bloqueada, contate... que serão integralmente exibidos para o usuário em pop-ups como o exemplo abaixo: Exemplo: <erro codigo=2> O período de avaliação expirou. Entre em contato com nosso departamento comercial para renovação. </erro> Obs. 1: O XML deverá retornar um único erro. Obs 2: É desejável um código numérico para cada erro ou exceção, para facilitar o tratamento de erros. Troubleshooting O provedor deve estar ciente que sempre que um erro ou exceção ocorrer no WebService, o cliente sempre acionará o Help Desk do ProJuris, pois é neste sistema que o erro aparecerá. Portanto é necessário que nossos operadores tenham subsídios para orientar o cliente na solução do problema. Por este motivo, é necessário que as situações de erro ou exceções sejam bem documentadas e que um troubleshooting que ajude nossa equipe de Help Desk a orientar o precisamente cliente seja entregue na época da ativação da integração. O troubleshooting deverá conter uma relação de todos os erros possíveis, e a orientação a ser passada para o cliente. Se a solução para o problema somente puder ser dada pelo provedor,

6 então a solução passada deve incluir os dados de contato como telefone ou a ser passado para o cliente. A liberação da integração no ProJuris está vinculada ao recebimento do troubleshooting. Exemplo de um item do troubleshooting: Erro Explicação Ação Token inexistente O token preenchido pelo usuário é inválido, possivelmente devido a um erro de digitação Verificar se o token informado corresponde exatamente ao fornecido pelo provedor e repetir a operação Ícone 16x16 Opcionalmente o provedor de recortes poderá encaminhar um ícone 16x16 que será apresentado no ProJuris ao lado dos recortes importados, associando visualmente com a origem da publicação. Obs.: Caso o ícone não seja fornecido, o ProJuris utilizará uma letra com a inicial do provedor. Autorização O parceiro deverá formalizar sua autorização para reproduzir o nome do serviço de recortes e ícone no software ProJuris. Esta autorização deverá ser encaminhada através de um documento assinado e com firma reconhecida. A liberação da integração no ProJuris está vinculada ao recebimento da autorização. Contato Gabriel Cherem: gabriel.cherem@duotecnologia.com.br