API do gfjuris
Para quem desenvolve a integração de um sistema do escritório (planilha, ERP, robô de relatório) com o gfjuris.
As chaves de API ainda estão desligadas nesta instalação. O que está descrito aqui passa a valer quando forem ligadas.
1. O que a API faz
É a mesma base do painel, em JSON sobre HTTPS, com as mesmas regras: cada escritório só enxerga o próprio dado, o processo restrito continua restrito e o prazo é calculado pelo motor, nunca informado.
- Processos: lista, ficha com partes e andamentos, cadastro pelo número CNJ e consulta à fonte (/processos).
- Prazos: a fila por data interna, o cálculo sem gravar e o ciclo de baixa: cumprir, conferir, devolver (/prazos).
- Publicações: as intimações capturadas no DJEN, com ciência, descarte e prazo aberto a partir delas (/publicacoes).
- Clientes: cadastro e busca por nome ou documento (/clientes).
- Também: equipe (só leitura pela chave), jurisprudência do acervo, diários municipais, análises de documentos, pesquisas e o consumo de IA.
- Webhooks: o aviso que o gfjuris manda ao sistema do escritório a cada publicação nova, prazo aberto, baixa, conferência e andamento novo (seção 11).
Datas vêm como AAAA-MM-DD; instantes, em ISO 8601 com fuso (UTC). Valores em dinheiro, em centavos (valor_causa).
2. Como criar a chave
- Entre no painel e abra o menu da sua conta, no alto: Chaves de API.
- Dê um nome (o sistema que vai usá-la), escolha o escopo e a validade: 30 dias, 90 dias, 1 ano ou sem validade.
- Confirme com a sua senha e, se você usa, o código do segundo fator.
- Copie a chave na hora: ela aparece uma vez só. O gfjuris guarda só um resumo que não a reconstrói.
A chave é de uma pessoa e age como ela: o mesmo papel, os mesmos processos visíveis, o mesmo plano do escritório. Tudo o que a chave faz fica registrado em nome dessa pessoa. Até 10 chaves ativas por pessoa; estagiário(a) não cria chave.
3. Autenticação
Toda requisição leva a chave no cabeçalho Authorization, no esquema Bearer. A chave tem o formato gfj_<escritório>_<segredo>.
export GFJURIS_CHAVE='gfj_…' # do cofre ou de uma variável de ambiente, nunca no código
curl -s https://www.gfjuris.com.br/auth/eu \
-H "Authorization: Bearer $GFJURIS_CHAVE"
A resposta diz de quem é a chave:
{"id": 7, "email": "pessoa@escritorio.com.br", "nome": "Nome da Pessoa",
"oab": "123456/SP", "papel": "advogado", "ativo": true}
A API aceita também o token de POST /auth/login (e-mail, senha e, com segundo fator, o campo codigo), que vence em 12 horas. Para integração, use a chave. Nenhuma tela do painel aceita a chave, e chave não cria chave.
4. Escopos
| Escopo | O que deixa fazer |
|---|---|
| leitura | Só GET, HEAD e OPTIONS. Qualquer outro método responde 403. |
| escrita | Tudo o que a pessoa dona faz pela API, menos administrar contas e equipe: POST em /auth/… e em /usuarios responde 403 para qualquer chave. |
O escopo segue o método, não a rota: POST /prazos/calcular não grava nada, mas pede chave de escrita. Prefira a chave de leitura sempre que bastar.
5. Limites
- 120 requisições por minuto por chave. Passou, a resposta é 429 com o cabeçalho Retry-After em segundos. A conta é feita em cada servidor da aplicação: com mais de um no ar, o teto efetivo pode ser maior. Não conte com isso; respeite o Retry-After.
- Chave que o servidor não reconhece, por endereço IP: depois de 30 em 15 minutos, a chave desconhecida ou fora do formato vinda daquele IP leva 429, com Retry-After, até a mais antiga sair da janela. A chave boa do mesmo IP continua passando. Chave revogada ou vencida não conta: responde 401 com o motivo, para a integração saber o que corrigir.
- Listas têm teto por página (abaixo, em Paginação).
6. Formato de erro
Todo erro vem em JSON, com a mensagem em detail:
{"detail": "Esta chave é só de leitura (GET, HEAD e OPTIONS). Para gravar, crie no painel uma chave de escrita."}
A 422 tem duas formas. Na validação do corpo ou dos parâmetros, detail é uma lista, um item por campo:
{"detail": [{"type": "value_error", "loc": ["body", "numero_cnj"],
"msg": "Value error, …", "input": "…"}]}
Na regra da própria API, detail é um texto. Por exemplo, POST /prazos/calcular sem tipo nem dias_uteis:
{"detail": "Informe `dias_uteis` ou `tipo` para calcular o prazo."}
Trate detail como texto ou como lista, conforme vier.
| Código | Quando |
|---|---|
| 401 | Sem chave, chave inválida, revogada ou vencida, pessoa dona desligada, ou senha da pessoa trocada depois de a chave ser criada. |
| 402 | O escritório está só em leitura (teste vencido ou acesso suspenso): consultar continua valendo, gravar não. |
| 403 | Chave de leitura num método que grava; chave em administração de contas; ação que exige administrador. |
| 404 | O item não existe ou não é visível para a pessoa dona da chave. |
| 409 | Conflito: processo já cadastrado, publicação que já saiu da fila. |
| 422 | Corpo ou parâmetro inválido. |
| 429 | Limite da chave ou do IP. Espere o Retry-After. |
| 502, 503 | Uma fonte externa (DataJud, IA) não respondeu ou está desligada. Tente de novo mais tarde. |
7. Paginação
- /processos e /clientes: limite (1 a 200, padrão 50) e offset. Processos vêm do cadastro mais novo para o mais antigo; clientes, por nome.
- /prazos: limite (1 a 500, padrão 100) e offset, em ordem de data interna.
- /publicacoes: limite (1 a 500, padrão 100) e offset, da disponibilização mais recente para a mais antiga; recorte também com desde e ate.
Em todas, o empate na ordem (mesma data, mesmo nome) é desfeito pelo id, e a página seguinte não repete nem pula item. Não há total no cabeçalho: some o limite ao offset e peça a página seguinte até vir menos itens que o limite. Item criado ou apagado no meio da leitura desloca as páginas; para uma cópia exata, leia de novo do começo.
8. Exemplos
Processos
# Os processos monitorados, 50 por vez
curl -s "https://www.gfjuris.com.br/processos?monitorado=true&limite=50&offset=0" \
-H "Authorization: Bearer $GFJURIS_CHAVE"
# Um processo, com partes e andamentos (a leitura fica registrada como acesso)
curl -s https://www.gfjuris.com.br/processos/42 \
-H "Authorization: Bearer $GFJURIS_CHAVE"
# Cadastrar pelo número CNJ (chave de escrita); a pessoa dona vira a responsável
curl -s -X POST https://www.gfjuris.com.br/processos \
-H "Authorization: Bearer $GFJURIS_CHAVE" \
-H "Content-Type: application/json" \
-d '{"numero_cnj": "NNNNNNN-DD.AAAA.J.TR.OOOO", "tribunal": "TJSP",
"area": "civel", "monitorado": true}'
Áreas: civel, trabalhista, tributario, penal, administrativo, ambiental, consumidor, societario. Número já cadastrado responde 409.
Prazos
# A fila (pendentes e aguardando conferência), pela data interna: a segunda página
curl -s "https://www.gfjuris.com.br/prazos?apenas_pendentes=true&limite=100&offset=100" \
-H "Authorization: Bearer $GFJURIS_CHAVE"
# Os de um processo, num estado: pendente, aguardando_conferencia, concluido ou perdido
curl -s "https://www.gfjuris.com.br/prazos?processo_id=42&estado=concluido" \
-H "Authorization: Bearer $GFJURIS_CHAVE"
# Calcular sem gravar: dias_pulados diz por que cada dia não contou (chave de escrita)
curl -s -X POST https://www.gfjuris.com.br/prazos/calcular \
-H "Authorization: Bearer $GFJURIS_CHAVE" \
-H "Content-Type: application/json" \
-d '{"data_intimacao": "2026-11-10", "origem": "publicacao_dje",
"tipo": "contestacao", "uf": "SP"}'
Publicações
# A fila (as novas), desde uma data
curl -s "https://www.gfjuris.com.br/publicacoes?desde=2026-11-01&limite=100" \
-H "Authorization: Bearer $GFJURIS_CHAVE"
# Todas, ou só as tratadas: todas=true, estado=tratada ou estado=descartada
curl -s "https://www.gfjuris.com.br/publicacoes?todas=true&processo_id=42" \
-H "Authorization: Bearer $GFJURIS_CHAVE"
# Dar ciência, sem prazo (chave de escrita)
curl -s -X POST https://www.gfjuris.com.br/publicacoes/123/tratar \
-H "Authorization: Bearer $GFJURIS_CHAVE"
Clientes
# Busca por trecho do nome ou do documento
curl -s "https://www.gfjuris.com.br/clientes?busca=Silva&limite=50" \
-H "Authorization: Bearer $GFJURIS_CHAVE"
# Cadastrar (chave de escrita); o tipo de pessoa sai do documento
curl -s -X POST https://www.gfjuris.com.br/clientes \
-H "Authorization: Bearer $GFJURIS_CHAVE" \
-H "Content-Type: application/json" \
-d '{"nome": "Nome do Cliente", "documento": "<CPF ou CNPJ>",
"email": "cliente@exemplo.com.br"}'
9. O esquema completo
Todas as rotas, com os campos de entrada e de saída, estão em /openapi.json (OpenAPI 3.1) e na página interativa /docs. A página interativa carrega o Swagger de um CDN externo: não cole a chave de API nela. Para experimentar ali, use o token de 12 horas de POST /auth/login no botão Authorize; as chamadas são de verdade.
10. Cuidado com a chave
- Guarde a chave como uma senha: cofre ou variável de ambiente do servidor que a usa. Nunca no código-fonte, em planilha compartilhada, em e-mail ou no navegador de outra pessoa.
- Uma chave por sistema, com o menor escopo e a menor validade que servirem. O nome ajuda a saber qual revogar.
- Vazou? Revogue no painel, na hora, e só depois crie a nova. Revogar vale também com o escritório só em leitura. O último uso de cada chave aparece na lista, com o IP de onde veio, e conta toda chamada que a chave abriu, inclusive a que terminou em erro.
- Criar e revogar uma chave manda um e-mail à pessoa dona, com o nome, o prefixo, o escopo, a validade, quando e quem fez. O e-mail nunca leva a chave.
- A chave para sozinha quando é revogada, quando vence, quando a pessoa é desligada da equipe e quando a senha dela é trocada.
11. Webhooks
Os webhooks ainda estão desligados nesta instalação. O que está descrito aqui passa a valer quando forem ligados.
Em vez de perguntar à API de tempos em tempos, o sistema do escritório recebe um aviso a cada fato. Quem cadastra é um administrador do escritório, no painel (menu da conta, Chaves de API, seção Webhooks): o endereço https:// que recebe, os eventos e se começa ativo. O segredo de assinatura (whsec_…) aparece uma vez, na criação e a cada troca; guarde-o como uma senha.
| Evento | Quando sai | Item |
|---|---|---|
| publicacao.nova | Publicação nova capturada no DJEN | publicacao |
| prazo.aberto | Prazo aberto | prazo |
| prazo.concluido | Baixa do prazo (cumprido) | prazo |
| prazo.conferido | Protocolo do prazo conferido | prazo |
| processo.andamento | Andamento novo da fonte (DataJud ou eproc) | processo |
Cada aviso é um POST com corpo JSON e estes cabeçalhos:
POST /avisos-gfjuris HTTP/1.1
Host: sistema.exemplo.com.br
Content-Type: application/json
User-Agent: gfjuris-webhooks/1
X-Gfjuris-Evento: prazo.aberto
X-Gfjuris-Entrega: 0b8f1c2e-5a7d-4c1e-9f3b-6d2a8e4c7b91
X-Gfjuris-Assinatura: t=1794489900,v1=<64 dígitos hexadecimais>
{"id":"0b8f1c2e-5a7d-4c1e-9f3b-6d2a8e4c7b91","evento":"prazo.aberto",
"criado_em":"2026-11-12T13:25:00+00:00","escritorio":12,
"recurso":{"tipo":"prazo","id":123,"url":"/prazos/123"}}
O corpo é magro de propósito: nada de cliente, parte, número de processo ou texto. O id é o da entrega; recurso.url é o caminho na API, onde o sistema busca o item com a chave dele — é ali que valem o papel da pessoa dona da chave, o processo restrito e o plano do escritório. Aviso de processo restrito não sai.
# O item do aviso, pela API (prazo, publicação ou processo)
curl -s https://www.gfjuris.com.br/prazos/123 \
-H "Authorization: Bearer $GFJURIS_CHAVE"
Conferir a assinatura
X-Gfjuris-Assinatura traz t, o momento do envio em segundos Unix, e v1, o HMAC-SHA256 em hexadecimal do segredo inteiro (com o whsec_) sobre o texto <t>.<corpo>: o número do t, um ponto e o corpo exatamente como chegou, em bytes, antes de qualquer leitura de JSON. Compare em tempo constante e recuse o aviso com t a mais de 5 minutos do seu relógio: é o que impede alguém de repetir um aviso antigo. O cabeçalho pode trazer mais de um v1=; vale se algum conferir.
import hashlib
import hmac
import time
def assinatura_confere(segredo, corpo, cabecalho, agora=None):
"""segredo: o whsec_... do painel; corpo: os bytes do POST, como chegaram;
cabecalho: o valor de X-Gfjuris-Assinatura."""
partes = [item.split("=", 1) for item in cabecalho.split(",") if "=" in item]
momentos = [valor.strip() for nome, valor in partes if nome.strip() == "t"]
assinaturas = [valor.strip() for nome, valor in partes if nome.strip() == "v1"]
if len(momentos) != 1 or not momentos[0].isdecimal() or not assinaturas:
return False
if len(momentos[0]) > 12: # um t forjado com centenas de dígitos não chega ao int()
return False
momento = int(momentos[0])
if abs((time.time() if agora is None else agora) - momento) > 5 * 60:
return False
mensagem = str(momento).encode() + b"." + corpo
esperada = hmac.new(segredo.encode(), mensagem, hashlib.sha256).hexdigest().encode()
return any(hmac.compare_digest(esperada, assinatura.encode()) for assinatura in assinaturas)
Resposta e novas tentativas
- Responda 2xx logo, antes de processar (ponha o aviso numa fila sua): o limite é de 10 segundos, e resposta acima de 5 segundos já é lentidão. O aviso lento vale como entregue, mas o gfjuris não manda mais nenhum a esse endereço naquela passada: o resto da fila dele anda devagar, um por passada. Outro código, redirecionamento (não é seguido) ou falta de resposta é falha. Só o código importa; o corpo da resposta não é lido além de 1 KB nem guardado.
- Cada aviso é tentado até 6 vezes: na primeira passada (a cada minuto) e depois de 1 min, 5 min, 30 min, 2 h e 12 h. A passada tem um orçamento de tempo, para um endereço lento não atrasar os outros: o que não coube nele sai na passada seguinte, sem gastar tentativa.
- 410 desativa o webhook na hora; 20 falhas seguidas, de qualquer aviso, também. Os administradores do escritório recebem um e-mail, e os avisos da fila esperam o webhook ser ativado de novo.
- A entrega é pelo menos uma vez, e a ordem não é garantida: o mesmo aviso pode chegar de novo (um administrador pode reenviar), com o mesmo id. Descarte o repetido pelo id e leia o estado atual do item pela API.
- O endereço tem de ser público: o gfjuris resolve o nome a cada envio e não manda nada para endereço de rede interna, nem segue redirecionamento.
12. O que ainda não existe
Autorização OAuth para aplicativo de terceiros, chave do escritório sem pessoa dona e assinatura do webhook por chave pública. Até lá, a integração usa a chave de uma pessoa da equipe, e o webhook diz quando vale consultar.
Dúvidas: contato@gfjuris.com.br.