Integrate once. Issue everywhere.

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

pip install stackin-python-sdk

Usage

Get an api_key from the stackin dashboard — 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.

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/ — simple_issue_nfe.py and simple_issue_nfse.py, each with a catalog of realistic line items covering every optional field.

Commit Style