Documentation Index
Fetch the complete documentation index at: https://docs.judit.io/llms.txt
Use this file to discover all available pages before exploring further.
🤖 A Judit API NÃO utiliza o padrão Authorization: Bearer <token>. A autenticação é feita exclusivamente através da passagem da chave no cabeçalho HTTP customizado chamado api-key. Isso se aplica a todos os endpoints e URLs Base da Judit.
1. Como Obter sua API Key
Sua API Key é a credencial única que vincula suas requisições à sua conta e plano contratado.
- Entre em contato com nossa equipe comercial via WhatsApp.
- Forneça o contexto: Explique seu caso de uso e volume esperado de requisições.
- Receba a Chave: Sua API Key será enviada de forma segura para o e-mail cadastrado.
⚠️ Segurança em 1º Lugar: Considere sua API Key como uma senha em texto claro. Nunca a exponha em repositórios públicos (ex: GitHub), código front-end (navegador do cliente) ou aplicativos mobile sem ofuscação.
Em todas as requisições feitas para a Judit API, independentemente do serviço ou módulo (Consultas, Monitoramento, etc.), você deve incluir o cabeçalho api-key.
Exemplo de Requisição HTTP Básica
GET /requests HTTP/1.1
Host: requests.prod.judit.io
api-key: sua_api_key_aqui
Content-Type: application/json
Exemplos Práticos de Implementação
Abaixo, mostramos como realizar uma requisição autenticada utilizando a URL Base de Consultas Assíncronas (https://requests.prod.judit.io), consumindo a chave a partir de variáveis de ambiente.
import os
import requests
# Configurar API Key
api_key = os.getenv('JUDIT_API_KEY')
# Headers padrão
headers = {
'api-key': api_key,
'Content-Type': 'application/json'
}
# Fazer requisição
response = requests.get(
'https://requests.prod.judit.io/requests',
headers=headers
)
3. Gestão Segura e Boas Práticas
Para evitar o vazamento da sua credencial, consolide a gestão da sua chave seguindo estas regras:
1. Uso Exclusivo de Variáveis de Ambiente
Nunca hardcode sua API Key no código:
# ❌ ERRADO - Nunca faça isso
api_key = "sk_live_1234567890abcdef"
# ✅ CORRETO - Use variáveis de ambiente
api_key = os.getenv('JUDIT_API_KEY')
# No arquivo ~/.bashrc ou ~/.zshrc
export JUDIT_API_KEY="sua-api-key-aqui"
# Ou para sessão atual
export JUDIT_API_KEY="sua-api-key-aqui"
# Command Prompt
set JUDIT_API_KEY=sua-api-key-aqui
# PowerShell
$env:JUDIT_API_KEY="sua-api-key-aqui"
# Dockerfile
ENV JUDIT_API_KEY=""
# docker-compose.yml
environment:
- JUDIT_API_KEY=${JUDIT_API_KEY}
3. Arquivo .env (Desenvolvimento)
# .env
JUDIT_API_KEY=sua-api-key-aqui
JUDIT_BASE_URL=https://requests.prod.judit.io
# Python com python-dotenv
from dotenv import load_dotenv
import os
load_dotenv()
api_key = os.getenv('JUDIT_API_KEY')
4. Rotação de Chaves
- Monitore o uso de sua API Key regularmente
- Solicite nova chave se suspeitar de comprometimento
- Implemente rotação implementação em ambientes críticos
Tratamento de Erros de Autenticação
Erro 401 - Unauthorized
{
"error": {
"name": "HttpUnauthorizedError",
"message": "UNAUTHORIZED",
"data": "USER_NOT_FOUND"
}
}
- API Key não fornecida
- API Key inválida ou expirada
- Header
api-key mal formatado
Erro 403 - Forbidden
{
"error": "Forbidden",
"message": "Acesso negado para este recurso",
"code": "INSUFFICIENT_PERMISSIONS"
}
- API Key válida mas sem permissão para o recurso
- Limite de uso excedido
- Recurso não disponível no seu plano
Validação da API Key
Teste de Conectividade
import requests
def test_api_key(api_key):
"""Testa se a API Key está válida"""
headers = {'api-key': api_key}
try:
response = requests.get(
'https://requests.prod.judit.io/requests',
headers=headers,
params={'page': 1, 'page_size': 1}
)
if response.status_code == 200:
print("✅ API Key válida")
return True
elif response.status_code == 401:
print("❌ API Key inválida")
return False
else:
print(f"⚠️ Erro inesperado: {response.status_code}")
return False
except requests.RequestException as e:
print(f"❌ Erro de conexão: {e}")
return False
# Usar a função
api_key = os.getenv('JUDIT_API_KEY')
test_api_key(api_key)
Monitoramento de Uso
def check_api_usage(response):
"""
Monitora o uso da API através dos headers da resposta.
Nota: A API possui um rate-limit estrito de 180 requisições por minuto.
Esta função calcula o percentual de consumo na janela de tempo atual.
"""
# Captura as informações de limite nos headers (Esperado: 180 por minuto)
limit = response.headers.get('X-RateLimit-Limit')
remaining = response.headers.get('X-RateLimit-Remaining')
reset = response.headers.get('X-RateLimit-Reset')
if limit and remaining:
# Calcula a porcentagem de uso baseada no limite retornado
usage_percent = ((int(limit) - int(remaining)) / int(limit)) * 100
print(f"Limite da API: {limit} requisições/minuto")
print(f"Uso da API: {usage_percent:.1f}%")
print(f"Requisições restantes neste minuto: {remaining}")
# Alerta se o consumo passar de 80% (aprox. 144 requisições)
if usage_percent > 80:
print("⚠️ Atenção: Próximo do limite de rate limit (180/min)!")
Configuração por Ambiente
# config/production.py
import os
API_KEY = os.getenv('JUDIT_API_KEY')
BASE_URL = 'https://requests.prod.judit.io'
TIMEOUT = 10
RETRY_ATTEMPTS = 3
Classe de Configuração
class JuditConfig:
def __init__(self, environment='production'):
self.environment = environment
self.api_key = self._get_api_key()
self.base_url = 'https://requests.prod.judit.io'
def _get_api_key(self):
key_name = f'JUDIT_API_KEY_{self.environment.upper()}'
api_key = os.getenv(key_name)
if not api_key:
raise ValueError(f"API Key não encontrada: {key_name}")
return api_key
@property
def headers(self):
return {
'api-key': self.api_key,
'Content-Type': 'application/json'
}
# Uso
config = JuditConfig('production')
response = requests.get(f"{config.base_url}/requests",
headers=config.headers)
Próximos Passos
Suporte: Em caso de problemas com autenticação, entre em contato com nosso suporte técnico.
