SmartCPF vs Consulta Manual na Receita Federal: Tempo e Confiabilidade

import os
import time
import httpx
from typing import Optional
from dataclasses import dataclass

API_BASE = "https://api.smartcpf.com.br/v2"
API_KEY = os.getenv("SMARTCPF_API_KEY")  # defina no ambiente, nunca no código

@dataclass
class CPFResult:
    cpf: str
    name: str
    birth_date: str
    age: int
    status: str
    mother_name: str
    gender: str
    emails: list[str]
    phones: list[dict]
    addresses: list[dict]
    consult_id: str
    balance: float
    execution_ms: float

class SmartCPFClient:
    def __init__(self, api_key: str, base_url: str = API_BASE):
        self.api_key = api_key
        self.base_url = base_url
        self.client = httpx.Client(timeout=30.0)
    
    def _headers(self) -> dict:
        return {"X-API-KEY": self.api_key, "Accept": "application/json"}
    
    def consultar(self, cpf: str, package: str = "complete") -> CPFResult:
        """
        Consulta CPF com retry exponencial em 429/5xx.
        Retorna CPFResult estruturado ou levanta exceção com detalhes.
        """
        url = f"{self.base_url}/individuals/{cpf}"
        params = {"package": package}
        max_retries = 3
        backoff = 1.0
        
        for attempt in range(max_retries):
            resp = self.client.get(url, params=params, headers=self._headers())
            
            if resp.status_code == 200:
                data = resp.json()
                meta = data.get("meta", {})
                result = data.get("result", {})
                
                if not data.get("success") or not result:
                    raise ValueError(f"API retornou success=false: {data.get('errors')}")
                
                return CPFResult(
                    cpf=result.get("cpf", ""),
                    name=result.get("name", ""),
                    birth_date=result.get("birthDate", ""),
                    age=result.get("age", 0),
                    status=result.get("status", ""),
                    mother_name=result.get("motherName", ""),
                    gender=result.get("gender", ""),
                    emails=result.get("emails", []),
                    phones=result.get("phones", []),
                    addresses=result.get("addresses", []),
                    consult_id=meta.get("consultId", ""),
                    balance=meta.get("balance", 0.0),
                    execution_ms=meta.get("executionTimeMs", 0.0),
                )
            
            elif resp.status_code == 401:
                raise PermissionError("API Key inválida ou ausente (header X-API-KEY)")
            elif resp.status_code == 404:
                raise LookupError(f"CPF {cpf} não encontrado na base da Receita Federal")
            elif resp.status_code == 422:
                raise ValueError(f"CPF inválido ou mal formatado: {resp.json()}")
            elif resp.status_code == 429:
                retry_after = float(resp.headers.get("Retry-After", backoff))
                time.sleep(retry_after)
                backoff *= 2
                continue
            elif 500 <= resp.status_code < 600:
                time.sleep(backoff)
                backoff *= 2
                continue
            else:
                raise RuntimeError(f"HTTP {resp.status_code}: {resp.text}")
        
        raise RuntimeError(f"Esgotadas {max_retries} tentativas para CPF {cpf}")

# Exemplo de uso
if __name__ == "__main__":
    if not API_KEY:
        raise SystemExit("Defina SMARTCPF_API_KEY no ambiente")
    
    client = SmartCPFClient(API_KEY)
    cpf_teste = "111.111.111-11"  # CPF de exemplo — substitua pelo real
    
    try:
        resultado = client.consultar(cpf_teste, package="complete")
        print(f"✓ Consulta ID: {resultado.consult_id}")
        print(f"✓ Nome: {resultado.name}")
        print(f"✓ Status: {resultado.status}")
        print(f"✓ Idade: {resultado.age} anos")
        print(f"✓ E-mails: {resultado.emails}")
        print(f"✓ Telefones: {len(resultado.phones)} encontrado(s)")
        print(f"✓ Saldo restante: {resultado.balance:.2f} créditos")
        print(f"✓ Tempo de execução: {resultado.execution_ms:.1f}ms")
    except (PermissionError, LookupError, ValueError, RuntimeError) as e:
        print(f"✗ Erro: {e}")

{
  "meta": {
    "searchType": "CPF C",
    "consultId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "user": "Fulano de Tal",
    "message": "CPF encontrado com sucesso",
    "ip": "127.0.0.1",
    "success": true,
    "apiVersion": "v2",
    "date": "2026-08-10T14:32:15.123Z",
    "executionTimeMs": 74.1,
    "balance": 9.77
  },
  "result": {
    "cpf": "111.111.111-11",
    "name": "João da Silva",
    "birthDate": "10/09/1992",
    "age": 33,
    "motherName": "Maria da Silva",
    "gender": "M",
    "status": "Regular",
    "emails": ["[email protected]"],
    "phones": [
      {
        "number": "(55) 99999-9999",
        "blockedTelemarketing": false,
        "operator": "VIVO",
        "type": "CELULAR",
        "whatsapp": false
      }
    ],
    "addresses": []
  },
  "success": true,
  "errors": []
}