stackin-python-sdk 0.9.0__tar.gz → 0.11.0__tar.gz

{stackin_python_sdk-0.9.0 → stackin_python_sdk-0.11.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackin-python-sdk
-Version: 0.9.0
+Version: 0.11.0
 Summary: Python SDK for issuing, consulting and cancelling electronic invoices.
 License-Expression: MIT
 License-File: LICENSE
@@ -180,9 +180,9 @@ client.issue(
 )
 ```
 
-`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.
+`recipient_address` is an `Address` — the buyer's address, **required for NFE**. On NFE 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. On NFSE it is the tomador's address: optional, except when any item has `tax_retained=True` (the ISSQN retained by the tomador), where the city authorizer refuses the document without it (`E0237`) — then every field except `city_code` is required. In both cases 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).
+`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). `ncm` is the full 8 digits, or `00` for a service line — the SEFAZ rejects any other short code (rejection `777`), so one fails at construction.
 
 ## Retrying safely
 
@@ -251,8 +251,15 @@ The original document does not change — the CC-e is an event attached to it, a
 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`.
+**NF-e only.** NFS-e has no correction letter — cancel and reissue it instead.
+The access key says which one it is: an NF-e access key is 44 characters, an
+NFS-e key 50. A key that is not an NF-e access key (44 characters: digits, with
+uppercase letters allowed in the first 12 positions of the issuer CNPJ, which
+can be alphanumeric from July 2026) raises a `ValueError` locally, before the call:
+`correct is NFe only. NFSe has no correction letter — cancel and reissue instead.`
+What only the API can know stays an `APIError` with status `409`: an NF-e key
+sent with `document_type=DocumentType.NFSE`, or a key for a document the API
+does not hold.
 
 ## Invalidating unused numbers
 
@@ -313,15 +320,48 @@ 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.
 - `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.
+- `ValueError` — `issue()`'s `items` is empty, missing `ncm`/`cfop` on an item for NFE, an item `description` over 120 characters on NFE (the `xProd` limit; NFSE has no such limit), any string in an NFE request with a character the NF-e cannot carry (outside ISO-8859-1, latin1: an emoji, CJK, Cyrillic…; the error names the field — typographic quotes, dashes, ellipsis, bullet, `€` and `™` are not refused, the API converts them and folds tabs and line breaks into a space), a missing/incomplete `recipient_address` on NFE, or a missing/incomplete `recipient_address` (every field except `city_code`) on NFSE when any item has `tax_retained=True` (the ISSQN retained by the tomador).
+- `ValueError` — `correct()` with a key that is not an NF-e access key (44 characters): a correction letter exists only on NF-e; an NFS-e is cancelled and reissued instead. An NF-e key sent with `DocumentType.NFSE`, or one the API does not hold, is an `APIError` 409, not a `ValueError`.
+- `pydantic.ValidationError` (a `ValueError`) — a model built with a value the NF-e 4.00 XSD refuses: an `ncm` that is not 8 digits (or `00` for a service line), a `barcode` that is not `SEM GTIN` or an 8/12/13/14-digit GTIN with a valid GS1 check digit, or an `Address` `street`/`neighborhood` under 2 characters once trimmed.
 
 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.
+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.9.0 → stackin_python_sdk-0.11.0}/README.md

@@ -151,9 +151,9 @@ client.issue(
 )
 ```
 
-`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.
+`recipient_address` is an `Address` — the buyer's address, **required for NFE**. On NFE 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. On NFSE it is the tomador's address: optional, except when any item has `tax_retained=True` (the ISSQN retained by the tomador), where the city authorizer refuses the document without it (`E0237`) — then every field except `city_code` is required. In both cases 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).
+`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). `ncm` is the full 8 digits, or `00` for a service line — the SEFAZ rejects any other short code (rejection `777`), so one fails at construction.
 
 ## Retrying safely
 
