stackin-python-sdk 0.8.0__tar.gz → 0.10.0__tar.gz

{stackin_python_sdk-0.8.0 → stackin_python_sdk-0.10.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackin-python-sdk
-Version: 0.8.0
+Version: 0.10.0
 Summary: Python SDK for issuing, consulting and cancelling electronic invoices.
 License-Expression: MIT
 License-File: LICENSE
@@ -137,7 +137,7 @@ invoice = client.issue(
     document_type=DocumentType.NFSE,
     client_name="John Doe",
     tax_id="00000000000",
-    items=[Product(description="Software development", amount=5000.00)],
+    items=[Product(description="Software development", unit_price=Decimal("5000.00"))],
 )
 
 status = client.consult("ACCESS_KEY...", document_type=DocumentType.NFSE)
@@ -194,13 +194,15 @@ burned, and undoing it means cancelling, which has a deadline.
 Pass `idempotency_key` to make the retry safe:
 
 ```python
+from decimal import Decimal
+
 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)],
+    items=[Product(description="Consultoria", unit_price=Decimal("1500.00"))],
     idempotency_key=key,
 )
 ```
@@ -311,6 +313,37 @@ Realizada. Only the last one takes a reason, and it requires one — both rules
 checked locally, before the request goes out, because a round trip to be told a
 fixed rule is a round trip wasted.
 
+## Looking up a code, or who a CNPJ belongs to
+
+Two more clients, for the tables an issuer reads while filling a document. Neither writes anything.
+
+```python
+from stackin import FiscalReference, Taxpayer
+
+ref = FiscalReference(api_key="...")          # country="BR" by default
+
+ref.ncm.get("84716052")                       # one code
+ref.ncm.search("teclado", limit=5)            # a page of matches
+ref.cfop.get("5102")
+ref.kinds()                                   # what this country has
+ref.kind("ibs_cbs_class").get("000001")       # any kind, named or not
+ref.search("teclado")                         # every kind at once
+
+Taxpayer(api_key="...").get("00000000000191")
+```
+
+`cfop`, `ncm`, `cest`, `cst`, `csosn`, `iss_service`, `icms_fuel` and `ibs_cbs_class` have accessors. **`kind(name)` reaches anything else**, including a classification published after this release — ask `kinds()` rather than trusting this list.
+
+`metadata` is passed through as the API sends it and differs per kind: `utrib` on an NCM, `ncm_code` on a CEST, `tax_type` on a CST, `None` on an ISS service.
+
+Three things worth knowing before you loop:
+
+- **These share the invoice read allowance** — 600 calls a minute per key, the same bucket `consult()`, `history()`, `received()` and `pdf()` draw from. One `search()` page beats N `get()` calls.
+- **Ordering is fixed** (kind, then code, ascending). Unlike `history()`, these take no `sort_by`/`order_by`.
+- **A 404 from `Taxpayer` does not mean the company does not exist.** That registry reloads monthly, so a recently registered CNPJ is simply not in it yet. Do not build a validation rule on it.
+
+`Taxpayer` has one method and keeps one: the registry holds the names and addresses of real people, so there is no search over it, by design.
+
 ## 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.
@@ -321,5 +354,5 @@ Building the full fiscal document (issuer data, service code, tax groups, schema
 
 ## 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.
+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. `examples/lookup_fiscal_reference.py` and `examples/lookup_taxpayer.py` cover the two read-only clients.
 

{stackin_python_sdk-0.8.0 → stackin_python_sdk-0.10.0}/README.md

@@ -108,7 +108,7 @@ invoice = client.issue(
     document_type=DocumentType.NFSE,
     client_name="John Doe",
     tax_id="00000000000",
-    items=[Product(description="Software development", amount=5000.00)],
+    items=[Product(description="Software development", unit_price=Decimal("5000.00"))],
 )
 
 status = client.consult("ACCESS_KEY...", document_type=DocumentType.NFSE)
@@ -165,13 +165,15 @@ burned, and undoing it means cancelling, which has a deadline.
 Pass `idempotency_key` to make the retry safe:
 
 ```python
+from decimal import Decimal
+
 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)],
+    items=[Product(description="Consultoria", unit_price=Decimal("1500.00"))],
     idempotency_key=key,
 )
 ```
@@ -282,6 +284,37 @@ Realizada. Only the last one takes a reason, and it requires one — both rules
 checked locally, before the request goes out, because a round trip to be told a
 fixed rule is a round trip wasted.
 
+## Looking up a code, or who a CNPJ belongs to
+
+Two more clients, for the tables an issuer reads while filling a document. Neither writes anything.
+
+```python
+from stackin import FiscalReference, Taxpayer
+
+ref = FiscalReference(api_key="...")          # country="BR" by default
+
+ref.ncm.get("84716052")                       # one code
+ref.ncm.search("teclado", limit=5)            # a page of matches
+ref.cfop.get("5102")
+ref.kinds()                                   # what this country has
+ref.kind("ibs_cbs_class").get("000001")       # any kind, named or not
+ref.search("teclado")                         # every kind at once
+
+Taxpayer(api_key="...").get("00000000000191")
+```
+
+`cfop`, `ncm`, `cest`, `cst`, `csosn`, `iss_service`, `icms_fuel` and `ibs_cbs_class` have accessors. **`kind(name)` reaches anything else**, including a classification published after this release — ask `kinds()` rather than trusting this list.
+
+`metadata` is passed through as the API sends it and differs per kind: `utrib` on an NCM, `ncm_code` on a CEST, `tax_type` on a CST, `None` on an ISS service.
+
+Three things worth knowing before you loop:
+
+- **These share the invoice read allowance** — 600 calls a minute per key, the same bucket `consult()`, `history()`, `received()` and `pdf()` draw from. One `search()` page beats N `get()` calls.
+- **Ordering is fixed** (kind, then code, ascending). Unlike `history()`, these take no `sort_by`/`order_by`.
+- **A 404 from `Taxpayer` does not mean the company does not exist.** That registry reloads monthly, so a recently registered CNPJ is simply not in it yet. Do not build a validation rule on it.
+
+`Taxpayer` has one method and keeps one: the registry holds the names and addresses of real people, so there is no search over it, by design.
+
 ## 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.
@@ -292,4 +325,4 @@ Building the full fiscal document (issuer data, service code, tax groups, schema
 
 ## 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.
+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. `examples/lookup_fiscal_reference.py` and `examples/lookup_taxpayer.py` cover the two read-only clients.

{stackin_python_sdk-0.8.0 → stackin_python_sdk-0.10.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackin-python-sdk"
-version = "0.8.0"
+version = "0.10.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.8.0"
+version = "0.10.0"
 description = "Python SDK for issuing, consulting and cancelling electronic invoices."
 authors = ["Fernando Celmer <email@fernandocelmer.com>"]
 readme = "README.md"

{stackin_python_sdk-0.8.0 → stackin_python_sdk-0.10.0}/stackin/__init__.py

@@ -1,6 +1,6 @@
 """Invoice __init__ module."""
 
-__version__ = "0.8.0"
+__version__ = "0.10.0"
 __description__ = (
     "Python SDK for issuing, consulting and cancelling electronic invoices."
 )
@@ -8,10 +8,16 @@ __description__ = (
 from .core.address import Address
 from .core.client import Invoice
 from .core.exceptions import APIError, ConnectionFailedError, InvoiceError
+from .core.reference import KINDS, FiscalReference, Kind
+from .core.taxpayer import Taxpayer
 from .core.types import DocumentType, Environment, Manifestation
 
 __all__ = [
     "Invoice",
+    "FiscalReference",
+    "Kind",
+    "KINDS",
+    "Taxpayer",
     "DocumentType",
     "Environment",
     "Manifestation",

{stackin_python_sdk-0.8.0 → stackin_python_sdk-0.10.0}/stackin/br/__init__.py

@@ -1,6 +1,6 @@
 """Brazil-specific document fields."""
 
-from stackin.br.product import PresumedCredit, Product
+from stackin.br.product import IbsCbs, PresumedCredit, Product
 from stackin.br.tax import (
     CofinsAliq,
     CofinsNt,
@@ -42,6 +42,7 @@ from stackin.br.tax import (
 
 __all__ = [
     "Product",
+    "IbsCbs",
     "PresumedCredit",
     "Tax",
     "Icms00",

{stackin_python_sdk-0.8.0 → stackin_python_sdk-0.10.0}/stackin/br/product.py

@@ -10,6 +10,17 @@ from pydantic import BaseModel, Field
 from stackin.br.tax import Tax
 
 
+class IbsCbs(BaseModel):
+    """The Reforma Tributária group for one item."""
+
+    cst: str = Field(pattern=r"^\d{3}$")
+    classification: str = Field(pattern=r"^\d{6}$")
+    base: float | None = Field(default=None, gt=0)
+    rate_state: float = Field(ge=0)
+    rate_city: float = Field(ge=0)
+    rate_federal: float = Field(ge=0)
+
+
 class PresumedCredit(BaseModel):
     """A presumed tax credit applied to this item."""
 
@@ -33,6 +44,7 @@ _BR_FIELDS = {
     "import_content_control_number",
     "recopi_number",
     "extra_groups",
+    "ibs_cbs",
     "tax",
 }
 
@@ -80,6 +92,7 @@ class Product(BaseModel):
         ),
     )
     recopi_number: str | None = Field(default=None, pattern=r"^\d{20}$")
+    ibs_cbs: IbsCbs | None = Field(default=None)
     extra_groups: dict[str, Any] | None = Field(default=None)
     tax: Tax | dict[str, Any] | None = Field(default=None)
 

{stackin_python_sdk-0.8.0 → stackin_python_sdk-0.10.0}/stackin/core/client.py

@@ -63,8 +63,13 @@ def _validate_nfe_address(address: Address | None) -> None:
         )
 
 
-class Invoice:
-    """Client for issuing, consulting, and cancelling fiscal documents."""
+class _Client:
+    """Where an api_key becomes an HTTP call, for every entry point.
+
+    Lives here rather than in a module of its own because the tests
+    patch `stackin.core.client.requests`, and so every request the SDK
+    makes has to be issued from this module.
+    """
 
     def __init__(
         self,
@@ -78,6 +83,77 @@ class Invoice:
         self.api_key = api_key or os.environ.get("STACKIN_API_KEY")
         self.timeout = timeout
 
+    def _headers(self, idempotency_key: str | None = None) -> dict:
+        headers = {}
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        if idempotency_key:
+            headers["Idempotency-Key"] = idempotency_key
+        return headers
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict | None = None,
+        params: dict | None = None,
+        idempotency_key: str | None = None,
+    ) -> Any:
+        response = self._send(
+            method,
+            path,
+            json=json,
+            params=params,
+            idempotency_key=idempotency_key,
+        )
+        try:
+            body = response.json() if response.content else {}
+        except ValueError:
+            body = {}
+        if isinstance(body, dict):
+            return body.get("result", body)
+        return 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:
+            response = requests.request(
+                method,
+                url,
+                json=json,
+                params=params,
+                headers=self._headers(idempotency_key),
+                timeout=self.timeout,
+            )
+        except requests.RequestException as error:
+            raise ConnectionFailedError(str(error)) from error
+
+        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 response
+
+
+class Invoice(_Client):
+    """Client for issuing, consulting, and cancelling fiscal documents."""
+
     def issue(
         self,
         *,
@@ -328,70 +404,3 @@ class Invoice:
             f"/received-invoices/{access_key}/manifestation",
             json=payload,
         )
-
-    def _headers(self, idempotency_key: str | None = None) -> dict:
-        headers = {}
-        if self.api_key:
-            headers["Authorization"] = f"Bearer {self.api_key}"
-        if idempotency_key:
-            headers["Idempotency-Key"] = idempotency_key
-        return headers
-
-    def _request(
-        self,
-        method: str,
-        path: str,
-        *,
-        json: dict | None = None,
-        params: dict | None = None,
-        idempotency_key: str | None = None,
-    ) -> Any:
-        response = self._send(
-            method,
-            path,
-            json=json,
-            params=params,
-            idempotency_key=idempotency_key,
-        )
-        try:
-            body = response.json() if response.content else {}
-        except ValueError:
-            body = {}
-        if isinstance(body, dict):
-            return body.get("result", body)
-        return 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:
-            response = requests.request(
-                method,
-                url,
-                json=json,
-                params=params,
-                headers=self._headers(idempotency_key),
-                timeout=self.timeout,
-            )
-        except requests.RequestException as error:
-            raise ConnectionFailedError(str(error)) from error
-
-        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 response

stackin_python_sdk-0.10.0/stackin/core/reference.py

@@ -0,0 +1,173 @@
+"""The published classification tables — CFOP, NCM, CEST and the rest.
+
+None of this is the company's own data and none of it is writable. The
+eight named accessors are ergonomics; `kind()` is the contract, and it
+reaches a classification published after this release without one.
+"""
+
+from __future__ import annotations
+
+from typing import Any, cast
+from urllib.parse import quote
+
+from stackin.core.client import _Client
+from stackin.core.types import Environment
+
+
+def _segment(value: str) -> str:
+    """One path segment, escaped, refusing what would leave it.
+
+    `safe=""` because a code the caller typed may hold a `/`. The dot
+    segments need refusing rather than escaping: RFC 3986 calls `.`
+    unreserved, so `quote` leaves it alone and the HTTP client then
+    collapses `..` into a different endpoint.
+    """
+    if value in ("", ".", ".."):
+        raise ValueError(f"{value!r} is not a usable path segment")
+    return quote(value, safe="")
+
+
+KINDS = (
+    "cfop",
+    "ncm",
+    "cest",
+    "cst",
+    "csosn",
+    "iss_service",
+    "icms_fuel",
+    "ibs_cbs_class",
+)
+
+
+class Kind:
+    """One classification, bound to a country."""
+
+    def __init__(self, client: _Client, name: str, country: str) -> None:
+        self._client = client
+        self.name = name
+        self.country = country
+
+    def get(self, code: str, *, country: str | None = None) -> dict:
+        """One code. A code that does not exist raises APIError (404)."""
+        return cast(
+            dict,
+            self._client._request(
+                "GET",
+                f"/fiscal-references/{_segment(self.name)}"
+                f"/{_segment(code)}",
+                params={"country": country or self.country},
+            ),
+        )
+
+    def search(
+        self,
+        term: str | None = None,
+        *,
+        country: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> dict:
+        """This classification, searched or simply paged through.
+
+        Rows come back ordered by kind then code; the API takes no
+        sort_by or order_by here, unlike Invoice.history().
+        """
+        return _search(
+            self._client,
+            country=country or self.country,
+            kind=self.name,
+            term=term,
+            limit=limit,
+            offset=offset,
+        )
+
+
+def _search(
+    client: _Client,
+    *,
+    country: str,
+    kind: str | None,
+    term: str | None,
+    limit: int | None,
+    offset: int | None,
+) -> dict:
+    """Shared by Kind.search and FiscalReference.search."""
+    params: dict[str, Any] = {"country": country}
+    if kind is not None:
+        params["kind"] = kind
+    if term:
+        params["search"] = term
+    if limit is not None:
+        params["limit"] = limit
+    if offset is not None:
+        params["offset"] = offset
+
+    return cast(
+        dict,
+        client._request("GET", "/fiscal-references", params=params),
+    )
+
+
+class FiscalReference(_Client):
+    """Client for the published fiscal classification tables."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        environment: Environment | str | None = None,
+        api_key: str | None = None,
+        timeout: int = 30,
+        country: str = "BR",
+    ) -> None:
+        super().__init__(base_url, environment, api_key, timeout)
+        self.country = country
+
+        self.cfop = Kind(self, "cfop", country)
+        self.ncm = Kind(self, "ncm", country)
+        self.cest = Kind(self, "cest", country)
+        self.cst = Kind(self, "cst", country)
+        self.csosn = Kind(self, "csosn", country)
+        self.iss_service = Kind(self, "iss_service", country)
+        self.icms_fuel = Kind(self, "icms_fuel", country)
+        self.ibs_cbs_class = Kind(self, "ibs_cbs_class", country)
+
+    def kinds(self, *, country: str | None = None) -> list[str]:
+        """Which classifications this country has data for.
+
+        The only honest answer to "what else is there" — a hard-coded
+        list in a README goes stale the next time the ETL grows one.
+        """
+        return cast(
+            list[str],
+            self._request(
+                "GET",
+                "/fiscal-references/kinds",
+                params={"country": country or self.country},
+            ),
+        )
+
+    def kind(self, name: str, *, country: str | None = None) -> Kind:
+        """Any classification by name, including one with no accessor."""
+        return Kind(self, name, country or self.country)
+
+    def search(
+        self,
+        term: str | None = None,
+        *,
+        country: str | None = None,
+        limit: int | None = None,
+        offset: int | None = None,
+    ) -> dict:
+        """Every classification at once, which no accessor can express.
+
+        The most expensive call the endpoint accepts: it is the whole
+        country's tables, not one of them.
+        """
+        return _search(
+            self,
+            country=country or self.country,
+            kind=None,
+            term=term,
+            limit=limit,
+            offset=offset,
+        )

stackin_python_sdk-0.10.0/stackin/core/taxpayer.py

@@ -0,0 +1,49 @@
+"""The taxpayer registry, looked up one tax id at a time.
+
+One method, and it stays one method. The registry names and addresses
+real people and companies: an exact lookup answers the question an
+issuer has — who is this CNPJ I am about to invoice — and answers
+nothing else. A prefix or wildcard search over the same table is a bulk
+export wearing the costume of a query. Do not add one, not for parity
+with FiscalReference, not "just by name", not "just within one state".
+"""
+
+from __future__ import annotations
+
+from typing import cast
+
+from stackin.core.client import _Client
+from stackin.core.reference import _segment
+from stackin.core.types import Environment
+
+
+class Taxpayer(_Client):
+    """Client for the taxpayer registry."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        environment: Environment | str | None = None,
+        api_key: str | None = None,
+        timeout: int = 30,
+        country: str = "BR",
+    ) -> None:
+        super().__init__(base_url, environment, api_key, timeout)
+        self.country = country
+
+    def get(self, tax_id: str, *, country: str | None = None) -> dict:
+        """One taxpayer, by exact tax id.
+
+        A 404 raises APIError and does not mean the taxpayer does not
+        exist: the registry reloads monthly, so a company registered in
+        the last few weeks is simply not in it yet. Never build a
+        validation rule on top of it.
+        """
+        return cast(
+            dict,
+            self._request(
+                "GET",
+                f"/taxpayers/{_segment(tax_id)}",
+                params={"country": country or self.country},
+            ),
+        )