foxnfe 1.3.0__tar.gz

foxnfe-1.3.0/PKG-INFO

@@ -0,0 +1,260 @@
+Metadata-Version: 2.4
+Name: foxnfe
+Version: 1.3.0
+Summary: SDK oficial FOX NF-e para Python — emissão NF-e, NFSe, cancelamento, consulta e MCP
+Author-email: Central Fox Tecnologia <dev@centralfox.online>
+License: MIT
+Project-URL: Homepage, https://centralfox.online
+Project-URL: Documentation, https://docs.centralfox.online/sdks/python
+Project-URL: Repository, https://github.com/foxdigital/foxnfe-python
+Keywords: nfe,nfse,nota-fiscal,fiscal,brasil
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Topic :: Office/Business :: Financial
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28.0
+
+# foxnfe (Python SDK)
+
+SDK oficial FOX NF-e para Python — emissão NF-e, NFSe, cancelamento, consulta e integração MCP.
+
+## Requisitos
+
+- Python 3.9+
+- [requests](https://requests.readthedocs.io) `>=2.28`
+
+## Instalação
+
+```bash
+pip install foxnfe
+# ou
+poetry add foxnfe
+# ou
+uv add foxnfe
+```
+
+## Quick Start
+
+```python
+from foxnfe import Client
+
+client = Client(tenant_slug="minha-empresa")
+
+# Autenticar
+auth = client.login("email@empresa.com", "senha-segura")
+print(f"Token: {auth.token}")
+
+# Ou usar token existente
+client = Client(tenant_slug="minha-empresa", token="seu-token-aqui")
+# Ou via with_token (retorna nova instância)
+authed = client.with_token("seu-token-aqui")
+```
+
+## NF-e
+
+```python
+from foxnfe import Client, NfeEmitRequest
+
+client = Client(tenant_slug="minha-empresa", token="seu-token")
+
+payload = NfeEmitRequest(
+    ambiente=2,  # 2=homologação
+    certificate_id=1,
+    tomador={
+        "cnpj": "12345678000190",
+        "razao_social": "Empresa Tomadora Ltda",
+        "endereco": {
+            "logradouro": "Rua das Flores",
+            "numero": "100",
+            "municipio": "São Paulo",
+            "uf": "SP",
+            "cep": "01310100",
+        },
+    },
+    itens=[{
+        "codigo": "SRV001",
+        "descricao": "Serviço de consultoria",
+        "cfop": "5933",
+        "quantidade": 1,
+        "valor_unitario": 1000.00,
+        "valor_total": 1000.00,
+    }],
+    pagamentos=[{"forma": "01", "valor": 1000.00}],
+    total=1000.00,
+)
+
+result = client.nfe.emit(payload)
+print(f"NF-e ID: {result['id']}")
+
+# Aguardar autorização (polling automático)
+nfe_autorizada = client.nfe.wait_for_authorization(result["id"])
+print(f"Status: {nfe_autorizada.status}")  # authorized
+
+# Baixar XML
+xml_bytes = client.nfe.xml(result["id"])
+with open("nfe.xml", "wb") as f:
+    f.write(xml_bytes)
+
+# Baixar DANFE PDF
+pdf_bytes = client.nfe.pdf(result["id"])
+with open("danfe.pdf", "wb") as f:
+    f.write(pdf_bytes)
+
+# Cancelar
+client.nfe.cancel(result["id"], "Cancelamento solicitado pelo cliente")
+```
+
+## NFSe
+
+```python
+from foxnfe import Client, NfseEmitRequest
+
+client = Client(tenant_slug="minha-empresa", token="seu-token")
+
+payload = NfseEmitRequest(
+    ambiente=2,
+    certificate_id=1,
+    prestador={
+        "cnpj": "12345678000190",
+        "inscricao_municipal": "123456",
+        "razao_social": "Minha Empresa Ltda",
+        "codigo_municipio": "3550308",  # São Paulo (IBGE)
+    },
+    tomador={
+        "cnpj": "98765432000110",
+        "nome": "Cliente S.A.",
+    },
+    servico={
+        "codigo_tributacao_nacional": "01.01.00001",
+        "descricao": "Desenvolvimento de software",
+        "data_competencia": "2026-05-01",
+        "valor": 5000.00,
+        "aliquota_iss": 2.0,
+    },
+)
+
+result = client.nfse.emit(payload)
+nfse = client.nfse.get(result["id"])
+print(f"Número NFSe: {nfse.numero_nfse}")
+
+# Consultar por RPS ou chave
+client.nfse.consult_by_numero("00000001")
+client.nfse.consult_by_chave("SP3550308202605010000000000001")
+
+# Cancelar / Substituir
+client.nfse.cancel(result["id"], "Erro nos dados do tomador")
+client.nfse.substitute(result["id"], payload, "Correção de dados")
+```
+
+## MCP (Model Context Protocol)
+
+```python
+from foxnfe import Client
+
+client = Client(tenant_slug="minha-empresa", token="seu-token")
+
+# Inicializar sessão MCP
+info = client.mcp.initialize()
+print(f"MCP Server: {info['result']['serverInfo']['name']}")
+
+# Listar tools
+tools = client.mcp.list_tools()
+for tool in tools:
+    print(f"{tool.name}: {tool.description}")
+
+# Chamar uma tool
+result = client.mcp.call_tool("emitir_nfe", {
+    "ambiente": 2,
+    "certificate_id": 1,
+})
+
+if result.get("result", {}).get("isError"):
+    print("Tool error:", result["result"]["content"][0]["text"])
+else:
+    print("Tool result:", result["result"]["content"][0]["text"])
+```
+
+## Tratamento de Erros
+
+```python
+from foxnfe import Client
+from foxnfe.exceptions import ApiException, AuthException, FoxNfeException
+
+try:
+    client.nfe.emit(payload)
+except AuthException as e:
+    # Token inválido ou expirado (401/403)
+    print(f"Auth error: {e}")
+except ApiException as e:
+    # Erro da API (422, 500, etc.)
+    print(f"API error {e.status_code}: {e}")
+    print(f"Body: {e.response_body}")
+except FoxNfeException as e:
+    # Timeout, erro de conexão, etc.
+    print(f"SDK error: {e}")
+```
+
+## Uso com context manager
+
+```python
+from foxnfe import Client
+
+# Client usa requests.Session internamente (pode ser fechado manualmente)
+client = Client(tenant_slug="minha-empresa", token="seu-token")
+try:
+    result = client.nfe.emit(payload)
+finally:
+    client._session.close()
+```
+
+## Configuração avançada
+
+```python
+client = Client(
+    tenant_slug="minha-empresa",
+    token="seu-token",
+    base_url="https://sandbox.centralfox.online/api/v1",
+    timeout=60.0,
+)
+```
+
+## Estrutura do pacote
+
+```
+foxnfe/
+├── __init__.py      # Exports públicos
+├── client.py        # Cliente HTTP principal
+├── nfe.py           # Módulo NF-e
+├── nfse.py          # Módulo NFSe
+├── mcp.py           # Módulo MCP
+├── types.py         # Dataclasses com tipagem
+└── exceptions.py    # Classes de erro
+```
+
+## Links
+
+- [Documentação API](https://docs.centralfox.online)
+- [Portal FOX NF-e](https://foxnfe.centralfox.online)
+- [Suporte](mailto:suporte@centralfox.online)
+
+## 1.3.0 — eventos, rejeições, homologação, RTC, cobertura NFS-e e suporte
+
+```python
+ev = client.nfe_events
+ev.ator_interessado(15, "11222333000181")                       # 110150
+ev.insucesso_entrega(15, "2026-09-08T10:00:00-03:00", tp_motivo=1)  # 110192
+ev.inutilizar(serie=1, numero_inicial=10, numero_final=12, justificativa="Numeração pulada por falha do ERP")
+ev.contratos(); ev.registrar_evento(15, "econf", {...})           # eventos por contrato (conciliação financeira, RTC…)
+
+client.nfe.rejeicao("539"); client.nfe.homologacao_run(65)         # rejeições explicadas / amostras simuladas
+client.nfse.cobertura_municipio("2304400")                        # driver, operações e provas
+client.rtc.verify_resolution("550e8400-e29b-41d4-a716-446655440000")
+client.support.create_case("Webhook sem entrega desde ontem", priority="high")
+```
+
+Validação local (ids, dígitos, tamanhos, enums) antes do transporte; regra fiscal fica na API. `NfeResource.rejection` traz a rejeição classificada.

foxnfe-1.3.0/README.md

@@ -0,0 +1,239 @@
+# foxnfe (Python SDK)
+
+SDK oficial FOX NF-e para Python — emissão NF-e, NFSe, cancelamento, consulta e integração MCP.
+
+## Requisitos
+
+- Python 3.9+
+- [requests](https://requests.readthedocs.io) `>=2.28`
+
+## Instalação
+
+```bash
+pip install foxnfe
+# ou
+poetry add foxnfe
+# ou
+uv add foxnfe
+```
+
+## Quick Start
+
+```python
+from foxnfe import Client
+
+client = Client(tenant_slug="minha-empresa")
+
+# Autenticar
+auth = client.login("email@empresa.com", "senha-segura")
+print(f"Token: {auth.token}")
+
+# Ou usar token existente
+client = Client(tenant_slug="minha-empresa", token="seu-token-aqui")
+# Ou via with_token (retorna nova instância)
+authed = client.with_token("seu-token-aqui")
+```
+
+## NF-e
+
+```python
+from foxnfe import Client, NfeEmitRequest
+
+client = Client(tenant_slug="minha-empresa", token="seu-token")
+
+payload = NfeEmitRequest(
+    ambiente=2,  # 2=homologação
+    certificate_id=1,
+    tomador={
+        "cnpj": "12345678000190",
+        "razao_social": "Empresa Tomadora Ltda",
+        "endereco": {
+            "logradouro": "Rua das Flores",
+            "numero": "100",
+            "municipio": "São Paulo",
+            "uf": "SP",
+            "cep": "01310100",
+        },
+    },
+    itens=[{
+        "codigo": "SRV001",
+        "descricao": "Serviço de consultoria",
+        "cfop": "5933",
+        "quantidade": 1,
+        "valor_unitario": 1000.00,
+        "valor_total": 1000.00,
+    }],
+    pagamentos=[{"forma": "01", "valor": 1000.00}],
+    total=1000.00,
+)
+
+result = client.nfe.emit(payload)
+print(f"NF-e ID: {result['id']}")
+
+# Aguardar autorização (polling automático)
+nfe_autorizada = client.nfe.wait_for_authorization(result["id"])
+print(f"Status: {nfe_autorizada.status}")  # authorized
+
+# Baixar XML
+xml_bytes = client.nfe.xml(result["id"])
+with open("nfe.xml", "wb") as f:
+    f.write(xml_bytes)
+
+# Baixar DANFE PDF
+pdf_bytes = client.nfe.pdf(result["id"])
+with open("danfe.pdf", "wb") as f:
+    f.write(pdf_bytes)
+
+# Cancelar
+client.nfe.cancel(result["id"], "Cancelamento solicitado pelo cliente")
+```
+
+## NFSe
+
+```python
+from foxnfe import Client, NfseEmitRequest
+
+client = Client(tenant_slug="minha-empresa", token="seu-token")
+
+payload = NfseEmitRequest(
+    ambiente=2,
+    certificate_id=1,
+    prestador={
+        "cnpj": "12345678000190",
+        "inscricao_municipal": "123456",
+        "razao_social": "Minha Empresa Ltda",
+        "codigo_municipio": "3550308",  # São Paulo (IBGE)
+    },
+    tomador={
+        "cnpj": "98765432000110",
+        "nome": "Cliente S.A.",
+    },
+    servico={
+        "codigo_tributacao_nacional": "01.01.00001",
+        "descricao": "Desenvolvimento de software",
+        "data_competencia": "2026-05-01",
+        "valor": 5000.00,
+        "aliquota_iss": 2.0,
+    },
+)
+
+result = client.nfse.emit(payload)
+nfse = client.nfse.get(result["id"])
+print(f"Número NFSe: {nfse.numero_nfse}")
+
+# Consultar por RPS ou chave
+client.nfse.consult_by_numero("00000001")
+client.nfse.consult_by_chave("SP3550308202605010000000000001")
+
+# Cancelar / Substituir
+client.nfse.cancel(result["id"], "Erro nos dados do tomador")
+client.nfse.substitute(result["id"], payload, "Correção de dados")
+```
+
+## MCP (Model Context Protocol)
+
+```python
+from foxnfe import Client
+
+client = Client(tenant_slug="minha-empresa", token="seu-token")
+
+# Inicializar sessão MCP
+info = client.mcp.initialize()
+print(f"MCP Server: {info['result']['serverInfo']['name']}")
+
+# Listar tools
+tools = client.mcp.list_tools()
+for tool in tools:
+    print(f"{tool.name}: {tool.description}")
+
+# Chamar uma tool
+result = client.mcp.call_tool("emitir_nfe", {
+    "ambiente": 2,
+    "certificate_id": 1,
+})
+
+if result.get("result", {}).get("isError"):
+    print("Tool error:", result["result"]["content"][0]["text"])
+else:
+    print("Tool result:", result["result"]["content"][0]["text"])
+```
+
+## Tratamento de Erros
+
+```python
+from foxnfe import Client
+from foxnfe.exceptions import ApiException, AuthException, FoxNfeException
+
+try:
+    client.nfe.emit(payload)
+except AuthException as e:
+    # Token inválido ou expirado (401/403)
+    print(f"Auth error: {e}")
+except ApiException as e:
+    # Erro da API (422, 500, etc.)
+    print(f"API error {e.status_code}: {e}")
+    print(f"Body: {e.response_body}")
+except FoxNfeException as e:
+    # Timeout, erro de conexão, etc.
+    print(f"SDK error: {e}")
+```
+
+## Uso com context manager
+
+```python
+from foxnfe import Client
+
+# Client usa requests.Session internamente (pode ser fechado manualmente)
+client = Client(tenant_slug="minha-empresa", token="seu-token")
+try:
+    result = client.nfe.emit(payload)
+finally:
+    client._session.close()
+```
+
+## Configuração avançada
+
+```python
+client = Client(
+    tenant_slug="minha-empresa",
+    token="seu-token",
+    base_url="https://sandbox.centralfox.online/api/v1",
+    timeout=60.0,
+)
+```
+
+## Estrutura do pacote
+
+```
+foxnfe/
+├── __init__.py      # Exports públicos
+├── client.py        # Cliente HTTP principal
+├── nfe.py           # Módulo NF-e
+├── nfse.py          # Módulo NFSe
+├── mcp.py           # Módulo MCP
+├── types.py         # Dataclasses com tipagem
+└── exceptions.py    # Classes de erro
+```
+
+## Links
+
+- [Documentação API](https://docs.centralfox.online)
+- [Portal FOX NF-e](https://foxnfe.centralfox.online)
+- [Suporte](mailto:suporte@centralfox.online)
+
+## 1.3.0 — eventos, rejeições, homologação, RTC, cobertura NFS-e e suporte
+
+```python
+ev = client.nfe_events
+ev.ator_interessado(15, "11222333000181")                       # 110150
+ev.insucesso_entrega(15, "2026-09-08T10:00:00-03:00", tp_motivo=1)  # 110192
+ev.inutilizar(serie=1, numero_inicial=10, numero_final=12, justificativa="Numeração pulada por falha do ERP")
+ev.contratos(); ev.registrar_evento(15, "econf", {...})           # eventos por contrato (conciliação financeira, RTC…)
+
+client.nfe.rejeicao("539"); client.nfe.homologacao_run(65)         # rejeições explicadas / amostras simuladas
+client.nfse.cobertura_municipio("2304400")                        # driver, operações e provas
+client.rtc.verify_resolution("550e8400-e29b-41d4-a716-446655440000")
+client.support.create_case("Webhook sem entrega desde ontem", priority="high")
+```
+
+Validação local (ids, dígitos, tamanhos, enums) antes do transporte; regra fiscal fica na API. `NfeResource.rejection` traz a rejeição classificada.

foxnfe-1.3.0/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-1.3.0/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