foxnfe 1.3.0__py3-none-any.whl

foxnfe/__init__.py

@@ -0,0 +1,40 @@
+"""SDK oficial FOX NF-e para Python."""
+
+from .client import Client
+from .exceptions import ApiException, AuthException, FoxNfeException
+from .types import (
+    LoginResponse,
+    McpTool,
+    NfeEmitRequest,
+    NfeResource,
+    NfseEmitRequest,
+    NfseResource,
+)
+from .webhook import Webhook
+from .reference import Reference
+from .documents import Documents
+from .events import NfeEvents
+from .distribuicao import Distribuicao
+from .rtc import Rtc
+from .support import Support
+
+__version__ = "1.3.0"
+__all__ = [
+    "Client",
+    "FoxNfeException",
+    "ApiException",
+    "AuthException",
+    "NfeEmitRequest",
+    "NfeResource",
+    "NfseEmitRequest",
+    "NfseResource",
+    "McpTool",
+    "LoginResponse",
+    "Webhook",
+    "Reference",
+    "Documents",
+    "NfeEvents",
+    "Distribuicao",
+    "Rtc",
+    "Support",
+]

foxnfe/client.py

@@ -0,0 +1,172 @@
+"""Cliente HTTP base do SDK FOX NF-e."""
+
+from __future__ import annotations
+from typing import Any, Optional
+import requests
+from requests import Response, Session
+
+from .exceptions import ApiException, AuthException, FoxNfeException
+from .types import LoginResponse
+
+
+class Client:
+    """Cliente principal do SDK FOX NF-e."""
+
+    DEFAULT_BASE_URL = "https://foxnfe.centralfox.online/api/v1"
+
+    def __init__(
+        self,
+        tenant_slug: str,
+        token: Optional[str] = None,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = 30.0,
+    ) -> None:
+        self.tenant_slug = tenant_slug
+        self._token = token
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._session = Session()
+        self._session.headers.update({
+            "Accept": "application/json",
+            "Content-Type": "application/json",
+            "X-Tenant-ID": tenant_slug,
+        })
+
+    def login(self, email: str, password: str) -> LoginResponse:
+        """Autentica e armazena o token internamente."""
+        data = self.post("auth/login", {"email": email, "password": password})
+        token = data.get("token")
+        if not token:
+            raise AuthException("Token não retornado pela API.")
+        self._token = token
+        return LoginResponse.from_dict(data)
+
+    def with_token(self, token: str) -> "Client":
+        """Retorna uma nova instância com token definido."""
+        client = Client(
+            tenant_slug=self.tenant_slug,
+            token=token,
+            base_url=self._base_url,
+            timeout=self._timeout,
+        )
+        return client
+
+    def logout(self) -> None:
+        """Invalida o token na API e limpa internamente."""
+        self.post("auth/logout")
+        self._token = None
+
+    def me(self) -> dict[str, Any]:
+        return self.get("auth/me")
+
+    # ── Módulos ─────────────────────────────────────────────────────────────
+
+    @property
+    def nfe(self) -> "Nfe":  # type: ignore[name-defined]
+        from .nfe import Nfe
+        return Nfe(self)
+
+    @property
+    def nfse(self) -> "Nfse":  # type: ignore[name-defined]
+        from .nfse import Nfse
+        return Nfse(self)
+
+    @property
+    def mcp(self) -> "Mcp":  # type: ignore[name-defined]
+        from .mcp import Mcp
+        return Mcp(self)
+
+    @property
+    def webhook(self) -> "Webhook":  # type: ignore[name-defined]
+        from .webhook import Webhook
+        return Webhook(self)
+
+    @property
+    def reference(self) -> "Reference":  # type: ignore[name-defined]
+        from .reference import Reference
+        return Reference(self)
+
+    @property
+    def documents(self) -> "Documents":  # type: ignore[name-defined]
+        from .documents import Documents
+        return Documents(self)
+
+    @property
+    def nfe_events(self) -> "NfeEvents":  # type: ignore[name-defined]
+        from .events import NfeEvents
+        return NfeEvents(self)
+
+    @property
+    def distribuicao(self) -> "Distribuicao":  # type: ignore[name-defined]
+        from .distribuicao import Distribuicao
+        return Distribuicao(self)
+
+    @property
+    def rtc(self) -> "Rtc":  # type: ignore[name-defined]
+        from .rtc import Rtc
+        return Rtc(self)
+
+    @property
+    def support(self) -> "Support":  # type: ignore[name-defined]
+        from .support import Support
+        return Support(self)
+
+    # ── HTTP helpers ─────────────────────────────────────────────────────────
+
+    def get(self, path: str, params: Optional[dict] = None) -> dict[str, Any]:
+        return self._request("GET", path, params=params)
+
+    def post(self, path: str, body: Optional[dict] = None) -> dict[str, Any]:
+        return self._request("POST", path, json=body)
+
+    def put(self, path: str, body: Optional[dict] = None) -> dict[str, Any]:
+        return self._request("PUT", path, json=body)
+
+    def delete(self, path: str) -> dict[str, Any]:
+        return self._request("DELETE", path)
+
+    def upload(self, path: str, field: str, filename: str, content: bytes, fields: Optional[dict] = None) -> dict[str, Any]:
+        """Envio multipart (upload de XML); o Content-Type JSON da sessão é removido."""
+        return self._request("POST", path, files={field: (filename, content, "application/xml")}, data=fields or {})
+
+    def download(self, path: str) -> bytes:
+        """Retorna bytes do conteúdo (XML, PDF)."""
+        resp = self._raw_request("GET", path)
+        if not resp.ok:
+            raise ApiException.from_response(resp.status_code, resp.json() if resp.content else {})
+        return resp.content
+
+    def _request(self, method: str, path: str, **kwargs: Any) -> dict[str, Any]:
+        resp = self._raw_request(method, path, **kwargs)
+        try:
+            body = resp.json()
+        except Exception as exc:
+            raise FoxNfeException(f"Resposta JSON inválida: {exc}") from exc
+
+        if not resp.ok:
+            if resp.status_code in (401, 403):
+                raise AuthException(body.get("message", "Não autorizado."))
+            raise ApiException.from_response(resp.status_code, body)
+
+        return body  # type: ignore[return-value]
+
+    def _raw_request(self, method: str, path: str, **kwargs: Any) -> Response:
+        url = f"{self._base_url}/{path.lstrip('/')}"
+        headers: dict[str, Any] = {}
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        if "files" in kwargs:
+            headers["Content-Type"] = None  # requests define o boundary multipart
+
+        try:
+            return self._session.request(
+                method,
+                url,
+                headers=headers,
+                timeout=self._timeout,
+                **kwargs,
+            )
+        except requests.exceptions.Timeout as exc:
+            raise FoxNfeException(f"Timeout após {self._timeout}s") from exc
+        except requests.exceptions.ConnectionError as exc:
+            raise FoxNfeException(f"Erro de conexão: {exc}") from exc

