stackin-python-sdk 0.1.2__py3-none-any.whl → 0.3.0__py3-none-any.whl

stackin/__init__.py

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

stackin/core/client.py

@@ -36,6 +36,32 @@ def _resolve_base_url(
     return DEFAULT_BASE_URL
 
 
+_NFE_ADDRESS_FIELDS = (
+    "street",
+    "number",
+    "neighborhood",
+    "city",
+    "state",
+    "zip_code",
+    "city_code",
+)
+
+
+def _validate_nfe_address(address: Address | None) -> None:
+    """NFE needs the buyer's full address — a partial one is a SEFAZ rejection."""
+    if address is None:
+        raise ValueError("recipient_address is required for NFE")
+
+    missing = [
+        field for field in _NFE_ADDRESS_FIELDS if not getattr(address, field)
+    ]
+    if missing:
+        raise ValueError(
+            "recipient_address is missing required fields for NFE: "
+            + ", ".join(missing)
+        )
+
+
 class Invoice:
     """Client for issuing, consulting, and cancelling fiscal documents."""
 
@@ -61,6 +87,7 @@ class Invoice:
         recipient_address: Address | None = None,
         series: str | None = None,
         number: str | None = None,
+        idempotency_key: str | None = None,
     ) -> dict:
         """Issues a fiscal document."""
         if not items:
@@ -74,6 +101,7 @@ class Invoice:
                     raise ValueError(
                         f"items[{index}].cfop is required for NFE"
                     )
