Referência da API

curl -X POST https://api.stackin.io/api/v1/invoices \
  -H "Authorization: Bearer $STACKIN_API_KEY" \
  -H "Idempotency-Key: 3f7c1e9a-2b4d-4f6a-8c1e-9d0b5a7f2c34" \
  -H "Content-Type: application/json" \
  -d '{
  "document_type": "nfse",
  "client_name": "John Doe",
  "tax_id": "00000000000",
  "items": [
    { "description": "Technical consulting - 10 hours", "unit_price": "1500.00" }
  ]
}'

Idempotency-Key

header | optionalsua chave, no máximo 255 caracteres. O escopo é a sua empresa: a chave de uma conta nunca colide com a de outra.

201

replaymesma chave, mesmo corpo: devolve a resposta gravada, sem reprocessar.

422

mismatchmesma chave, corpo diferente. Reusar uma chave em outra requisição é erro do cliente, não repetição.

409

in progressa primeira chamada ainda está rodando. Consulte antes de tentar de novo.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1788556800

{
  "detail": "Rate limit reached: 60 requests per 60s for this operation. Retry after the window resets."
}

POST /invoices

60 / mingera documento e consome crédito.

POST /invoices/{id}/reissue

60 / mingera documento e consome crédito.

GET /invoices/{access_key}

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

POST /invoices/{access_key}/cancel

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

GET /invoices

600 / minnão sai da stackin.

curl -X POST https://api.stackin.io/api/v1/webhooks \
  -H "Authorization: Bearer $STACKIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://seu-erp.com.br/stackin", "secret": "um-segredo-longo-e-aleatorio", "events": []}'

{
  "event": "invoice.authorized",
  "data": {
    "invoice_id": "9f2c1e3a-4b5d-6e7f-8a9b-0c1d2e3f4a5b",
    "document_type": "nfe",
    "access_key": "35240912345678000199550010000000011000000017",
    "status": "issued",
    "amount": 1500.0
  }
}

import hashlib, hmac, time

def verify(secret: str, body: str, header: str, tolerance: int = 300) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    if abs(int(time.time()) - int(parts["t"])) > tolerance:
        return False
    expected = hmac.new(
        secret.encode(),
        f'{parts["t"]}.{body}'.encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

invoice.authorized

eventa SEFAZ autorizou o documento.

invoice.rejected

eventa SEFAZ recusou. O motivo está no histórico da nota.

invoice.cancelled

evento cancelamento foi aceito.

invoice.corrected

eventuma carta de correção foi registrada.

Stackin-Signature

headero timestamp entra no que é assinado, então uma entrega capturada não pode ser reenviada depois.

Stackin-Delivery-Id

headeridentifica a entrega. Duas com o mesmo id são a mesma coisa, reenviada.

Deprecation: Fri, 01 Jan 2027 00:00:00 GMT
Sunset: Sat, 01 Jan 2028 00:00:00 GMT
Link: <https://docs.stackin.io/api#versioning>; rel="deprecation"

aditivo

sem versão novacampo novo, valor novo num enum, endpoint novo, parâmetro opcional novo.

breaking

exige /v2remover algo, mudar tipo, apertar validação, mudar o significado de um valor, tornar obrigatório o que era opcional.

Deprecation

HTTP-datequando a versão foi marcada para sair. É HTTP-date, não ISO.

Sunset

HTTP-datequando ela para de responder. Ao menos 12 meses depois do anúncio.

Valores do item

unit_price é o preço de uma unidade. amount é o valor bruto total dos produtos da linha, antes de desconto, frete, seguro e outras despesas.

Envie um dos dois. Enviar os dois é afirmar que fecham: quantity x unit_price é comparado com amount e a nota é recusada antes da transmissão se divergirem. Valores decimais podem ir como string para não perder precisão — unit_price aceita até 10 casas.

# unit_price: what one unit costs
{
  "description": "Teclado",
  "product": { "quantity": 2, "unit": "UN", "br": { "ncm": "84716052", "cfop": "5102" } },
  "unit_price": "120.00"
}
# -> qCom 2.0000  vUnCom 120.0000000000  vProd 240.00

# amount: the line's gross total (the original contract)
{
  "description": "Teclado",
  "product": { "quantity": 3 },
  "amount": "50.00"
}
# -> qCom 3.0000  vUnCom 16.6666666667  vProd 50.00

# both, checked against each other before transmission
{
  "description": "Teclado",
  "product": { "quantity": 2 },
  "unit_price": "120.00",
  "amount": "240.00"
}

Quando não fecham, a resposta é 422 e diz qual linha e quais números:

{
  "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"
  }
}

Também são recusados: nenhum dos dois campos (ITEM_AMOUNT_MISSING), valores menores ou iguais a zero, desconto maior que o valor bruto (ITEM_DISCOUNT_EXCEEDS_GROSS) e precisão que o XML não carrega (ITEM_PRECISION_UNSUPPORTED). Nada precisa migrar: amount mantém o significado que sempre teve.

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.

{
  "description": "Teclado",
  "unit_price": "120.00",
  "product": {
    "quantity": 2,
    "br": {
      "ncm": "84716052",
      "cfop": "5102",
      "ibs_cbs": {
        "cst": "000",
        "classification": "000001",
        "rate_state": 0.1,
        "rate_city": 0.0,
        "rate_federal": 0.9
      }
    }
  }
}

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.

Listar notas

Lista o histórico de emissões da empresa, paginado (veja Paginação acima). Filtre com document_type e and (issued, rejected, cancelled).

Consultar nota

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

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.

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.

Corrigir nota

Guia:Carta de correção NF-e: o que pode ser corrigido, prazo e como fazer

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. 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 a resposta é 409.

Inutilizar faixa

Guia:Inutilizar numeração da NF-e na SEFAZ: quando e como fazer

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. Número que já chegou na SEFAZ não pode ser inutilizado: conferimos primeiro nos nossos registros e respondemos 409 dizendo quais são, sem ida à SEFAZ — e a SEFAZ confere de novo o que não dá para ver daqui. Só NF-e, e sem chave de acesso: não há documento para apontar. Use GET /invoices/invalidations para listar as faixas já inutilizadas.

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.

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.

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.

Manifestação

Guia:Manifestação do Destinatário da NF-e: eventos, prazo e download do XML

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.