foxnfe/distribuicao.py

@@ -0,0 +1,73 @@
+"""NF-e recebidas: distribuição DF-e, cursor, captura automática e manifestação do destinatário."""
+
+from __future__ import annotations
+import re
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from .client import Client
+
+TIPOS_MANIFESTACAO = (210200, 210210, 210220, 210240)
+
+
+class Distribuicao:
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._client.get("nfe-distribuicao", params=_clean(params))
+
+    def cursor(self) -> dict[str, Any]:
+        return self._client.get("nfe-distribuicao/cursor")
+
+    def optins(self) -> dict[str, Any]:
+        return self._client.get("nfe-distribuicao/captura-automatica")
+
+    def enable_optin(self, certificate_id: int, ambiente: int) -> dict[str, Any]:
+        _positive(certificate_id, "certificate_id")
+        return self._client.put("nfe-distribuicao/captura-automatica", {"certificate_id": certificate_id, "ambiente": ambiente})
+
+    def disable_optin(self, optin_id: int) -> dict[str, Any]:
+        _positive(optin_id, "optin_id")
+        return self._client.delete(f"nfe-distribuicao/captura-automatica/{optin_id}")
+
+    def capturar(self, certificate_id: Optional[int] = None, ambiente: Optional[int] = None) -> dict[str, Any]:
+        return self._client.post("nfe-distribuicao/capturar", _clean({"certificate_id": certificate_id, "ambiente": ambiente}))
+
+    def manifestacoes(self, **params: Any) -> dict[str, Any]:
+        return self._client.get("nfe-distribuicao/manifestacoes", params=_clean(params))
+
+    def manifestacao(self, manifestacao_id: int) -> dict[str, Any]:
+        _positive(manifestacao_id, "manifestacao_id")
+        return self._client.get(f"nfe-distribuicao/manifestacoes/{manifestacao_id}")
+
+    def solicitar_manifestacao(self, chave_acesso: str, tipo_evento: int, **extra: Any) -> dict[str, Any]:
+        if not re.fullmatch(r"[0-9]{6}[0-9A-Z]{12}[0-9]{26}", chave_acesso or ""):
+            raise ValueError("chave_acesso inválida (44 posições).")
+        if tipo_evento not in TIPOS_MANIFESTACAO:
+            raise ValueError("tipo_evento inválido.")
+        return self._client.post("nfe-distribuicao/manifestacoes", {"chave_acesso": chave_acesso, "tipo_evento": tipo_evento, **_clean(extra)})
+
+    def aprovar_manifestacao(self, manifestacao_id: int, payload_hash: str) -> dict[str, Any]:
+        """Aprovação vinculada ao payload_hash devolvido na solicitação."""
+        _positive(manifestacao_id, "manifestacao_id")
+        if not re.fullmatch(r"[0-9a-f]{64}", payload_hash or ""):
+            raise ValueError("payload_hash deve ser sha256 hex minúsculo.")
+        return self._client.post(f"nfe-distribuicao/manifestacoes/{manifestacao_id}/aprovar", {"payload_hash": payload_hash})
+
+    def transmitir_manifestacao(self, manifestacao_id: int) -> dict[str, Any]:
+        _positive(manifestacao_id, "manifestacao_id")
+        return self._client.post(f"nfe-distribuicao/manifestacoes/{manifestacao_id}/transmitir")
+
+    def reconciliar_manifestacao(self, manifestacao_id: int) -> dict[str, Any]:
+        _positive(manifestacao_id, "manifestacao_id")
+        return self._client.post(f"nfe-distribuicao/manifestacoes/{manifestacao_id}/reconciliar")
+
+
+def _clean(d: dict[str, Any]) -> dict[str, Any]:
+    return {k: v for k, v in d.items() if v is not None}
+
+
+def _positive(v: int, label: str) -> None:
+    if not isinstance(v, int) or v < 1:
+        raise ValueError(f"{label} deve ser inteiro positivo.")

