Como funciona a integração do Vigilant com Google Sheets

TL;DR: Google Sheets + Google Apps Script + API do Vigilant = pesquisa processual automatizada direto na planilha, sem sair do Google Workspace. O advogado adiciona um CPF na planilha, clica em “Pesquisar” (ou agenda pra rodar toda semana), e os processos aparecem nas linhas abaixo. Zero infra, zero custo de ferramenta (Apps Script é grátis), custo da API = R$ 0,10 por consulta. Limite prático: ~50-100 CPFs por execução. Pra volumes maiores, escala pra Make/n8n.

Google Sheets é uma das ferramentas mais presentes em escritórios de advocacia brasileiros. Advogados e estagiários montam planilhas para controlar carteira de clientes, prazos, custas — e, quase sempre, resultados de pesquisa processual copiados à mão. Esta é uma das várias formas de automatizar a pesquisa processual no escritório.

O problema: essa pesquisa ainda é um processo manual. O advogado abre cada tribunal, digita o CPF, copia o resultado para a planilha. Como a planilha já existe e já é parte do fluxo do escritório, a pergunta natural é: por que não chamar a API do Vigilant de dentro da própria planilha?

Este artigo explica o conceito, quando faz sentido usar essa abordagem, e quais decisões você precisa tomar antes de começar. Para entender os endpoints, schemas e formatos de resposta que você vai consumir, a documentação oficial da API tem a referência técnica completa em curl, Python e JavaScript — você adapta para o ambiente que usar.

A ideia central

Google Sheets tem um motor de scripts embutido chamado Google Apps Script, que é JavaScript rodando na nuvem do Google, gratuito, com acesso direto às células da planilha. Apps Script pode fazer chamadas HTTP externas, ou seja: pode chamar a API do Vigilant como se fosse qualquer outro cliente.

Isso permite criar funções personalizadas que o advogado usa como qualquer fórmula nativa do Google Sheets:

=PESQUISAR_CPF(A2, "TJSP,TJMG")

Você digita essa fórmula na célula, o Apps Script chama a API do Vigilant, recebe o JSON com os processos e devolve um resumo na célula. O advogado vê o número de processos aparecer em tempo real, sem sair da planilha.

Arquitetura em alto nível

[ Planilha Google Sheets ]
       │
       │ (fórmula custom =PESQUISAR_CPF)
       ↓
[ Apps Script (JavaScript) ]
       │
       │ HTTPS
       ↓
[ API Vigilant ]
       │
       ↓
[ Tribunais brasileiros ]

Nada mais complexo que isso. A planilha dispara o script, o script chama a API, a API retorna o JSON, o script extrai o que interessa e escreve na célula.

Quando faz sentido usar essa abordagem

Esse padrão é ideal quando:

• Volume baixo a médio — até ~500 pesquisas por mês. Acima disso, a API direta ou um backend próprio ficam mais eficientes.
• Escritório sem equipe técnica — não exige um desenvolvedor. Um advogado com noções básicas copia o exemplo oficial da doc e adapta.
• Workflow já centrado em planilha — faz mais sentido integrar na ferramenta que o escritório já usa do que forçar uma mudança de processo.
• Pesquisas pontuais ou exploratórias — advogado preenche uma lista de CPFs prospectivos e rapidamente vê quem tem histórico processual.

Não faz sentido quando:

• Volume alto (milhares de pesquisas/mês) — Apps Script tem limite de execução de 30 segundos por função personalizada, e o Google impõe cotas diárias de fetch externo
• Fluxo precisa ser transacional — não dá para rodar em produção com SLA
• Dados sensíveis — a API key fica no código do Apps Script e pode vazar se a planilha for compartilhada incorretamente

Decisões que você precisa tomar antes

1. Onde guardar a API key

A forma mais segura é usar PropertiesService do Apps Script, que armazena a chave fora do código-fonte. Assim, mesmo se alguém visualizar o script, a chave não aparece. A documentação oficial da API explica o passo-a-passo.

2. Função síncrona ou assíncrona

O Vigilant retorna resultados em cache instantaneamente (status 200) ou inicia um job em background (status 202). Para planilhas, o jeito mais confortável é usar só o cache: se os dados estão frescos, retorna na hora; se não, retorna “processando” e você re-roda a fórmula depois. Isso evita timeouts dentro do Apps Script.

3. Uma célula = um CPF ou uma célula = um tribunal

Você pode estruturar a planilha de dois jeitos:

