stackinReferencia
Glosario fiscal
El vocabulario que usa esta documentación. Cada entrada dice qué es el término, dónde aparece en una llamada a stackin, y lleva a donde la documentación lo trata a fondo.
Campos de la petición
Cada campo que usted completa, con el nombre que lleva en cada SDK y la etiqueta en que se convierte en el XML. Los nombres son en inglés; lo que significan es fiscal brasileño.
Documento
| Campo | SDK (Python / Go / PHP) | Tipo | Exigido en | Etiqueta XML | |
|---|---|---|---|---|---|
document_type | py·document_typego·DocumentTypephp/ts·documentType | "nfe" | "nfse" | nfenfse | mod | |
| Descripción Qué documento emitir. | |||||
client_name | py·client_namego·ClientNamephp/ts·clientName | string (1–120) | nfenfse | dest/xNome | |
| Descripción Razón social o nombre de quien recibe. En homologación la SEFAZ exige la frase de prueba en lugar del nombre real — stackin la sustituye por usted. | |||||
tax_id | py·tax_idgo·TaxIDphp/ts·taxId | string (11 | 14) | nfenfse | dest/CPF · dest/CNPJ | |
| Descripción El documento de quien recibe: CPF con 11 dígitos, CNPJ con 14. Usted no indica cuál es — la longitud lo decide. Vale para NF-e y NFS-e. Desde el 2026-07-31 el CNPJ puede llevar letras en sus 12 primeros caracteres. | |||||
items[] | py·itemsgo·Itemsphp/ts·items | Product[] | nfenfse | det | |
| Descripción Las líneas de la nota. Cada una es un producto (NF-e) o un servicio (NFS-e). | |||||
recipient_address | py·recipient_addressgo·RecipientAddressphp/ts·recipientAddress | Address | nfe | dest/enderDest | |
| Descripción Dirección del destinatario. Obligatoria y completa en NF-e; opcional en NFS-e. | |||||
series | py·seriesgo·Seriesphp/ts·series | string | — | ide/serie | |
| Descripción Serie del documento. Omitida, stackin usa la serie configurada en la empresa. | |||||
number | py·numbergo·Numberphp/ts·number | string | — | ide/nNF | |
| Descripción Número del documento. Omitido, stackin toma el siguiente de la secuencia — que es lo correcto en la mayoría de los casos. | |||||
contingency | py·—go·—php/ts·— | boolean | nfe | ide/tpEmis | |
| Descripción Emite por contingencia cuando la SEFAZ del estado está caída. Cambia el tipo de emisión en el XML y el destino de la transmisión. Solo por la API — ningún SDK expone este campo todavía. | |||||
Idempotency-Key | py·idempotency_keygo·IdempotencyKeyphp/ts·idempotencyKey | string | — | — | |
| Descripción La clave de reintento seguro. La misma clave con el mismo cuerpo devuelve la respuesta guardada en vez de emitir de nuevo — es lo que impide que un timeout se convierta en una nota duplicada. | |||||
Ítem
| Campo | SDK (Python / Go / PHP) | Tipo | Exigido en | Etiqueta XML | |
|---|---|---|---|---|---|
items[].description | py·descriptiongo·Descriptionphp/ts·description | string (1–120) | nfenfse | prod/xProd | |
| Descripción Descripción del producto o servicio, tal como sale en la nota y en el DANFE. | |||||
items[].unit_price | py·unit_pricego·UnitPricephp/ts·unitPrice | decimal (10) | nfenfse | prod/vUnCom | |
| Descripción Precio de una unidad. Acepta hasta 10 decimales. | |||||
items[].amount | py·amountgo·Amountphp/ts·amount | decimal (2) | nfenfse | prod/vProd | |
| Descripción Valor bruto total de la línea, antes de descuento, flete, seguro y otros gastos. Dos decimales. | |||||
items[].product.quantity | py·quantitygo·Quantityphp/ts·quantity | decimal (4) | nfe | prod/qCom | |
| Descripción Cantidad de la línea. Hasta 4 decimales — la cantidad fraccionada es normal a granel. | |||||
items[].product.unit | py·unitgo·Unitphp/ts·unit | string (≤6) | nfe | prod/uCom | |
| Descripción Unidad comercial: UN, CX, KG, L. Texto libre de hasta 6 caracteres. | |||||
items[].product.barcode | py·barcodego·Barcodephp/ts·barcode | string | — | prod/cEAN | |
| Descripción GTIN real del producto. Omitido, el XML lleva | |||||
items[].product.discount | py·discountgo·Discountphp/ts·discount | decimal (2) | — | prod/vDesc | |
| Descripción Descuento del producto, en la NF-e. Reduce el importe bruto de la línea y no puede superarlo. El descuento de servicio de la NFS-e es otro campo: | |||||
items[].product.freight | py·freightgo·Freightphp/ts·freight | decimal (2) | — | prod/vFrete | |
| Descripción Flete prorrateado en esta línea. | |||||
items[].product.insurance | py·insurancego·Insurancephp/ts·insurance | decimal (2) | — | prod/vSeg | |
| Descripción Seguro prorrateado en esta línea. | |||||
items[].product.other_expenses | py·other_expensesgo·OtherExpensesphp/ts·otherExpenses | decimal (2) | — | prod/vOutro | |
| Descripción Otros gastos accesorios de la línea. | |||||
items[].discount | py·discountgo·Discountphp/ts·discount | decimal (2) | nfse | vDescCondIncond/vDescIncond | |
| Descripción Descuento incondicional del servicio, en la NFS-e. Sale del importe gravable — no lo confundas con el descuento del producto, | |||||
items[].service_code | py·service_codego·ServiceCodephp/ts·serviceCode | string | nfse | cServ/cTribNac | |
| Descripción Ítem de la lista de la LC 116 — | |||||
items[].tax_retained | py·tax_retainedgo·TaxRetainedphp/ts·taxRetained | boolean | nfse | tribMun/tpRetISSQN | |
| Descripción ISSQN retenido por el tomador. Solo NFS-e. | |||||
items[].observations | py·observationsgo·Observationsphp/ts·observations | string (≤2000) | nfse | infAdic/infCpl | |
| Descripción Observaciones impresas en el cuerpo de la nota. Solo NFS-e. | |||||
Ítem — campos brasileños
| Campo | SDK (Python / Go / PHP) | Tipo | Exigido en | Etiqueta XML | |
|---|---|---|---|---|---|
items[].product.br.ncm | py·ncmgo·NCMphp/ts·ncm | string (8) | nfe | prod/NCM | |
| Descripción Clasificación de la mercancía en el Mercosur, 8 dígitos. Obligatoria en cada ítem de NF-e. | |||||
items[].product.br.cfop | py·cfopgo·CFOPphp/ts·cfop | string (4) | nfe | prod/CFOP | |
| Descripción Naturaleza de la operación, 4 dígitos. Obligatoria en cada ítem de NF-e. | |||||
items[].product.br.cest | py·cestgo·CESTphp/ts·cest | string (7) | — | prod/CEST | |
| Descripción Código de sustitución tributaria, 7 dígitos. Solo cuando la mercancía está en ese régimen. | |||||
items[].product.br.tax | py·taxgo·Taxphp/ts·tax | Tax | nfe | imposto | |
| Descripción Los grupos de impuesto del ítem — ICMS, IPI, PIS, COFINS. Es decisión fiscal del emisor; stackin no lo infiere. | |||||
items[].product.br.manufacturer_cnpj | py·manufacturer_cnpjgo·ManufacturerCNPJphp/ts·manufacturerCnpj | string (14) | — | prod/CNPJFab | |
| Descripción CNPJ del fabricante, cuando la operación exige identificarlo. | |||||
items[].product.br.ibs_cbs | py·ibs_cbsgo·IbsCbsphp/ts·ibsCbs | IbsCbs | nfe | imposto/IBSCBS | |
| Descripción Grupo IBS/CBS de la reforma tributaria. Las alícuotas y el CST vienen de usted; los importes se derivan de ellos. | |||||
Dirección del destinatario
| Campo | SDK (Python / Go / PHP) | Tipo | Exigido en | Etiqueta XML | |
|---|---|---|---|---|---|
recipient_address.street | py·streetgo·Streetphp/ts·street | string | nfe | enderDest/xLgr | |
| Descripción Calle del destinatario. | |||||
recipient_address.number | py·numbergo·Numberphp/ts·number | string | nfe | enderDest/nro | |
| Descripción Número del inmueble. Sin número, use | |||||
recipient_address.neighborhood | py·neighborhoodgo·Neighborhoodphp/ts·neighborhood | string | nfe | enderDest/xBairro | |
| Descripción Barrio. | |||||
recipient_address.city | py·citygo·Cityphp/ts·city | string | nfe | enderDest/xMun | |
| Descripción Nombre del municipio — pero lo que manda es | |||||
recipient_address.state | py·statego·Statephp/ts·state | string (2) | nfe | enderDest/UF | |
| Descripción Estado en dos letras. | |||||
recipient_address.zip_code | py·zip_codego·ZipCodephp/ts·zipCode | string (8) | nfe | enderDest/CEP | |
| Descripción Código postal, 8 dígitos, sin guion. | |||||
recipient_address.city_code | py·city_codego·CityCodephp/ts·cityCode | string (7) | nfe | enderDest/cMun | |
| Descripción Código IBGE del municipio, 7 dígitos. Es lo que la SEFAZ lee de verdad. | |||||
Documentos
- NF-e
- Modelo 55, emitida en cada salida de mercancía. Lo que la distingue en la práctica: cada ítem exige NCM y CFOP, el destinatario exige dirección completa con código de municipio, y la autorización es estatal — responde la SEFAZ del estado del emisor. Es la única que acepta carta de corrección e inutilización de rango.
document_type: "nfe"ReferenciasPortal Nacional da NF-eEsquemas XML espelhadosVer en la API - NFS-e
- Documento municipal de servicio. No hay mercancía, así que no hay NCM ni CFOP: cada ítem necesita descripción, precio y el código de servicio de la LC 116. La dirección del tomador es opcional. No existe carta de corrección — corregir significa cancelar y emitir de nuevo, dentro del plazo del municipio.
document_type: "nfse"ReferenciasNFS-e Nacional (gov.br)Lei Complementar 116/2003Ver en la API - DPS
- Es lo que efectivamente sube al entorno nacional: la DPS es la declaración que envía el emisor, y la nota es lo que el ADN devuelve a partir de ella. Nunca arma una DPS en stackin — la API la construye desde los campos de negocio y guarda el XML resultante.ReferenciasNFS-e — documentação técnicaPublicações NFS-e espelhadas
- DANFE
- El papel que acompaña la carga, con la clave de acceso como código de barras para la fiscalización en ruta. No es el documento fiscal: es una representación. Un DANFE sin el XML autorizado correspondiente no prueba nada.
GET /invoices/{access_key}/pdfReferenciasPortal Nacional da NF-eVer en la API - DANFSe
- La representación impresa de la NFS-e, generada por el entorno nacional. Misma relación: el valor jurídico está en el XML, el PDF es para que lo lea una persona.
GET /invoices/{access_key}/pdfReferenciasNFS-e Nacional (gov.br) - XML
- El documento en sí. Es lo que se firma con el certificado A1 del emisor, lo que la SEFAZ o el ADN autoriza, y lo que hay que guardar por cinco años. Todo lo demás — PDF, correo, pantalla — es representación.
xmlReferenciasEsquemas XML espelhadosVer en la API
Quién participa
- SEFAZ
- La autorizadora estatal de la NF-e. Cada estado tiene la suya, con su propia disponibilidad: una SEFAZ caída no derriba a las demás, y por eso existe la contingencia. Los rechazos vienen de aquí, con código numérico y motivo.ReferenciasPortal Nacional da NF-ePortal DF-e SVRSVer en la API
- ADN
- El entorno de datos nacional de la NFS-e. Centraliza la emisión de los municipios que adoptaron el estándar nacional, sustituyendo una integración por ayuntamiento por una sola. Los municipios que no adhirieron siguen con sistema propio.ReferenciasNFS-e Nacional (gov.br)NFS-e — documentação técnica
- Emitente
- Quien emite el documento. En stackin el emisor nunca viaja en el cuerpo de la petición: identificación fiscal, inscripción estatal, dirección, régimen tributario, certificado y entorno se resuelven desde la API key. Es deliberado — una key filtrada no permite emitir en nombre de otra empresa.ReferenciasCNPJ — Receita Federal
- Destinatário
- Quien recibe. Para NF-e la dirección es obligatoria y completa, incluido el código IBGE del municipio; para NFS-e es opcional.
tax_idacepta CPF o CNPJ y distingue cuál es por la longitud.client_nametax_idrecipient_addressReferenciasCódigos de município — IBGEVer en la API
Campos e identificadores
- Chave de acesso
- 44 dígitos en la NF-e, 50 en la NFS-e. No es aleatoria: lleva el estado, el año y mes, la identificación fiscal del emisor, el modelo, la serie, el número, el tipo de emisión y un dígito verificador. Es como se consulta y se cancela un documento — y lo que codifica el código de barras del DANFE.
access_keyReferenciasPortal Nacional da NF-eNotas Técnicas espelhadasVer en la API - Protocolo
- El número que devuelve la autorizadora cuando acepta el documento. Solo existe tras la autorización: un documento rechazado no tiene protocolo, por eso vuelve nulo mientras el estado no sea autorizado.
protocolReferenciasPortal Nacional da NF-e - Série e número
- Numeración secuencial por emisor, serie y modelo. No puede tener huecos: si un número se quemó y nunca llegó a ser documento autorizado, hay que inutilizarlo formalmente, o la SEFAZ lo preguntará en una fiscalización.
seriesnumberReferenciasPortal Nacional da NF-eVer en la API - Preço unitário e valor da linha
unit_pricees el precio de una unidad;amountes el valor bruto total de la línea, antes de descuento y recargos. Envíe uno de los dos — enviar ambos afirma que coinciden, y la API comparaquantity × unit_priceconamountantes de transmitir. En el XML se convierten envUnCom(10 decimales) yvProd(2 decimales).items[].unit_priceitems[].amountitems[].product.quantityReferenciasEsquemas XML espelhadosPortal Nacional da NF-eVer en la API- Encargos do item
- Descuento, flete, seguro y otros gastos pertenecen al ítem, no a la nota. El total del ítem es
bruto − descuento + flete + seguro + otros gastos, y la suma de estos campos alimenta los totalizadoresvDesc,vFrete,vSegyvOutro. Un descuento mayor que el valor bruto se rechaza antes de la transmisión.items[].product.discountitems[].product.freightitems[].product.insuranceitems[].product.other_expensesReferenciasEsquemas XML espelhadosVer en la API - CFOP
- Cuatro dígitos que declaran la naturaleza de la operación: el primero es el destino (5 dentro del estado, 6 fuera, 7 exterior) y los otros tres la finalidad — venta, devolución, remesa, industrialización. Decide cómo el estado grava la operación, así que un CFOP equivocado produce impuesto equivocado, no un error de esquema.
items[].product.br.cfopReferenciasAjuste SINIEF 07/05Ver en la API - NCM
- Ocho dígitos que clasifican la mercancía en el Mercosur. Determina la alícuota de IPI, el tratamiento de ICMS-ST y el régimen de importación. stackin valida el formato, nunca la elección: qué NCM aplica a su producto es decisión fiscal del emisor.
items[].product.br.ncmReferenciasNCM — Receita FederalVer en la API - CEST
- Siete dígitos, obligatorios solo para mercancía sujeta a sustitución tributaria. Si el producto no está en ese régimen el campo simplemente no va — enviar CEST en un producto fuera del ST es motivo de rechazo.
items[].product.br.cestReferenciasConvênio ICMS 142/18 - Unidade comercial
- La unidad en que se vende la mercancía — UN, CX, KG, L. Es texto libre de hasta 6 caracteres en el XML, no una lista cerrada, pero debe ser coherente con la cantidad: 2 CX a R$ 120,00 no es lo mismo que 2 UN a R$ 120,00 al verificar la carga.
items[].product.unitReferenciasEsquemas XML espelhados - GTIN
- El GTIN real del producto, cuando existe. Cuando no existe, el XML lleva la literal
SEM GTIN— que es lo que stackin envía si omite el campo. Inventar un número es peor que omitirlo: el dígito verificador se comprueba.items[].product.barcodeReferenciasNotas Técnicas espelhadas - Código de serviço
- El ítem de la lista de la LC 116/2003 —
1.07,7.02y así. Cada municipio desglosa esa lista a su manera, así que el mismo servicio puede tener un subítem distinto por ciudad. Sin él, stackin usa el código del perfil fiscal de la empresa.items[].service_codeReferenciasLei Complementar 116/2003NFS-e — documentação técnicaVer en la API - CNPJ e CPF
- CPF (11 dígitos) o CNPJ (14). Desde el 2026-07-31 el CNPJ es alfanumérico: los 12 primeros caracteres pueden ser letras, solo los 2 dígitos verificadores siguen siendo numéricos. Valide longitud y forma, nunca una regla de dígito de una revisión antigua — rechaza documentos válidos.
tax_idReferenciasCNPJ — Receita FederalVer en la API - Código de município
- El código IBGE de 7 dígitos del municipio. Obligatorio en la NF-e para emisor y destinatario, y es él — no el nombre de la ciudad — lo que lee la SEFAZ. Una ciudad bien escrita con el código equivocado es un rechazo.
recipient_address.city_codeReferenciasCódigos de município — IBGE
Eventos
- Cancelamento
- Un evento posterior a la autorización, con plazo legal contado desde ella (24 horas en la mayoría de los estados para NF-e) y un motivo de al menos 15 caracteres. Pasado el plazo no hay cancelación: la salida es una nota de devolución. Cancelar no borra el documento, registra un evento sobre él.
POST /invoices/{access_key}/cancelreasonReferenciasPortal Nacional da NF-eNotas Técnicas espelhadasVer en la API - CC-e
- La carta de corrección electrónica. Corrige lo que no altera valor, impuesto, emisor ni destinatario — típicamente la descripción, los datos de transporte, la información complementaria. Solo NF-e. Hasta 20 cartas por documento, y cada una sustituye a la anterior.
POST /invoices/{access_key}/correctioncorrectionReferenciasPortal Nacional da NF-eNotas Técnicas espelhadasVer en la API - Inutilização
- Declara a la SEFAZ que un rango de números nunca llegó a ser documento — quemado por una falla de sistema, por ejemplo. Es lo que impide que un hueco en la secuencia se vuelva un problema en fiscalización. No deshace una nota autorizada: para eso está la cancelación.
POST /invoices/invalidationsnumber_startnumber_endReferenciasPortal Nacional da NF-eVer en la API - Reemissão
- Reenvío de un documento que fue rechazado o falló en la transmisión. Consume un número nuevo, porque el anterior se quemó. stackin guarda los ítems del intento original, así que la reemisión no vuelve a pedir el cuerpo.
POST /invoices/{invoice_id}/reissueVer en la API - Rejeição
- La respuesta de la autorizadora rechazando el documento, con código numérico y motivo. Un rechazo no es un error de red ni un bug: es el fisco diciendo que el contenido está mal. El código es lo que importa — la 972, por ejemplo, es la ausencia del grupo de responsable técnico.
statusdetailReferenciasNotas Técnicas espelhadasPortal Nacional da NF-eVer en la API
Entornos
- Homologação
- El entorno de prueba de la propia autorizadora. Un documento emitido allí no tiene valor fiscal y el destinatario sale como
NF-E EMITIDA EM AMBIENTE DE HOMOLOGACAO - SEM VALOR FISCAL, por exigencia del fisco. Úselo sin límite: es gratuito e ilimitado.ReferenciasPortal Nacional da NF-eVer en la API - Produção
- El entorno real. Un documento emitido aquí tiene valor jurídico, entra en la liquidación de impuestos y solo sale por cancelación dentro del plazo. El entorno queda fijado en la API key, no viaja en la llamada — no se emite en producción por cambiar un parámetro sin querer.ReferenciasPortal Nacional da NF-eVer en la API
- Contingência
- El camino alternativo cuando la SEFAZ del estado no está disponible: el documento va a un entorno nacional (SVC-AN o SVC-RS, según el estado) en vez de esperar. Cambia el tipo de emisión dentro del XML, así que no es solo un reintento.
contingencyReferenciasPortal DF-e SVRSNotas Técnicas espelhadas - data-source
- El espejo público de las publicaciones oficiales que stackin sigue: notas técnicas, esquemas XML y manuales de NF-e y NFS-e, rastreados cada 6 horas, versionados y publicados como feed Atom y manifest JSON. Es lo que responde "¿cambió algo en el layout?" sin entrar en ningún portal.Referenciasstackin-io/data-sourceNotas Técnicas espelhadasEsquemas XML espelhados