stackin-python-sdk 0.3.0__tar.gz → 0.4.0__tar.gz

{stackin_python_sdk-0.3.0 → stackin_python_sdk-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: stackin-python-sdk
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python SDK for issuing, consulting and cancelling electronic invoices.
 License-Expression: MIT
 License-File: LICENSE
@@ -47,7 +47,7 @@ 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()`, 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`/`amount` are universal, everything else (`ncm`/`cfop`/`cest`/tax groups...) is Brazil-specific and only required for NFE; NFSE ignores it.
 
 ## Install
 
@@ -200,6 +200,40 @@ round trip — and the authorizer checks again for what we can't see from here.
 
 **NF-e only**, and it takes no access key: there is no document to point at.
 
+## Documents issued against you
+
+Everything above serves the **issuer**. These two serve the **recipient**: what
+suppliers billed to this CNPJ, and the formal answer to it.
+
+Reading the list never calls the SEFAZ. The authorizer caps how many times a CNPJ
+may ask for its distribution per day, so collecting runs on a schedule on the API
+side and a page refresh cannot spend that allowance.
+
+```python
+from stackin import Manifestation
+
+page = client.received(limit=20)
+for document in page["data"]:
+    print(document["access_key"], document["issuer_name"], document["amount"])
+
+client.manifest(access_key, manifestation=Manifestation.CIENCIA)
+client.manifest(
+    access_key,
+    manifestation=Manifestation.OPERACAO_NAO_REALIZADA,
+    reason="Mercadoria nunca chegou ao endereco",
+)
+```
+
+Before you answer a document the SEFAZ sends only a **summary** (`resNFe`): access
+key, issuer, amount, date. The **full document** (`nfeProc`) arrives after a
+manifestation, and the `schema` field on each row says which one you hold.
+
+The four answers are `210200` Confirmação da Operação, `210210` Ciência da
+Operação, `210220` Desconhecimento da Operação and `210240` Operação não
+Realizada. Only the last one takes a reason, and it requires one — both rules are
+checked locally, before the request goes out, because a round trip to be told a
+fixed rule is a round trip wasted.
+
 ## 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_python_sdk-0.3.0 → stackin_python_sdk-0.4.0}/README.md

@@ -18,7 +18,7 @@
 
 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()`, 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`/`amount` are universal, everything else (`ncm`/`cfop`/`cest`/tax groups...) is Brazil-specific and only required for NFE; NFSE ignores it.
 
 ## Install
 
@@ -171,6 +171,40 @@ round trip — and the authorizer checks again for what we can't see from here.
 
 **NF-e only**, and it takes no access key: there is no document to point at.
 
+## Documents issued against you
+
+Everything above serves the **issuer**. These two serve the **recipient**: what
+suppliers billed to this CNPJ, and the formal answer to it.
+
+Reading the list never calls the SEFAZ. The authorizer caps how many times a CNPJ
+may ask for its distribution per day, so collecting runs on a schedule on the API
+side and a page refresh cannot spend that allowance.
+
+```python
+from stackin import Manifestation
+
+page = client.received(limit=20)
+for document in page["data"]:
+    print(document["access_key"], document["issuer_name"], document["amount"])
+
+client.manifest(access_key, manifestation=Manifestation.CIENCIA)
+client.manifest(
+    access_key,
+    manifestation=Manifestation.OPERACAO_NAO_REALIZADA,
+    reason="Mercadoria nunca chegou ao endereco",
+)
+```
+
+Before you answer a document the SEFAZ sends only a **summary** (`resNFe`): access
+key, issuer, amount, date. The **full document** (`nfeProc`) arrives after a
+manifestation, and the `schema` field on each row says which one you hold.
+
+The four answers are `210200` Confirmação da Operação, `210210` Ciência da
+Operação, `210220` Desconhecimento da Operação and `210240` Operação não
+Realizada. Only the last one takes a reason, and it requires one — both rules are
+checked locally, before the request goes out, because a round trip to be told a
+fixed rule is a round trip wasted.
+
 ## 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_python_sdk-0.3.0 → stackin_python_sdk-0.4.0}/pyproject.toml

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

{stackin_python_sdk-0.3.0 → stackin_python_sdk-0.4.0}/stackin/__init__.py

@@ -1,6 +1,6 @@
 """Invoice __init__ module."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 __description__ = (
     "Python SDK for issuing, consulting and cancelling electronic invoices."
 )
@@ -8,12 +8,13 @@ __description__ = (
 from .core.address import Address
 from .core.client import Invoice
 from .core.exceptions import APIError, ConnectionFailedError, InvoiceError
-from .core.types import DocumentType, Environment
+from .core.types import DocumentType, Environment, Manifestation
 
 __all__ = [
     "Invoice",
     "DocumentType",
     "Environment",
+    "Manifestation",
     "Address",
     "InvoiceError",
     "APIError",

{stackin_python_sdk-0.3.0 → stackin_python_sdk-0.4.0}/stackin/br/__init__.py

@@ -5,12 +5,29 @@ from stackin.br.tax import (
     CofinsAliq,
     CofinsNt,
     CofinsOutr,
+    CofinsQtde,
+    CofinsSt,
     Icms00,
+    Icms02,
+    Icms10,
+    Icms15,
+    Icms20,
+    Icms30,
     Icms40,
+    Icms51,
+    Icms53,
     Icms60,
+    Icms61,
+    Icms70,
+    Icms90,
+    IcmsPart,
     IcmsSn101,
     IcmsSn102,
+    IcmsSn201,
+    IcmsSn202,
+    IcmsSn500,
     IcmsSn900,
+    IcmsSt,
     IcmsUfDest,
     Ipi,
     IpiNt,
@@ -18,6 +35,8 @@ from stackin.br.tax import (
     PisAliq,
     PisNt,
     PisOutr,
+    PisQtde,
+    PisSt,
     Tax,
 )
 
@@ -26,19 +45,38 @@ __all__ = [
     "PresumedCredit",
     "Tax",
     "Icms00",
+    "Icms02",
+    "Icms10",
+    "Icms15",
+    "Icms20",
+    "Icms30",
     "Icms40",
+    "Icms51",
+    "Icms53",
     "Icms60",
+    "Icms61",
+    "Icms70",
+    "Icms90",
+    "IcmsPart",
+    "IcmsSt",
     "IcmsSn101",
     "IcmsSn102",
+    "IcmsSn201",
+    "IcmsSn202",
+    "IcmsSn500",
     "IcmsSn900",
     "IcmsUfDest",
     "Ipi",
     "IpiTrib",
     "IpiNt",
     "PisAliq",
+    "PisQtde",
     "PisNt",
     "PisOutr",
+    "PisSt",
     "CofinsAliq",
+    "CofinsQtde",
     "CofinsNt",
     "CofinsOutr",
+    "CofinsSt",
 ]

{stackin_python_sdk-0.3.0 → stackin_python_sdk-0.4.0}/stackin/br/product.py

@@ -67,7 +67,10 @@ class Product(BaseModel):
     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}$",
+        pattern=(
+            r"^[A-F0-9]{8}-[A-F0-9]{4}-[A-F0-9]{4}"
+            r"-[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)