• Uma linha por CPF, com uma célula resumo por tribunal: =PESQUISAR_CPF(A2, "TJSP"), =PESQUISAR_CPF(A2, "TJMG"), etc.
• Uma linha por processo encontrado, usando uma função que retorna múltiplas linhas (Apps Script suporta arrays de retorno)

A primeira é mais simples; a segunda é melhor para análise detalhada. Escolha conforme o uso.

4. Quando re-pesquisar

Apps Script não re-executa fórmulas sozinho a menos que você mude alguma célula. Se você quer atualização automática (monitoramento), use um gatilho de tempo (trigger) que re-executa uma função toda segunda-feira às 7h, por exemplo. Aí a planilha vira um pequeno sistema de monitoramento — não uma consulta sob demanda.

Padrões de uso no escritório

Due diligence de novos clientes

Uma aba com lista de CPFs prospectivos. Coluna com fórmula =PESQUISAR_CPF(cpf, tribunais). Advogado cola os CPFs, aperta Enter, e em segundos vê quem tem histórico — ferramenta de triagem antes de aceitar o caso.

Monitoramento de carteira ativa

Lista de clientes ativos. Gatilho semanal que re-pesquisa todos e compara com o total anterior. Se algum cliente tem novos processos, envia e-mail ao advogado responsável (Apps Script tem acesso nativo ao Gmail).

Triagem de fornecedores

Lista de fornecedores + CPFs dos sócios. Re-pesquisa mensal. Alerta se o volume de processos cruzar um limite.

Limites práticos

• Timeout: funções personalizadas do Apps Script têm 30 segundos de timeout. Pesquisa em 10+ tribunais pode estourar esse limite. Quebre em chamadas menores.
• Cota diária: Google limita chamadas UrlFetchApp a 20.000/dia em contas gratuitas. Mais que suficiente para escritórios pequenos e médios.
• Compartilhamento: se você compartilhar a planilha editavelmente com outra pessoa, o Apps Script roda com as credenciais do proprietário. Pode ser problema para quem paga, não é para a chave.
• Dados retornados: o JSON do Vigilant é grande (parte, movimentações, assuntos). Extraia só o que interessa na fórmula — não cole o JSON inteiro em uma célula.

Quando migrar para algo mais robusto

Quando você sentir:

• Lentidão nas pesquisas (timeout frequente)
• Necessidade de agendamento preciso (não só “segunda-feira às 7h”, mas “todo dia às 3h”)
• Armazenamento histórico (comparar processos entre execuções, gerar relatórios)
• Integração com outras ferramentas (CRM, Slack, ERP do escritório)

A evolução natural é sair do Apps Script e usar uma ferramenta de automação visual (Make, n8n, Zapier) ou um backend próprio. Mas para 80% dos casos, planilha resolve.

Aspectos legais

Dados processuais públicos têm base legal de tratamento sob a LGPD (Art. 7º, §4º). Nenhum problema em processar resultados de consulta pública dentro de uma planilha corporativa do escritório, desde que a finalidade seja legítima (defesa do cliente, gestão de risco, compliance).

A API key é um dado sensível do seu próprio escritório (não do titular do CPF). Proteja a chave como senha — use PropertiesService, não deixe exposta em planilhas compartilhadas.

Referência técnica da API

A implementação concreta depende dos endpoints, schemas e respostas que a API expõe. A documentação oficial é o lugar onde isso vive mantido e atualizado:

• vigilant.trackjud.com.br/api/docs — Scalar UI interativa (PT/EN)

Você encontra lá: fluxo de autenticação (como obter uma API key), formato de cada endpoint, schemas de resposta (ProcessRecord, Consult, CourtSources), códigos de erro segundo RFC 7807, e exemplos de chamada em curl, Python e JavaScript. A partir desses exemplos base, você adapta para o ambiente que preferir — seja uma função de Apps Script, um workflow no Make, ou um backend próprio.

Conclusão

Integrar Vigilant a Google Sheets é um atalho realista para escritórios que já têm o workflow centralizado em planilha e querem eliminar a parte manual da pesquisa. A complexidade é baixa, o retorno é imediato, e o limite de escala (Apps Script) é suficiente para a maioria dos escritórios pequenos e médios.

Se você está nesse perfil, começe pelo caso de uso mais doloroso (normalmente triagem de novos clientes ou monitoramento de carteira), monte uma planilha pequena de prova, valide, e expanda.

5 créditos grátis no cadastro. Sem cartão de crédito. Criar conta no Vigilant.