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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackin-python-sdk
-Version: 0.7.0
+Version: 0.9.0
 Summary: Python SDK for issuing, consulting and cancelling electronic invoices.
 License-Expression: MIT
 License-File: LICENSE
@@ -47,7 +47,73 @@ Description-Content-Type: text/markdown
 
 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()`/`reissue()`/`correct()`/`invalidate()`/`pdf()`/`received()`/`manifest()`, 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.
+**One class, `Invoice`** — `issue()`/`consult()`/`cancel()`/`reissue()`/`correct()`/`invalidate()`/`pdf()`/`received()`/`manifest()`, nothing else to instantiate. Each line item is a `Product` (`stackin.br`) — `description` plus either `unit_price` or `amount` are universal, everything else (`ncm`/`cfop`/`cest`/tax groups...) is Brazil-specific and only required for NFE; NFSE ignores it.
+
+## What a line item is worth
+
+`unit_price` is the price of **one unit**. `amount` is the **gross total of
+the line's products**, before discount, freight, insurance and other
+expenses. Send either; sending both asserts that they agree.
+
+```python
+from decimal import Decimal
+
+# One unit
+Product(description="Consultoria", quantity=Decimal("1"), unit_price=Decimal("1500.00"))
+
+# More than one unit — amount is computed as 2 x 120.00 = 240.00
+Product(description="Teclado", quantity=Decimal("2"), unit_price=Decimal("120.00"))
+
+# A fractional quantity — 1.5 x 30.00 = 45.00
+Product(description="Cabo", quantity=Decimal("1.5"), unit_price=Decimal("30.00"))
+
+# Legacy: amount alone still means the line's gross total
+Product(description="Servico", quantity=Decimal("3"), amount=Decimal("150.00"))
+
+# Both, checked against each other before the document is transmitted
+Product(
+    description="Teclado",
+    quantity=Decimal("2"),
+    unit_price=Decimal("120.00"),
+    amount=Decimal("240.00"),
+)
+
+# With charges: 5000.00 - 100.50 + 40.00 + 10.00 = 4949.50 on the note
+Product(
+    description="Servidor",
+    quantity=Decimal("2"),
+    unit_price=Decimal("2500.00"),
+    discount=100.50,
+    freight=40.00,
+    insurance=10.00,
+)
+```
+
+Amounts that do not add up are refused before the authorizer sees them,
+with a `422` naming the line and both numbers:
+
+```json
+{
+  "detail": {
+    "code": "ITEM_TOTAL_MISMATCH",
+    "field": "items[0].amount",
+    "message": "amount is 50.00, but quantity x unit_price is 150.00.",
+    "expected": "150.00",
+    "received": "50.00"
+  }
+}
+```
+
+### Migrating
+
+```text
+Before:  quantity = 3, amount = 150.00
+After:   quantity = 3, unit_price = 50.00
+```
+
+Nothing has to migrate. `amount` keeps the meaning it always had and is
+not deprecated in this release; a line sent with `amount` alone is built
+exactly as it was before.
 
 ## Install
 
@@ -60,6 +126,8 @@ pip install stackin-python-sdk
 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 decimal import Decimal
+
 from stackin import Invoice, DocumentType, Address
 from stackin.br import Product  # Brazil-specific line item — NCM/CFOP
 
@@ -69,7 +137,7 @@ invoice = client.issue(
     document_type=DocumentType.NFSE,
     client_name="John Doe",
     tax_id="00000000000",
-    items=[Product(description="Software development", amount=5000.00)],
+    items=[Product(description="Software development", unit_price=Decimal("5000.00"))],
 )
 
 status = client.consult("ACCESS_KEY...", document_type=DocumentType.NFSE)
@@ -90,7 +158,16 @@ 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")],
+    items=[
+        Product(
+            description="Teclado",
+            quantity=Decimal("2"),
+            unit_price=Decimal("120.00"),
+            unit="UN",
+            ncm="84716052",
+            cfop="5102",
+        )
+    ],
     recipient_address=Address(
         street="Avenida Atlantica",
         number="500",
@@ -117,13 +194,15 @@ burned, and undoing it means cancelling, which has a deadline.
 Pass `idempotency_key` to make the retry safe:
 
 ```python
