POST
/v1/emitir
Emite uma NFC-e a partir do JSON da venda e transmite à SEFAZ em tempo real. Aceita idempotência via identificador_venda e cai em contingência offline sozinha se a SEFAZ estiver fora do ar.
Campos, JSON completo e respostas
Corpo da requisição
| Campo | Obrigatório | Descrição |
|---|---|---|
serie | Opcional | Número da série de NFC-e. Sem ele, usa a série marcada como padrão da empresa. |
identificador_venda | Opcional | Referência livre da venda no sistema chamador (cabe um UUID). Reenviar o mesmo valor devolve a nota já emitida, sem duplicar. |
consumidor.cnpj_cpf | Opcional | CPF ou CNPJ do consumidor. Dígito verificador validado se enviado. |
consumidor.nome | Opcional | Nome do consumidor identificado. |
natureza_operacao | Opcional | Default "VENDA". |
troco | Opcional | Default 0. Vira Pag.vTroco quando o pagamento em dinheiro supera o total. |
itens[] | Obrigatório | Ao menos um item — ver tabela de campos do item abaixo. |
totais.valor_total / valor_desconto | Obrigatório | Totais da nota. |
pagamentos[] | Obrigatório | Ao menos um pagamento — ver tabela de formas de pagamento abaixo. |
Campos por item (itens[])
| Campo | Obrigatório | Descrição |
|---|---|---|
quantidade | Obrigatório | Sem default. |
cfop | Obrigatório | 4 dígitos (NFC-e é sempre saída/venda). |
unidade | Obrigatório | Sem default. |
ncm | Obrigatório | Exatamente 8 dígitos. |
valor_desconto | Opcional | Default 0. |
origem_mercadoria | Opcional | Default "0" (nacional). Tabela B do CST. |
cst_csosn | Obrigatório | Campo único de código tributário do ICMS — a API decide CSOSN ou CST a partir do regime (CRT) da empresa. |
aliquota_icms | Opcional | Default 0. Só tem efeito fora do Simples Nacional. |
cst_pis / cst_cofins | Obrigatório | Ex.: "49". |
aliquota_pis / aliquota_cofins | Opcional | Default 0. |
cst_ibscbs | Obrigatório | CST da Reforma Tributária (IBS/CBS). |
cclasstrib | Obrigatório | Código de Classificação Tributária da Reforma — sem default. |
aliquota_ibs_uf / aliquota_ibs_mun / aliquota_cbs | Opcional | Default 0 cada. |
cest | Opcional | 7 dígitos se preenchido. "0" e vazio contam como não informado. |
combustivel | Opcional | Objeto — ativa o regime de ICMS monofásico (CST 61). Ver tabela dedicada abaixo. |
Objeto combustivel (posto / revenda de GLP)
| Campo | Obrigatório | Descrição |
|---|---|---|
codigo_anp | Obrigatório | Código do produto na tabela ANP (ex. 210203001 = GLP). |
descricao_anp | Obrigatório | Descrição do produto conforme ANP. |
uf_consumo | Opcional | Default = UF da empresa. |
quantidade_tributavel | Obrigatório | Na unidade da ANP (kg para GLP, litro para líquidos). |
aliquota_ad_rem | Obrigatório | Valor fixo em R$ por unidade — "ad rem", não percentual. |
percentual_glp | Obrigatório se GLP | % de GLP na mistura, sem default — revenda de botijão puro manda 100 explicitamente. |
percentual_gn_nacional / percentual_gn_importado | Opcional | Default 0 — mistura GLGN. |
valor_partida | Opcional | Default 0 — rateio de preço da mistura. |
Requisição completa — biscoito (Simples Nacional) + GLP monofásico
POST /v1/emitirX-Emitente / X-Api-Key obrigatórios
{
"serie": 2,
"identificador_venda": "a1b2c3d4-5e6f-47a8-9b21-venda-pdv-0042",
"consumidor": { "cnpj_cpf": "12345678909", "nome": "Cliente Teste" },
"natureza_operacao": "VENDA",
"troco": 0,
"itens": [
{
"produto_id": "SKU-0031",
"descricao": "Biscoito Recheado 130g",
"ncm": "19053100",
"cfop": "5102",
"unidade": "UN",
"quantidade": 3,
"valor_unitario": 4.5,
"valor_total": 13.5,
"valor_desconto": 0,
"origem_mercadoria": "0",
"cst_csosn": "102",
"aliquota_icms": 0,
"cst_pis": "49",
"aliquota_pis": 0,
"cst_cofins": "49",
"aliquota_cofins": 0,
"cst_ibscbs": "000",
"cclasstrib": "000001",
"aliquota_ibs_uf": 0,
"aliquota_ibs_mun": 0,
"aliquota_cbs": 0,
"cest": "1706300"
},
{
"produto_id": "SKU-GLP-13",
"descricao": "GLP 13kg (Botijão)",
"ncm": "27111910",
"cfop": "5405",
"unidade": "KG",
"quantidade": 1,
"valor_unitario": 120.0,
"valor_total": 120.0,
"valor_desconto": 0,
"origem_mercadoria": "0",
"cst_csosn": "61",
"cst_pis": "49",
"aliquota_pis": 0,
"cst_cofins": "49",
"aliquota_cofins": 0,
"cst_ibscbs": "000",
"cclasstrib": "000001",
"aliquota_ibs_uf": 0,
"aliquota_ibs_mun": 0,
"aliquota_cbs": 0,
"combustivel": {
"codigo_anp": 210203001,
"descricao_anp": "GLP",
"uf_consumo": "PB",
"quantidade_tributavel": 13,
"aliquota_ad_rem": 143.66,
"percentual_glp": 100,
"percentual_gn_nacional": 0,
"percentual_gn_importado": 0,
"valor_partida": 0
}
}
],
"totais": { "valor_total": 133.5, "valor_desconto": 0 },
"pagamentos": [
{
"forma": "01",
"valor": 133.5,
"descricao": "",
"cnpj_credenciadora": "",
"bandeira": "",
"tipo_integracao": "2",
"autorizacao": ""
}
]
}Formas de pagamento (pagamentos[].forma)
Código SEFAZ direto (NT 2020.006 / Anexo I, Grupo YA) — sem tradução interna. "03"/"04"/"17" (crédito, débito, PIX dinâmico) exigem cnpj_credenciadora e bandeira; "99" exige descricao.
| Código | Descrição | Código | Descrição |
|---|---|---|---|
01 | Dinheiro | 16 | Depósito Bancário |
02 | Cheque | 17 | PIX Dinâmico |
03 | Cartão de Crédito | 18 | Transferência / Carteira Digital |
04 | Cartão de Débito | 19 | Fidelidade / Cashback |
05 | Crédito Loja | 20 | PIX Estático |
10 | Vale Alimentação | 90 | Sem Pagamento |
11 | Vale Refeição | 91 | Pagamento Posterior |
12 | Vale Presente | 99 | Outros (exige descricao) |
13 | Vale Combustível | ||
15 | Boleto Bancário |
Respostas
Autorizada201
{
"sucesso": true,
"contingencia": false,
"status": 100,
"motivo": "Autorizado o uso da NF-e",
"chave": "25082055254933...",
"protocolo": "135260000123456",
"numero": 55,
"serie": 2,
"data_autorizacao": "2026-08-11T14:32:07",
"qrcode": "https://sefaz.../nfcehom?p=...",
"xml_url": "/v1/nfce/.../xml",
"danfe_url": "/v1/nfce/.../danfe",
"documento_id": 512
}Rejeitada pela SEFAZ422
{
"sucesso": false,
"contingencia": false,
"status": 539,
"motivo": "Rejeicao: Duplicidade de NF-e",
"chave": "25082055254933...",
"protocolo": ""
}
// numero NAO avanca numa rejeicao real —
// reenviar o mesmo payload corrigido reusa o numeroContingência (SEFAZ fora do ar)201
{
"sucesso": true,
"contingencia": true,
"status": 0,
"chave": "25082055254933...",
"aviso": "Emitida em contingencia offline -- SEFAZ inacessivel. Pendente de transmissao (POST /nfce/{chave}/transmitir-contingencia) dentro de 24 horas."
}Replay de venda duplicada201
{
"sucesso": true,
"duplicado": true,
"chave": "25082055254933...",
"aviso": "Requisicao identica ja processada anteriormente (mesmo identificador_venda) — retornando o resultado da emissao original, nenhuma nota nova foi criada."
}