ProJuris 8: Manual de Integração com
Provedores de Recortes
Versão 2.0
por Gabriel Cherem
agosto/2014
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:
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.
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:
http://www.provedor.com/webservices/obterRecortes?login=abc123&s
enha=12345&dataInicial=2014-08-14&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*
NÚMERO DO
PROCESSO
DATA
ID
TEXTO
OAB
ADVOGADO
ORIGEM
LOCAL
Descrição
É o número do processo relacionado com a publicação, que o
ProJuris utilizará para fazer o vínculo.
Data da Publicação (formato definido pelo provedor).
Identificador único da publicação no provedor (número inteiro
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.
O texto da publicação.
Número da OAB do advogado vinculado a publicação
Nome do advogado
Origem da publicação (jornal, caderno, seção, página, etc.)
Orgão que originou a publicação
Obrigatório
Obrigatório
Obrigatório
Obrigatório
Obrigatório
Desejável
* 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
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,
então a solução passada deve incluir os dados de contato como telefone ou email 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
Token inexistente
Explicação
O token preenchido pelo usuário
é inválido, possivelmente devido
a um erro de digitação
Açã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: [email protected]