@@ -222,8 +222,15 @@ The original document does not change — the CC-e is an event attached to it, a
 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`.
+**NF-e only.** NFS-e has no correction letter — cancel and reissue it instead.
+The access key says which one it is: an NF-e access key is 44 characters, an
+NFS-e key 50. A key that is not an NF-e access key (44 characters: digits, with
+uppercase letters allowed in the first 12 positions of the issuer CNPJ, which
+can be alphanumeric from July 2026) raises a `ValueError` locally, before the call:
+`correct is NFe only. NFSe has no correction letter — cancel and reissue instead.`
+What only the API can know stays an `APIError` with status `409`: an NF-e key
+sent with `document_type=DocumentType.NFSE`, or a key for a document the API
+does not hold.
 
 ## Invalidating unused numbers
 
@@ -284,14 +291,47 @@ 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.
 - `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.
+- `ValueError` — `issue()`'s `items` is empty, missing `ncm`/`cfop` on an item for NFE, an item `description` over 120 characters on NFE (the `xProd` limit; NFSE has no such limit), any string in an NFE request with a character the NF-e cannot carry (outside ISO-8859-1, latin1: an emoji, CJK, Cyrillic…; the error names the field — typographic quotes, dashes, ellipsis, bullet, `€` and `™` are not refused, the API converts them and folds tabs and line breaks into a space), a missing/incomplete `recipient_address` on NFE, or a missing/incomplete `recipient_address` (every field except `city_code`) on NFSE when any item has `tax_retained=True` (the ISSQN retained by the tomador).
+- `ValueError` — `correct()` with a key that is not an NF-e access key (44 characters): a correction letter exists only on NF-e; an NFS-e is cancelled and reissued instead. An NF-e key sent with `DocumentType.NFSE`, or one the API does not hold, is an `APIError` 409, not a `ValueError`.
+- `pydantic.ValidationError` (a `ValueError`) — a model built with a value the NF-e 4.00 XSD refuses: an `ncm` that is not 8 digits (or `00` for a service line), a `barcode` that is not `SEM GTIN` or an 8/12/13/14-digit GTIN with a valid GS1 check digit, or an `Address` `street`/`neighborhood` under 2 characters once trimmed.
 
 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.
+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.9.0 → stackin_python_sdk-0.11.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackin-python-sdk"
-version = "0.9.0"
+version = "0.11.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.9.0"
+version = "0.11.0"
 description = "Python SDK for issuing, consulting and cancelling electronic invoices."
 authors = ["Fernando Celmer <email@fernandocelmer.com>"]
 readme = "README.md"
@@ -65,6 +65,8 @@ python-dotenv = "^1.0.1"
 
 [tool.poetry.group.code-quality.dependencies]
 ruff = "^0.8.0"
+mypy = "^2.4.1"
+types-requests = "^2.33.0.20261030"
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

{stackin_python_sdk-0.9.0 → stackin_python_sdk-0.11.0}/stackin/__init__.py

@@ -1,6 +1,6 @@
 """Invoice __init__ module."""
 
-__version__ = "0.9.0"
+__version__ = "0.11.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.9.0 → stackin_python_sdk-0.11.0}/stackin/br/product.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 from decimal import Decimal
 from typing import Annotated, Any
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 from stackin.br.tax import Tax
 
@@ -49,6 +49,15 @@ _BR_FIELDS = {
 }
 
 
+def _gtin_check_digit_ok(gtin: str) -> bool:
+    """GS1 modulo 10: weights 3,1,3,1... from the right, check excluded."""
+    body = gtin[-2::-1]
+    total = sum(
+        int(digit) * (3 if index % 2 == 0 else 1) for index, digit in enumerate(body)
+    )
+    return (10 - total % 10) % 10 == int(gtin[-1])
+
+
 def _decimal_str(value: Decimal | None) -> str | None:
     """JSON has no decimal; a float would lose the tenth place."""
     return None if value is None else format(value, "f")
@@ -62,7 +71,11 @@ class Product(BaseModel):
     unit_price: Decimal | None = Field(default=None, gt=0)
     unit: str = Field(default="UN")
     quantity: float = Field(default=1.0, gt=0)
-    barcode: str | None = Field(default=None)
+    barcode: str | None = Field(
+        default=None,
+        pattern=r"^(SEM GTIN|\d{8}|\d{12,14})$",
+        description="cEAN: a GTIN-8/12/13/14, or SEM GTIN.",
+    )
     freight: float | None = Field(default=None)
     insurance: float | None = Field(default=None)
     discount: float | None = Field(default=None)