foxnfe/documents.py

@@ -0,0 +1,58 @@
+"""Central de Documentos: consulta unificada, detalhe, importação de XML com prévia e exportação ZIP."""
+
+from __future__ import annotations
+import re
+from typing import TYPE_CHECKING, Any, Optional
+from urllib.parse import quote
+
+if TYPE_CHECKING:
+    from .client import Client
+
+_UUID = re.compile(r"[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}")
+
+
+class Documents:
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    def list(self, **params: Any) -> dict[str, Any]:
+        return self._client.get("documents", params={k: v for k, v in params.items() if v is not None})
+
+    def show(self, source: str, doc_id: int) -> dict[str, Any]:
+        if not re.fullmatch(r"[a-z_]+", source):
+            raise ValueError("source inválido.")
+        _positive(doc_id, "doc_id")
+        return self._client.get(f"documents/{source}/{doc_id}")
+
+    def import_preview(self, xml: bytes, filename: str = "nota.xml") -> dict[str, Any]:
+        """Valida e vincula SEM persistir; devolve integrity.raw_sha256 para o commit."""
+        return self._client.upload("documents/imports/preview", "file", filename, xml)
+
+    def import_xml(self, xml: bytes, preview_sha256: Optional[str] = None, filename: str = "nota.xml") -> dict[str, Any]:
+        fields: dict[str, str] = {}
+        if preview_sha256 is not None:
+            if not re.fullmatch(r"[0-9a-f]{64}", preview_sha256):
+                raise ValueError("preview_sha256 deve ser sha256 hex minúsculo.")
+            fields["preview_sha256"] = preview_sha256
+        return self._client.upload("documents/imports", "file", filename, xml, fields)
+
+    def export_request(self, **filters: Any) -> dict[str, Any]:
+        return self._client.post("documents/exports", {k: v for k, v in filters.items() if v is not None})
+
+    def export_status(self, request_id: str) -> dict[str, Any]:
+        _uuid(request_id)
+        return self._client.get(f"documents/exports/{quote(request_id, safe='')}")
+
+    def export_download(self, request_id: str) -> bytes:
+        _uuid(request_id)
+        return self._client.download(f"documents/exports/{quote(request_id, safe='')}/download")
+
+
+def _positive(v: int, label: str) -> None:
+    if not isinstance(v, int) or v < 1:
+        raise ValueError(f"{label} deve ser inteiro positivo.")
+
+
+def _uuid(v: str) -> None:
+    if not _UUID.fullmatch(v or ""):
+        raise ValueError("request_id deve ser um UUID válido.")

