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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackin-python-sdk
-Version: 0.2.0
+Version: 0.3.0
 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()`, 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,

{stackin_python_sdk-0.2.0 → stackin_python_sdk-0.3.0}/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()`, 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,

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

@@ -1,6 +1,6 @@
 [project]
 name = "stackin-python-sdk"
-version = "0.2.0"
+version = "0.3.0"
 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.0"
 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.0}/stackin/__init__.py

@@ -1,6 +1,6 @@
 """Invoice __init__ module."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 __description__ = (
     "Python SDK for issuing, consulting and cancelling electronic invoices."
 )

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

@@ -204,6 +204,26 @@ 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 _headers(self, idempotency_key: str | None = None) -> dict:
         headers = {}
         if self.api_key:
@@ -221,6 +241,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 +277,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