@@ -71,25 +84,27 @@ class Product(BaseModel):
     purchase_order: str | None = Field(default=None)
     purchase_order_item: str | None = Field(default=None, pattern=r"^\d{1,6}$")
 
-    ncm: str | None = Field(default=None, pattern=r"^\d{2}$|^\d{8}$")
+    ncm: str | None = Field(
+        default=None,
+        pattern=r"^(00|\d{8})$",
+        description=(
+            "The full 8 digits, or 00 for a service line. Any other "
+            "short code the SEFAZ rejects with 777."
+        ),
+    )
     cfop: str | None = Field(default=None, pattern=r"^[123567]\d{3}$")
     cest: str | None = Field(default=None, pattern=r"^\d{7}$")
-    nve_codes: (
-        list[Annotated[str, Field(pattern=r"^[A-Z]{2}\d{4}$")]] | None
-    ) = Field(default=None)
-    ind_escala: str | None = Field(default=None)
-    manufacturer_cnpj: str | None = Field(
-        default=None, pattern=r"^[0-9A-Z]{12}\d{2}$"
+    nve_codes: list[Annotated[str, Field(pattern=r"^[A-Z]{2}\d{4}$")]] | None = Field(
+        default=None
     )
+    ind_escala: str | None = Field(default=None)
+    manufacturer_cnpj: str | None = Field(default=None, pattern=r"^[0-9A-Z]{12}\d{2}$")
     tax_benefit_code: str | None = Field(default=None, pattern=_CBENEF_PATTERN)
     presumed_credits: list[PresumedCredit] | None = Field(default=None)
     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}"
-            r"-[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}$")
     ibs_cbs: IbsCbs | None = Field(default=None)
@@ -109,6 +124,16 @@ class Product(BaseModel):
         default=None, max_length=2000, description="nfse only."
     )
 
+    @field_validator("barcode")
+    @classmethod
+    def _valid_gtin_check_digit(cls, value: str | None) -> str | None:
+        """Runs after the pattern: SEM GTIN or digits by now."""
+        if value is None or not value.isdigit():
+            return value
+        if not _gtin_check_digit_ok(value):
+            raise ValueError("barcode has an invalid GTIN check digit")
+        return value
+
     def to_dict(self) -> dict:
         """Returns the item as a plain dict, ready for the request body."""
         _NFSE_FIELDS = {

{stackin_python_sdk-0.9.0 → stackin_python_sdk-0.11.0}/stackin/core/address.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, field_validator
 
 
 class Address(BaseModel):
@@ -16,6 +16,14 @@ class Address(BaseModel):
     city: str | None = Field(default=None)
     zip_code: str | None = Field(default=None)
 
+    @field_validator("street", "neighborhood")
+    @classmethod
+    def _at_least_two_characters(cls, value: str | None, info) -> str | None:
+        """The NF-e XSD sets xLgr and xBairro at 2 characters minimum."""
+        if value is not None and len(value.strip()) < 2:
+            raise ValueError(f"{info.field_name} must have at least 2 characters")
+        return value
+
     def to_dict(self) -> dict:
         """Returns the address as a plain dict."""
         return self.model_dump(exclude_none=True)

{stackin_python_sdk-0.9.0 → stackin_python_sdk-0.11.0}/stackin/core/client.py

@@ -3,7 +3,8 @@
 from __future__ import annotations
 
 import os
-from typing import Any
+import re
+from typing import Any, cast
 
 import requests
 
@@ -37,6 +38,12 @@ def _resolve_base_url(
     return DEFAULT_BASE_URL
 
 
+_NFE_DESCRIPTION_MAX = 120
+
+# cUF+AAMM, then the issuer CNPJ (alphanumeric from July 2026: letters
+# in its first 12 positions), then the rest. Same check as the API's.
+_NFE_ACCESS_KEY = re.compile(r"[0-9]{6}[0-9A-Z]{12}[0-9]{26}")
+
 _NFE_ADDRESS_FIELDS = (
     "street",
     "number",
@@ -53,9 +60,7 @@ def _validate_nfe_address(address: Address | None) -> None:
     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)
-    ]
+    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: "
@@ -63,8 +68,84 @@ def _validate_nfe_address(address: Address | None) -> None:
         )
 
 
