stackin-python-sdk 0.2.0__tar.gz → 0.3.1__tar.gz

{stackin_python_sdk-0.2.0 → stackin_python_sdk-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackin-python-sdk
-Version: 0.2.0
+Version: 0.3.1
 Summary: Python SDK for issuing, consulting and cancelling electronic invoices.
 License-Expression: MIT
 License-File: LICENSE
@@ -47,7 +47,7 @@ Description-Content-Type: text/markdown
 
 Python SDK for fiscal document issuance — a handful of business fields, nothing about certificates, XML, XSD, signing or SOAP. The API resolves all of that from the issuer's own configuration, identified by `api_key`.
 
-**One class, `Invoice`** — `issue()`/`consult()`/`cancel()`/`reissue()`, nothing else to instantiate. Each line item is a `Product` (`stackin.br`) — `description`/`amount` are universal, everything else (`ncm`/`cfop`/`cest`/tax groups...) is Brazil-specific and only required for NFE; NFSE ignores it.
+**One class, `Invoice`** — `issue()`/`consult()`/`cancel()`/`reissue()`/`correct()`/`invalidate()`/`pdf()`/`received()`/`manifest()`, nothing else to instantiate. Each line item is a `Product` (`stackin.br`) — `description`/`amount` are universal, everything else (`ncm`/`cfop`/`cest`/tax groups...) is Brazil-specific and only required for NFE; NFSE ignores it.
 
 ## Install
 
@@ -80,6 +80,11 @@ client.cancel(
 )
 client.reissue(invoice["id"])  # retries a rejected/failed submission
 
+# The authorizer's PDF, as raw bytes. NFS-e only; the XML stays the
+# legally valid document, and a 502 here means the authorizer is down.
+with open("nota.pdf", "wb") as file:
+    file.write(client.pdf(access_key, document_type=DocumentType.NFSE))
+
 # NFE requires ncm/cfop on every item, plus the buyer's full recipient_address:
 client.issue(
     document_type=DocumentType.NFE,
@@ -195,6 +200,40 @@ round trip — and the authorizer checks again for what we can't see from here.
 
 **NF-e only**, and it takes no access key: there is no document to point at.
 
+## Documents issued against you
+
+Everything above serves the **issuer**. These two serve the **recipient**: what
+suppliers billed to this CNPJ, and the formal answer to it.
+
+Reading the list never calls the SEFAZ. The authorizer caps how many times a CNPJ
+may ask for its distribution per day, so collecting runs on a schedule on the API
+side and a page refresh cannot spend that allowance.
+
+```python
+from stackin import Manifestation
+
+page = client.received(limit=20)
+for document in page["data"]:
+    print(document["access_key"], document["issuer_name"], document["amount"])
+
+client.manifest(access_key, manifestation=Manifestation.CIENCIA)
+client.manifest(
+    access_key,
+    manifestation=Manifestation.OPERACAO_NAO_REALIZADA,
+    reason="Mercadoria nunca chegou ao endereco",
+)
+```
+
+Before you answer a document the SEFAZ sends only a **summary** (`resNFe`): access
+key, issuer, amount, date. The **full document** (`nfeProc`) arrives after a
+manifestation, and the `schema` field on each row says which one you hold.
+
+The four answers are `210200` Confirmação da Operação, `210210` Ciência da
+Operação, `210220` Desconhecimento da Operação and `210240` Operação não
+Realizada. Only the last one takes a reason, and it requires one — both rules are
+checked locally, before the request goes out, because a round trip to be told a
+fixed rule is a round trip wasted.
+
 ## Errors
 
 - `stackin.APIError` — the API responded with a non-2xx status (`status_code`, `detail`) — a 401 here means `api_key` is missing, wrong, or was rotated.

{stackin_python_sdk-0.2.0 → stackin_python_sdk-0.3.1}/README.md

@@ -18,7 +18,7 @@
 
 Python SDK for fiscal document issuance — a handful of business fields, nothing about certificates, XML, XSD, signing or SOAP. The API resolves all of that from the issuer's own configuration, identified by `api_key`.
 
-**One class, `Invoice`** — `issue()`/`consult()`/`cancel()`/`reissue()`, nothing else to instantiate. Each line item is a `Product` (`stackin.br`) — `description`/`amount` are universal, everything else (`ncm`/`cfop`/`cest`/tax groups...) is Brazil-specific and only required for NFE; NFSE ignores it.
+**One class, `Invoice`** — `issue()`/`consult()`/`cancel()`/`reissue()`/`correct()`/`invalidate()`/`pdf()`/`received()`/`manifest()`, nothing else to instantiate. Each line item is a `Product` (`stackin.br`) — `description`/`amount` are universal, everything else (`ncm`/`cfop`/`cest`/tax groups...) is Brazil-specific and only required for NFE; NFSE ignores it.
 
 ## Install
 
@@ -51,6 +51,11 @@ client.cancel(
 )
 client.reissue(invoice["id"])  # retries a rejected/failed submission
 
+# The authorizer's PDF, as raw bytes. NFS-e only; the XML stays the
+# legally valid document, and a 502 here means the authorizer is down.
+with open("nota.pdf", "wb") as file:
+    file.write(client.pdf(access_key, document_type=DocumentType.NFSE))
+
 # NFE requires ncm/cfop on every item, plus the buyer's full recipient_address:
 client.issue(
     document_type=DocumentType.NFE,
@@ -166,6 +171,40 @@ round trip — and the authorizer checks again for what we can't see from here.
 
 **NF-e only**, and it takes no access key: there is no document to point at.
 
+## Documents issued against you
+
+Everything above serves the **issuer**. These two serve the **recipient**: what
+suppliers billed to this CNPJ, and the formal answer to it.
+
+Reading the list never calls the SEFAZ. The authorizer caps how many times a CNPJ
+may ask for its distribution per day, so collecting runs on a schedule on the API
+side and a page refresh cannot spend that allowance.
+
+```python
+from stackin import Manifestation
+
+page = client.received(limit=20)
+for document in page["data"]:
+    print(document["access_key"], document["issuer_name"], document["amount"])
+
+client.manifest(access_key, manifestation=Manifestation.CIENCIA)
+client.manifest(
+    access_key,
+    manifestation=Manifestation.OPERACAO_NAO_REALIZADA,
+    reason="Mercadoria nunca chegou ao endereco",
+)
+```
+
+Before you answer a document the SEFAZ sends only a **summary** (`resNFe`): access
+key, issuer, amount, date. The **full document** (`nfeProc`) arrives after a
+manifestation, and the `schema` field on each row says which one you hold.
+
+The four answers are `210200` Confirmação da Operação, `210210` Ciência da
+Operação, `210220` Desconhecimento da Operação and `210240` Operação não
+Realizada. Only the last one takes a reason, and it requires one — both rules are
+checked locally, before the request goes out, because a round trip to be told a
+fixed rule is a round trip wasted.
+
 ## Errors
 
 - `stackin.APIError` — the API responded with a non-2xx status (`status_code`, `detail`) — a 401 here means `api_key` is missing, wrong, or was rotated.

{stackin_python_sdk-0.2.0 → stackin_python_sdk-0.3.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackin-python-sdk"
-version = "0.2.0"
+version = "0.3.1"
 authors = [
   { name = "Fernando Celmer", email = "email@fernandocelmer.com" },
 ]
@@ -45,7 +45,7 @@ Changelog = "https://github.com/stackin-io/stackin-python-sdk/releases"
 
 [tool.poetry]
 name = "stackin-python-sdk"
-version = "0.2.0"
+version = "0.3.1"
 description = "Python SDK for issuing, consulting and cancelling electronic invoices."
 authors = ["Fernando Celmer <email@fernandocelmer.com>"]
 readme = "README.md"

{stackin_python_sdk-0.2.0 → stackin_python_sdk-0.3.1}/stackin/__init__.py

@@ -1,6 +1,6 @@
 """Invoice __init__ module."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.1"
 __description__ = (
     "Python SDK for issuing, consulting and cancelling electronic invoices."
 )
@@ -8,12 +8,13 @@ __description__ = (
 from .core.address import Address
 from .core.client import Invoice
 from .core.exceptions import APIError, ConnectionFailedError, InvoiceError
-from .core.types import DocumentType, Environment
+from .core.types import DocumentType, Environment, Manifestation
 
 __all__ = [
     "Invoice",
     "DocumentType",
     "Environment",
+    "Manifestation",
     "Address",
     "InvoiceError",
     "APIError",

{stackin_python_sdk-0.2.0 → stackin_python_sdk-0.3.1}/stackin/br/product.py

@@ -67,7 +67,10 @@ class Product(BaseModel):
     ex_tipi: str | None = Field(default=None, pattern=r"^\d{2,3}$")
     import_content_control_number: str | None = Field(
         default=None,
-        pattern=r"^[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{4}-[A-F0-9]{12}$",
+        pattern=(
+            r"^[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}"
+            r"-[A-F0-9]{4}-[A-F0-9]{12}$"
+        ),
     )
     recopi_number: str | None = Field(default=None, pattern=r"^\d{20}$")
     extra_groups: dict[str, Any] | None = Field(default=None)

{stackin_python_sdk-0.2.0 → stackin_python_sdk-0.3.1}/stackin/core/client.py

@@ -9,7 +9,7 @@ import requests
 from stackin.br.product import Product
 from stackin.core.address import Address
 from stackin.core.exceptions import APIError, ConnectionFailedError
-from stackin.core.types import DocumentType, Environment
+from stackin.core.types import DocumentType, Environment, Manifestation
 
 DEFAULT_BASE_URL = "https://sdk.stackin.io"
 
@@ -23,7 +23,7 @@ _ENVIRONMENT_URLS = {
 def _resolve_base_url(
     base_url: str | None, environment: Environment | str | None
 ) -> str:
-    """Resolution order: explicit param, then env var, then environment's default."""
+    """Explicit param, then env var, then the environment's default."""
     if base_url:
         return base_url
     if url := os.environ.get("STACKIN_BASE_URL"):
@@ -48,7 +48,7 @@ _NFE_ADDRESS_FIELDS = (
 
 
 def _validate_nfe_address(address: Address | None) -> None:
-    """NFE needs the buyer's full address — a partial one is a SEFAZ rejection."""
+    """NFE needs the full address — a partial one the SEFAZ rejects."""
     if address is None:
         raise ValueError("recipient_address is required for NFE")
 
@@ -204,6 +204,81 @@ class Invoice:
             idempotency_key=idempotency_key,
         )
 
+    def pdf(
+        self,
+        access_key: str,
+        *,
+        document_type: DocumentType,
+    ) -> bytes:
+        """The authorizer's rendering of an authorized document.
+
+        Returns raw bytes — the only method that does not return a
+        parsed object. The XML is the legally valid document; this is a
+        convenience, and the authorizer's endpoint for it is unstable,
+        so an APIError with status 502 means the authorizer is
+        unavailable, not that the invoice is wrong. NFS-e only.
+        """
+        params = {"document_type": document_type.value}
+        response = self._send(
+            "GET", f"/invoices/{access_key}/pdf", params=params
+        )
+        return response.content
+
+    def received(
+        self,
+        *,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> dict:
+        """Documents other companies issued against this one.
+
+        Reads what the API already collected; it does not call the
+        authorizer. Collecting runs on a schedule there, because the
+        SEFAZ caps how many times a CNPJ may ask per day.
+        """
+        params = {}
+        if limit is not None:
+            params["limit"] = limit
+        if offset is not None:
+            params["offset"] = offset
+
+        return self._request("GET", "/received-invoices", params=params)
+
+    def manifest(
+        self,
+        access_key: str,
+        *,
+        manifestation: Manifestation,
+        reason: str | None = None,
+    ) -> dict:
+        """The recipient's formal answer to a received document.
+
+        Only `OPERACAO_NAO_REALIZADA` takes a reason, and it requires
+        one. Both are fixed rules, so they are checked here rather than
+        spending a round trip to be told.
+        """
+        needs_reason = manifestation is Manifestation.OPERACAO_NAO_REALIZADA
+        if needs_reason and not reason:
+            raise ValueError(
+                "manifestation 210240 (operação não realizada) requires "
+                "a reason"
+            )
+        if not needs_reason and reason:
+            raise ValueError(
+                f"manifestation {manifestation.value} does not take a "
+                "reason"
+            )
+
+        payload = {"manifestation": manifestation.value}
+        if reason:
+            payload["reason"] = reason
+
+        return self._request(
+            "POST",
+            f"/received-invoices/{access_key}/manifestation",
+            json=payload,
+        )
+
     def _headers(self, idempotency_key: str | None = None) -> dict:
         headers = {}
         if self.api_key:
@@ -221,6 +296,28 @@ class Invoice:
         params: dict | None = None,
         idempotency_key: str | None = None,
     ) -> dict:
+        response = self._send(
+            method,
+            path,
+            json=json,
+            params=params,
+            idempotency_key=idempotency_key,
+        )
+        try:
+            body = response.json() if response.content else {}
+        except ValueError:
+            body = {}
+        return body.get("result", body)
+
+    def _send(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict | None = None,
+        params: dict | None = None,
+        idempotency_key: str | None = None,
+    ) -> requests.Response:
         url = f"{self.base_url}/api/v1{path}"
 
         try:
@@ -235,15 +332,14 @@ class Invoice:
         except requests.RequestException as error:
             raise ConnectionFailedError(str(error)) from error
 
-        try:
-            body = response.json() if response.content else {}
-        except ValueError:
-            body = {}
-
         if not response.ok:
+            try:
+                body = response.json() if response.content else {}
+            except ValueError:
+                body = {}
             raise APIError(
                 status_code=response.status_code,
                 detail=body.get("detail", response.text),
             )
 
-        return body.get("result", body)
+        return response

{stackin_python_sdk-0.2.0 → stackin_python_sdk-0.3.1}/stackin/core/exceptions.py

@@ -15,4 +15,4 @@ class APIError(InvoiceError):
 
 
 class ConnectionFailedError(InvoiceError):
-    """Raised when the invoice API can't be reached at all (network/DNS/timeout)."""
+    """The API could not be reached at all (network/DNS/timeout)."""

{stackin_python_sdk-0.2.0 → stackin_python_sdk-0.3.1}/stackin/core/types.py

@@ -13,8 +13,17 @@ class DocumentType(str, Enum):
 
 
 class Environment(str, Enum):
-    """Which host to talk to — pass to `Invoice(environment=...)` instead of a raw `base_url`."""
+    """Which host to talk to, instead of a raw `base_url`."""
 
     LOCAL = "local"
     TEST = "test"
     PRODUCTION = "production"
+
+
+class Manifestation(str, Enum):
+    """The recipient's four possible answers to a received document."""
+
+    CONFIRMACAO = "210200"
+    CIENCIA = "210210"
+    DESCONHECIMENTO = "210220"
+    OPERACAO_NAO_REALIZADA = "210240"