+            _validate_nfe_address(recipient_address)
 
         payload = {
             "document_type": document_type.value,
@@ -88,7 +116,12 @@ class Invoice:
         if number:
             payload["number"] = number
 
-        return self._request("POST", "/invoices", json=payload)
+        return self._request(
+            "POST",
+            "/invoices",
+            json=payload,
+            idempotency_key=idempotency_key,
+        )
 
     def consult(
         self,
@@ -118,10 +151,86 @@ class Invoice:
             "POST", f"/invoices/{access_key}/cancel", json=payload
         )
 
-    def _headers(self) -> dict:
+    def invalidate(
+        self,
+        *,
+        series: str,
+        number_start: int,
+        number_end: int,
+        reason: str,
+    ) -> dict:
+        """Reports a reserved but never used NFE numbering range."""
+        if not 15 <= len(reason) <= 255:
+            raise ValueError("reason must be 15 to 255 characters")
+        if number_end < number_start:
+            raise ValueError("number_end can't be below number_start")
+
+        payload = {
+            "series": series,
+            "number_start": number_start,
+            "number_end": number_end,
+            "reason": reason,
+        }
+
+        return self._request("POST", "/invoices/invalidations", json=payload)
+
+    def correct(
+        self,
+        access_key: str,
+        *,
+        document_type: DocumentType,
+        correction: str,
+    ) -> dict:
+        """Files a correction letter (CC-e) against an issued document."""
+        if not 15 <= len(correction) <= 1000:
+            raise ValueError("correction must be 15 to 1000 characters")
+
+        payload = {
+            "document_type": document_type.value,
+            "correction": correction,
+        }
+
+        return self._request(
+            "POST", f"/invoices/{access_key}/correction", json=payload
+        )
+
+    def reissue(
+        self, invoice_id: str, *, idempotency_key: str | None = None
+    ) -> dict:
+        """Retries a previous invoice submission by its local id."""
+        return self._request(
+            "POST",
+            f"/invoices/{invoice_id}/reissue",
+            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:
-            return {"Authorization": f"Bearer {self.api_key}"}
-        return {}
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return headers
 
     def _request(
         self,
@@ -130,7 +239,30 @@ class Invoice:
         *,
         json: dict | None = None,
         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:
@@ -139,21 +271,20 @@ class Invoice:
                 url,
                 json=json,
                 params=params,
-                headers=self._headers(),
+                headers=self._headers(idempotency_key),
                 timeout=self.timeout,
             )
         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.3.0.dist-info/METADATA

@@ -0,0 +1,214 @@
+Metadata-Version: 2.4
+Name: stackin-python-sdk
+Version: 0.3.0
+Summary: Python SDK for issuing, consulting and cancelling electronic invoices.
+License-Expression: MIT
+License-File: LICENSE
+Keywords: nfe,nfse,nota-fiscal,nota-fiscal-eletronica,invoice,fiscal-document,brazil,sefaz,e-invoicing
+Author: Fernando Celmer
+Author-email: email@fernandocelmer.com
+Requires-Python: >=3.10
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Office/Business :: Financial :: Accounting
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Natural Language :: Portuguese (Brazilian)
+Requires-Dist: pydantic
+Requires-Dist: requests
+Project-URL: Changelog, https://github.com/stackin-io/stackin-python-sdk/releases
+Project-URL: Documentation, https://docs.stackin.io/blog/python-sdk
+Project-URL: Homepage, https://docs.stackin.io
+Project-URL: Issues, https://github.com/stackin-io/stackin-python-sdk/issues
+Project-URL: Repository, https://github.com/stackin-io/stackin-python-sdk
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/stackin-io/stackin-python-sdk/master/docs/assets/stackin.png" width="120" />
+
+**Integrate once. Issue everywhere.**
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square)](pyproject.toml)
+[![PyPI](https://img.shields.io/pypi/v/stackin-python-sdk?style=flat-square)](https://pypi.org/project/stackin-python-sdk/)
+[![License](https://img.shields.io/badge/license-MIT-informational?style=flat-square)](https://github.com/stackin-io/stackin-python-sdk)
+
+[API Reference](https://docs.stackin.io) · [Python SDK guide](https://docs.stackin.io/blog/python-sdk)
+
+</div>
+
+---
+
+# stackin
+
+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()`/`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
+
+```bash
+pip install stackin-python-sdk
+```
+
+## Usage
+
+Get an `api_key` from the [stackin dashboard](https://app.stackin.io) — select the issuing company, then Settings → API key (context `sdk`). One key per issuing company, shown once at creation. The API resolves the issuer (CNPJ, state, address, certificate, environment) entirely from it; nothing about the issuer is ever passed on a call.
+
+```python
+from stackin import Invoice, DocumentType, Address
+from stackin.br import Product  # Brazil-specific line item — NCM/CFOP
+
+client = Invoice(api_key="COMPANY_API_KEY")  # defaults to https://sdk.stackin.io
+
+invoice = client.issue(
+    document_type=DocumentType.NFSE,
+    client_name="John Doe",
+    tax_id="00000000000",
+    items=[Product(description="Software development", amount=5000.00)],
+)
+
+status = client.consult("ACCESS_KEY...", document_type=DocumentType.NFSE)
+client.cancel(
+    "ACCESS_KEY...",
+    document_type=DocumentType.NFSE,
+    reason="Typo",
+)
+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,
+    client_name="Buyer Company Ltd",
+    tax_id="11111111111111",
+    items=[Product(description="Test product", amount=100.00, ncm="84713012", cfop="5102")],
+    recipient_address=Address(
+        street="Avenida Atlantica",
+        number="500",
+        neighborhood="Copacabana",
+        city="Rio de Janeiro",
+        state="RJ",
+        zip_code="22010000",
+        city_code="3304557",
+    ),
+)
+```
+
+`recipient_address` is an `Address` — the buyer's address, **required for NFE** and ignored for NFSE. Every field is required, `city_code` (the 7-digit IBGE municipality code) included: it becomes `enderDest` on the wire and the SEFAZ rejects a partial one. `state` is also what resolves `idDest` — a buyer in another state is emitted as an interstate operation automatically. A missing or incomplete address raises a `ValueError` locally, before the request goes out.
+
+`items` is a list of `Product` (`stackin.br`) — `description`/`amount` apply to any document type; `ncm`/`cfop` (plus everything else on `Product`: `cest`, tax groups, presumed credits...) are Brazil-specific and required per item for NFE, ignored for NFSE (a service isn't a physical good).
+
+## Retrying safely
+
+Issuing is the one call you must not repeat blindly. If the response is lost — a
+timeout, a dropped connection — the document may well have been authorized, and a
+second attempt issues a **second** fiscal document: another credit, another number
+burned, and undoing it means cancelling, which has a deadline.
+
+Pass `idempotency_key` to make the retry safe:
+
+```python
+key = str(uuid.uuid4())
+
+result = invoice.issue(
+    document_type=DocumentType.NFSE,
+    client_name="Maria Silva",
+    tax_id="12345678909",
+    items=[Product(description="Consultoria", amount=1500.00)],
+    idempotency_key=key,
+)
+```
+
+Retry with the **same key and the same body** and you get the first response back,
+replayed — no second document, no credit consumed. `reissue()` takes the same
+argument.
+
+| Situation | What the API does |
+|---|---|
+| New key | issues normally, records the response |
+| Same key, same body | replays the recorded response |
+| Same key, different body | `APIError` 422 |
+| Same key, first call still running | `APIError` 409 |
+| Previous attempt failed | key is released — the retry issues |
+| Key older than 24 hours | treated as new |
+
+Generate the key yourself and keep it for as long as you might retry — a `uuid4` per
+business event, not per HTTP call. The SDK never generates one, because a key minted
+per call would protect nothing, and because two genuinely separate invoices for the
+same customer and amount on the same day are a normal thing to issue.
+
+## Correcting a document
+
+Some mistakes don't need a cancellation. A wrong product name, wrong
+transport details, a typo in the extra information — a **CC-e** (carta de
+correção) fixes those, and it is free: no new credit, no burned series
+number, no reissue.
+
+```python
+result = invoice.correct(
+    "35240912345678000199550010000000011000000017",
+    document_type=DocumentType.NFE,
+    correction="Transportadora corrigida para Rapido Ltda",
+)
+```
+
+The correction text is 15 to 1000 characters, checked locally before the call.
+
+What a CC-e **cannot** fix: anything that changes the tax owed (base, rate,
+price, quantity, totals), the buyer or the seller, or the issue date. Those
+still mean cancelling and reissuing. The API sends the legally fixed wording
+that says exactly this, attached to every correction.
+
+The original document does not change — the CC-e is an event attached to it, and
+the authorized XML stays as it was. A document accepts at most 20 of them, and
+they are numbered for you.
+
+**NF-e only.** NFS-e has no correction letter, and asking for one returns
+a `409`.
+
+## Invalidating unused numbers
+
+NF-e numbering is sequential and the SEFAZ expects it to have no gaps. A number
+gets reserved the moment issuing starts, so a submission that fails afterwards —
+a rejection, a timeout — leaves a hole in the series. Reporting that range is how
+you close it.
+
+```python
+result = invoice.invalidate(
+    series="1",
+    number_start=10,
+    number_end=12,
+    reason="Numeracao reservada e nao utilizada por falha no ERP",
+)
+```
+
+The reason is 15 to 255 characters and the range is inclusive; both are checked
+locally, as is `number_end` not being below `number_start`.
+
+A number that already reached the authorizer can't be invalidated. The API checks
+its own records first and answers `409` naming the offending numbers, without a
+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.
+
+## 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.ConnectionFailedError` — the API didn't respond (network/DNS/timeout).
+- `ValueError` — `issue()`'s `items` is empty, missing `ncm`/`cfop` on an item for NFE, or a missing/incomplete `recipient_address` on NFE.
+
+Building the full fiscal document (issuer data, service code, tax groups, schema-accurate XML) is the API's job — configured once per company, not passed on every call.
+
+## Examples
+
+Runnable end-to-end scripts in [`examples/nfe/`](examples/nfe/) and [`examples/nfse/`](examples/nfse/) — one file per field/variant, from the bare minimum to every field filled. `examples/consult_invoice.py`, `examples/cancel_invoice.py`, and `examples/reissue_invoice.py` cover the operations that act on an already-issued document.
+

{stackin_python_sdk-0.1.2.dist-info → stackin_python_sdk-0.3.0.dist-info}/RECORD

@@ -1,13 +1,13 @@
-stackin/__init__.py,sha256=zY-ivw5Pckpw-tXwUmn4hwJzU4TZ6MJrW8RLEpPDG_c,495
+stackin/__init__.py,sha256=rsEjE3iiFCRB4EySvHJiK8B-OTrtB35teC6LHX9uo-Y,495
 stackin/br/__init__.py,sha256=Nw5VyeoFFJPqweZI60uADtBrxilXqkpzpkYtR5WZ630,656
 stackin/br/product.py,sha256=nuHQkWMz0eRmWYWPoduwmAfibBQvrcajEMxerwHGa9E,4004
 stackin/br/tax.py,sha256=PdUkg5JdNKy7AHlt5ZpM9svvilZA93FPMr2QNi0SRlw,7716
 stackin/core/__init__.py,sha256=dxtOP1DopMSNFYGh3Hf12RVcs58R9xwLn-gqfKFo-HE,19
 stackin/core/address.py,sha256=-w5R3nzfU5T3VoxIeygu5Dq4DRb_lJHAGc0lmSMwEMU,616
-stackin/core/client.py,sha256=abXZ71nz-skXM2afUOFNwY1j0_zlJRssihOQT4hwrXg,4591
+stackin/core/client.py,sha256=u8Q14sF844Pd0oMWy8AA0F4ry78p_s17mYprE2E8NNY,8486
 stackin/core/exceptions.py,sha256=enl8GS_WlDV6PyH1M_KTxzLG9Qdr-9MJrMXB_AlCtYg,521
 stackin/core/types.py,sha256=SYpLS2EnqKcudm7wFwCTOVAQe1IYT5T0TGSD0E6z8bo,416
-stackin_python_sdk-0.1.2.dist-info/METADATA,sha256=PRoF8vxBg3HZFqW3exHsmqeYT6JNLUuTnElpnyUJhwQ,5200
-stackin_python_sdk-0.1.2.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
-stackin_python_sdk-0.1.2.dist-info/licenses/LICENSE,sha256=D-XHDcKFFhzEo9C5Dp4QPvt00pb_u__hi4Bc08zpxyU,1072
-stackin_python_sdk-0.1.2.dist-info/RECORD,,
+stackin_python_sdk-0.3.0.dist-info/METADATA,sha256=pvDErFOVR0AphHcoXLuIU-cYwsHSgWvgEZLwwbctohI,9628
+stackin_python_sdk-0.3.0.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+stackin_python_sdk-0.3.0.dist-info/licenses/LICENSE,sha256=D-XHDcKFFhzEo9C5Dp4QPvt00pb_u__hi4Bc08zpxyU,1072
+stackin_python_sdk-0.3.0.dist-info/RECORD,,

stackin_python_sdk-0.1.2.dist-info/METADATA

@@ -1,108 +0,0 @@
-Metadata-Version: 2.4
-Name: stackin-python-sdk
-Version: 0.1.2
-Summary: Python SDK for issuing, consulting and cancelling electronic invoices.
-License-Expression: MIT
-License-File: LICENSE
-Keywords: nfe,nfse,nota-fiscal,nota-fiscal-eletronica,invoice,fiscal-document,brazil,sefaz,e-invoicing
-Author: Fernando Celmer
-Author-email: email@fernandocelmer.com
-Requires-Python: >=3.10
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Office/Business :: Financial :: Accounting
-Classifier: Topic :: Software Development :: Libraries :: Python Modules
-Classifier: Natural Language :: Portuguese (Brazilian)
-Requires-Dist: pydantic
-Requires-Dist: requests
-Project-URL: Changelog, https://github.com/stackin-io/stackin-python-sdk/releases
-Project-URL: Documentation, https://docs.stackin.io/blog/python-sdk
-Project-URL: Homepage, https://docs.stackin.io
-Project-URL: Issues, https://github.com/stackin-io/stackin-python-sdk/issues
-Project-URL: Repository, https://github.com/stackin-io/stackin-python-sdk
-Description-Content-Type: text/markdown
-
-<div align="center">
-
-<img src="https://raw.githubusercontent.com/stackin-io/stackin-python-sdk/master/docs/assets/stackin.png" width="120" />
-
-**Integrate once. Issue everywhere.**
-
-[![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square)](pyproject.toml)
-[![PyPI](https://img.shields.io/pypi/v/stackin-python-sdk?style=flat-square)](https://pypi.org/project/stackin-python-sdk/)
-[![License](https://img.shields.io/badge/license-MIT-informational?style=flat-square)](https://github.com/stackin-io/stackin-python-sdk)
-
-[API Reference](https://docs.stackin.io) · [Python SDK guide](https://docs.stackin.io/blog/python-sdk)
-
-</div>
-
----
-
-# stackin
-
-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()`, 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
-
-```bash
-pip install stackin-python-sdk
-```
-
-## Usage
-
-Get an `api_key` from the [stackin dashboard](https://app.stackin.io) — select the issuing company, then Settings → API key (context `sdk`). One key per issuing company, shown once at creation. The API resolves the issuer (CNPJ, state, address, certificate, environment) entirely from it; nothing about the issuer is ever passed on a call.
-
-```python
-from stackin import Invoice, DocumentType, Address
-from stackin.br import Product  # Brazil-specific line item — NCM/CFOP
-
-client = Invoice(api_key="COMPANY_API_KEY")  # defaults to https://sdk.stackin.io
-
-invoice = client.issue(
-    document_type=DocumentType.NFSE,
-    client_name="John Doe",
-    tax_id="00000000000",
-    items=[Product(description="Software development", amount=5000.00)],
-)
-
-status = client.consult("ACCESS_KEY...", document_type=DocumentType.NFSE)
-client.cancel(
-    "ACCESS_KEY...",
-    document_type=DocumentType.NFSE,
-    reason="Typo",
-)
-
-# NFE requires ncm/cfop on every item, and optionally recipient_address.state
-# to get idDest right on interstate sales:
-client.issue(
-    document_type=DocumentType.NFE,
-    client_name="Buyer Company Ltd",
-    tax_id="11111111111111",
-    items=[Product(description="Test product", amount=100.00, ncm="84713012", cfop="5102")],
-    recipient_address=Address(state="RJ"),
-)
-```
-
-`recipient_address` is an `Address`, but despite the name only `.state` is read — the rest of the fields aren't sent anywhere yet. It's the actual customer's state, used only to set `idDest` (interstate vs internal) on NFE — optional, omitting it always produces `idDest=1` (internal).
-
-`items` is a list of `Product` (`stackin.br`) — `description`/`amount` apply to any document type; `ncm`/`cfop` (plus everything else on `Product`: `cest`, tax groups, presumed credits...) are Brazil-specific and required per item for NFE, ignored for NFSE (a service isn't a physical good).
-
-## 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.ConnectionFailedError` — the API didn't respond (network/DNS/timeout).
-- `ValueError` — `issue()`'s `items` is empty, or missing `ncm`/`cfop` on an item for NFE.
-
-Building the full fiscal document (issuer data, service code, tax groups, schema-accurate XML) is the API's job — configured once per company, not passed on every call.
-
-## Examples
-
-Runnable end-to-end scripts in [`examples/nfe/`](examples/nfe/) and [`examples/nfse/`](examples/nfse/) — one file per field/variant, from the bare minimum to every field filled.
-