-class Invoice:
-    """Client for issuing, consulting, and cancelling fiscal documents."""
+# What the API converts before its own latin1 check (stackin-api#228):
+# typographic quotes, dashes, ellipsis, bullet, euro and trademark.
+# Those are not refused here; the SDK does not translate them either.
+_API_CONVERTED = frozenset(
+    "\u2018\u2019\u201a\u201c\u201d\u201e\u2013\u2014\u2212\u2026\u2022\u20ac\u2122"
+)
+
+
+def _first_non_latin1(value: Any, path: str) -> tuple[str, str] | None:
+    """The first character in `value` the NF-e cannot carry, with its path.
+
+    Anything up to U+00FF passes (tab, newline and CR included: the API
+    folds them into a space), and so does what the API converts.
+    """
+    if isinstance(value, str):
+        for char in value:
+            if char > "\u00ff" and char not in _API_CONVERTED:
+                return path, char
+        return None
+    if isinstance(value, dict):
+        for key, nested in value.items():
+            child = f"{path}.{key}" if path else str(key)
+            if found := _first_non_latin1(nested, child):
+                return found
+        return None
+    if isinstance(value, (list, tuple)):
+        for index, nested in enumerate(value):
+            if found := _first_non_latin1(nested, f"{path}[{index}]"):
+                return found
+    return None
+
+
+def _validate_nfe_latin1(payload: dict) -> None:
+    """NF-e is encoded in ISO-8859-1; the SEFAZ refuses anything else.
+
+    Walks every string the request would carry, so a free-text field
+    added later is covered without being listed here. Refuses only what
+    the API would refuse after its own normalisation, never more.
+    """
+    if found := _first_non_latin1(payload, ""):
+        path, char = found
+        raise ValueError(
+            f"{path} contains a character outside ISO-8859-1 (latin1), "
+            f"which NF-e does not accept: '{char}'"
+        )
+
+
+_NFSE_RETAINED_ADDRESS_FIELDS = tuple(
+    field for field in _NFE_ADDRESS_FIELDS if field != "city_code"
+)
+
+
+def _validate_nfse_retained_address(address: Address | None) -> None:
+    """Retained ISSQN needs the tomador's address — the authorizer refuses
+    the document without it (E0237). Every field but city_code."""
+    if address is None:
+        raise ValueError(
+            "recipient_address is required on an NFS-e when any item "
+            "has tax_retained=true (ISSQN retained by the tomador)"
+        )
+
+    missing = [
+        field for field in _NFSE_RETAINED_ADDRESS_FIELDS if not getattr(address, field)
+    ]
+    if missing:
+        raise ValueError(
+            "recipient_address is missing required fields for NFSE with "
+            "tax_retained=true: " + ", ".join(missing)
+        )
+
+
+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 +159,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,
         *,
@@ -96,15 +248,21 @@ class Invoice:
 
         if document_type is DocumentType.NFE:
             for index, item in enumerate(items):
+                if len(item.description) > _NFE_DESCRIPTION_MAX:
+                    raise ValueError(
+                        f"items[{index}].description exceeds "
+                        f"{_NFE_DESCRIPTION_MAX} characters (NF-e xProd limit)"
+                    )
                 if not item.ncm:
                     raise ValueError(f"items[{index}].ncm is required for NFE")
                 if not item.cfop:
-                    raise ValueError(
-                        f"items[{index}].cfop is required for NFE"
-                    )
+                    raise ValueError(f"items[{index}].cfop is required for NFE")
             _validate_nfe_address(recipient_address)
+        retained = any(item.tax_retained for item in items)
+        if document_type is DocumentType.NFSE and retained:
+            _validate_nfse_retained_address(recipient_address)
 
