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

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/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/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,

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

@@ -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.dist-info → stackin_python_sdk-0.9.0.dist-info}/RECORD

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