+from decimal import Decimal
+
 key = str(uuid.uuid4())
 
 result = invoice.issue(
     document_type=DocumentType.NFSE,
     client_name="Maria Silva",
     tax_id="12345678909",
-    items=[Product(description="Consultoria", amount=1500.00)],
+    items=[Product(description="Consultoria", unit_price=Decimal("1500.00"))],
     idempotency_key=key,
 )
 ```

{stackin_python_sdk-0.7.0 → stackin_python_sdk-0.9.0}/README.md

@@ -18,7 +18,73 @@
 
 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()`/`reissue()`/`correct()`/`invalidate()`/`pdf()`/`received()`/`manifest()`, 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.
+**One class, `Invoice`** — `issue()`/`consult()`/`cancel()`/`reissue()`/`correct()`/`invalidate()`/`pdf()`/`received()`/`manifest()`, nothing else to instantiate. Each line item is a `Product` (`stackin.br`) — `description` plus either `unit_price` or `amount` are universal, everything else (`ncm`/`cfop`/`cest`/tax groups...) is Brazil-specific and only required for NFE; NFSE ignores it.
+
+## What a line item is worth
+
+`unit_price` is the price of **one unit**. `amount` is the **gross total of
+the line's products**, before discount, freight, insurance and other
+expenses. Send either; sending both asserts that they agree.
+
+```python
+from decimal import Decimal
+
+# One unit
+Product(description="Consultoria", quantity=Decimal("1"), unit_price=Decimal("1500.00"))
+
+# More than one unit — amount is computed as 2 x 120.00 = 240.00
+Product(description="Teclado", quantity=Decimal("2"), unit_price=Decimal("120.00"))
+
+# A fractional quantity — 1.5 x 30.00 = 45.00
+Product(description="Cabo", quantity=Decimal("1.5"), unit_price=Decimal("30.00"))
+
+# Legacy: amount alone still means the line's gross total
+Product(description="Servico", quantity=Decimal("3"), amount=Decimal("150.00"))
+
+# Both, checked against each other before the document is transmitted
+Product(
+    description="Teclado",
+    quantity=Decimal("2"),
+    unit_price=Decimal("120.00"),
+    amount=Decimal("240.00"),
+)
+
+# With charges: 5000.00 - 100.50 + 40.00 + 10.00 = 4949.50 on the note
+Product(
+    description="Servidor",
+    quantity=Decimal("2"),
+    unit_price=Decimal("2500.00"),
+    discount=100.50,
+    freight=40.00,
+    insurance=10.00,
+)
+```
+
+Amounts that do not add up are refused before the authorizer sees them,
+with a `422` naming the line and both numbers:
+
+```json
+{
+  "detail": {
+    "code": "ITEM_TOTAL_MISMATCH",
+    "field": "items[0].amount",
+    "message": "amount is 50.00, but quantity x unit_price is 150.00.",
+    "expected": "150.00",
+    "received": "50.00"
+  }
+}
+```
+
+### Migrating
+
+```text
+Before:  quantity = 3, amount = 150.00
+After:   quantity = 3, unit_price = 50.00
+```
+
+Nothing has to migrate. `amount` keeps the meaning it always had and is
+not deprecated in this release; a line sent with `amount` alone is built
+exactly as it was before.
 
 ## Install
 
@@ -31,6 +97,8 @@ pip install stackin-python-sdk
 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 decimal import Decimal
+
 from stackin import Invoice, DocumentType, Address
 from stackin.br import Product  # Brazil-specific line item — NCM/CFOP
 