foxnfe/events.py

@@ -0,0 +1,115 @@
+"""Eventos pós-emissão da NF-e: Carta de Correção Eletrônica (assíncrona e durável)."""
+
+from __future__ import annotations
+import re
+from typing import TYPE_CHECKING, Any, Optional
+
+if TYPE_CHECKING:
+    from .client import Client
+
+
+class NfeEvents:
+    def __init__(self, client: "Client") -> None:
+        self._client = client
+
+    def cce_list(self, invoice_id: int) -> dict[str, Any]:
+        _positive(invoice_id)
+        return self._client.get(f"nfe/{invoice_id}/cce")
+
+    def cce_create(self, invoice_id: int, correcao: str, sequencial: Optional[int] = None) -> dict[str, Any]:
+        """Correção de 15 a 1000 caracteres; sequencial (1..20) opcional — o servidor aloca sob lock."""
+        _positive(invoice_id)
+        if not 15 <= len(correcao.strip()) <= 1000:
+            raise ValueError("correcao deve ter entre 15 e 1000 caracteres.")
+        body: dict[str, Any] = {"correcao": correcao}
+        if sequencial is not None:
+            if not isinstance(sequencial, int) or not 1 <= sequencial <= 20:
+                raise ValueError("sequencial deve ser inteiro entre 1 e 20.")
+            body["sequencial"] = sequencial
+        return self._client.post(f"nfe/{invoice_id}/cce", body)
+
+
+    # ── 1.3.0 — outros eventos da NF-e própria (L17) ─────────────────────────
+
+    def ator_interessado_list(self, invoice_id: int) -> dict[str, Any]:
+        _positive(invoice_id)
+        return self._client.get(f"nfe/{invoice_id}/ator-interessado")
+
+    def ator_interessado(self, invoice_id: int, documento: str, **extra: Any) -> dict[str, Any]:
+        """Ator interessado (110150). documento = CPF (11) ou CNPJ (14) só dígitos; extra: tp_autor, tp_autorizacao, sequencial."""
+        _positive(invoice_id)
+        if not re.fullmatch(r"\d{11}|\d{14}", documento):
+            raise ValueError("documento deve ter 11 (CPF) ou 14 (CNPJ) dígitos.")
+        return self._client.post(f"nfe/{invoice_id}/ator-interessado", {"documento": documento, **extra})
+
+    def insucesso_entrega_list(self, invoice_id: int) -> dict[str, Any]:
+        _positive(invoice_id)
+        return self._client.get(f"nfe/{invoice_id}/insucesso-entrega")
+
+    def insucesso_entrega(self, invoice_id: int, dh_tentativa: str, tp_motivo: int, justificativa: Optional[str] = None, **extra: Any) -> dict[str, Any]:
+        """Insucesso na entrega (110192). tp_motivo 1..4; 4 exige justificativa (15..250). A imagem não é persistida."""
+        _positive(invoice_id)
+        if tp_motivo not in (1, 2, 3, 4):
+            raise ValueError("tp_motivo deve ser 1, 2, 3 ou 4.")
+        if tp_motivo == 4 and not 15 <= len((justificativa or "").strip()) <= 250:
+            raise ValueError("justificativa (15..250) é obrigatória quando tp_motivo=4.")
+        body: dict[str, Any] = {"dh_tentativa": dh_tentativa, "tp_motivo": tp_motivo, **extra}
+        if justificativa is not None:
+            body["justificativa"] = justificativa
+        return self._client.post(f"nfe/{invoice_id}/insucesso-entrega", body)
+
+    def cancelar_insucesso_entrega(self, invoice_id: int, evento_id: int) -> dict[str, Any]:
+        _positive(invoice_id); _positive(evento_id)
+        return self._client.post(f"nfe/{invoice_id}/insucesso-entrega/{evento_id}/cancelar")
+
+    def inutilizacoes(self) -> dict[str, Any]:
+        return self._client.get("nfe/inutilizacoes")
+
+    def inutilizacao(self, inutilizacao_id: int) -> dict[str, Any]:
+        _positive(inutilizacao_id)
+        return self._client.get(f"nfe/inutilizacoes/{inutilizacao_id}")
+
+    def inutilizar(self, serie: int, numero_inicial: int, numero_final: int, justificativa: str, **extra: Any) -> dict[str, Any]:
+        """Inutiliza uma faixa de numeração (assíncrono e durável); extra: modelo (55|65), ano."""
+        if numero_inicial < 1 or numero_final < numero_inicial:
+            raise ValueError("numero_final deve ser >= numero_inicial >= 1.")
+        if not 15 <= len(justificativa.strip()) <= 255:
+            raise ValueError("justificativa deve ter entre 15 e 255 caracteres.")
+        return self._client.post("nfe/inutilizacoes", {"serie": serie, "numero_inicial": numero_inicial, "numero_final": numero_final, "justificativa": justificativa, **extra})
+
+    # ── 1.3.0 — eventos por contrato oficial (L18) ───────────────────────────
+
+    def contratos(self) -> dict[str, Any]:
+        return self._client.get("nfe/eventos/contratos")
+
+    def eventos(self, invoice_id: int) -> dict[str, Any]:
+        _positive(invoice_id)
+        return self._client.get(f"nfe/{invoice_id}/eventos")
+
+    def registrar_evento(self, invoice_id: int, tipo: str, payload: Optional[dict[str, Any]] = None, sequencial: Optional[int] = None) -> dict[str, Any]:
+        _positive(invoice_id); _tipo(tipo)
+        body: dict[str, Any] = {"tipo": tipo, **(payload or {})}
+        if sequencial is not None:
+            body["sequencial"] = sequencial
+        return self._client.post(f"nfe/{invoice_id}/eventos", body)
+
+    def eventos_recebida(self, distribuicao_id: int) -> dict[str, Any]:
+        _positive(distribuicao_id)
+        return self._client.get(f"nfe/recebidas/{distribuicao_id}/eventos")
+
+    def registrar_evento_recebida(self, distribuicao_id: int, tipo: str, payload: Optional[dict[str, Any]] = None, sequencial: Optional[int] = None) -> dict[str, Any]:
+        _positive(distribuicao_id); _tipo(tipo)
+        body: dict[str, Any] = {"tipo": tipo, **(payload or {})}
+        if sequencial is not None:
+            body["sequencial"] = sequencial
+        return self._client.post(f"nfe/recebidas/{distribuicao_id}/eventos", body)
+
+
+def _tipo(tipo: str) -> None:
+    if not re.fullmatch(r"[a-z0-9_]{3,60}", tipo):
+        raise ValueError("tipo deve ser um identificador do catálogo (GET nfe/eventos/contratos).")
+
+
+def _positive(v: int) -> None:
+    if not isinstance(v, int) or v < 1:
+        raise ValueError("invoice_id deve ser inteiro positivo.")

