Issuing an NF-e
Complete tutorial for issuing an NF-e (Nota Fiscal Eletronica) through the NF-e SP connector.
Overview
NF-e issuance is done through the nfe_autorizacao action, which receives a JSON payload with the invoice data and returns the SEFAZ authorization protocol.
Basic Structure
from abstra.connectors import run_connection_action
params = {
"id_lote": "1",
"ind_sinc": "1",
"versao": "4.00",
"nfe": [
{
"inf_nfe": {
"versao": "4.00",
"ide": {
# Invoice identification
},
"emit": {
# Issuer data
},
"dest": {
# Recipient data
},
"det": [
# Line items
],
"total": {
# Totals
},
"transp": {
# Shipping
},
"pag": {
# Payment
}
}
}
]
}
result = run_connection_action("nfe-sp", "nfe_autorizacao", params)
Important: The fields
id(access key) andc_dv(check digit) are computed automatically by the connector. You don't need to provide them.
Identification (ide)
"ide": {
"c_uf": "35", # State code (35 = SP)
"c_nf": "12345678", # Random numeric code (8 digits)
"nat_op": "VENDA", # Operation type
"mod": "55", # Model (55 = NF-e)
"serie": "1", # Series (no leading zeros)
"n_nf": "1001", # NF-e number
"dh_emi": "2026-03-26T10:00:00-03:00", # Emission datetime with timezone
"tp_nf": "1", # Type (0=inbound, 1=outbound)
"id_dest": "1", # Destination (1=in-state, 2=interstate, 3=international)
"c_mun_fg": "3550308", # IBGE municipality code
"tp_imp": "1", # DANFE format (1=portrait)
"tp_emis": "1", # Emission type (1=normal)
"tp_amb": "1", # Environment (1=production, 2=homologation)
"fin_nfe": "1", # Purpose (1=normal, 2=complementary, 3=adjustment, 4=return)
"ind_final": "0", # End consumer (0=no, 1=yes)
"ind_pres": "1", # Presence (1=in-person, 2=online, 9=other)
"proc_emi": "0", # Emission process (0=application)
"ver_proc": "1.0" # Application version
}
Key rules for ide fields
| Field | Rule | Valid | Invalid |
|---|---|---|---|
serie | No leading zeros. Values: 0 or 1 to 999 | "3" | "003" |
n_nf | No leading zeros. Range: 1 to 999999999 | "74110" | "074110" |
c_nf | Exactly 8 digits | "12345678" | "1234567" |
dh_emi | ISO 8601 with mandatory timezone | "2026-03-26T10:00:00-03:00" | "2026-03-26T10:00:00" |
Return invoices (NF-e de Devolucao)
For return invoices, set fin_nfe: "4" and add a reference to the original invoice:
"ide": {
"fin_nfe": "4",
"n_fref": [
{
"ref_nfe": "35260312345678000199550010000010011123456789" # Original invoice access key
}
],
...
}
Issuer (emit)
"emit": {
"cnpj": "12345678000199", # CNPJ (14 digits, no punctuation)
"x_nome": "COMPANY NAME LTDA", # Legal name (2-60 chars)
"ender_emit": {
"x_lgr": "RUA EXEMPLO", # Street
"nro": "100", # Number
"x_bairro": "CENTRO", # Neighborhood
"c_mun": "3550308", # IBGE municipality code
"x_mun": "SAO PAULO", # Municipality name
"uf": "SP", # State
"cep": "01000000", # ZIP code (8 digits)
"c_pais": "1058", # Country code (1058 = Brazil)
"x_pais": "BRASIL" # Country name
},
"ie": "123456789012", # State registration
"crt": "3" # Tax regime (1=Simples, 2=Simples excess, 3=Normal)
}
Line Items (det)
Each item is an object in the det array:
"det": [
{
"n_item": "1",
"prod": {
"c_prod": "PROD001",
"c_ean": "SEM GTIN",
"x_prod": "PRODUCT DESCRIPTION",
"ncm": "94016100", # NCM code (8 digits)
"cfop": "5102", # CFOP (4 digits, starts with 1,2,3,5,6,7)
"u_com": "UN",
"q_com": "1.0000",
"v_un_com": "100.0000",
"v_prod": "100.00",
"c_ean_trib": "SEM GTIN",
"u_trib": "UN",
"q_trib": "1.0000",
"v_un_trib": "100.0000",
"ind_tot": "1" # Included in totals (1=yes)
},
"imposto": {
# Item taxes (see taxes section)
}
}
]
Taxes (imposto)
Each item must have exactly one variant of each tax. You cannot combine variants.
ICMS
Choose only one of the options:
| Variant | When to use |
|---|---|
icms00 | Full taxation |
icms10 | With ST (tax substitution) |
icms20 | With reduced tax base |
icms30 | Exempt with ST |
icms40 | Exempt / Not taxed / Suspended |
icms51 | Deferral |
icms60 | Previously collected via ST |
icms70 | With reduced tax base and ST |
icms90 | Other |
icmssn101 to icmssn900 | Simples Nacional |
"imposto": {
"icms": {
"icms00": { # Only ONE variant
"orig": "0",
"cst": "00",
"mod_bc": "3",
"v_bc": "100.00",
"p_icms": "18.0000",
"v_icms": "18.00"
}
}
}
IPI
Choose only one of the options:
# Option 1: IPI taxed
"ipi": {
"c_enq": "999",
"ipi_trib": {
"cst": "50",
"v_bc": "100.00",
"p_ipi": "5.0000",
"v_ipi": "5.00"
}
}
# Option 2: IPI not taxed
"ipi": {
"c_enq": "999",
"ipint": {
"cst": "53"
}
}
PIS and COFINS
Same single-choice logic:
# PIS
"pis": {
"pis_aliq": { "cst": "01", "v_bc": "100.00", "p_pis": "1.6500", "v_pis": "1.65" }
# OR pis_qtde, pisnt, pis_outr
}
# COFINS
"cofins": {
"cofins_aliq": { "cst": "01", "v_bc": "100.00", "p_cofins": "7.6000", "v_cofins": "7.60" }
# OR cofins_qtde, cofinsnt, cofins_outr
}
Return IPI (imposto_devol)
For return invoices with returned IPI, the imposto_devol field must be a sibling of imposto inside det, not a child:
"det": [
{
"n_item": "1",
"prod": { ... },
"imposto": {
"icms": { ... },
"ipi": {
"c_enq": "999",
"ipint": { "cst": "53" }
},
"pis": { ... },
"cofins": { ... }
},
"imposto_devol": { # Sibling of "imposto", NOT a child
"p_devol": "100.00", # Return percentage (0-100)
"ipi": {
"v_ipi_devol": "16.90"
}
}
}
]
warning
Common mistake: Placing imposto_devol inside imposto. This causes rejection 225 (XML schema failure) because SEFAZ does not recognize the field in that position.
# WRONG
"imposto": {
"icms": { ... },
"imposto_devol": { ... } # CANNOT be inside imposto
}
# CORRECT
"imposto": {
"icms": { ... },
},
"imposto_devol": { ... } # Must be here, at the same level as imposto
Totals (total)
"total": {
"icms_tot": {
"v_bc": "100.00",
"v_icms": "18.00",
"v_icms_deson": "0.00",
"v_fcp": "0.00",
"v_bcst": "0.00",
"v_st": "0.00",
"v_fcpst": "0.00",
"v_fcpst_ret": "0.00",
"v_prod": "100.00",
"v_frete": "0.00",
"v_seg": "0.00",
"v_desc": "0.00",
"v_ii": "0.00",
"v_ipi": "0.00",
"v_ipi_devol": "0.00", # Sum of returned IPI
"v_pis": "1.65",
"v_cofins": "7.60",
"v_outro": "0.00",
"v_nf": "100.00" # Total invoice value
}
}
Note: For return invoices,
v_ipishould be"0.00"if there's no taxed IPI on the items. The returned IPI value goes inv_ipi_devol.
Shipping and Payment
"transp": {
"mod_frete": "9" # 9 = no shipping
},
"pag": {
"det_pag": [
{
"t_pag": "01", # Payment method (01=cash, 90=no payment)
"v_pag": "100.00"
}
]
}
Complete Example: Return Invoice
from abstra.connectors import run_connection_action
params = {
"id_lote": "1",
"ind_sinc": "1",
"versao": "4.00",
"nfe": [
{
"inf_nfe": {
"versao": "4.00",
"ide": {
"c_uf": "35",
"c_nf": "55794074",
"nat_op": "DEVOLUCAO",
"mod": "55",
"serie": "3",
"n_nf": "1001",
"dh_emi": "2026-03-26T10:50:22-03:00",
"tp_nf": "1",
"id_dest": "2",
"c_mun_fg": "3550308",
"tp_imp": "1",
"tp_emis": "1",
"tp_amb": "1",
"fin_nfe": "4",
"ind_final": "0",
"ind_pres": "2",
"proc_emi": "0",
"ver_proc": "1.0",
"n_fref": [
{
"ref_nfe": "35260312345678000199550010000010011123456789"
}
]
},
"emit": {
"cnpj": "12345678000199",
"x_nome": "COMPANY NAME LTDA",
"ender_emit": {
"x_lgr": "RUA EXEMPLO",
"nro": "1200",
"x_cpl": "SALA 1",
"x_bairro": "CENTRO",
"c_mun": "3550308",
"x_mun": "SAO PAULO",
"uf": "SP",
"cep": "01000000",
"c_pais": "1058",
"x_pais": "BRASIL"
},
"ie": "123456789012",
"crt": "3"
},
"dest": {
"cnpj": "98765432000188",
"x_nome": "SUPPLIER COMPANY LTDA",
"ender_dest": {
"x_lgr": "AV BRASIL",
"nro": "500",
"x_bairro": "INDUSTRIAL",
"c_mun": "4101507",
"x_mun": "ARAPONGAS",
"uf": "PR",
"cep": "86702001",
"c_pais": "1058",
"x_pais": "BRASIL"
},
"ind_ie_dest": "1",
"ie": "1234567890"
},
"det": [
{
"n_item": "1",
"prod": {
"c_prod": "PROD001",
"c_ean": "SEM GTIN",
"x_prod": "WOODEN CHAIR MODEL A",
"ncm": "94016100",
"cfop": "6202",
"u_com": "UN",
"q_com": "1.0000",
"v_un_com": "519.9200",
"v_prod": "519.92",
"c_ean_trib": "SEM GTIN",
"u_trib": "UN",
"q_trib": "1.0000",
"v_un_trib": "519.9200",
"ind_tot": "1"
},
"imposto": {
"icms": {
"icms00": {
"orig": "0",
"cst": "00",
"mod_bc": "3",
"v_bc": "519.92",
"p_icms": "12.0000",
"v_icms": "62.39"
}
},
"ipi": {
"c_enq": "999",
"ipint": {
"cst": "53"
}
},
"pis": {
"pis_outr": {
"cst": "99",
"v_bc": "519.92",
"p_pis": "0.00",
"v_pis": "0.00"
}
},
"cofins": {
"cofins_outr": {
"cst": "99",
"v_bc": "519.92",
"p_cofins": "0.00",
"v_cofins": "0.00"
}
}
},
"imposto_devol": {
"p_devol": "100.00",
"ipi": {
"v_ipi_devol": "16.90"
}
}
}
],
"total": {
"icms_tot": {
"v_bc": "519.92",
"v_icms": "62.39",
"v_icms_deson": "0.00",
"v_fcp": "0.00",
"v_bcst": "0.00",
"v_st": "0.00",
"v_fcpst": "0.00",
"v_fcpst_ret": "0.00",
"v_prod": "519.92",
"v_frete": "0.00",
"v_seg": "0.00",
"v_desc": "0.00",
"v_ii": "0.00",
"v_ipi": "0.00",
"v_ipi_devol": "16.90",
"v_pis": "0.00",
"v_cofins": "0.00",
"v_outro": "0.00",
"v_nf": "536.82"
}
},
"transp": {
"mod_frete": "9"
},
"pag": {
"det_pag": [
{
"t_pag": "90",
"v_pag": "0.00"
}
]
},
"inf_adic": {
"inf_cpl": "Return invoice for NF 1000 - Key: 35260312345678000199550010000010011123456789"
}
}
}
]
}
result = run_connection_action("nfe-sp", "nfe_autorizacao", params)