stackin-python-sdk 0.9.0__py3-none-any.whl → 0.10.0__py3-none-any.whl

stackin/__init__.py

@@ -1,6 +1,6 @@
 """Invoice __init__ module."""
 
-__version__ = "0.9.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/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/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/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},
+            ),
+        )

{stackin_python_sdk-0.9.0.dist-info → stackin_python_sdk-0.10.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackin-python-sdk
-Version: 0.9.0
+Version: 0.10.0
 Summary: Python SDK for issuing, consulting and cancelling electronic invoices.
 License-Expression: MIT
 License-File: LICENSE
@@ -313,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.
@@ -323,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.10.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+stackin/__init__.py,sha256=mssUlglaIcPNx4tAm_JRW_NamEYTyRUdUOSwxRXsASY,689
+stackin/br/__init__.py,sha256=-s-2-ZyCmGZA8jTR8KFgNOSoPjjgV57Ss_cdI-FjRRY,1206
+stackin/br/product.py,sha256=4T5urNCi0LJrxs03Kt2vbXs1DBzYlRijBULWxi6bZ44,4830
+stackin/br/tax.py,sha256=UxcYX-kJw1HxUixB0hRABSgoHqT6CLoEjup4xIRFaYg,54747
+stackin/core/__init__.py,sha256=dxtOP1DopMSNFYGh3Hf12RVcs58R9xwLn-gqfKFo-HE,19
+stackin/core/address.py,sha256=-w5R3nzfU5T3VoxIeygu5Dq4DRb_lJHAGc0lmSMwEMU,616
+stackin/core/client.py,sha256=Iipq9V9J4nbQ4LBmxqJeYphIWe1sWcPNVO8RxicAiCc,12374
+stackin/core/exceptions.py,sha256=ELn-uL8rwjAFsD1PgM8Zr-1if3Z5yOWU81chUs4k6tU,505
+stackin/core/reference.py,sha256=xNAcaRuiiHYF5M7l42Jr5W9GFfzqh3CeJaqZAwomkdw,5096
+stackin/core/taxpayer.py,sha256=4YN7Oi5PDHGhLBW4M7eZlw9ARQn5sk4GLrC2_Z7-NhA,1669
+stackin/core/types.py,sha256=NpfYVN58Ug9fEY7VYeQ2TC1eekoFGHZq_habvrqEeTY,604
+stackin_python_sdk-0.10.0.dist-info/METADATA,sha256=8dGhwQSagI7jHluUufFtoW9K3qyU2dq3WK8QDoBuy74,15049
+stackin_python_sdk-0.10.0.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+stackin_python_sdk-0.10.0.dist-info/licenses/LICENSE,sha256=D-XHDcKFFhzEo9C5Dp4QPvt00pb_u__hi4Bc08zpxyU,1072
+stackin_python_sdk-0.10.0.dist-info/RECORD,,

stackin_python_sdk-0.9.0.dist-info/RECORD

@@ -1,13 +0,0 @@
-stackin/__init__.py,sha256=3t_IUn9nn3GSfJp-qb-h5xisouQu1jXmits5PONx1yA,531
-stackin/br/__init__.py,sha256=-s-2-ZyCmGZA8jTR8KFgNOSoPjjgV57Ss_cdI-FjRRY,1206
-stackin/br/product.py,sha256=4T5urNCi0LJrxs03Kt2vbXs1DBzYlRijBULWxi6bZ44,4830
-stackin/br/tax.py,sha256=UxcYX-kJw1HxUixB0hRABSgoHqT6CLoEjup4xIRFaYg,54747
-stackin/core/__init__.py,sha256=dxtOP1DopMSNFYGh3Hf12RVcs58R9xwLn-gqfKFo-HE,19
-stackin/core/address.py,sha256=-w5R3nzfU5T3VoxIeygu5Dq4DRb_lJHAGc0lmSMwEMU,616
-stackin/core/client.py,sha256=G80o4ORwNtazasIlmJBEhyrwG5VgTAsit9MTxK7FcEI,12086
-stackin/core/exceptions.py,sha256=ELn-uL8rwjAFsD1PgM8Zr-1if3Z5yOWU81chUs4k6tU,505
-stackin/core/types.py,sha256=NpfYVN58Ug9fEY7VYeQ2TC1eekoFGHZq_habvrqEeTY,604
-stackin_python_sdk-0.9.0.dist-info/METADATA,sha256=zbT293Pa4yPTsivPQS46yx5NcIZU_YaT1npTt9dh8Jc,13160
-stackin_python_sdk-0.9.0.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
-stackin_python_sdk-0.9.0.dist-info/licenses/LICENSE,sha256=D-XHDcKFFhzEo9C5Dp4QPvt00pb_u__hi4Bc08zpxyU,1072
-stackin_python_sdk-0.9.0.dist-info/RECORD,,