Referência

Glossário fiscal

O vocabulário que a documentação usa. Cada verbete diz o que o termo é, quando ele aparece numa chamada à stackin, e leva para onde a doc trata do assunto a fundo.

Campos da requisição

Cada campo que você preenche, com o nome que ele tem em cada SDK e a tag que vira no XML. Os nomes são em inglês; o que eles significam é fiscal brasileiro.

Documento

Campo	SDK (Python / Go / PHP)	Tipo	Exigido em	Tag no XML
`document_type`	py·document_typego·DocumentTypephp/ts·documentType	`"nfe" \| "nfse"`	`nfenfse`	`mod`
Descrição Qual documento emitir. `nfe` é mercadoria e exige NCM, CFOP e endereço do destinatário; `nfse` é serviço e exige código de serviço.
`client_name`	py·client_namego·ClientNamephp/ts·clientName	`string (1–120)`	`nfenfse`	`dest/xNome`
Descrição Razão social ou nome de quem recebe. Em homologação a SEFAZ exige a frase de teste no lugar do nome real — a stackin substitui sozinha.
`tax_id`	py·tax_idgo·TaxIDphp/ts·taxId	`string (11 \| 14)`	`nfenfse`	`dest/CPF · dest/CNPJ`
Descrição O documento de quem recebe: CPF se tiver 11 dígitos, CNPJ se tiver 14. Você não diz qual é — o comprimento decide. Vale para NF-e e NFS-e. Desde 2026-07-31 o CNPJ pode ter letras nos 12 primeiros caracteres.
`items[]`	py·itemsgo·Itemsphp/ts·items	`Product[]`	`nfenfse`	`det`
Descrição As linhas da nota. Cada uma é um produto (NF-e) ou um serviço (NFS-e).
`recipient_address`	py·recipient_addressgo·RecipientAddressphp/ts·recipientAddress	`Address`	`nfe`	`dest/enderDest`
Descrição Endereço do destinatário. Obrigatório e completo na NF-e; opcional na NFS-e.
`series`	py·seriesgo·Seriesphp/ts·series	`string`	—	`ide/serie`
Descrição Série do documento. Omitido, a stackin usa a série configurada na empresa.
`number`	py·numbergo·Numberphp/ts·number	`string`	—	`ide/nNF`
Descrição Número do documento. Omitido, a stackin usa o próximo da sequência — que é o comportamento correto na maioria dos casos.
`contingency`	py·—go·—php/ts·—	`boolean`	`nfe`	`ide/tpEmis`
Descrição Emite por contingência quando a SEFAZ do estado está fora. Muda o tipo de emissão no XML e o destino da transmissão. Só pela API — nenhum SDK expõe esse campo ainda.
`Idempotency-Key`	py·idempotency_keygo·IdempotencyKeyphp/ts·idempotencyKey	`string`	—	—
Descrição Chave de repetição segura. A mesma chave com o mesmo corpo devolve a resposta guardada em vez de emitir de novo — é o que protege contra timeout virar nota duplicada.

Item