foxnfe/exceptions.py

@@ -0,0 +1,30 @@
+"""Exceções do SDK FOX NF-e."""
+
+from __future__ import annotations
+from typing import Any, Optional
+
+
+class FoxNfeException(Exception):
+    """Exceção base do SDK."""
+
+    def __init__(self, message: str, context: Optional[dict[str, Any]] = None) -> None:
+        super().__init__(message)
+        self.context = context
+
+
+class ApiException(FoxNfeException):
+    """Erro retornado pela API FOX NF-e."""
+
+    def __init__(self, status_code: int, message: str, response_body: Optional[dict] = None) -> None:
+        super().__init__(message, response_body)
+        self.status_code = status_code
+        self.response_body = response_body
+
+    @classmethod
+    def from_response(cls, status_code: int, body: dict) -> "ApiException":
+        message = body.get("message") or body.get("error") or f"HTTP {status_code}"
+        return cls(status_code, message, body)
+
+
+class AuthException(FoxNfeException):
+    """Erro de autenticação."""

foxnfe/mcp.py

@@ -0,0 +1,45 @@
+"""Módulo MCP do SDK FOX NF-e."""
+
+from __future__ import annotations
+from typing import Any
+
+from .types import McpTool
+
+
+class Mcp:
+    MCP_PATH = "mcp"
+
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def list_tools(self) -> list[McpTool]:
+        """Lista todas as tools MCP disponíveis."""
+        resp = self._client.post(self.MCP_PATH, {
+            "jsonrpc": "2.0",
+            "id": 1,
+            "method": "tools/list",
+            "params": {},
+        })
+        return [McpTool.from_dict(t) for t in resp.get("result", {}).get("tools", [])]
+
+    def call_tool(self, tool: str, input: dict[str, Any] | None = None) -> dict[str, Any]:
+        """Chama uma tool MCP pelo nome."""
+        return self._client.post(self.MCP_PATH, {
+            "jsonrpc": "2.0",
+            "id": 2,
+            "method": "tools/call",
+            "params": {"name": tool, "arguments": input or {}},
+        })
+
+    def initialize(self) -> dict[str, Any]:
+        """Retorna informações do servidor MCP."""
+        return self._client.post(self.MCP_PATH, {
+            "jsonrpc": "2.0",
+            "id": 0,
+            "method": "initialize",
+            "params": {
+                "protocolVersion": "2024-11-05",
+                "clientInfo": {"name": "foxnfe-python-sdk", "version": "1.0.0"},
+                "capabilities": {},
+            },
+        })

