SDKs

result = client.issue(
    document_type=DocumentType.NFSE,
    client_name="Maria Silva",
    tax_id="12345678909",
    items=[Product(description="Consultoria", unit_price=Decimal("1500.00"))],
    idempotency_key=key,
)

idempotency_key

string | optionalsua chave, no máximo 255 caracteres. O SDK só a repassa no header — nunca gera nem guarda nada.

replay

same key, same bodymesma chave, mesmo corpo: devolve a resposta gravada, sem reprocessar.

APIError 422

same key, other bodymesma chave, corpo diferente. Reusar uma chave em outra requisição é erro do cliente, não repetição.

APIError 409

still runninga primeira chamada ainda está rodando. Consulte antes de tentar de novo.

try:
    result = client.issue(...)
except APIError as error:
    if error.status_code == 429:
        # Wait before calling again — reuse the same idempotency_key.
        raise

issue / reissue

60 / mingera documento e consome crédito.

consult / cancel

120 / minfala com a SEFAZ, mas não gera documento.

APIError 429

over the limitespere e repita com a mesma chave de idempotência.

IBS/CBS — Reforma Tributária

O grupo da Reforma Tributária, por item. Obrigatório a partir de 2026 para o regime normal. cst e classification (cClassTrib) são decisão fiscal sua; a API deriva os valores das alíquotas.

As três alíquotas são percentuais: rate_state (pIBSUF), rate_city (pIBSMun) e rate_federal (pCBS). base é opcional — sem ela, a base é o valor do item. Item sem o grupo não emite nada, que é como a NF-e era antes da reforma.

from stackin.br import IbsCbs, Product

Product(
    description="Teclado",
    quantity=Decimal("2"),
    unit_price=Decimal("120.00"),
    ncm="84716052",
    cfop="5102",
    ibs_cbs=IbsCbs(
        cst="000",
        classification="000001",
        rate_state=0.1,
        rate_city=0.0,
        rate_federal=0.9,
    ),
)

Grupos de imposto do item

ICMS, IPI, PIS e COFINS por item, através de Tax. Cada grupo tem sua classe por CST/CSOSN — IcmsSn102 para Simples Nacional sem crédito, PisNt e CofinsNt para não tributado, e assim por diante.

A stackin não infere tributação: qual grupo se aplica é decisão fiscal do emitente, e errar aqui gera imposto errado, não erro de schema. Sem tax, nenhum grupo de imposto vai no XML.

from stackin.br import CofinsNt, IcmsSn102, PisNt, Product, Tax

Product(
    description="Teclado",
    quantity=Decimal("2"),
    unit_price=Decimal("120.00"),
    ncm="84716052",
    cfop="5102",
    tax=Tax(icms=IcmsSn102(csosn="102"), pis=PisNt(cst="07"), cofins=CofinsNt(cst="07")),
)

Notas fiscais

Emitir nota

Emite um novo documento. items[].product.br (ncm, cfop) é obrigatório para , ignorado em , ignored for — serviço não tem código de classificação fiscal, então nfse só lê description e amount de cada item.

A mesma chamada funciona para nfse — basta trocar document_type.

from decimal import Decimal

from stackin import Address, DocumentType, Invoice
from stackin.br import Product

client = Invoice(api_key="$STACKIN_API_KEY")

result = client.issue(
    document_type=DocumentType.NFE,
    client_name="Buyer Company Ltd",
    tax_id="11222333000181",
    items=[
        Product(
            description="Rosa Holambra Vermelha",
            unit_price=Decimal("112.44"),
            ncm="06031100",
            cfop="5102",
        )
    ],
    recipient_address=Address(
        street="Rua das Flores",
        number="1200",
        neighborhood="Centro",
        city="Joinville",
        state="SC",
        zip_code="89201100",
        city_code="4209102",
    ),
)

Consultar nota

Consulta o status atual de um documento direto no autorizador pela access key. Requer como query param.

result = client.consult(
    document_type=DocumentType.NFE,
    access_key="42260831112223330001815500000012341123456789",
)

Cancelar nota

Cancela um documento previamente autorizado. precisa ter pelo menos 15 caracteres para nfe (o campo xJust do autorizador exige). Cancelar não devolve cota do plano — a capacidade do autorizador já foi gasta na emissão.

result = client.cancel(
    document_type=DocumentType.NFE,
    access_key="42260831112223330001815500000012341123456789",
    reason="Duplicate order, cancelled by the buyer within 24h",
)

Reemitir nota

