Gerenciamento de Credenciais#

Introdução#

Processos em segredo de justiça possuem acesso restrito nos sistemas dos tribunais, exigindo que o advogado ou parte interessada realize autenticação para visualizar as movimentações vinculadas a eles. O método de autenticação varia conforme o tribunal: alguns exigem apenas usuário e senha, outros requerem autenticação em dois fatores (2FA) e outros ainda exigem um certificado digital A1.

Para que a API realize a consulta automática nesses processos, é necessário fornecer as credenciais de acesso ao tribunal correspondente. O tipo de credencial exigido — DEFAULT, 2FA, CERT ou CERT_2FA — depende do sistema e está indicado na tabela de sistemas suportados.

As credenciais são armazenadas de forma segura por meio de criptografia híbrida RSA-4096-OAEP + AES-256-GCM e nunca são transmitidas em texto claro.

Nota

O cadastro de credenciais requer a permissão proc.segredo_justica.criar. Entre em contato com o suporte em suportesolucoes@jusbrasil.com.br para habilitá-la em sua conta.

Tipos de credencial#

O campo tipo determina quais dados compõem o segredo a ser criptografado:

Tipo	Campos obrigatórios no segredo	Quando usar
`DEFAULT`	`usuario`, `senha`	Tribunais que aceitam apenas usuário e senha.
`2FA`	`usuario`, `senha`, `segredo_otp`	Tribunais com autenticação em dois fatores via aplicativo autenticador.
`CERT`	`certificado_arquivo`, `certificado_senha`	Tribunais que exigem certificado digital A1 sem 2FA.
`CERT_2FA`	`certificado_arquivo`, `certificado_senha`, `segredo_otp`	Tribunais que exigem certificado digital A1 com autenticador 2FA.

Sistemas suportados#

A lista de sistemas suportados é expandida continuamente. Consulte o suporte para verificar a cobertura mais recente ou confirmar o tipo de credencial exigido por um sistema específico.

`sistema_id`	Sistema	Tipo de credencial	Observação
51	Sistema PDPJ (Domicílio Judicial Eletrônico)	`CERT_2FA`	Certificado A1 + autenticador 2FA

Nota

Sistemas do PJe e outros tribunais com autenticação por usuário/senha (DEFAULT ou 2FA) serão adicionados progressivamente. O tipo de credencial correto para cada sistema é informado no momento da habilitação do acesso.

Fluxo de integração#

Obtenha a chave pública via GET /credenciais/public_key.
Criptografe o segredo localmente usando a chave pública obtida.
Cadastre a credencial via POST /credenciais com o segredo criptografado.
Aguarde a validação: a API realiza o login no tribunal de forma automática em até 90 minutos. O status da credencial muda de CONECTANDO para CONECTADO (ou FALHOU em caso de erro).
Consulte o status a qualquer momento via GET /credenciais/{id}.

Importante

A conclusão da validação de login só é notificada via webhook. Sem o webhook de segredo de justiça configurado (veja Configuração do webhook de segredo), você não recebe nenhum aviso de que o status mudou de CONECTANDO para CONECTADO/FALHOU — é necessário fazer polling manual em GET /credenciais/{id} até lá. Configure o webhook antes de cadastrar a credencial para não perder essa notificação.

Criptografia do segredo#

O campo segredo de todas as requisições deve conter o payload criptografado com o esquema descrito abaixo. A criptografia é sempre realizada pelo cliente antes de enviar os dados à API.

Esquema: criptografia híbrida RSA-4096-OAEP + AES-256-GCM

Gere uma chave de dados (DEK) aleatória de 32 bytes.
Gere um nonce aleatório de 12 bytes.
Cifre o payload JSON com AES-256-GCM. O campo AAD (Additional Authenticated Data) deve ser a representação em string do user_company_id da sua empresa, codificada em UTF-8.
Cifre a DEK com RSA-4096-OAEP (SHA-256) usando a chave pública obtida em GET /credenciais/public_key.
Concatene: [DEK cifrada (512 bytes)] + [nonce (12 bytes)] + [ciphertext AES-GCM].
Codifique o resultado em Base64 — esse é o valor do campo segredo.

Estrutura do payload JSON por tipo de credencial:

DEFAULT

{
  "usuario": "<usuário de acesso ao tribunal>",
  "senha": "<senha de acesso ao tribunal>"
}

2FA

{
  "usuario": "<usuário de acesso ao tribunal>",
  "senha": "<senha de acesso ao tribunal>",
  "segredo_otp": "<chave secreta OTP do autenticador>"
}

CERT

{
  "certificado_arquivo": "<arquivo PFX codificado em Base64>",
  "certificado_senha": "<senha do certificado PFX>"
}

CERT_2FA