Campo	SDK (Python / Go / PHP)	Tipo	Exigido em	Tag no XML
`items[].description`	py·descriptiongo·Descriptionphp/ts·description	`string (1–120)`	`nfenfse`	`prod/xProd`
Descrição Descrição do produto ou serviço, como sai na nota e no DANFE.
`items[].unit_price`	py·unit_pricego·UnitPricephp/ts·unitPrice	`decimal (10)`	`nfenfse`	`prod/vUnCom`
Descrição Preço de uma unidade. Aceita até 10 casas decimais.
`items[].amount`	py·amountgo·Amountphp/ts·amount	`decimal (2)`	`nfenfse`	`prod/vProd`
Descrição Valor bruto total da linha, antes de desconto, frete, seguro e outras despesas. Duas casas decimais.
`items[].product.quantity`	py·quantitygo·Quantityphp/ts·quantity	`decimal (4)`	`nfe`	`prod/qCom`
Descrição Quantidade da linha. Até 4 casas decimais — quantidade fracionada é normal em granel.
`items[].product.unit`	py·unitgo·Unitphp/ts·unit	`string (≤6)`	`nfe`	`prod/uCom`
Descrição Unidade comercial: UN, CX, KG, L. Texto livre de até 6 caracteres.
`items[].product.barcode`	py·barcodego·Barcodephp/ts·barcode	`string`	—	`prod/cEAN`
Descrição GTIN real do produto. Omitido, o XML leva `SEM GTIN`.
`items[].product.discount`	py·discountgo·Discountphp/ts·discount	`decimal (2)`	—	`prod/vDesc`
Descrição Desconto do produto, na NF-e. Reduz o valor bruto da linha e não pode ser maior que ele. O desconto de serviço da NFS-e é outro campo: `items[].discount`.
`items[].product.freight`	py·freightgo·Freightphp/ts·freight	`decimal (2)`	—	`prod/vFrete`
Descrição Frete rateado nesta linha.
`items[].product.insurance`	py·insurancego·Insurancephp/ts·insurance	`decimal (2)`	—	`prod/vSeg`
Descrição Seguro rateado nesta linha.
`items[].product.other_expenses`	py·other_expensesgo·OtherExpensesphp/ts·otherExpenses	`decimal (2)`	—	`prod/vOutro`
Descrição Outras despesas acessórias da linha.
`items[].discount`	py·discountgo·Discountphp/ts·discount	`decimal (2)`	`nfse`	`vDescCondIncond/vDescIncond`
Descrição Desconto incondicional do serviço, na NFS-e. Sai do valor tributável — não confunda com o desconto do produto, que é `items[].product.discount` e só vale na NF-e.
`items[].service_code`	py·service_codego·ServiceCodephp/ts·serviceCode	`string`	`nfse`	`cServ/cTribNac`
Descrição Item da lista da LC 116 — `1.07`, `7.02`. Omitido, usa o do perfil fiscal da empresa.
`items[].tax_retained`	py·tax_retainedgo·TaxRetainedphp/ts·taxRetained	`boolean`	`nfse`	`tribMun/tpRetISSQN`
Descrição ISSQN retido pelo tomador. Só NFS-e.
`items[].observations`	py·observationsgo·Observationsphp/ts·observations	`string (≤2000)`	`nfse`	`infAdic/infCpl`
Descrição Observações que saem no corpo da nota. Só NFS-e.

Item — campos brasileiros

Campo	SDK (Python / Go / PHP)	Tipo	Exigido em	Tag no XML
`items[].product.br.ncm`	py·ncmgo·NCMphp/ts·ncm	`string (8)`	`nfe`	`prod/NCM`
Descrição Classificação da mercadoria no Mercosul, 8 dígitos. Obrigatório em cada item de NF-e.
`items[].product.br.cfop`	py·cfopgo·CFOPphp/ts·cfop	`string (4)`	`nfe`	`prod/CFOP`
Descrição Natureza da operação, 4 dígitos. Obrigatório em cada item de NF-e.
`items[].product.br.cest`	py·cestgo·CESTphp/ts·cest	`string (7)`	—	`prod/CEST`
Descrição Código de substituição tributária, 7 dígitos. Só quando a mercadoria está no regime de ST.
`items[].product.br.tax`	py·taxgo·Taxphp/ts·tax	`Tax`	`nfe`	`imposto`
Descrição Os grupos de imposto do item — ICMS, IPI, PIS, COFINS. É decisão fiscal do emitente, a stackin não infere.
`items[].product.br.manufacturer_cnpj`	py·manufacturer_cnpjgo·ManufacturerCNPJphp/ts·manufacturerCnpj	`string (14)`	—	`prod/CNPJFab`
Descrição CNPJ do fabricante, quando a operação exige identificá-lo.
`items[].product.br.ibs_cbs`	py·ibs_cbsgo·IbsCbsphp/ts·ibsCbs	`IbsCbs`	`nfe`	`imposto/IBSCBS`
Descrição Grupo IBS/CBS da Reforma Tributária. Alíquotas e CST vêm de você; os valores são calculados a partir delas.

Endereço do destinatário

