stackin-python-sdk 0.6.0__py3-none-any.whl → 0.8.0__py3-none-any.whl

stackin/__init__.py

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

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
@@ -36,11 +37,17 @@ _BR_FIELDS = {
 }
 
 
+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)
@@ -102,6 +109,7 @@ class Product(BaseModel):
             exclude={
                 "description",
                 "amount",
+                "unit_price",
                 "tax",
                 *_BR_FIELDS,
                 *_NFSE_FIELDS,
@@ -116,7 +124,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/core/client.py

@@ -141,15 +141,25 @@ class Invoice:
         *,
         document_type: DocumentType,
         reason: str,
+        idempotency_key: str | None = None,
     ) -> dict:
-        """Cancels a fiscal document by its access key."""
+        """Cancels a fiscal document by its access key.
+
+        Repeating the same idempotency_key with the same body replays
+        the first answer instead of cancelling twice. Cancelling is
+        irreversible and has a legal window, so a blind retry on a
+        dropped connection is the case this exists for.
+        """
         payload = {
             "document_type": document_type.value,
             "reason": reason,
         }
 
         return self._request(
-            "POST", f"/invoices/{access_key}/cancel", json=payload
+            "POST",
+            f"/invoices/{access_key}/cancel",
+            json=payload,
+            idempotency_key=idempotency_key,
         )
 
     def invalidate(

{stackin_python_sdk-0.6.0.dist-info → stackin_python_sdk-0.8.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackin-python-sdk
-Version: 0.6.0
+Version: 0.8.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
 
@@ -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",

{stackin_python_sdk-0.6.0.dist-info → stackin_python_sdk-0.8.0.dist-info}/RECORD

@@ -1,13 +1,13 @@
-stackin/__init__.py,sha256=H9pBLgWFY-FCi4oOnoW-RM63GgAIJQfTICEfO61LPZw,531
+stackin/__init__.py,sha256=d07OH2vuFftm39TnZQmE1pIEWq3kHeTjkuRWFChVVE8,531
 stackin/br/__init__.py,sha256=ktBhaGVPE81n8r5jdIloERq4x9B2AE1k9-1IlzqVhVM,1184
-stackin/br/product.py,sha256=877FGYgVZ8iBIJFecsDRbbnEiKmbMY5WBuVtHoEoia4,4044
+stackin/br/product.py,sha256=DrQ0DGIfQlJh8ANN1xK74y8LXnMLZGtN8bV_zsOpn14,4431
 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=Jh5Qkg_AHXBlKZ_rIkSFXEMMcjiC_928EDvMVZewnko,11701
+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.6.0.dist-info/METADATA,sha256=OBtsl_XghGyuIZlQVJMe1fjxsLJyR6gWWHRYu3DcbLc,11041
-stackin_python_sdk-0.6.0.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
-stackin_python_sdk-0.6.0.dist-info/licenses/LICENSE,sha256=D-XHDcKFFhzEo9C5Dp4QPvt00pb_u__hi4Bc08zpxyU,1072
-stackin_python_sdk-0.6.0.dist-info/RECORD,,
+stackin_python_sdk-0.8.0.dist-info/METADATA,sha256=s_AljpFSzWMedZupxxXaCkcDbEf90TjdV4Zdb0Z8AsE,13101
+stackin_python_sdk-0.8.0.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
+stackin_python_sdk-0.8.0.dist-info/licenses/LICENSE,sha256=D-XHDcKFFhzEo9C5Dp4QPvt00pb_u__hi4Bc08zpxyU,1072
+stackin_python_sdk-0.8.0.dist-info/RECORD,,