Como atualizar um processo pela API v2?

Ao solicitar um processo na API v2, pela rota /api/v2/processos/numero_cnj/<numero> pode ser que o processo esteja desatualizado. Ou seja, pode ser que a versão presente no Escavador seja mais antiga, em relação a versão que está no tribunal. É possível constatar essa informação através do campo data_ultima_verificacao.

Esse campo nos diz quando foi a última vez que os robôs do escavador foram aos sistemas dos tribunais em que aquele processo está, e atualizou a nossa base. Caso essa data seja antiga, o cliente pode solicitar a atualização do processo. Para isso, você pode usar a rota /api/v2/processos/numero_cnj/<numero>/solicitar-atualizacao.

Essa solicitação de atualização manda os nossos robôs se conectarem aos sistemas dos tribunais daquele processo, trazendo as atualizações do mesmo para a nossa base. Além disso, pode ser que essa busca demore, já que depende da conexão com o tribunal, além de outros fatores como autenticação, CAPTCHA, etc. e portanto esse rota é assíncrona - isto é - não tem uma resposta imediata, no momento da requisição.

Como saber se a atualização terminou?

É possível configurar o parâmetro send_callback=1 ao fazer a solicitação. Dessa forma, quando o fluxo de atualização terminar, nós enviaremos um callback de notificação para o servidor do cliente. O servidor é aquele que foi cadastrado no painel da API, para receber os callbacks de monitoramento.

Também é possível consultar o status atual da atualização, através da rota /api/v2/processos/numero_cnj/<numero>/status-atualizacao. Os possíveis retornos para o status da atualização são:

PENDENTE - Os nossos robôs ainda estão capturando o processo no sistema do tribunal
SUCESSO - O processo foi retornado e atualizado e já se encontra disponível na rota principal de processos.
ERRO - Não foi possível capturar o processo, por algum motivo. Pode ser indisponibilidade do sistema do tribunal, má conexão, mudança de autenticação, etc.

Abaixo, seguem exemplos dessas consultas ao status e as mensagens, na prática:

Quando se consulta o status, sem ter solicitado uma atualização ainda, a mensagem mostrada é a última vez que o processo foi atualizado.

Quando se consulta o status, depois que foi solicitado uma atualização, alguns dados sobre a solicitação são mostrados, além da mensagem "PENDENTE".

Por último, a mensagem de conclusão e dados de intervalo de tempo sobre a atualização.

Funcionalidade extra: incluir um processo na base do Escavador.

A rota de atualização também serve para incluir um processo na nossa base. Ao solicitar um processo na rota principal de processos, pode ser que a resposta seja do tipo 404, e nesse caso a mensagem vai ser "Recurso não encontrado". Isso pode acontecer e não é um erro. Só indica que aquele processo não está na nossa base ainda.

Para incluir o processo, você pode solicitar a mesma rota de atualização, passando o número do processo. O fluxo vai ser o mesmo. Nós vamos buscar o processo no sistema do tribunal, e o status vai ser mostrado na rota de status, ao ser consultado. O cliente também vai receber um callback de status, caso passe o parâmetro send_callback=1.

Em resumo, a solicitação é a mesma e o fluxo de execução é o mesmo. O que muda é o parâmetro a ser passado que é o número CNJ do processo a ser incluído.

Resolvendo eventuais problemas de inconsistência do processo em relação ao sistema do tribunal.

Essa rota de atualização também é útil quando se percebe algum problema nos dados do processo, no retorno da API. Caso seja notado alguma movimentação faltando ou algum dado inconsistente, é interessante solicitar a rota de atualização para que os nossos robôs capturem qualquer atualização no sistema do tribunal (inclusive, a retirada de alguma movimentação ou dado, que também pode acontecer).

Exemplo: Documentos do processo não estão na resposta da rota de documentos, mas estão no tribunal

Nesse caso, pode ser que a atualização do processo, recupere os documentos no sistema do tribunal.
Sobre a rota de documentos públicos, como acessar os documentos e eventuais dúvidas, você pode ver melhor aqui: https://api.escavador.com/v2/docs/#documentos-pblicos-de-um-processo.