@@ -40,7 +108,7 @@ invoice = client.issue(
     document_type=DocumentType.NFSE,
     client_name="John Doe",
     tax_id="00000000000",
-    items=[Product(description="Software development", amount=5000.00)],
+    items=[Product(description="Software development", unit_price=Decimal("5000.00"))],
 )
 
 status = client.consult("ACCESS_KEY...", document_type=DocumentType.NFSE)
@@ -61,7 +129,16 @@ 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")],
+    items=[
+        Product(
+            description="Teclado",
+            quantity=Decimal("2"),
+            unit_price=Decimal("120.00"),
+            unit="UN",
+            ncm="84716052",
+            cfop="5102",
+        )
+    ],
     recipient_address=Address(
         street="Avenida Atlantica",
         number="500",
@@ -88,13 +165,15 @@ burned, and undoing it means cancelling, which has a deadline.
 Pass `idempotency_key` to make the retry safe:
 
 ```python
+from decimal import Decimal
+
 key = str(uuid.uuid4())
 
 result = invoice.issue(
     document_type=DocumentType.NFSE,
     client_name="Maria Silva",
     tax_id="12345678909",
-    items=[Product(description="Consultoria", amount=1500.00)],
+    items=[Product(description="Consultoria", unit_price=Decimal("1500.00"))],
     idempotency_key=key,
 )
 ```

{stackin_python_sdk-0.7.0 → stackin_python_sdk-0.9.0}/pyproject.toml

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

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

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

{stackin_python_sdk-0.7.0 → stackin_python_sdk-0.9.0}/stackin/br/__init__.py

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

{stackin_python_sdk-0.7.0 → stackin_python_sdk-0.9.0}/stackin/br/product.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+from decimal import Decimal
 from typing import Annotated, Any
 
 from pydantic import BaseModel, Field
@@ -9,6 +10,17 @@ from pydantic import BaseModel, Field
 from stackin.br.tax import Tax
 
 
+class IbsCbs(BaseModel):
+    """The Reforma Tributária group for one item."""
+
+    cst: str = Field(pattern=r"^\d{3}$")
+    classification: str = Field(pattern=r"^\d{6}$")
+    base: float | None = Field(default=None, gt=0)
+    rate_state: float = Field(ge=0)
+    rate_city: float = Field(ge=0)
+    rate_federal: float = Field(ge=0)
+
+
 class PresumedCredit(BaseModel):
     """A presumed tax credit applied to this item."""
 
@@ -32,15 +44,22 @@ _BR_FIELDS = {
     "import_content_control_number",
     "recopi_number",
     "extra_groups",
+    "ibs_cbs",
     "tax",
 }
 
 
+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")
+
+
 class Product(BaseModel):
     """One product or service line item on an invoice."""
 
     description: str = Field(..., min_length=1)
-    amount: float = Field(..., gt=0)
+    amount: Decimal | None = Field(default=None, gt=0)
+    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)
@@ -73,6 +92,7 @@ class Product(BaseModel):
         ),
     )
     recopi_number: str | None = Field(default=None, pattern=r"^\d{20}$")
+    ibs_cbs: IbsCbs | None = Field(default=None)
     extra_groups: dict[str, Any] | None = Field(default=None)
     tax: Tax | dict[str, Any] | None = Field(default=None)
 
@@ -102,6 +122,7 @@ class Product(BaseModel):
             exclude={
                 "description",
                 "amount",
+                "unit_price",
                 "tax",
                 *_BR_FIELDS,
                 *_NFSE_FIELDS,
@@ -116,7 +137,8 @@ class Product(BaseModel):
             data["br"] = br
         return {
             "description": self.description,
-            "amount": self.amount,
+            "amount": _decimal_str(self.amount),
+            "unit_price": _decimal_str(self.unit_price),
             "product": data,
             "service_code": self.service_code,
             "discount": self.service_discount,