-        payload = {
+        payload: dict[str, Any] = {
             "document_type": document_type.value,
             "client_name": client_name,
             "tax_id": tax_id,
@@ -116,12 +274,17 @@ class Invoice:
             payload["series"] = series
         if number:
             payload["number"] = number
-
-        return self._request(
-            "POST",
-            "/invoices",
-            json=payload,
-            idempotency_key=idempotency_key,
+        if document_type is DocumentType.NFE:
+            _validate_nfe_latin1(payload)
+
+        return cast(
+            dict,
+            self._request(
+                "POST",
+                "/invoices",
+                json=payload,
+                idempotency_key=idempotency_key,
+            ),
         )
 
     def consult(
@@ -133,7 +296,9 @@ class Invoice:
         """Consults a fiscal document by its access key."""
         params = {"document_type": document_type.value}
 
-        return self._request("GET", f"/invoices/{access_key}", params=params)
+        return cast(
+            dict, self._request("GET", f"/invoices/{access_key}", params=params)
+        )
 
     def cancel(
         self,
@@ -155,11 +320,14 @@ class Invoice:
             "reason": reason,
         }
 
-        return self._request(
-            "POST",
-            f"/invoices/{access_key}/cancel",
-            json=payload,
-            idempotency_key=idempotency_key,
+        return cast(
+            dict,
+            self._request(
+                "POST",
+                f"/invoices/{access_key}/cancel",
+                json=payload,
+                idempotency_key=idempotency_key,
+            ),
         )
 
     def invalidate(
@@ -183,7 +351,9 @@ class Invoice:
             "reason": reason,
         }
 
-        return self._request("POST", "/invoices/invalidations", json=payload)
+        return cast(
+            dict, self._request("POST", "/invoices/invalidations", json=payload)
+        )
 
     def correct(
         self,
@@ -192,7 +362,20 @@ class Invoice:
         document_type: DocumentType,
         correction: str,
     ) -> dict:
-        """Files a correction letter (CC-e) against an issued document."""
+        """Files a correction letter (CC-e) against an issued NF-e.
+
+        Only an NF-e has one, so the access key must be an NF-e access
+        key (44 characters; the CNPJ slot may carry letters); an NFS-e is
+        cancelled and issued again instead. That is checked here. An NF-e
+        key sent with DocumentType.NFSE, or one
+        for a document the API does not hold, is still answered by the
+        API as an APIError with status 409.
+        """
+        if not _NFE_ACCESS_KEY.fullmatch(access_key):
+            raise ValueError(
+                "correct is NFe only. NFSe has no correction letter — "
+                "cancel and reissue instead."
+            )
         if not 15 <= len(correction) <= 1000:
             raise ValueError("correction must be 15 to 1000 characters")
 
@@ -201,18 +384,20 @@ class Invoice:
             "correction": correction,
         }
 
-        return self._request(
-            "POST", f"/invoices/{access_key}/correction", json=payload
+        return cast(
+            dict,
+            self._request("POST", f"/invoices/{access_key}/correction", json=payload),
         )
 
-    def reissue(
-        self, invoice_id: str, *, idempotency_key: str | None = None
-    ) -> dict:
+    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,
+        return cast(
+            dict,
+            self._request(
+                "POST",
+                f"/invoices/{invoice_id}/reissue",
+                idempotency_key=idempotency_key,
+            ),
         )
 
     def pdf(
@@ -230,9 +415,7 @@ class Invoice:
         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
-        )
+        response = self._send("GET", f"/invoices/{access_key}/pdf", params=params)
         return response.content
 
     def received(
@@ -253,7 +436,7 @@ class Invoice:
         if offset is not None:
             params["offset"] = offset
 
-        return self._request("GET", "/received-invoices", params=params)
+        return cast(dict, self._request("GET", "/received-invoices", params=params))
 
     def history(
         self,
@@ -284,7 +467,7 @@ class Invoice:
         if order_by is not None:
             params["order_by"] = order_by
 
-        return self._request("GET", "/invoices", params=params)
+        return cast(dict, self._request("GET", "/invoices", params=params))
 
     def submissions(self, invoice_id: str) -> list:
         """Every attempt made for one invoice, and what came back.
@@ -292,7 +475,7 @@ class Invoice:
         consult() gives the status; this gives the reason. Takes the
         invoice_id because a rejected document has no access key.
         """
-        return self._request("GET", f"/invoices/{invoice_id}/submissions")
+        return cast(list, self._request("GET", f"/invoices/{invoice_id}/submissions"))
 
     def manifest(
         self,
@@ -310,88 +493,22 @@ class Invoice:
         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"
+                "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"
+                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,
+        return cast(
+            dict,
+            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:
-            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.11.0/stackin/core/reference.py

@@ -0,0 +1,172 @@
+"""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.11.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},
+            ),
+        )