Campo	SDK (Python / Go / PHP)	Tipo	Exigido em	Tag no XML
`recipient_address.street`	py·streetgo·Streetphp/ts·street	`string`	`nfe`	`enderDest/xLgr`
Descrição Logradouro do destinatário.
`recipient_address.number`	py·numbergo·Numberphp/ts·number	`string`	`nfe`	`enderDest/nro`
Descrição Número do imóvel. Sem número, use `S/N`.
`recipient_address.neighborhood`	py·neighborhoodgo·Neighborhoodphp/ts·neighborhood	`string`	`nfe`	`enderDest/xBairro`
Descrição Bairro.
`recipient_address.city`	py·citygo·Cityphp/ts·city	`string`	`nfe`	`enderDest/xMun`
Descrição Nome do município — mas quem manda é o `city_code`.
`recipient_address.state`	py·statego·Statephp/ts·state	`string (2)`	`nfe`	`enderDest/UF`
Descrição UF em duas letras.
`recipient_address.zip_code`	py·zip_codego·ZipCodephp/ts·zipCode	`string (8)`	`nfe`	`enderDest/CEP`
Descrição CEP, 8 dígitos, sem hífen.
`recipient_address.city_code`	py·city_codego·CityCodephp/ts·cityCode	`string (7)`	`nfe`	`enderDest/cMun`
Descrição Código IBGE do município, 7 dígitos. É o que a SEFAZ lê de fato.

Documentos

NF-e: Modelo 55, emitida a cada saída de mercadoria. O que a distingue na prática: cada item exige NCM e CFOP, o destinatário exige endereço completo com código de município, e a autorização é estadual — quem responde é a SEFAZ do estado do emitente. É a única que aceita carta de correção e inutilização de faixa.document_type: "nfe"ReferênciasPortal Nacional da NF-e Esquemas XML espelhadosVer na API
NFS-e: Documento municipal de serviço. Não há mercadoria, então não há NCM nem CFOP: cada item precisa de descrição, preço e o código de serviço da LC 116. Endereço do tomador é opcional. Não existe carta de correção — corrigir significa cancelar e emitir de novo, dentro do prazo do município.document_type: "nfse"ReferênciasNFS-e Nacional (gov.br)Lei Complementar 116/2003Ver na API
DPS: É o que efetivamente sobe para o ambiente nacional: a DPS é a declaração que o emitente manda, e a nota é o que o ADN devolve a partir dela. Você nunca monta uma DPS na stackin — a API monta a partir dos campos de negócio e guarda o XML resultante.ReferênciasNFS-e — documentação técnica Publicações NFS-e espelhadas
DANFE: Papel que acompanha a carga, com o código de barras da chave de acesso para leitura em barreira fiscal. Não é o documento fiscal: é uma representação dele. Uma DANFE sem o XML correspondente autorizado não prova nada.GET /invoices/{access_key}/pdfReferênciasPortal Nacional da NF-eVer na API
DANFSe: Representação impressa da NFS-e, gerada pelo ambiente nacional. Mesma relação: o valor jurídico está no XML, o PDF é para o cliente ler.GET /invoices/{access_key}/pdfReferênciasNFS-e Nacional (gov.br)
XML: O documento em si. É ele que é assinado com o certificado A1 do emitente, é ele que a SEFAZ ou o ADN autoriza, e é ele que precisa ser guardado por cinco anos. Todo o resto — PDF, e-mail, tela — é representação.xmlReferênciasEsquemas XML espelhadosVer na API

Quem participa

SEFAZ: Autorizadora estadual da NF-e. Cada estado tem a sua, com disponibilidade própria: uma SEFAZ fora do ar não derruba as outras, e é por isso que existe contingência. As rejeições vêm dela, com código numérico e motivo.ReferênciasPortal Nacional da NF-e Portal DF-e SVRSVer na API
ADN: Ambiente de Dados Nacional da NFS-e. Centraliza a emissão dos municípios que aderiram ao padrão nacional, o que substitui uma integração por prefeitura por uma só. Municípios que não aderiram continuam com sistema próprio.ReferênciasNFS-e Nacional (gov.br)NFS-e — documentação técnica
Emitente: Quem emite a nota. Na stackin o emitente nunca vai no corpo da requisição: CNPJ, inscrição estadual, endereço, regime tributário, certificado e ambiente são resolvidos a partir da API key. Isso é deliberado — significa que uma key vazada não permite emitir em nome de outra empresa.ReferênciasCNPJ — Receita Federal
Destinatário: Quem recebe. Para NF-e o endereço é obrigatório e completo, incluindo o código IBGE do município; para NFS-e é opcional. O tax_id aceita CPF ou CNPJ e decide sozinho qual dos dois é, pelo comprimento.client_nametax_idrecipient_addressReferênciasCódigos de município — IBGEVer na API