{
  "certificado_arquivo": "<arquivo PFX codificado em Base64>",
  "certificado_senha": "<senha do certificado PFX>",
  "segredo_otp": "<chave secreta OTP do autenticador>"
}

Nota

O campo segredo_otp é a chave secreta de 32 caracteres do autenticador — não o código de 6 dígitos gerado a cada 30 segundos. Essa chave só existe após o usuário ter configurado o 2FA no sistema do tribunal e vinculado a conta a um aplicativo autenticador (como Google Authenticator, Authy ou FreeOTP). Para obtê-la, acesse a página de configuração do 2FA no tribunal e clique em “Não consigo ler o QR Code” (ou equivalente). O tribunal exibirá a chave em texto, no formato AAAA BBBB CCCC .... Remova os espaços e utilize a sequência resultante como valor de segredo_otp.

Exemplo de implementação em Python (para CERT_2FA):

import base64
import json
import os
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

def encrypt_secret(plaintext: bytes, user_company_id: int, public_key_pem: str) -> str:
    public_key = serialization.load_pem_public_key(public_key_pem.encode())
    dek = os.urandom(32)
    nonce = os.urandom(12)
    aad = str(user_company_id).encode()

    aes_ciphertext = AESGCM(dek).encrypt(nonce, plaintext, aad)
    dek_ciphertext = public_key.encrypt(
        dek,
        padding.OAEP(
            mgf=padding.MGF1(algorithm=hashes.SHA256()),
            algorithm=hashes.SHA256(),
            label=None,
        ),
    )
    return base64.b64encode(dek_ciphertext + nonce + aes_ciphertext).decode()

# Exemplo para CERT_2FA:
secret = {
    "certificado_arquivo": base64.b64encode(open("certificado.pfx", "rb").read()).decode(),
    "certificado_senha": "senha_do_pfx",
    "segredo_otp": "CHAVE_SECRETA_OTP",
}
segredo = encrypt_secret(
    plaintext=json.dumps(secret).encode(),
    user_company_id=123,           # seu user_company_id
    public_key_pem=chave_publica,  # obtida via GET /credenciais/public_key
)

Como converter o arquivo PFX para Base64:

Em terminal Linux ou macOS:

base64 certificado.pfx > certificado_base64.txt

No Windows (PowerShell):