Reenvia uma emissão que falhou, pelo `id` local do documento (não pela chave de acesso — uma nota rejeitada não tem uma). Útil pra retentar depois de corrigir um problema de configuração ou uma indisponibilidade do autorizador. Consome crédito como uma emissão nova, já que é uma nova transmissão.

result = client.reissue(
    invoice_id="9f2c1e3a-4b5d-6e7f-8a9b-0c1d2e3f4a5b",
)

Corrigir nota

Corrige uma nota já autorizada com uma carta de correção, sem cancelar nem reemitir — não consome crédito nem queima número da série. Serve para erro que não muda o imposto: nome de produto, dados de transporte, informações complementares.

O texto vai de 15 a 1000 caracteres, conferido pelo SDK antes da chamada. Uma CC-e não corrige nada que mude o valor do imposto, o emitente, o destinatário ou a data de emissão — nesses casos ainda é cancelar e reemitir. A nota original não muda: a correção fica anexada a ela. São no máximo 20 por nota, numeradas automaticamente. Só NF-e; para NFS-e vem APIError 409.

result = client.correct(
    "35240912345678000199550010000000011000000017",
    document_type=DocumentType.NFE,
    correction="Transportadora corrigida para Rapido Ltda",
)

Inutilizar faixa

A numeração da NF-e é sequencial e a SEFAZ cobra que não tenha buraco. O número é reservado quando a emissão começa, então uma emissão que falha depois disso — rejeição, timeout — deixa um vão na série. Inutilizar a faixa é como se fecha esse vão.

O motivo vai de 15 a 255 caracteres e a faixa é inclusiva — o SDK confere os dois, e que o fim não seja menor que o início, antes da chamada. Número que já chegou na SEFAZ não pode ser inutilizado: vem APIError 409 dizendo quais são. Só NF-e, e sem chave de acesso: não há documento para apontar.

result = client.invalidate(
    series="1",
    number_start=10,
    number_end=12,
    reason="Numeracao reservada e nao utilizada por falha no ERP",
)

PDF do documento

A representação impressa que a autorizadora gera — DANFE para NF-e, DANFSe para NFS-e. Retorna bytes crus, o único método que não devolve objeto: grave em arquivo ou sirva direto.

O XML continua sendo o documento com valor jurídico; o PDF é conveniência. O endpoint da autorizadora para isso é instável, então um erro 502 aqui significa autorizadora indisponível, não que a nota está errada.

pdf = client.pdf(access_key, document_type=DocumentType.NFSE)

with open("nota.pdf", "wb") as file:
    file.write(pdf)

Histórico

O que esta empresa emitiu, mais recente primeiro. É a contrapartida de received: aquele lista o que emitiram contra você, este o que você emitiu.

Filtra por document_type e status (issued, rejected, cancelled) e pagina com limit e offset. A resposta traz o envelope de paginação padrão.

page = client.history(
    document_type=DocumentType.NFE,
    status="issued",
    limit=20,
    offset=0,
)

for row in page["data"]:
    print(row["access_key"], row["client_name"], row["amount"])

Tentativas

Toda tentativa feita para uma nota e o que voltou da autorizadora. consult dá o status; este dá o motivo — o código da rejeição e o XML que foi enviado.

Recebe o invoice_id, não a chave de acesso: um documento rejeitado nunca teve chave. É por aqui que se descobre, por exemplo, que a rejeição foi 972.

attempts = client.submissions(invoice["id"])

for attempt in attempts:
    print(attempt["status"], attempt["detail"])

Notas recebidas

Documentos que outras empresas emitiram contra o seu CNPJ. Lê o que a API já coletou — não chama a autorizadora na hora.

A coleta roda em agenda do lado da API porque a SEFAZ limita quantas vezes um CNPJ pode consultar por dia. Consultar aqui não gasta essa cota.

page = client.received(limit=20)

for document in page["data"]:
    print(document["access_key"], document["issuer_name"], document["amount"])

Manifestação

A resposta formal de quem recebeu: confirmação, ciência, desconhecimento ou operação não realizada.

Só operação não realizada aceita justificativa — e exige uma. O SDK verifica isso antes de sair da sua máquina, em vez de gastar uma ida à API para ser informado.

from stackin import Manifestation

client.manifest(access_key, manifestation=Manifestation.CONFIRMACAO)

client.manifest(
    access_key,
    manifestation=Manifestation.OPERACAO_NAO_REALIZADA,
    reason="Mercadoria nao recebida",
)