Certificate Client

O módulo Certificate Client do SDK fornece funcionalidade para fazer requisições HTTP que requerem certificados cliente para autenticação.

🚀 Características Principais

• Autenticação por certificado - Requisições HTTPS com certificados cliente
• Interface simplificada - Métodos HTTP familiares (get, post, put, delete)
• Gestão automática - Certificados são carregados e limpos automaticamente
• Tratamento de erros - raise_for_status() automático e exceções tipadas
• Timeout padrão - 30 segundos por padrão para todas as requisições

---

🔧 Uso

Inicialização

A classe CertificateClient é inicializada com o conteúdo do certificado:

# Dentro do código da ferramenta
cert_client = CertificateClient(cert_content=secrets["CERTIFICADO_PEM"])

GET Request

# Requisição GET simples
response = cert_client.get(
    url="https://api.example.com/data",
    headers={"X-API-Key": "sua-api-key"},
    timeout=30
)

data = response.json()

POST Request

# Requisição POST com JSON
response = cert_client.post(
    url="https://api.example.com/create",
    json={"nome": "João", "idade": 30},
    headers={"Content-Type": "application/json"},
    timeout=30
)

result = response.json()

Requisições com Query Parameters

# GET com parâmetros de consulta
response = cert_client.get(
    url="https://api.example.com/search",
    params={"q": "termo", "page": 1, "size": 20},
    headers={"Authorization": "Bearer token"}
)

---

📝 Exemplo Prático

Consulta de Recurso

def consultar_dados_recurso(resource_id: str):
    """
    Consulta dados detalhados de um recurso usando CertificateClient
    """
    try:
        cert_client = CertificateClient(cert_content=secrets["CERTIFICATE_PEM"])

        headers = {
            "Authorization": f"Bearer {secrets['API_TOKEN']}",
            "X-API-Key": secrets["API_KEY"],
        }

        url = f"{secrets['API_HOST']}/v1/resources/{resource_id}/details"

        response = cert_client.get(url=url, headers=headers, timeout=30)
        data = response.json()
        return {"success": True, "data": data}

    except Exception as e:
        return {"success": False, "error": str(e)}

---

🛡️ Tratamento de Erros

try:
    response = cert_client.get("https://api.example.com/data")
    data = response.json()
    
except requests.HTTPError as e:
    # Erro HTTP (4xx, 5xx)
    print(f"Erro HTTP: {e.response.status_code}")
    
except requests.RequestException as e:
    # Erro de rede/conexão
    print(f"Erro de conexão: {e}")
    
except ValueError as e:
    # Erro no parsing do certificado
    print(f"Erro no certificado: {e}")

---

📚 Métodos Disponíveis

A classe CertificateClient suporta todos os métodos HTTP principais:

• get() - Requisições GET
• post() - Requisições POST
• put() - Requisições PUT
• delete() - Requisições DELETE
• request() - Método genérico para qualquer verbo HTTP

---

🎯 Exemplo Completo

Listagem de Recursos com Tratamento Completo

def listar_recursos():
    """
    Lista recursos de um serviço externo usando CertificateClient
    """
    try:
        # Inicializar cliente com certificado
        cert_client = CertificateClient(cert_content=secrets["CERTIFICATE_PEM"])
        
        # Preparar headers
        headers = {
            "Authorization": f"Bearer {secrets['API_TOKEN']}",
            "X-API-Key": secrets["API_KEY"],
            "X-User-Id": state_manager.get("user.id") or "unknown"
        }
        
        # Preparar URL
        url = f"{secrets['API_HOST']}/v1/resources/list"
        params = {
            "status": "active",
            "page": 1,
            "size": 40
        }
        
        # Fazer requisição
        response = cert_client.get(
            url=url,
            headers=headers,
            params=params,
            timeout=30
        )
        
        data = response.json()
        
        # Mapear resposta
        recursos = []
        if "items" in data and isinstance(data["items"], list):
            for item in data["items"]:
                recursos.append({
                    "id": item.get("id"),
                    "numero": item.get("number"),
                    "resumo": item.get("summary"),
                    "categoriaCodigo": item.get("category", {}).get("code")
                })
        
        return ResponseToUser(
            message=f"Encontrados {len(recursos)} recursos ativos.",
            status=ResponseStatus.SUCCESS,
            metadata={"items": recursos}
        )
        
    except requests.HTTPError as e:
        return ResponseToUser(
            message=f"Erro na API externa: {e.response.status_code}",
            status=ResponseStatus.ERROR
        )
        
    except requests.RequestException as e:
        return ResponseToUser(
            message="Problema de conectividade com a API externa. Tente novamente.",
            status=ResponseStatus.ERROR
        )
        
    except Exception:
        return ResponseToUser(
            message="Erro inesperado ao listar recursos.",
            status=ResponseStatus.ERROR
        )

---

✨ Vantagens do CertificateClient

Benefícios

1. Simplicidade: Não precisa gerenciar context managers manualmente
2. Tratamento de Erros: raise_for_status() automático em todas as requisições
3. Timeout Padrão: 30 segundos por padrão em todas as requisições
4. Padrão SDK: Retornos consistentes com ResponseToUser
5. Type Safety: Melhor suporte a IDEs com type hints
6. Reutilização: Uma instância pode ser usada para múltiplas requisições

---

⚠️ Notas Importantes

Considerações de Segurança

1. Formato do Certificado: Deve estar em formato PEM com private key e certificados
2. Segurança: O certificado é carregado temporariamente e limpo automaticamente
3. Performance: O certificado é reprocessado a cada requisição por segurança
4. Timeout: Sempre especifique um timeout apropriado para sua API
5. Logs: Erros são automaticamente propagados para melhor debugging