foxnfe/nfe.py

@@ -0,0 +1,93 @@
+"""Módulo NF-e do SDK FOX NF-e."""
+
+from __future__ import annotations
+import re
+import time
+from typing import Any, Optional
+
+from .exceptions import FoxNfeException
+from .types import NfeEmitRequest, NfeResource
+
+
+class Nfe:
+    def __init__(self, client: Any) -> None:
+        self._client = client
+
+    def emit(self, payload: NfeEmitRequest) -> dict[str, Any]:
+        """Emite uma NF-e. Retorna imediatamente com status 'pending'."""
+        return self._client.post("nfe/emit", payload.to_dict())
+
+    def get(self, nfe_id: int) -> NfeResource:
+        """Consulta status e dados de uma NF-e."""
+        data = self._client.get(f"nfe/{nfe_id}")
+        return NfeResource.from_dict(data)
+
+    def xml(self, nfe_id: int) -> bytes:
+        """Baixa o XML assinado da NF-e autorizada."""
+        return self._client.download(f"nfe/{nfe_id}/xml")
+
+    def pdf(self, nfe_id: int) -> bytes:
+        """Baixa o DANFE em PDF."""
+        return self._client.download(f"nfe/{nfe_id}/pdf")
+
+    def cancel(self, nfe_id: int, justificativa: str) -> NfeResource:
+        """Cancela uma NF-e autorizada. Justificativa mínima: 15 chars."""
+        data = self._client.post(f"nfe/{nfe_id}/cancel", {"justificativa": justificativa})
+        return NfeResource.from_dict(data)
+
+    # ── 1.3.0 — rejeições explicadas e homologação por modelo (L20) ──────────
+
+    def rejeicoes(self) -> dict[str, Any]:
+        """Catálogo de rejeições SEFAZ: categoria, ação e dica por cStat."""
+        return self._client.get("nfe/rejeicoes")
+
+    def rejeicao(self, cstat: int | str) -> dict[str, Any]:
+        c = str(cstat)
+        if not re.fullmatch(r"\d{3}", c):
+            raise ValueError("cstat deve ter 3 dígitos.")
+        return self._client.get(f"nfe/rejeicoes/{c}")
+
+    def homologacao(self) -> dict[str, Any]:
+        """Matriz de homologação (modelo/UF/cenário) e últimas corridas."""
+        return self._client.get("nfe/homologacao")
+
+    def homologacao_run(self, modelo: int, cenario: Optional[str] = None, mode: str = "simulated") -> dict[str, Any]:
+        """simulated (padrão): amostras XML/PDF assinadas sem transmitir; sefaz: só com autorização no servidor (409)."""
+        if modelo not in (55, 65):
+            raise ValueError("modelo deve ser 55 ou 65.")
+        if mode not in ("simulated", "sefaz"):
+            raise ValueError("mode deve ser 'simulated' ou 'sefaz'.")
+        body: dict[str, Any] = {"modelo": modelo, "mode": mode}
+        if cenario:
+            body["cenario"] = cenario
+        return self._client.post("nfe/homologacao/run", body)
+
+    def homologacao_xml(self, run_id: int) -> bytes:
+        _positive(run_id)
+        return self._client.download(f"nfe/homologacao/{run_id}/xml")
+
+    def homologacao_pdf(self, run_id: int) -> bytes:
+        _positive(run_id)
+        return self._client.download(f"nfe/homologacao/{run_id}/pdf")
+
+    def wait_for_authorization(
+        self,
+        nfe_id: int,
+        max_wait_s: float = 120.0,
+        poll_s: float = 3.0,
+    ) -> NfeResource:
+        """Aguarda até que a NF-e saia do status 'pending'."""
+        deadline = time.monotonic() + max_wait_s
+
+        while time.monotonic() < deadline:
+            nfe = self.get(nfe_id)
+            if nfe.status != "pending":
+                return nfe
+            time.sleep(poll_s)
+
+        raise FoxNfeException(f"NF-e {nfe_id} ainda pendente após {max_wait_s}s.")
+
+
+def _positive(v: int) -> None:
+    if not isinstance(v, int) or v < 1:
+        raise ValueError("id deve ser inteiro positivo.")