Campos e identificadores

Chave de acesso: 44 dígitos na NF-e, 50 na NFS-e. Não é aleatória: carrega UF, ano e mês, CNPJ do emitente, modelo, série, número, tipo de emissão e um dígito verificador. É por ela que se consulta e se cancela um documento — e é o que vai no código de barras da DANFE.access_keyReferênciasPortal Nacional da NF-e Notas Técnicas espelhadasVer na API
Protocolo: O número que a autorizadora devolve quando aceita o documento. Só existe depois da autorização: um documento rejeitado não tem protocolo, e é por isso que ele vem nulo enquanto o status não for autorizado.protocolReferênciasPortal Nacional da NF-e
Série e número: Numeração sequencial por emitente, por série e por modelo. Não pode ter buraco: se um número foi queimado e nunca virou documento autorizado, ele precisa ser inutilizado formalmente, senão a SEFAZ cobra a explicação em fiscalização.seriesnumberReferênciasPortal Nacional da NF-eVer na API
Preço unitário e valor da linha: unit_price é o preço de uma unidade; amount é o valor bruto total da linha, antes de desconto e acréscimos. Envie um dos dois — mandar os dois é afirmar que fecham, e a API compara quantity × unit_price com amount antes de transmitir. No XML viram vUnCom (10 casas) e vProd (2 casas).items[].unit_priceitems[].amountitems[].product.quantityReferênciasEsquemas XML espelhados Portal Nacional da NF-eVer na API
Encargos do item: Desconto, frete, seguro e outras despesas entram por item, não na nota. O total do item é bruto − desconto + frete + seguro + outras despesas, e a soma desses campos alimenta os totalizadores vDesc, vFrete, vSeg e vOutro. Desconto maior que o valor bruto é recusado antes da transmissão.items[].product.discountitems[].product.freightitems[].product.insuranceitems[].product.other_expensesReferênciasEsquemas XML espelhadosVer na API
CFOP: Quatro dígitos que dizem a natureza da operação: o primeiro é o destino (5 dentro do estado, 6 fora, 7 exterior) e os outros três a finalidade — venda, devolução, remessa, industrialização. É o campo que determina como o estado tributa a operação, então um CFOP errado gera imposto errado, não erro de schema.items[].product.br.cfopReferênciasAjuste SINIEF 07/05Ver na API
NCM: Oito dígitos que classificam a mercadoria no Mercosul. Define alíquota de IPI, tratamento de ICMS-ST e regime de importação. A stackin valida o formato, nunca a escolha: qual NCM se aplica ao seu produto é decisão fiscal do emitente.items[].product.br.ncmReferênciasNCM — Receita FederalVer na API
CEST: Sete dígitos, obrigatórios apenas para mercadoria sujeita a substituição tributária. Se o produto não está no regime, o campo simplesmente não vai — mandar CEST em produto fora do ST é motivo de rejeição.items[].product.br.cestReferênciasConvênio ICMS 142/18
Unidade comercial: A unidade em que a mercadoria é vendida — UN, CX, KG, L. É texto livre de até 6 caracteres no XML, não uma lista fechada, mas precisa ser coerente com a quantidade: 2 CX a R$ 120,00 é diferente de 2 UN a R$ 120,00 na hora de conferir a carga.items[].product.unitReferênciasEsquemas XML espelhados
GTIN: O GTIN real do produto, quando existe. Quando não existe, o XML leva a literal SEM GTIN — que é o que a stackin envia se você omitir o campo. Mandar um número inventado é pior que omitir: o dígito verificador é conferido.items[].product.barcodeReferênciasNotas Técnicas espelhadas
Código de serviço: O item da lista da LC 116/2003 — 1.07, 7.02 e assim por diante. Cada município desdobra essa lista do seu jeito, então o mesmo serviço pode ter subitem diferente por cidade. Sem ele, a stackin usa o código do perfil fiscal da empresa.items[].service_codeReferênciasLei Complementar 116/2003 NFS-e — documentação técnicaVer na API
CNPJ e CPF: CPF (11 dígitos) ou CNPJ (14). Desde 2026-07-31 o CNPJ é alfanumérico: os 12 primeiros caracteres podem ser letras, só os 2 dígitos verificadores continuam numéricos. Valide comprimento e formato, nunca a regra de dígito de uma revisão antiga — ela rejeita documento válido.tax_idReferênciasCNPJ — Receita FederalVer na API
Código de município: Código IBGE de 7 dígitos do município. Obrigatório na NF-e para emitente e destinatário, e é ele — não o nome da cidade — que a SEFAZ usa. Cidade escrita certo com código errado é rejeição.recipient_address.city_codeReferênciasCódigos de município — IBGE

