stackin-python-sdk 0.1.0__tar.gz → 0.1.2__tar.gz

{stackin_python_sdk-0.1.0 → stackin_python_sdk-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackin-python-sdk
-Version: 0.1.0
+Version: 0.1.2
 Summary: Python SDK for issuing, consulting and cancelling electronic invoices.
 License-Expression: MIT
 License-File: LICENSE
@@ -20,6 +20,11 @@ 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">
@@ -29,8 +34,11 @@ Description-Content-Type: text/markdown
 **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>
 
 ---
@@ -49,7 +57,7 @@ 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. 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.
+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
@@ -96,19 +104,5 @@ Building the full fiscal document (issuer data, service code, tax groups, schema
 
 ## Examples
 
-Runnable end-to-end scripts in [`examples/`](examples/) — `simple_issue_nfe.py` and `simple_issue_nfse.py`, each with a catalog of realistic line items covering every optional field.
-
-## Commit Style
-
-| Icon | Type      | Description                                |
-|------|-----------|--------------------------------------------|
-| ⚙️   | FEATURE   | New feature                                |
-| 📝   | PEP8      | Formatting fixes following PEP8            |
-| 📌   | ISSUE     | Reference to issue                         |
-| 🪲   | BUG       | Bug fix                                    |
-| 📘   | DOCS      | Documentation changes                      |
-| 📦   | PyPI      | PyPI releases                              |
-| ❤️️   | TEST      | Automated tests                            |
-| ⬆️   | CI/CD     | Changes in continuous integration/delivery |
-| ⚠️   | SECURITY  | Security improvements                      |
+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.
 

{stackin_python_sdk-0.1.0 → stackin_python_sdk-0.1.2}/README.md

@@ -5,8 +5,11 @@
 **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>
 
 ---
@@ -25,7 +28,7 @@ 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. 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.
+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
@@ -72,18 +75,4 @@ Building the full fiscal document (issuer data, service code, tax groups, schema
 
 ## Examples
 
-Runnable end-to-end scripts in [`examples/`](examples/) — `simple_issue_nfe.py` and `simple_issue_nfse.py`, each with a catalog of realistic line items covering every optional field.
-
-## Commit Style
-
-| Icon | Type      | Description                                |
-|------|-----------|--------------------------------------------|
-| ⚙️   | FEATURE   | New feature                                |
-| 📝   | PEP8      | Formatting fixes following PEP8            |
-| 📌   | ISSUE     | Reference to issue                         |
-| 🪲   | BUG       | Bug fix                                    |
-| 📘   | DOCS      | Documentation changes                      |
-| 📦   | PyPI      | PyPI releases                              |
-| ❤️️   | TEST      | Automated tests                            |
-| ⬆️   | CI/CD     | Changes in continuous integration/delivery |
-| ⚠️   | SECURITY  | Security improvements                      |
+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.

{stackin_python_sdk-0.1.0 → stackin_python_sdk-0.1.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "stackin-python-sdk"
-version = "0.1.0"
+version = "0.1.2"
 authors = [
   { name = "Fernando Celmer", email = "email@fernandocelmer.com" },
 ]
@@ -36,9 +36,16 @@ dependencies = [
   "pydantic",
 ]
 
+[project.urls]
+Homepage = "https://docs.stackin.io"
+Documentation = "https://docs.stackin.io/blog/python-sdk"
+Repository = "https://github.com/stackin-io/stackin-python-sdk"
+Issues = "https://github.com/stackin-io/stackin-python-sdk/issues"
+Changelog = "https://github.com/stackin-io/stackin-python-sdk/releases"
+
 [tool.poetry]
 name = "stackin-python-sdk"
-version = "0.1.0"
+version = "0.1.2"
 description = "Python SDK for issuing, consulting and cancelling electronic invoices."
 authors = ["Fernando Celmer <email@fernandocelmer.com>"]
 readme = "README.md"

{stackin_python_sdk-0.1.0 → stackin_python_sdk-0.1.2}/stackin/__init__.py

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

{stackin_python_sdk-0.1.0 → stackin_python_sdk-0.1.2}/stackin/br/__init__.py

@@ -10,6 +10,7 @@ from stackin.br.tax import (
     Icms60,
     IcmsSn101,
     IcmsSn102,
+    IcmsSn900,
     IcmsUfDest,
     Ipi,
     IpiNt,
@@ -29,6 +30,7 @@ __all__ = [
     "Icms60",
     "IcmsSn101",
     "IcmsSn102",
+    "IcmsSn900",
     "IcmsUfDest",
     "Ipi",
     "IpiTrib",

{stackin_python_sdk-0.1.0 → stackin_python_sdk-0.1.2}/stackin/br/product.py

@@ -55,11 +55,13 @@ class Product(BaseModel):
     ncm: str | None = Field(default=None, pattern=r"^\d{2}$|^\d{8}$")
     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
-    )
+    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}$")
+    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}$")
@@ -71,11 +73,36 @@ class Product(BaseModel):
     extra_groups: dict[str, Any] | None = Field(default=None)
     tax: Tax | dict[str, Any] | None = Field(default=None)
 
+    service_code: str | None = Field(
+        default=None, description="LC 116/2003 item.subitem, nfse only."
+    )
+    service_discount: float | None = Field(
+        default=None, description="Unconditional discount, nfse only."
+    )
+    tax_retained: bool = Field(
+        default=False, description="ISSQN retained by the tomador, nfse only."
+    )
+    observations: str | None = Field(
+        default=None, max_length=2000, description="nfse only."
+    )
+
     def to_dict(self) -> dict:
         """Returns the item as a plain dict, ready for the request body."""
+        _NFSE_FIELDS = {
+            "service_code",
+            "service_discount",
+            "tax_retained",
+            "observations",
+        }
         data = self.model_dump(
             exclude_none=True,
-            exclude={"description", "amount", "tax", *_BR_FIELDS},
+            exclude={
+                "description",
+                "amount",
+                "tax",
+                *_BR_FIELDS,
+                *_NFSE_FIELDS,
+            },
         )
         br = self.model_dump(exclude_none=True, include=_BR_FIELDS - {"tax"})
         if isinstance(self.tax, Tax):
@@ -84,4 +111,12 @@ class Product(BaseModel):
             br["tax"] = self.tax
         if br:
             data["br"] = br
-        return {"description": self.description, "amount": self.amount, "product": data}
+        return {
+            "description": self.description,
+            "amount": self.amount,
+            "product": data,
+            "service_code": self.service_code,
+            "discount": self.service_discount,
+            "tax_retained": self.tax_retained,
+            "observations": self.observations,
+        }

{stackin_python_sdk-0.1.0 → stackin_python_sdk-0.1.2}/stackin/br/tax.py

@@ -44,7 +44,9 @@ class Icms60(BaseModel):
     cst: str = Field(default="60", alias="CST")
     v_bc_st_ret: str | None = Field(default=None, alias="vBCSTRet")
     p_st: str | None = Field(default=None, alias="pST")
-    v_icms_substituto: str | None = Field(default=None, alias="vICMSSubstituto")
+    v_icms_substituto: str | None = Field(
+        default=None, alias="vICMSSubstituto"
+    )
     v_icms_st_ret: str | None = Field(default=None, alias="vICMSSTRet")
     v_bc_fcp_st_ret: str | None = Field(default=None, alias="vBCFCPSTRet")
     p_fcp_st_ret: str | None = Field(default=None, alias="pFCPSTRet")
@@ -75,6 +77,19 @@ class IcmsSn102(BaseModel):
     csosn: str = Field(alias="CSOSN")
 
 
+class IcmsSn900(BaseModel):
+    """Simples Nacional ICMS, other cases (used with interstate partilha)."""
+
+    model_config = _CONFIG
+
+    orig: str | None = None
+    csosn: str = Field(default="900", alias="CSOSN")
+    mod_bc: str | None = Field(default=None, alias="modBC")
+    v_bc: str | None = Field(default=None, alias="vBC")
+    p_icms: str | None = Field(default=None, alias="pICMS")
+    v_icms: str | None = Field(default=None, alias="vICMS")
+
+
 class IcmsUfDest(BaseModel):
     """Interstate ICMS share owed to the destination state."""
 
@@ -191,7 +206,15 @@ class CofinsOutr(BaseModel):
     v_cofins: str = Field(alias="vCOFINS")
 
 
-IcmsGroup = Icms00 | Icms40 | Icms60 | IcmsSn101 | IcmsSn102 | dict[str, Any]
+IcmsGroup = (
+    Icms00
+    | Icms40
+    | Icms60
+    | IcmsSn101
+    | IcmsSn102
+    | IcmsSn900
+    | dict[str, Any]
+)
 PisGroup = PisAliq | PisNt | PisOutr | dict[str, Any]
 CofinsGroup = CofinsAliq | CofinsNt | CofinsOutr | dict[str, Any]
 
@@ -201,6 +224,7 @@ _ICMS_TAGS = {
     Icms60: "ICMS60",
     IcmsSn101: "ICMSSN101",
     IcmsSn102: "ICMSSN102",
+    IcmsSn900: "ICMSSN900",
 }
 _PIS_TAGS = {PisAliq: "PISAliq", PisNt: "PISNT", PisOutr: "PISOutr"}
 _COFINS_TAGS = {
@@ -234,7 +258,9 @@ class Tax(BaseModel):
                 by_alias=True, exclude_none=True
             )
         if self.ipi is not None:
-            data["IPI"] = self.ipi.to_dict() if isinstance(self.ipi, Ipi) else self.ipi
+            data["IPI"] = (
+                self.ipi.to_dict() if isinstance(self.ipi, Ipi) else self.ipi
+            )
         if self.pis is not None:
             data["PIS"] = _wrap(self.pis, _PIS_TAGS)
         if self.cofins is not None:
@@ -246,4 +272,6 @@ def _wrap(group: BaseModel | dict, tags: dict[type, str]) -> dict:
     """Nests a tax group under its variant name."""
     if isinstance(group, dict):
         return group
-    return {tags[type(group)]: group.model_dump(by_alias=True, exclude_none=True)}
+    return {
+        tags[type(group)]: group.model_dump(by_alias=True, exclude_none=True)
+    }

{stackin_python_sdk-0.1.0 → stackin_python_sdk-0.1.2}/stackin/core/client.py

@@ -6,8 +6,8 @@ import os
 
 import requests
 
-from stackin.core.address import Address
 from stackin.br.product import Product
+from stackin.core.address import Address
 from stackin.core.exceptions import APIError, ConnectionFailedError
 from stackin.core.types import DocumentType, Environment
 
@@ -23,9 +23,7 @@ _ENVIRONMENT_URLS = {
 def _resolve_base_url(
     base_url: str | None, environment: Environment | str | None
 ) -> str:
-    """Resolution order, same shape as the AWS CLI: explicit param,
-    then env var, then the environment's default — `base_url` always
-    wins over `environment` at each step."""
+    """Resolution order: explicit param, then env var, then environment's default."""
     if base_url:
         return base_url
     if url := os.environ.get("STACKIN_BASE_URL"):
@@ -61,6 +59,8 @@ class Invoice:
         tax_id: str,
         items: list[Product],
         recipient_address: Address | None = None,
+        series: str | None = None,
+        number: str | None = None,
     ) -> dict:
         """Issues a fiscal document."""
         if not items:
@@ -71,7 +71,9 @@ class Invoice:
                 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"
+                    )
 
         payload = {
             "document_type": document_type.value,
@@ -79,8 +81,12 @@ class Invoice:
             "tax_id": tax_id,
             "items": [item.to_dict() for item in items],
         }
-        if recipient_address and recipient_address.state:
-            payload["recipient_state"] = recipient_address.state
+        if recipient_address:
+            payload["recipient_address"] = recipient_address.to_dict()
+        if series:
+            payload["series"] = series
+        if number:
+            payload["number"] = number
 
         return self._request("POST", "/invoices", json=payload)
 
@@ -108,7 +114,9 @@ class Invoice:
             "reason": reason,
         }
 
-        return self._request("POST", f"/invoices/{access_key}/cancel", json=payload)
+        return self._request(
+            "POST", f"/invoices/{access_key}/cancel", json=payload
+        )
 
     def _headers(self) -> dict:
         if self.api_key:

{stackin_python_sdk-0.1.0 → stackin_python_sdk-0.1.2}/stackin/core/exceptions.py

@@ -15,5 +15,4 @@ class APIError(InvoiceError):
 
 
 class ConnectionFailedError(InvoiceError):
-    """Raised when the invoice API can't be reached at all
-    (network/DNS/timeout)."""
+    """Raised when the invoice API can't be reached at all (network/DNS/timeout)."""

{stackin_python_sdk-0.1.0 → stackin_python_sdk-0.1.2}/stackin/core/types.py

@@ -13,10 +13,7 @@ class DocumentType(str, Enum):
 
 
 class Environment(str, Enum):
-    """Which host to talk to — pass to `Invoice(environment=...)`
-    instead of a raw `base_url`. `TEST` and `PRODUCTION` resolve to the
-    same host: homologation vs. production invoicing is a per-company
-    setting on the platform side, not a different SDK host."""
+    """Which host to talk to — pass to `Invoice(environment=...)` instead of a raw `base_url`."""
 
     LOCAL = "local"
     TEST = "test"