[Convert]::ToBase64String([IO.File]::ReadAllBytes("C:\caminho\certificado.pfx")) `
  | Out-File -Encoding ASCII certificado_base64.txt

Obter chave pública#

Retorna a chave pública RSA em formato PEM, necessária para criptografar o segredo antes de enviar à API.

curl -X GET \
    "https://op.digesto.com.br/api/credenciais/public_key" \
    -H "Authorization: Bearer <token>"

Resposta

HTTP/1.1 200 OK
Content-Type: text/plain

-----BEGIN PUBLIC KEY-----
MIICIjANBgkqhkiG9w0BAQEFAAOCAg8AMIICCgKCAgEA...
-----END PUBLIC KEY-----

Cadastrar credencial#

Registra uma nova credencial para um sistema judicial. Após o cadastro, a API realiza o login de forma assíncrona: o status inicial é CONECTANDO e muda para CONECTADO ou FALHOU após a tentativa de autenticação no tribunal.

curl -X POST \
    "https://op.digesto.com.br/api/credenciais" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{
          "sistema_id": 51,
          "tipo": "CERT_2FA",
          "segredo": "<blob criptografado em Base64>",
          "instancia": "Todas",
          "tipo_acesso": "default"
        }'

Parâmetros de requisição

Parâmetro	Tipo	Descrição
sistema_id	integer	Obrigatório. ID do sistema judicial. Ver tabela de sistemas suportados.
tipo	string	Obrigatório. Tipo de credencial. Para segredo de justiça: `CERT_2FA`.
segredo	string	Obrigatório. Payload criptografado em Base64. Ver seção Criptografia do segredo.
instancia	integer ou string	Instância do tribunal. Use `"Todas"` para todas as instâncias disponíveis. Default: `"Todas"`.
tipo_acesso	string	Tipo de acesso da credencial no sistema do tribunal. Default: `"default"`.

Resposta

HTTP/1.1 201 Created
Content-Type: application/json

{
  "id": 42,
  "sistema_id": 51,
  "status": "CONECTANDO",
  "instancia": "Todas",
  "criado_em": "2026-06-30T14:00:00Z",
  "criado_por": "João Silva"
}

Campos da resposta

Campo	Tipo	Descrição
id	integer	Identificador único da credencial. Use-o nos demais endpoints.
sistema_id	integer	ID do sistema judicial vinculado.
status	string	Status atual da credencial. Ver tabela de status abaixo.
instancia	integer ou string	Instância configurada (`"Todas"` quando não especificada).
criado_em	string	Data e hora de criação (ISO 8601).
criado_por	string	Nome do usuário que cadastrou a credencial.

Status possíveis

Status	Descrição
`CONECTANDO`	Credencial recém-cadastrada. O login no tribunal ainda não foi realizado.
`CONECTADO`	Login realizado com sucesso. A coleta de processos em segredo está ativa.
`FALHOU`	A tentativa de login falhou. Verifique as credenciais e tente novamente via `PATCH`.

Listar credenciais#

Retorna a lista paginada de credenciais cadastradas para a empresa.

curl -X GET \
    "https://op.digesto.com.br/api/credenciais?page=1&per_page=10" \
    -H "Authorization: Bearer <token>"

Parâmetros de query

Parâmetro	Tipo	Descrição
page	integer	Página da listagem. Default: `1`.
per_page	integer	Itens por página. Mínimo: `5`, máximo: `100`. Default: `10`.

Resposta (200 OK com itens) ou 204 No Content (sem credenciais cadastradas).

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": 42,
    "sistema_id": 51,
    "sistema": "PDPJ",
    "status": "CONECTADO",
    "customer_id": "bd666d17-3eda-459a-92b0-683dc162a391",
    "user_company_id": "123",
    "tipo_acesso": "default",
    "instancia": "Todas",
    "criado_em": "2026-06-30T14:00:00Z",
    "criado_por": "João Silva",
    "atualizado_em": "",
    "atualizado_por": "",
    "arquivado_em": "",
    "arquivado_por": ""
  }
]

Obter credencial por ID#

Retorna os detalhes de uma credencial específica. Os campos do segredo são incluídos na resposta: retornam "******" quando utilizados pelo tipo da credencial, ou "" quando não se aplicam.

curl -X GET \
    "https://op.digesto.com.br/api/credenciais/42" \
    -H "Authorization: Bearer <token>"

Resposta (exemplo para tipo CERT_2FA)

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "sistema_id": 51,
  "sistema": "PDPJ",
  "status": "CONECTADO",
  "customer_id": "bd666d17-3eda-459a-92b0-683dc162a391",
  "user_company_id": "123",
  "tipo_acesso": "default",
  "instancia": "Todas",
  "criado_em": "2026-06-30T14:00:00Z",
  "criado_por": "João Silva",
  "atualizado_em": "",
  "atualizado_por": "",
  "arquivado_em": "",
  "arquivado_por": "",
  "usuario": "",
  "senha": "",
  "certificado_arquivo": "******",
  "certificado_senha": "******",
  "segredo_otp": "******"
}

Atualizar credencial#

Atualiza o segredo ou as configurações de uma credencial existente. Todos os campos são opcionais: envie apenas os que deseja alterar. Após a atualização do segredo, a API realiza um novo login no tribunal de forma automática.

curl -X PATCH \
    "https://op.digesto.com.br/api/credenciais/42" \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer <token>" \
    -d '{
          "segredo": "<novo blob criptografado em Base64>"
        }'

Parâmetros de requisição

Parâmetro	Tipo	Descrição
segredo	string, null	Novo payload criptografado em Base64. Ver seção Criptografia do segredo.
tipo	string, null	Novo tipo de credencial (caso o sistema permita alteração).
instancia	integer ou string, null	Nova instância do tribunal.
tipo_acesso	string, null	Novo tipo de acesso.

Resposta

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "status": "CONECTANDO",
  "atualizado_em": "2026-06-30T16:00:00Z",
  "atualizado_por": "João Silva"
}

Desabilitar credencial#

Desabilita permanentemente uma credencial. A credencial é arquivada e a coleta de processos em segredo vinculados a ela é encerrada.

Aviso

Esta operação não pode ser desfeita. Para reativar o acesso ao tribunal, será necessário cadastrar uma nova credencial via POST /credenciais.

curl -X DELETE \
    "https://op.digesto.com.br/api/credenciais/42" \
    -H "Authorization: Bearer <token>"

Resposta

HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": 42,
  "sistema_id": 51,
  "sistema": "PDPJ",
  "desabilitado_por": "João Silva",
  "desabilitado_em": "2026-06-30T17:00:00Z"
}

Respostas de erro#

Todos os erros retornam no seguinte formato (exceto o 422, que usa o padrão nativo do FastAPI):

{ "message": "<descrição do erro>", "status": <código HTTP> }

O código 422 é exclusivo para parâmetros de path inválidos (ex.: credencial_id não numérico) e retorna { "detail": [...] }.

POST /credenciais#

HTTP	Mensagem / Causa
201	Sucesso. Retorna `{ id, sistema_id, status: "CONECTANDO", instancia, criado_em, criado_por }`.
400	`Tipo credencial "{tipo}" não compatível. Tipos permitidos: DEFAULT, 2FA, CERT, CERT_2FA` — valor inválido no campo `tipo`.
400	`Instância "{valor}" inválida. Passe um número inteiro ou "Todas".` — campo `instancia` é uma string não numérica.
400	`Não foi possível descriptografar o segredo. Verifique se o campo foi corretamente cifrado com a chave pública obtida em GET /credenciais/public_key.` — segredo mal formado ou cifrado com chave incorreta.
400	`Os campos {campos} são obrigatórios para o tipo de autenticação {tipo}.` — o JSON dentro do segredo não contém exatamente os campos exigidos pelo tipo (ex.: faltou `segredo_otp` para `CERT_2FA`).
400	`Certificado inválido: senha incorreta ou arquivo PFX corrompido.` — o arquivo PFX é ilegível ou a senha está errada.
400	`Sistema de ID {id} não possui cobertura.` — `sistema_id` não existe ou não está mapeado para segredo de justiça.
400	`Coleta de processos em segredo de justiça ainda não implementada para o sistema (ID={id}).` — sistema existe, mas ainda não suporta consulta em segredo de justiça.
400	`Instância "{valor}" não compatível. Valores permitidos para o sistema: {valores}.` — instância não disponível para o sistema informado.
400	`Tipo acesso "{valor}" não compatível. Valores permitidos para o sistema: {valores}.` — tipo de acesso não disponível para o sistema informado.
400	`O sistema de ID {id} não aceita tipo de credencial "{tipo}".` — tipo incompatível com o sistema (ex.: sistema não aceita certificado).
401	`Necessário autenticação. Veja documentação em https://api.jusbrasil.com.br/docs/autenticacao/index.html` — token ausente ou inválido.
403	`Permissão 'proc.segredo_justica.criar' não habilitada para esse usuário, entre em contato com suportesolucoes@jusbrasil.com.br.`
500	`Erro interno ao processar a requisição` — exceção inesperada ao comunicar com nossos serviços.
503	`Serviço temporariamente indisponível` — falha de conexão com nossos serviços.

