API Reference

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 | optionalyour key, up to 255 characters. It is scoped to your company: one account's key never collides with another's.

201

replaysame key, same body: returns the recorded response without reprocessing.

422

mismatchsame key, different body. Reusing a key on another request is a client bug, not a retry.

409

in progressthe first call is still running. Consult before trying again.

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 / minproduces a document and consumes credit.

POST /invoices/{id}/reissue

60 / minproduces a document and consumes credit.

GET /invoices/{access_key}

120 / minreaches the SEFAZ, but produces no document.

POST /invoices/{access_key}/cancel

120 / minreaches the SEFAZ, but produces no document.

GET /invoices

600 / minnever leaves 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

eventthe SEFAZ authorized the document.

invoice.rejected

eventthe SEFAZ refused it. The reason is on the invoice's history.

invoice.cancelled

eventthe cancellation went through.

invoice.corrected

eventa correction letter was filed.

Stackin-Signature

headerthe timestamp is part of what is signed, so a captured delivery cannot be replayed later.

Stackin-Delivery-Id

headeridentifies the delivery. Two with the same id are the same thing, sent again.

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"

additive

no new versionnew field, new enum value, new endpoint, new optional parameter.

breaking

requires /v2removing something, changing a type, tightening a validation, changing what a value means, making an optional parameter required.

Deprecation

HTTP-datewhen the version was marked to go. It is an HTTP-date, not ISO.

Sunset

HTTP-datewhen it stops answering. At least 12 months after the announcement.

Item values

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 they agree: quantity x unit_price is compared with amount and the document is refused before transmission if they differ. Decimal values may be sent as strings to keep their precision — unit_price takes up to 10 places.

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

When they do not agree the answer is 422, naming the line and both numbers:

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

Also refused: neither field (ITEM_AMOUNT_MISSING), values at or below zero, a discount larger than the gross amount (ITEM_DISCOUNT_EXCEEDS_GROSS) and precision the XML cannot carry (ITEM_PRECISION_UNSUPPORTED). Nothing has to migrate: amount keeps the meaning it always had.

IBS/CBS — tax reform

The tax-reform group, per item. Required from 2026 for the regime normal. cst and classification (cClassTrib) are your fiscal decision; the API derives the amounts from the rates.

The three rates are percentages: rate_state (pIBSUF), rate_city (pIBSMun) and rate_federal (pCBS). base is optional — without it, the base is the item amount. An item without the group emits nothing, which is what an NF-e looked like before the reform.

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

Invoices

Issue an invoice

Issues a new document. items[].product.br (ncm, cfop) is required for , ignored for , ignored for — a service has no tax classification code, so nfse only reads description and amount off each item.

List invoices

Lists the company's issuance history, paginated (see Pagination above). Filter with document_type and and (issued, rejected, cancelled).

Consult an invoice

Looks up a document's current status directly at the authorizer by its access key. Requires as a query param.

Cancel an invoice

Cancels a previously authorized document. must be at least 15 characters for nfe (the authorizer's xJust field requires it). Cancelling doesn't refund plan quota — the authorizer capacity was already spent on issuance.

Reissue invoice

Retries a failed submission by the document's local `id` (not its access key — a rejected invoice doesn't have one). Useful for retrying after fixing a configuration problem or an authorizer outage. Consumes credit like a fresh issuance, since it's a new transmission.

Correct invoice

Guide:NF-e correction letter (CC-e): what can be corrected, deadline, how-to

Corrects an already-authorized document with a correction letter (CC-e), without cancelling and reissuing — it consumes no credit and burns no series number. It covers mistakes that don't change the tax: a product name, transport details, extra information.

The text runs 15 to 1000 characters. A CC-e cannot fix anything that changes the tax owed, the seller, the buyer, or the issue date — those still mean cancelling and reissuing. The original document doesn't change: the correction is attached to it. At most 20 per document, numbered for you. NF-e only; NFS-e answers 409.

Invalidate range

Guide:Invalidating NF-e numbers at the SEFAZ: when and how

NF-e numbering is sequential and the SEFAZ expects it to have no gaps. The number is reserved the moment issuing starts, so a submission that fails afterwards — a rejection, a timeout — leaves a hole in the series. Invalidating the range is how that hole gets closed.

The reason runs 15 to 255 characters and the range is inclusive. A number that already reached the SEFAZ can't be invalidated: we check our own records first and answer 409 naming them, without a round trip — and the SEFAZ checks again for what we can't see from here. NF-e only, and no access key: there is no document to point at. Use GET /invoices/invalidations to list the ranges already reported.

Document PDF

The printed representation the authorizer generates — DANFE for NF-e, DANFSe for NFS-e. Returns raw bytes, the only method that does not return an object: write it to a file or serve it directly.

The XML remains the legally valid document; the PDF is a convenience. The authorizer’s endpoint for it is unstable, so a 502 here means the authorizer is unavailable, not that the invoice is wrong.

Attempts

Every attempt made for one invoice and what came back from the authorizer. consult gives the status; this gives the reason — the rejection code and the XML that was sent.

It takes the invoice_id, not the access key: a rejected document never had one. This is how you find out that a rejection was, say, 972.

Received invoices

Documents other companies issued against your tax id. It reads what the API already collected — it does not call the authorizer on the spot.

Collection runs on a schedule on the API side because the SEFAZ caps how many times a tax id may ask per day. Reading here does not spend that quota.

Manifestation

Guide:NF-e Recipient Manifestation: events, deadlines and XML download

The recipient’s formal answer: confirmation, acknowledgement, unknown operation or operation not performed.

Only operation not performed takes a reason — and it requires one. The SDK checks that before leaving your machine, rather than spending a round trip to be told.