Eventos

Cancelamento: Evento posterior à autorização, com prazo legal contado da autorização (24 horas na maioria dos estados para NF-e) e motivo de no mínimo 15 caracteres. Depois do prazo não existe cancelamento: a saída é nota de devolução. Cancelar não apaga o documento, registra um evento sobre ele.POST /invoices/{access_key}/cancelreasonReferênciasPortal Nacional da NF-e Notas Técnicas espelhadasVer na API
CC-e: Carta de Correção eletrônica. Corrige o que não altera valor, imposto, emitente ou destinatário — tipicamente descrição, dados de transporte, informações complementares. Só NF-e. Até 20 cartas por documento, e cada uma substitui a anterior.POST /invoices/{access_key}/correctioncorrectionReferênciasPortal Nacional da NF-e Notas Técnicas espelhadasVer na API
Inutilização: Declara à SEFAZ que uma faixa de numeração não virou documento — queimada por falha de sistema, por exemplo. É o que impede um buraco na sequência de virar problema em fiscalização. Não serve para desfazer nota autorizada: para isso é cancelamento.POST /invoices/invalidationsnumber_startnumber_endReferênciasPortal Nacional da NF-eVer na API
Reemissão: Reenvio de um documento que foi rejeitado ou falhou na transmissão. Consome um número novo, porque o anterior foi queimado. A stackin guarda os itens da tentativa original, então a reemissão não pede o corpo de novo.POST /invoices/{invoice_id}/reissueVer na API
Rejeição: Resposta da autorizadora recusando o documento, com código numérico e motivo. Rejeição não é erro de rede nem bug: é o fisco dizendo que o conteúdo está errado. O código é o que importa — a 972, por exemplo, é ausência do grupo de responsável técnico.statusdetailReferênciasNotas Técnicas espelhadas Portal Nacional da NF-eVer na API

Ambientes

Homologação: Ambiente de teste da própria autorizadora. Documento emitido ali não tem valor fiscal e o destinatário sai como NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL por exigência do fisco. Use à vontade: é gratuito e ilimitado.ReferênciasPortal Nacional da NF-eVer na API
Produção: Ambiente real. Documento emitido aqui tem valor jurídico, entra na apuração de imposto e só sai por cancelamento dentro do prazo. O ambiente é fixado na API key, não vai na chamada — não existe emitir em produção por engano trocando um parâmetro.ReferênciasPortal Nacional da NF-eVer na API
Contingência: Caminho alternativo quando a SEFAZ do estado está indisponível: o documento vai para um ambiente nacional (SVC-AN ou SVC-RS, conforme a UF) em vez de esperar. Muda o tipo de emissão dentro do XML, então não é só um retry.contingencyReferênciasPortal DF-e SVRS Notas Técnicas espelhadas
data-source: O espelho público das publicações oficiais que a stackin acompanha: notas técnicas, esquemas XML e manuais da NF-e e da NFS-e, varridos a cada 6 horas, versionados e publicados como feed Atom e manifest JSON. É a fonte que responde 'mudou alguma coisa no leiaute?' sem entrar em portal nenhum.Referênciasstackin-io/data-source Notas Técnicas espelhadas Esquemas XML espelhados