GET /credenciais#

HTTP	Mensagem / Causa
200	Sucesso. Retorna lista de credenciais.
204	Nenhuma credencial cadastrada (sem corpo na resposta).
401	`Necessário autenticação.`
403	`Permissão 'proc.segredo_justica.listar' não habilitada para esse usuário.`
500	`Erro interno ao processar a requisição`
503	`Serviço temporariamente indisponível`

GET /credenciais/{id}#

HTTP	Mensagem / Causa
200	Sucesso. Campos sensíveis (`certificado_arquivo`, `segredo_otp`, etc.) retornam `"******"` quando aplicáveis ao tipo; `""` caso contrário.
401	`Necessário autenticação.`
403	`Permissão 'proc.segredo_justica.listar' não habilitada para esse usuário.`
404	`Credencial de ID {id} não encontrada para cliente {user_company_id}.` — ID inexistente ou pertencente a outro cliente.
422	FastAPI path-param validation — `credencial_id` não é um número inteiro. Formato: `{ "detail": [...] }`.
500	`Erro interno ao processar a requisição`
503	`Serviço temporariamente indisponível`

PATCH /credenciais/{id}#

HTTP	Mensagem / Causa
200	Sucesso. Retorna `{ id, status: "CONECTANDO", atualizado_em, atualizado_por }`.
400	`Tipo credencial "{tipo}" não compatível. Tipos permitidos: DEFAULT, 2FA, CERT, CERT_2FA`
400	`Instância "{valor}" inválida. Passe um número inteiro ou "Todas".`
400	`Campo "segredo" é obrigatório quando tipo de credencial é passado.`
400	`Campo "tipo" é obrigatório quando segredo é passado.`
400	`Não foi possível descriptografar o segredo. Verifique se o campo foi corretamente cifrado com a chave pública obtida em GET /credenciais/public_key.`
400	`Os campos {campos} são obrigatórios para o tipo de autenticação {tipo}.`
400	`Certificado inválido: {erro}.`
400	`O sistema de ID {id} não aceita tipo de credencial "{tipo}".`
401	`Necessário autenticação.`
403	`Permissão 'proc.segredo_justica.editar' não habilitada para esse usuário.`
403	`Credencial de ID {id} encontra-se arquivada.`
404	`Credencial de ID {id} não encontrada para cliente {user_company_id}.`
422	FastAPI path-param validation.
500	`Erro interno ao processar a requisição`
503	`Serviço temporariamente indisponível`

DELETE /credenciais/{id}#

HTTP	Mensagem / Causa
200	Sucesso. Retorna `{ id, sistema_id, sistema, desabilitado_por, desabilitado_em }`.
401	`Necessário autenticação.`
403	`Permissão 'proc.segredo_justica.deletar' não habilitada para esse usuário.`
404	`Credencial de ID {id} não encontrada para cliente {user_company_id}.`
422	FastAPI path-param validation.
500	`Erro interno ao processar a requisição`
503	`Serviço temporariamente indisponível`