stackin-python-sdk 0.1.0__tar.gz

stackin_python_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fernando Celmer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stackin_python_sdk-0.1.0/PKG-INFO

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

stackin_python_sdk-0.1.0/README.md

@@ -0,0 +1,89 @@
+<div align="center">
+
+<img src="https://raw.githubusercontent.com/stackin-io/stackin-python-sdk/master/docs/assets/stackin.png" width="120" />
+
+**Integrate once. Issue everywhere.**
+
+[![Python](https://img.shields.io/badge/python-3.10%2B-blue?style=flat-square)](pyproject.toml)
+[![License](https://img.shields.io/badge/license-MIT-informational?style=flat-square)](https://github.com/stackin-io/stackin-python-sdk)
+
+</div>
+
+---
+
+# stackin
+
+Python SDK for fiscal document issuance — a handful of business fields, nothing about certificates, XML, XSD, signing or SOAP. The API resolves all of that from the issuer's own configuration, identified by `api_key`.
+
+**One class, `Invoice`** — `issue()`/`consult()`/`cancel()`, nothing else to instantiate. Each line item is a `Product` (`stackin.br`) — `description`/`amount` are universal, everything else (`ncm`/`cfop`/`cest`/tax groups...) is Brazil-specific and only required for NFE; NFSE ignores it.
+
+## Install
+
+```bash
+pip install stackin-python-sdk
+```
+
+## Usage
+
+Get an `api_key` from the [stackin dashboard](https://app.stackin.io) — select the issuing company, then Settings → API key. One key per issuing company, shown once at creation. The API resolves the issuer (CNPJ, state, address, certificate, environment) entirely from it; nothing about the issuer is ever passed on a call.
+
+```python
+from stackin import Invoice, DocumentType, Address
+from stackin.br import Product  # Brazil-specific line item — NCM/CFOP
+
+client = Invoice(api_key="COMPANY_API_KEY")  # defaults to https://sdk.stackin.io
+
+invoice = client.issue(
+    document_type=DocumentType.NFSE,
+    client_name="John Doe",
+    tax_id="00000000000",
+    items=[Product(description="Software development", amount=5000.00)],
+)
+
+status = client.consult("ACCESS_KEY...", document_type=DocumentType.NFSE)
+client.cancel(
+    "ACCESS_KEY...",
+    document_type=DocumentType.NFSE,
+    reason="Typo",
+)
+
+# NFE requires ncm/cfop on every item, and optionally recipient_address.state
+# to get idDest right on interstate sales:
+client.issue(
+    document_type=DocumentType.NFE,
+    client_name="Buyer Company Ltd",
+    tax_id="11111111111111",
+    items=[Product(description="Test product", amount=100.00, ncm="84713012", cfop="5102")],
+    recipient_address=Address(state="RJ"),
+)
+```
+
+`recipient_address` is an `Address`, but despite the name only `.state` is read — the rest of the fields aren't sent anywhere yet. It's the actual customer's state, used only to set `idDest` (interstate vs internal) on NFE — optional, omitting it always produces `idDest=1` (internal).
+
+`items` is a list of `Product` (`stackin.br`) — `description`/`amount` apply to any document type; `ncm`/`cfop` (plus everything else on `Product`: `cest`, tax groups, presumed credits...) are Brazil-specific and required per item for NFE, ignored for NFSE (a service isn't a physical good).
+
+## Errors
+
+- `stackin.APIError` — the API responded with a non-2xx status (`status_code`, `detail`) — a 401 here means `api_key` is missing, wrong, or was rotated.
+- `stackin.ConnectionFailedError` — the API didn't respond (network/DNS/timeout).
+- `ValueError` — `issue()`'s `items` is empty, or missing `ncm`/`cfop` on an item for NFE.
+
+Building the full fiscal document (issuer data, service code, tax groups, schema-accurate XML) is the API's job — configured once per company, not passed on every call.
+
+## Examples
+
+Runnable end-to-end scripts in [`examples/`](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                      |

stackin_python_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "stackin-python-sdk"
+version = "0.1.0"
+authors = [
+  { name = "Fernando Celmer", email = "email@fernandocelmer.com" },
+]
+description = "Python SDK for issuing, consulting and cancelling electronic invoices."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+keywords = [
+  "nfe",
+  "nfse",
+  "nota-fiscal",
+  "nota-fiscal-eletronica",
+  "invoice",
+  "fiscal-document",
+  "brazil",
+  "sefaz",
+  "e-invoicing",
+]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Developers",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: Office/Business :: Financial :: Accounting",
+  "Topic :: Software Development :: Libraries :: Python Modules",
+  "Natural Language :: Portuguese (Brazilian)",
+]
+dependencies = [
+  "requests",
+  "pydantic",
+]
+
+[tool.poetry]
+name = "stackin-python-sdk"
+version = "0.1.0"
+description = "Python SDK for issuing, consulting and cancelling electronic invoices."
+authors = ["Fernando Celmer <email@fernandocelmer.com>"]
+readme = "README.md"
+license = "MIT"
+package-mode = true
+packages = [{ include = "stackin" }]
+
+[tool.poetry.dependencies]
+python = ">=3.10.0"
+requests = "^2.32.4"
+pydantic = "^2.11.7"
+
+[tool.poetry.group.dev.dependencies]
+pytest = "^8.3.4"
+pytest-cov = "^6.0.0"
+python-dotenv = "^1.0.1"
+
+[tool.poetry.group.code-quality.dependencies]
+ruff = "^0.8.0"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["poetry-core"]
+build-backend = "poetry.core.masonry.api"

stackin_python_sdk-0.1.0/stackin/__init__.py

@@ -0,0 +1,21 @@
+"""Invoice __init__ module."""
+
+__version__ = "0.1.0"
+__description__ = (
+    "Python SDK for issuing, consulting and cancelling electronic invoices."
+)
+
+from .core.address import Address
+from .core.client import Invoice
+from .core.exceptions import APIError, ConnectionFailedError, InvoiceError
+from .core.types import DocumentType, Environment
+
+__all__ = [
+    "Invoice",
+    "DocumentType",
+    "Environment",
+    "Address",
+    "InvoiceError",
+    "APIError",
+    "ConnectionFailedError",
+]

stackin_python_sdk-0.1.0/stackin/br/__init__.py

@@ -0,0 +1,42 @@
+"""Brazil-specific document fields."""
+
+from stackin.br.product import PresumedCredit, Product
+from stackin.br.tax import (
+    CofinsAliq,
+    CofinsNt,
+    CofinsOutr,
+    Icms00,
+    Icms40,
+    Icms60,
+    IcmsSn101,
+    IcmsSn102,
+    IcmsUfDest,
+    Ipi,
+    IpiNt,
+    IpiTrib,
+    PisAliq,
+    PisNt,
+    PisOutr,
+    Tax,
+)
+
+__all__ = [
+    "Product",
+    "PresumedCredit",
+    "Tax",
+    "Icms00",
+    "Icms40",
+    "Icms60",
+    "IcmsSn101",
+    "IcmsSn102",
+    "IcmsUfDest",
+    "Ipi",
+    "IpiTrib",
+    "IpiNt",
+    "PisAliq",
+    "PisNt",
+    "PisOutr",
+    "CofinsAliq",
+    "CofinsNt",
+    "CofinsOutr",
+]

stackin_python_sdk-0.1.0/stackin/br/product.py

@@ -0,0 +1,87 @@
+"""Product module."""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Field
+
+from stackin.br.tax import Tax
+
+
+class PresumedCredit(BaseModel):
+    """A presumed tax credit applied to this item."""
+
+    code: str = Field(pattern=r"^[\x21-\xff]{8}$|^[\x21-\xff]{10}$")
+    percentage: float
+    amount: float
+
+
+_CBENEF_PATTERN = r"^(SEM CBENEF|[\x21-\xff]{8}|[\x21-\xff]{10})$"
+
+_BR_FIELDS = {
+    "ncm",
+    "cfop",
+    "cest",
+    "nve_codes",
+    "ind_escala",
+    "manufacturer_cnpj",
+    "tax_benefit_code",
+    "presumed_credits",
+    "ex_tipi",
+    "import_content_control_number",
+    "recopi_number",
+    "extra_groups",
+    "tax",
+}
+
+
+class Product(BaseModel):
+    """One product or service line item on an invoice."""
+
+    description: str = Field(..., min_length=1)
+    amount: float = Field(..., gt=0)
+    unit: str = Field(default="UN")
+    quantity: float = Field(default=1.0, gt=0)
+    barcode: str | None = Field(default=None)
+    freight: float | None = Field(default=None)
+    insurance: float | None = Field(default=None)
+    discount: float | None = Field(default=None)
+    other_expenses: float | None = Field(default=None)
+    used_movable_asset: bool = Field(default=False)
+    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}$")
+    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}$")
+    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}-[A-F0-9]{4}-[A-F0-9]{12}$",
+    )
+    recopi_number: str | None = Field(default=None, pattern=r"^\d{20}$")
+    extra_groups: dict[str, Any] | None = Field(default=None)
+    tax: Tax | dict[str, Any] | None = Field(default=None)
+
+    def to_dict(self) -> dict:
+        """Returns the item as a plain dict, ready for the request body."""
+        data = self.model_dump(
+            exclude_none=True,
+            exclude={"description", "amount", "tax", *_BR_FIELDS},
+        )
+        br = self.model_dump(exclude_none=True, include=_BR_FIELDS - {"tax"})
+        if isinstance(self.tax, Tax):
+            br["tax"] = self.tax.to_dict()
+        elif self.tax is not None:
+            br["tax"] = self.tax
+        if br:
+            data["br"] = br
+        return {"description": self.description, "amount": self.amount, "product": data}

stackin_python_sdk-0.1.0/stackin/br/tax.py

@@ -0,0 +1,249 @@
+"""Tax module."""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+_CONFIG = ConfigDict(populate_by_name=True)
+
+
+class Icms00(BaseModel):
+    """ICMS fully taxed."""
+
+    model_config = _CONFIG
+
+    orig: str
+    cst: str = Field(default="00", alias="CST")
+    mod_bc: str = Field(alias="modBC")
+    v_bc: str = Field(alias="vBC")
+    p_icms: str = Field(alias="pICMS")
+    v_icms: str = Field(alias="vICMS")
+    p_fcp: str | None = Field(default=None, alias="pFCP")
+    v_fcp: str | None = Field(default=None, alias="vFCP")
+
+
+class Icms40(BaseModel):
+    """ICMS exempt or not taxed."""
+
+    model_config = _CONFIG
+
+    orig: str
+    cst: str = Field(alias="CST")
+    v_icms_deson: str | None = Field(default=None, alias="vICMSDeson")
+    mot_des_icms: str | None = Field(default=None, alias="motDesICMS")
+
+
+class Icms60(BaseModel):
+    """ICMS already charged by an earlier substitution."""
+
+    model_config = _CONFIG
+
+    orig: str
+    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_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")
+    v_fcp_st_ret: str | None = Field(default=None, alias="vFCPSTRet")
+    p_red_bc_efet: str | None = Field(default=None, alias="pRedBCEfet")
+    v_bc_efet: str | None = Field(default=None, alias="vBCEfet")
+    p_icms_efet: str | None = Field(default=None, alias="pICMSEfet")
+    v_icms_efet: str | None = Field(default=None, alias="vICMSEfet")
+
+
+class IcmsSn101(BaseModel):
+    """Simples Nacional ICMS with a credit."""
+
+    model_config = _CONFIG
+
+    orig: str
+    csosn: str = Field(default="101", alias="CSOSN")
+    p_cred_sn: str = Field(alias="pCredSN")
+    v_cred_icms_sn: str = Field(alias="vCredICMSSN")
+
+
+class IcmsSn102(BaseModel):
+    """Simples Nacional ICMS without a credit."""
+
+    model_config = _CONFIG
+
+    orig: str | None = None
+    csosn: str = Field(alias="CSOSN")
+
+
+class IcmsUfDest(BaseModel):
+    """Interstate ICMS share owed to the destination state."""
+
+    model_config = _CONFIG
+
+    v_bc_uf_dest: str = Field(alias="vBCUFDest")
+    v_bc_fcp_uf_dest: str | None = Field(default=None, alias="vBCFCPUFDest")
+    p_fcp_uf_dest: str | None = Field(default=None, alias="pFCPUFDest")
+    p_icms_uf_dest: str = Field(alias="pICMSUFDest")
+    p_icms_inter: Literal["4.00", "7.00", "12.00"] = Field(alias="pICMSInter")
+    p_icms_inter_part: str = Field(alias="pICMSInterPart")
+    v_fcp_uf_dest: str | None = Field(default=None, alias="vFCPUFDest")
+    v_icms_uf_dest: str = Field(alias="vICMSUFDest")
+    v_icms_uf_remet: str = Field(alias="vICMSUFRemet")
+
+
+class IpiTrib(BaseModel):
+    """IPI taxed by rate."""
+
+    model_config = _CONFIG
+
+    cst: Literal["00", "49", "50", "99"] = Field(alias="CST")
+    v_bc: str | None = Field(default=None, alias="vBC")
+    p_ipi: str | None = Field(default=None, alias="pIPI")
+    q_unid: str | None = Field(default=None, alias="qUnid")
+    v_unid: str | None = Field(default=None, alias="vUnid")
+    v_ipi: str = Field(alias="vIPI")
+
+
+class IpiNt(BaseModel):
+    """IPI not taxed."""
+
+    model_config = _CONFIG
+
+    cst: str = Field(alias="CST")
+
+
+IpiVariant = IpiTrib | IpiNt | dict[str, Any]
+_IPI_TAGS = {IpiTrib: "IPITrib", IpiNt: "IPINT"}
+
+
+class Ipi(BaseModel):
+    """This item's IPI."""
+
+    model_config = _CONFIG
+
+    c_enq: str = Field(alias="cEnq")
+    trib: IpiVariant
+
+    def to_dict(self) -> dict:
+        """Returns the IPI group as a plain dict."""
+        data = {"cEnq": self.c_enq}
+        data.update(_wrap(self.trib, _IPI_TAGS))
+        return data
+
+
+class PisAliq(BaseModel):
+    """PIS taxed by rate."""
+
+    model_config = _CONFIG
+
+    cst: str = Field(alias="CST")
+    v_bc: str = Field(alias="vBC")
+    p_pis: str = Field(alias="pPIS")
+    v_pis: str = Field(alias="vPIS")
+
+
+class PisNt(BaseModel):
+    """PIS not taxed."""
+
+    model_config = _CONFIG
+
+    cst: str = Field(alias="CST")
+
+
+class PisOutr(BaseModel):
+    """PIS taxed some other way."""
+
+    model_config = _CONFIG
+
+    cst: str = Field(alias="CST")
+    v_bc: str | None = Field(default=None, alias="vBC")
+    p_pis: str | None = Field(default=None, alias="pPIS")
+    v_pis: str = Field(alias="vPIS")
+
+
+class CofinsAliq(BaseModel):
+    """COFINS taxed by rate."""
+
+    model_config = _CONFIG
+
+    cst: str = Field(alias="CST")
+    v_bc: str = Field(alias="vBC")
+    p_cofins: str = Field(alias="pCOFINS")
+    v_cofins: str = Field(alias="vCOFINS")
+
+
+class CofinsNt(BaseModel):
+    """COFINS not taxed."""
+
+    model_config = _CONFIG
+
+    cst: str = Field(alias="CST")
+
+
+class CofinsOutr(BaseModel):
+    """COFINS taxed some other way."""
+
+    model_config = _CONFIG
+
+    cst: str = Field(alias="CST")
+    v_bc: str | None = Field(default=None, alias="vBC")
+    p_cofins: str | None = Field(default=None, alias="pCOFINS")
+    v_cofins: str = Field(alias="vCOFINS")
+
+
+IcmsGroup = Icms00 | Icms40 | Icms60 | IcmsSn101 | IcmsSn102 | dict[str, Any]
+PisGroup = PisAliq | PisNt | PisOutr | dict[str, Any]
+CofinsGroup = CofinsAliq | CofinsNt | CofinsOutr | dict[str, Any]
+
+_ICMS_TAGS = {
+    Icms00: "ICMS00",
+    Icms40: "ICMS40",
+    Icms60: "ICMS60",
+    IcmsSn101: "ICMSSN101",
+    IcmsSn102: "ICMSSN102",
+}
+_PIS_TAGS = {PisAliq: "PISAliq", PisNt: "PISNT", PisOutr: "PISOutr"}
+_COFINS_TAGS = {
+    CofinsAliq: "COFINSAliq",
+    CofinsNt: "COFINSNT",
+    CofinsOutr: "COFINSOutr",
+}
+
+
+class Tax(BaseModel):
+    """This item's taxes, already computed by the caller."""
+
+    model_config = _CONFIG
+
+    v_tot_trib: str | None = Field(default=None, alias="vTotTrib")
+    icms: IcmsGroup | None = None
+    icms_uf_dest: IcmsUfDest | None = None
+    ipi: Ipi | dict[str, Any] | None = None
+    pis: PisGroup | None = None
+    cofins: CofinsGroup | None = None
+
+    def to_dict(self) -> dict:
+        """Returns the taxes as a plain dict."""
+        data: dict[str, Any] = {}
+        if self.v_tot_trib is not None:
+            data["vTotTrib"] = self.v_tot_trib
+        if self.icms is not None:
+            data["ICMS"] = _wrap(self.icms, _ICMS_TAGS)
+        if self.icms_uf_dest is not None:
+            data["ICMSUFDest"] = self.icms_uf_dest.model_dump(
+                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
+        if self.pis is not None:
+            data["PIS"] = _wrap(self.pis, _PIS_TAGS)
+        if self.cofins is not None:
+            data["COFINS"] = _wrap(self.cofins, _COFINS_TAGS)
+        return data
+
+
+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)}

stackin_python_sdk-0.1.0/stackin/core/__init__.py

@@ -0,0 +1 @@
+"""Core module."""

stackin_python_sdk-0.1.0/stackin/core/address.py

@@ -0,0 +1,21 @@
+"""Address module."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class Address(BaseModel):
+    """A plain postal address."""
+
+    state: str | None = Field(default=None)
+    city_code: str | None = Field(default=None)
+    street: str | None = Field(default=None)
+    number: str | None = Field(default=None)
+    neighborhood: str | None = Field(default=None)
+    city: str | None = Field(default=None)
+    zip_code: str | None = Field(default=None)
+
+    def to_dict(self) -> dict:
+        """Returns the address as a plain dict."""
+        return self.model_dump(exclude_none=True)

stackin_python_sdk-0.1.0/stackin/core/client.py

@@ -0,0 +1,151 @@
+"""Client module"""
+
+from __future__ import annotations
+
+import os
+
+import requests
+
+from stackin.core.address import Address
+from stackin.br.product import Product
+from stackin.core.exceptions import APIError, ConnectionFailedError
+from stackin.core.types import DocumentType, Environment
+
+DEFAULT_BASE_URL = "https://sdk.stackin.io"
+
+_ENVIRONMENT_URLS = {
+    Environment.LOCAL: "http://localhost:8000",
+    Environment.TEST: DEFAULT_BASE_URL,
+    Environment.PRODUCTION: DEFAULT_BASE_URL,
+}
+
+
+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."""
+    if base_url:
+        return base_url
+    if url := os.environ.get("STACKIN_BASE_URL"):
+        return url
+
+    if environment is not None:
+        return _ENVIRONMENT_URLS[Environment(environment)]
+    if env_name := os.environ.get("STACKIN_ENVIRONMENT"):
+        return _ENVIRONMENT_URLS[Environment(env_name)]
+    return DEFAULT_BASE_URL
+
+
+class Invoice:
+    """Client for issuing, consulting, and cancelling fiscal documents."""
+
+    def __init__(
+        self,
+        base_url: str | None = None,
+        environment: Environment | str | None = None,
+        api_key: str | None = None,
+        timeout: int = 30,
+    ) -> None:
+        resolved_url = _resolve_base_url(base_url, environment)
+        self.base_url = resolved_url.rstrip("/")
+        self.api_key = api_key or os.environ.get("STACKIN_API_KEY")
+        self.timeout = timeout
+
+    def issue(
+        self,
+        *,
+        document_type: DocumentType,
+        client_name: str,
+        tax_id: str,
+        items: list[Product],
+        recipient_address: Address | None = None,
+    ) -> dict:
+        """Issues a fiscal document."""
+        if not items:
+            raise ValueError("items can't be empty")
+
+        if document_type is DocumentType.NFE:
+            for index, item in enumerate(items):
+                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")
+
+        payload = {
+            "document_type": document_type.value,
+            "client_name": client_name,
+            "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
+
+        return self._request("POST", "/invoices", json=payload)
+
+    def consult(
+        self,
+        access_key: str,
+        *,
+        document_type: DocumentType,
+    ) -> dict:
+        """Consults a fiscal document by its access key."""
+        params = {"document_type": document_type.value}
+
+        return self._request("GET", f"/invoices/{access_key}", params=params)
+
+    def cancel(
+        self,
+        access_key: str,
+        *,
+        document_type: DocumentType,
+        reason: str,
+    ) -> dict:
+        """Cancels a fiscal document by its access key."""
+        payload = {
+            "document_type": document_type.value,
+            "reason": reason,
+        }
+
+        return self._request("POST", f"/invoices/{access_key}/cancel", json=payload)
+
+    def _headers(self) -> dict:
+        if self.api_key:
+            return {"Authorization": f"Bearer {self.api_key}"}
+        return {}
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: dict | None = None,
+        params: dict | None = None,
+    ) -> dict:
+        url = f"{self.base_url}/api/v1{path}"
+
+        try:
+            response = requests.request(
+                method,
+                url,
+                json=json,
+                params=params,
+                headers=self._headers(),
+                timeout=self.timeout,
+            )
+        except requests.RequestException as error:
+            raise ConnectionFailedError(str(error)) from error
+
+        try:
+            body = response.json() if response.content else {}
+        except ValueError:
+            body = {}
+
+        if not response.ok:
+            raise APIError(
+                status_code=response.status_code,
+                detail=body.get("detail", response.text),
+            )
+
+        return body.get("result", body)

stackin_python_sdk-0.1.0/stackin/core/exceptions.py

@@ -0,0 +1,19 @@
+"""Exceptions module."""
+
+
+class InvoiceError(Exception):
+    """Base exception for the invoice SDK."""
+
+
+class APIError(InvoiceError):
+    """Raised when the invoice API responds with an error status."""
+
+    def __init__(self, status_code: int, detail: str) -> None:
+        self.status_code = status_code
+        self.detail = detail
+        super().__init__(f"[{status_code}] {detail}")
+
+
+class ConnectionFailedError(InvoiceError):
+    """Raised when the invoice API can't be reached at all
+    (network/DNS/timeout)."""

stackin_python_sdk-0.1.0/stackin/core/types.py

@@ -0,0 +1,23 @@
+"""Types module."""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class DocumentType(str, Enum):
+    """The kind of fiscal document to issue, consult, or cancel."""
+
+    NFE = "nfe"
+    NFSE = "nfse"
+
+
+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."""
+
+    LOCAL = "local"
+    TEST = "test"
+    PRODUCTION = "production"