Pular para o conteúdo principal

Componente NFC-e - Linux 2.0

Lucas Santos
Atualizado
Bem-vindo à API spdNFCe!
Esta documentação contém todas as informações necessárias para integrar sua aplicação com a API de emissão de NFC-e. A API roda na porta 8082 por padrão.
Emissão completa de NFC-e
Assinatura digital automática
Geração de DANFCE (PDF)
Suporte multi-tenant
Conversão TX2/JSON/XML

Índice

Nota: Clique nos links abaixo para navegar diretamente para cada seção.

Como Executar (após baixar)

A API é distribuída como um pacote .zip autocontido para Linux — não requer instalação, apenas extrair e executar.

Pré-requisito: o Google Chrome precisa estar instalado na máquina que vai rodar a API. Ele é usado internamente (via chromedp) para gerar o PDF da DANFCE nos endpoints /printcupom e /processar-nfce. Sem o Chrome instalado, a API sobe normalmente, mas esses dois endpoints falham ao tentar gerar o PDF.

Instalando o Chrome

Atenção: no Ubuntu 22+ não use apt install chromium-browser — a versão via snap não funciona corretamente em ambientes como WSL2/headless. 
# Baixar e instalar o .deb oficial do Google Chrome
wget -q https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb
sudo apt-get install -f -y
rm google-chrome-stable_current_amd64.deb

# Verificar instalação
/opt/google/chrome/google-chrome --version

Se o Chrome estiver instalado em um caminho diferente do padrão (/opt/google/chrome/google-chrome), defina a variável de ambiente CHROME_BIN antes de executar a API: 

CHROME_BIN=/caminho/para/chrome ./spdNFCe-api -port 8082

Extraindo e executando

# 1. Extrair o pacote
unzip spdNFCe-api-linux-amd64-*.zip
cd linux-amd64

# 2. Dar permissão de execução
chmod +x spdNFCe-api

# 3. Executar (porta padrão: 8082)
./spdNFCe-api -port 8082
Quer usar outra porta? É só trocar o valor de -port — não precisa de nenhuma outra configuração: 
./spdNFCe-api -port 9000
Se a porta escolhida já estiver em uso, a API falha ao iniciar com um erro do tipo address already in use; nesse caso, escolha outra porta livre.

Confirmando que subiu

Em outro terminal (ou navegador), verifique o health check (troque 8082 pela porta escolhida, se for diferente):

curl -X GET http://localhost:8082/health
# Resposta esperada: {"status":"ok"}
Próximo passo: a API sobe sem nenhuma configuração carregada (usa config/config.example.json apenas como referência, ele não é lido automaticamente). Configure a empresa/ certificado antes de emitir NFC-e — veja Modos de Configuração logo abaixo.

Parâmetros de linha de comando

-port opcional
Porta HTTP (padrão: 8082). Exemplo: -port 9000
-config opcional
Caminho para um config.json a carregar automaticamente na inicialização (padrão: config/config.json, se existir)

Modos de Configuração

A API suporta 3 modos de configuração diferentes, permitindo flexibilidade desde uso single-tenant até multi-tenant completo:

1. Configuração em Memória (Single-Tenant)

Carregue a configuração uma vez e reutilize em todas as requisições: 

curl -X POST http://localhost:8082/setconfig \
  -H "Content-Type: application/json" \
  -d @config.json
Vantagens: Simplifica chamadas subsequentes, ideal para ambiente single-tenant, não precisa passar config em cada request.

2. Via Header "config" (Multi-Tenant Stateless)

Passe a configuração completa em JSON em cada requisição:

curl -X POST http://localhost:8082/consultar \
  -H "config: {\"NFE\":{\"Documento\":\"NFCE\",\"CNPJ\":\"12345678000190\",...}}" \
  -H "chave: 41230512345678000190650010000000011234567890"

Nota: o ... acima indica que o JSON foi truncado só para caber na linha. O objeto completo precisa de todos os campos obrigatórios (Ambiente, SenhaCertificado, Certificado em base64 etc.) — veja o exemplo completo em Certificado Flexível acima.

Vantagens: Totalmente stateless, suporta múltiplos CNPJs simultaneamente, ideal para SaaS multi-tenant.

3. Via Header "config-path" (Referência a Arquivo)

Referencie um arquivo de configuração no servidor:

curl -X POST http://localhost:8082/consultar \
  -H "config-path: /etc/nfce/empresa1.json" \
  -H "chave: 41230512345678000190650010000000011234567890"
Vantagens: Gerenciamento centralizado, separação de certificados, facilita rotação de credenciais.

Certificado Flexível

O certificado pode ser passado de 4 formas diferentes:

1. Inline no JSON (certificado em base64)

{
  "NFE": {
    "Documento": "NFCE",
    "CNPJ": "12345678000190",
    "UF": "PR",
    "Ambiente": "2",
    "SenhaCertificado": "senha123",
    "Certificado": "MIIJqQIBAzCCCWUGCSqGSIb3DQEHAaCCCVYEgglSMIIJTjCCBXEGCSq...",
    "TokenNFCe": "ABC123XYZ789",
    "IdTokenNFCe": "000001",
    "Versao": "4.00"
  }
}

2. Header separado com certificado em base64

# Config sem certificado + header certificado
curl -X POST http://localhost:8082/processar-nfce \
  -H "config: {\"NFE\":{\"Documento\":\"NFCE\",\"CNPJ\":\"12345678000190\",\"UF\":\"PR\",\"Ambiente\":\"2\",\"SenhaCertificado\":\"senha123\",\"TokenNFCe\":\"ABC123\",\"IdTokenNFCe\":\"000001\"}}" \
  -H "certificado: MIIJqQIBAzCCCWUGCSqGSIb3DQEHAaCCCVYEgglSMIIJTjCCBXEGCSq..." \
  --data-binary @nota.xml

3. Header separado com caminho do arquivo

# Config sem certificado + header com caminho
curl -X POST http://localhost:8082/processar-nfce \
  -H "config: {\"NFE\":{\"Documento\":\"NFCE\",\"CNPJ\":\"12345678000190\",\"UF\":\"PR\",\"Ambiente\":\"2\",\"SenhaCertificado\":\"senha123\",\"TokenNFCe\":\"ABC123\",\"IdTokenNFCe\":\"000001\"}}" \
  -H "certificado: /etc/certs/empresa1.pfx" \
  --data-binary @nota.xml

4. Usando config-path com certificado em arquivo separado

# Config em arquivo (sem certificado) + header certificado
curl -X POST http://localhost:8082/processar-nfce \
  -H "config-path: /etc/nfce/empresa1-config.json" \
  -H "certificado: /etc/nfce/empresa1-cert.pfx" \
  --data-binary @nota.xml
Exemplo de config.json sem certificado (para usar com header separado): 
{
  "NFE": {
    "Documento": "NFCE",
    "UF": "PR",
    "CNPJ": "12345678901234",
    "Versao": "4.00",
    "SenhaCertificado": "sua_senha_aqui",
    "Ambiente": "2",
    "Serie": "1",
    "QRcode": "3",
    "TokenNFCe": "seu_token_csc_aqui",
    "IdTokenNFCe": "000001",
    "DiretorioLog": "log12345678901234",
    "DiretorioImpressao": "danfce12345678901234",
    "DiretorioXmlDestinatario": "XmlDestinatario12345678901234",
    "DiretorioXmlContingencia": "Contingencia12345678901234"
  }
}
QRcode: use "3" por padrão. A maioria das SEFAZ (confirmado em testes reais na SEFAZ-PR homologação) já não aceita mais o QR Code versão "2" (baseado em hash do CSC/Token) e rejeita a NFC-e com cStat 462 - Codigo Identificador do CSC no QR-Code nao cadastrado na SEFAZ — mesmo com TokenNFCe/ IdTokenNFCe corretos. A versão "3" do QR Code não depende de CSC (usa apenas chave|3|tpAmb na URL) e é o formato atual esperado pela maioria dos estados. Só use "2" se seu estado exigir explicitamente o formato antigo.

Endpoints de Gerenciamento de Configuração

Além dos 3 modos acima, a API expõe endpoints dedicados para consultar e persistir a configuração em memória/disco:

POST/setconfig

Cria/atualiza a configuração completa da API: persiste em config/config.json e atualiza a configuração em memória imediatamente (modo 1 — single-tenant, ver acima).

Body (JSON)

NFE.Documento obrigatório
"NFCE" ou "NFE"
NFE.CNPJ obrigatório
CNPJ do emitente
NFE.UF obrigatório
UF do emitente (ex: "PR")
NFE.Ambiente obrigatório
"1" (Produção) ou "2" (Homologação)
NFE.SenhaCertificado obrigatório
Senha do certificado
NFE.Certificado obrigatório
Certificado em base64, OU caminho de arquivo .pfx (é resolvido e convertido automaticamente)
NFE.Serie / TokenNFCe / IdTokenNFCe / QRcode opcional
Necessários para emissão real. Lembrar: QRcode: "3" é o formato atual (ver aviso acima)
NFE.DiretorioLog / DiretorioImpressao / DiretorioXmlDestinatario / DiretorioXmlContingencia / DiretorioLicense opcional
Se omitidos, a API cria pastas padrão automaticamente

Exemplo

curl -X POST http://localhost:8082/setconfig \
  -H "Content-Type: application/json" \
  -d @config.json

Responses

200 OK "Configuração criada com sucesso!"
400 Bad Request Campo obrigatório ausente na seção NFE

↑ Voltar ao índice de endpoints

GET/getconfig

Retorna a configuração atualmente persistida em config/config.json.

Exemplo

curl -X GET http://localhost:8082/getconfig

↑ Voltar ao índice de endpoints

POST/loadconfig

Carrega a configuração a partir de um config.json já existente no servidor, combinando com um certificado enviado como arquivo via multipart/form-data.

Body (multipart/form-data)

path opcional
Caminho do config.json (padrão: config/config.json)
senha obrigatório
Senha do certificado
certificado obrigatório
Arquivo .pfx enviado como form file

Exemplo

curl -X POST http://localhost:8082/loadconfig \
  -F "path=config/config.json" \
  -F "senha=senha123" \
  -F "certificado=@certificado.pfx"

↑ Voltar ao índice de endpoints

POST/loadconfigjson

Carrega a configuração a partir do conteúdo de um JSON (com certificado embutido em base64), enviado no corpo do campo arquivo.

Atenção: o campo arquivo espera o conteúdo JSON em si, não um caminho de arquivo. Use --data-urlencode "arquivo@caminho.json" (o curl lê o arquivo e envia o conteúdo) — passar apenas o caminho como texto (-F "arquivo=config/empresa1.json") falha silenciosamente e carrega uma configuração vazia.

Body (form-data)

arquivo obrigatório
Conteúdo completo do JSON de configuração (não o caminho)

Exemplo

curl -X POST http://localhost:8082/loadconfigjson \
  --data-urlencode "arquivo@config/empresa1.json"

↑ Voltar ao índice de endpoints

Geração de DANFCE (Cupom Fiscal)

POST/printcupom

Gera PDF do cupom fiscal (DANFCE) a partir de TX2, JSON ou XML.

Headers

config opcional
Configuração JSON completa
config-path opcional
Caminho para config.json
certificado opcional
Certificado em base64 ou caminho
formato opcional
TX2, JSON ou XML (auto-detectado se não informado)
paperWidth opcional
80mm (padrão) ou 58mm

Body

Conteúdo TX2, JSON ou XML da NFC-e

Exemplo

curl -X POST http://localhost:8082/printcupom \
  -H "Content-Type: text/xml" \
  --data-binary @nota.xml \
  --output cupom.pdf

Responses

200 OK PDF gerado (application/pdf)
400 Bad Request Erro na entrada
500 Error Erro ao gerar PDF

↑ Voltar ao índice de endpoints

Endpoints legados (uso interno): POST /print e POST /pdf são versões antigas de geração de DANFCE (single-tenant, sem suporte aos headers config/config-path). Prefira sempre /printcupom para novas integrações. POST /fluxonfce é um endpoint de teste/carga e não deve ser usado em produção.

Conversão de Formatos

POST/convtx2

Converte arquivo TX2 para XML de NFC-e.

Headers

saida opcional
Tipo de saída (padrão: XML)

Body

Conteúdo TX2 completo

Exemplo

curl -X POST http://localhost:8082/convtx2 \
  -H "Content-Type: text/plain" \
  --data-binary @nota.tx2

↑ Voltar ao índice de endpoints

POST/jsontoxml

Converte JSON de NFC-e para XML.

Body

Conteúdo JSON completo

Exemplo

curl -X POST http://localhost:8082/jsontoxml \
  -H "Content-Type: application/json" \
  --data-binary @nota.json

↑ Voltar ao índice de endpoints

Operações NFC-e

POST/assinar

Assina digitalmente uma NFC-e (aceita TX2, JSON ou XML) e retorna apenas o XML assinado, sem enviar para a SEFAZ.

Headers

config / config-path opcional
Configuração da empresa (ou usa a configuração em memória)
certificado opcional
Certificado em base64 ou caminho (se não incluído na config)

Body

Conteúdo XML, JSON ou TX2 da NFC-e

Exemplo

curl -X POST http://localhost:8082/assinar \
  -H "Content-Type: text/xml" \
  --data-binary @nota.xml

↑ Voltar ao índice de endpoints

POST/enviar

Assina (se necessário) e envia a NFC-e para a SEFAZ, retornando o XML do destinatário (nfeProc com protocolo). Diferente de /processar-nfce, não gera PDF nem o salva em disco.

Headers

config / config-path opcional
Configuração da empresa (ou usa a configuração em memória)
certificado opcional
Certificado em base64 ou caminho (se não incluído na config)

Body

Conteúdo XML, JSON ou TX2 da NFC-e (assinado ou não)

Exemplo

curl -X POST http://localhost:8082/enviar \
  -H "Content-Type: text/xml" \
  --data-binary @nota.xml

Responses

200 OK XML do destinatário (nfeProc)
400 Bad Request Erro ou rejeição SEFAZ

↑ Voltar ao índice de endpoints

POST/consultar

Consulta a situação de uma NFC-e na SEFAZ.

Headers

chave obrigatório
Chave de acesso da NFC-e (44 dígitos)

Exemplo

curl -X POST http://localhost:8082/consultar \
  -H "chave: 41230512345678000190650010000000011234567890"

↑ Voltar ao índice de endpoints

POST/status

Verifica o status do serviço da SEFAZ.

Exemplo

curl -X POST http://localhost:8082/status

↑ Voltar ao índice de endpoints

POST/processar-nfce

Endpoint Principal - Processa NFC-e completa: assina + envia + gera PDF.

Comportamento Importante:
• cStat 100/150: PDF retornado + XML destinatário salvo em XmlDestinatario/{CNPJ}/{chave}-nfce.xml
• cStat != 100/150: Apenas logs salvos em log{CNPJ}, PDF e XML NÃO são gerados

Body

Conteúdo da NFC-e (XML, JSON ou TX2)

Exemplo

curl -X POST http://localhost:8082/processar-nfce \
  -H "Content-Type: text/xml" \
  --data-binary @nota.xml \
  --output danfce.pdf

Responses

200 OK PDF da DANFCE (se autorizada)
400 Bad Request Erro ou rejeição SEFAZ

↑ Voltar ao índice de endpoints

POST/cancelar

Cancela uma NFC-e autorizada.

Headers

chave obrigatório
Chave de acesso (44 dígitos)
protocolo obrigatório
Protocolo de autorização
justificativa obrigatório
Justificativa (mínimo 15 caracteres)
dataHoraEvento opcional
Data/hora do evento (padrão: atual)
sequenciaEvento opcional
Sequência do evento (padrão: 1)
fusoHorario opcional
Fuso horário (padrão: -03:00)

Exemplo

curl -X POST http://localhost:8082/cancelar \
  -H "chave: 41230512345678000190650010000000011234567890" \
  -H "protocolo: 141230000000123" \
  -H "justificativa: Cancelamento por erro de digitacao"

↑ Voltar ao índice de endpoints

POST/inutilizar

Inutiliza uma faixa de numeração de NFC-e.

Headers

ano obrigatório
Ano da inutilização (ex: 25)
serie obrigatório
Série da NFC-e
nIni obrigatório
Número inicial da faixa
nFin obrigatório
Número final da faixa
justificativa obrigatório
Justificativa (mínimo 15 caracteres)

Exemplo

curl -X POST http://localhost:8082/inutilizar \
  -H "ano: 25" \
  -H "serie: 1" \
  -H "nIni: 100" \
  -H "nFin: 105" \
  -H "justificativa: Numeracao pulada por erro de sistema"

↑ Voltar ao índice de endpoints

Endpoints Extras

GET/health

Health check simples, útil para load balancers e orquestradores (Docker/Kubernetes). Não depende de configuração.

Exemplo

curl -X GET http://localhost:8082/health

Responses

200 OK {"status":"ok"}

↑ Voltar ao índice de endpoints

POST/escpos

Converte o XML de uma NFC-e diretamente para o formato binário ESC/POS, para impressão direta em impressoras térmicas compatíveis (sem passar por PDF).

Formato esperado: o Body deve ser o XML completo no formato nfeProc (com as tags <NFe> e <protNFe>), ou seja, a mesma saída de /processar-nfce ou /gerarxmldestinatario. O XML "cru" retornado por /convtx2 ou /jsontoxml (apenas <infNFe>, sem o envelope nfeProc) causa erro 500 em vez de uma mensagem de validação.

Body

Conteúdo XML completo (nfeProc) da NFC-e

Exemplo

curl -X POST http://localhost:8082/escpos \
  -H "Content-Type: text/xml" \
  --data-binary @nota.xml \
  --output cupom.escpos

↑ Voltar ao índice de endpoints

POST/gerarxmldestinatario

Gera e retorna o XML destinatário completo (nfeProc com protocolo).

Headers

chave obrigatório
Chave de acesso (44 dígitos)

Exemplo

curl -X POST http://localhost:8082/gerarxmldestinatario \
  -H "chave: 41230512345678000190650010000000011234567890"

↑ Voltar ao índice de endpoints

GET/pdf/{chave}

Recupera o PDF da DANFCE previamente salvo.

Parâmetros

chave path
Chave de acesso (44 dígitos)
cnpj query
CNPJ da empresa (14 dígitos)

Exemplos

# Com CNPJ
curl -X GET "http://localhost:8082/pdf/41230512345678000190650010000000011234567890?cnpj=12345678000190" \
  --output cupom.pdf

# Usando config em memória
curl -X GET "http://localhost:8082/pdf/41230512345678000190650010000000011234567890" \
  --output cupom.pdf

Responses

200 OK PDF da DANFCE
404 Not Found PDF não encontrado

↑ Voltar ao índice de endpoints

GET/xml-destinatario/{chave}

Recupera o XML destinatário previamente salvo.

Parâmetros

chave path
Chave de acesso (44 dígitos)
cnpj query
CNPJ da empresa (14 dígitos)

Exemplo

curl -X GET "http://localhost:8082/xml-destinatario/41230512345678000190650010000000011234567890?cnpj=12345678000190"

Responses

200 OK XML destinatário
404 Not Found XML não encontrado

↑ Voltar ao índice de endpoints

Exemplos de Uso

Fluxo Completo: Emitir NFC-e
# 1. Carregar configuração (uma vez)
curl -X POST http://localhost:8082/setconfig \
  -H "Content-Type: application/json" \
  -d @config.json

# 2. Verificar status da SEFAZ
curl -X POST http://localhost:8082/status

# 3. Processar NFC-e completa (assinar + enviar + PDF)
curl -X POST http://localhost:8082/processar-nfce \
  -H "Content-Type: text/xml" \
  --data-binary @nota.xml \
  --output danfce.pdf

# 4. Recuperar PDF posteriormente
curl -X GET "http://localhost:8082/pdf/41230512345678000190650010000000011234567890" \
  --output cupom.pdf

# 5. Recuperar XML destinatário
curl -X GET "http://localhost:8082/xml-destinatario/41230512345678000190650010000000011234567890" \
  --output nota-dest.xml
Multi-Tenant: Processar para 2 CNPJs diferentes com certificado separado 
# Empresa 1 (certificado em arquivo separado)
curl -X POST http://localhost:8082/processar-nfce \
  -H "config-path: /etc/nfce/empresa1.json" \
  -H "certificado: /etc/nfce/certs/empresa1.pfx" \
  --data-binary @nota-empresa1.xml \
  --output empresa1-cupom.pdf

# Empresa 2 (certificado em base64 no header)
curl -X POST http://localhost:8082/processar-nfce \
  -H "config-path: /etc/nfce/empresa2.json" \
  -H "certificado: $(base64 -w0 /etc/nfce/certs/empresa2.pfx)" \
  --data-binary @nota-empresa2.xml \
  --output empresa2-cupom.pdf
Conversão TX2 - XML - PDF
# 1. Converter TX2 para XML
curl -X POST http://localhost:8082/convtx2 \
  --data-binary @nota.tx2 \
  --output nota.xml

# 2. Gerar PDF do cupom
curl -X POST http://localhost:8082/printcupom \
  -H "paperWidth: 80mm" \
  --data-binary @nota.xml \
  --output cupom.pdf

Exemplos de Formatos

Exemplo TX2 Completo

FORMATO=tx2
NUMLOTE=1
INCLUIR
Id_A03=0
versao_A02=4.00
verProc_B27=spdNFCe v1.0
cNF_B03=22
natOp_B04=VENDA
mod_B06=65
serie_B07=1
nNF_B08=12
cUF_B02=41
dhEmi_B09=
tpNF_B11=1
idDest_B11a=1
cMunFG_B12=4115200
tpImp_B21=5
tpEmis_B22=1
cDV_B23=3
tpAmb_B24=2
finNFe_B25=1
indFinal_B25a=1
indPres_B25b=1
indintermed_b25c=0
procEmi_B26=0
CNPJ_C02=12345678000190
xNome_C03=EMPRESA TESTE LTDA
xFant_C04=EMPRESA TESTE
xLgr_C06=RUA TESTE
nro_C07=123
xBairro_C09=CENTRO
cMun_C10=4115200
xMun_C11=Maringa
UF_C12=PR
CEP_C13=87000000
cPais_C14=1058
xPais_C15=BRASIL
fone_C16=4430001234
IE_C17=1234567890
CPF_E03=12345678901
indIEDest_E16a=9
xNome_E04=CONSUMIDOR FINAL
CRT_C21=1

INCLUIRITEM
nItem_H02=1
cEAN_I03=SEM GTIN
cProd_I02=001
xProd_I04=PRODUTO TESTE
NCM_I05=22089000
CFOP_I08=5102
uCom_I09=UN
qCom_I10=1.0000
vUnCom_I10a=10.00
vProd_I11=10.00
cEANTrib_I12=SEM GTIN
uTrib_I13=UN
qTrib_I14=1.0000
vUnTrib_I14a=10.00
indTot_I17b=1
orig_N11=0
CSOSN_N12a=102
vTotTrib_M02=1.50
SALVARITEM

INCLUIRITEM
nItem_H02=2
cEAN_I03=SEM GTIN
cProd_I02=002
xProd_I04=PRODUTO TESTE 2
NCM_I05=22089000
CFOP_I08=5102
uCom_I09=UN
qCom_I10=2.0000
vUnCom_I10a=15.00
vProd_I11=30.00
cEANTrib_I12=SEM GTIN
uTrib_I13=UN
qTrib_I14=2.0000
vUnTrib_I14a=15.00
indTot_I17b=1
orig_N11=0
CSOSN_N12a=102
vTotTrib_M02=3.00
SALVARITEM

vBC_W03=0.00
vICMS_W04=0.00
vICMSDeson_W04a=0.00
vFCPUFDest_W04c=0.00
vICMSUFDest_W04e=0.00
vICMSUFRemet_W04g=0.00
vFCP_W04h=0.00
vBCST_W05=0.00
vST_W06=0.00
vFCPST_W06a=0.00
vFCPSTRet_W06b=0.00
vProd_W07=40.00
vFrete_W08=0.00
vSeg_W09=0.00
vDesc_W10=0.00
vII_W11=0.00
vIPI_W12=0.00
vIPIDevol_W12a=0.00
vPIS_W13=0.00
vCOFINS_W14=0.00
vOutro_W15=0.00
vNF_W16=40.00
modFrete_X02=9
vTotTrib_W16a=4.50

INCLUIRPARTE=YA
tPag_YA02=01
vPag_YA03=40.00
SALVARPARTE=YA

infCpl_Z03=Nota Fiscal de exemplo - Ambiente de homologacao
SALVAR

Exemplo JSON Completo

{
  "NFe": {
    "infNFe": {
      "versao": "4.00",
      "ide": {
        "cUF": "41",
        "cNF": "00000022",
        "natOp": "VENDA",
        "mod": "65",
        "serie": "1",
        "nNF": "12",
        "dhEmi": "2025-01-15T10:30:00-03:00",
        "tpNF": "1",
        "idDest": "1",
        "cMunFG": "4115200",
        "tpImp": "5",
        "tpEmis": "1",
        "cDV": "3",
        "tpAmb": "2",
        "finNFe": "1",
        "indFinal": "1",
        "indPres": "1",
        "indIntermed": "0",
        "procEmi": "0",
        "verProc": "spdNFCe v1.0"
      },
      "emit": {
        "CNPJ": "12345678000190",
        "xNome": "EMPRESA TESTE LTDA",
        "xFant": "EMPRESA TESTE",
        "enderEmit": {
          "xLgr": "RUA TESTE",
          "nro": "123",
          "xBairro": "CENTRO",
          "cMun": "4115200",
          "xMun": "Maringa",
          "UF": "PR",
          "CEP": "87000000",
          "cPais": "1058",
          "xPais": "BRASIL",
          "fone": "4430001234"
        },
        "IE": "1234567890",
        "CRT": "1"
      },
      "dest": {
        "CPF": "12345678901",
        "xNome": "CONSUMIDOR FINAL",
        "indIEDest": "9"
      },
      "det": [
        {
          "nItem": "1",
          "prod": {
            "cProd": "001",
            "cEAN": "SEM GTIN",
            "xProd": "PRODUTO TESTE",
            "NCM": "22089000",
            "CFOP": "5102",
            "uCom": "UN",
            "qCom": "1.0000",
            "vUnCom": "10.00",
            "vProd": "10.00",
            "cEANTrib": "SEM GTIN",
            "uTrib": "UN",
            "qTrib": "1.0000",
            "vUnTrib": "10.00",
            "indTot": "1"
          },
          "imposto": {
            "vTotTrib": "1.50",
            "ICMS": {
              "ICMSSN102": {
                "orig": "0",
                "CSOSN": "102"
              }
            }
          }
        },
        {
          "nItem": "2",
          "prod": {
            "cProd": "002",
            "cEAN": "SEM GTIN",
            "xProd": "PRODUTO TESTE 2",
            "NCM": "22089000",
            "CFOP": "5102",
            "uCom": "UN",
            "qCom": "2.0000",
            "vUnCom": "15.00",
            "vProd": "30.00",
            "cEANTrib": "SEM GTIN",
            "uTrib": "UN",
            "qTrib": "2.0000",
            "vUnTrib": "15.00",
            "indTot": "1"
          },
          "imposto": {
            "vTotTrib": "3.00",
            "ICMS": {
              "ICMSSN102": {
                "orig": "0",
                "CSOSN": "102"
              }
            }
          }
        }
      ],
      "total": {
        "ICMSTot": {
          "vBC": "0.00",
          "vICMS": "0.00",
          "vICMSDeson": "0.00",
          "vFCPUFDest": "0.00",
          "vICMSUFDest": "0.00",
          "vICMSUFRemet": "0.00",
          "vFCP": "0.00",
          "vBCST": "0.00",
          "vST": "0.00",
          "vFCPST": "0.00",
          "vFCPSTRet": "0.00",
          "vProd": "40.00",
          "vFrete": "0.00",
          "vSeg": "0.00",
          "vDesc": "0.00",
          "vII": "0.00",
          "vIPI": "0.00",
          "vIPIDevol": "0.00",
          "vPIS": "0.00",
          "vCOFINS": "0.00",
          "vOutro": "0.00",
          "vNF": "40.00",
          "vTotTrib": "4.50"
        }
      },
      "transp": {
        "modFrete": "9"
      },
      "pag": {
        "detPag": [
          {
            "tPag": "01",
            "vPag": "40.00"
          }
        ]
      },
      "infAdic": {
        "infCpl": "Nota Fiscal de exemplo - Ambiente de homologacao"
      }
    }
  }
}

Códigos de Status SEFAZ

Códigos de Sucesso

cStat Descrição
100 Autorizado o uso da NF-e
135 Evento registrado e vinculado à NF-e
150 Autorizado o uso da NF-e fora de prazo
204 Duplicidade de NF-e (já autorizada)

Códigos de Erro Comuns

cStat Descrição Solução
213 CNPJ do emitente inválido Verificar CNPJ no config
215 Falha no Schema XML Validar estrutura do XML
218 CNPJ do certificado diverge do emitente Certificado não pertence ao CNPJ
225 Falha na assinatura digital Verificar certificado e senha
301 Uso denegado - irregularidade fiscal Contatar SEFAZ
462 Codigo Identificador do CSC no QR-Code nao cadastrado na SEFAZ Usar QRcode: "3" na config (não depende de CSC)
501 NFC-e autorizada há mais de 30 minutos (ao tentar cancelar) Cancelamento só é aceito dentro da janela de tempo da SEFAZ
539 Prazo de cancelamento excedido NFC-e não pode mais ser cancelada

Status do Serviço

cStat Descrição
107 Serviço em Operação
108 Serviço Paralisado Momentaneamente
109 Serviço Paralisado Sem Previsão

Solução de Problemas

Erro: "Certificado não configurado"
Causa: Certificado não foi carregado.

Solução:
curl -X POST http://localhost:8082/setconfig -d @config.json
ou
curl -H "certificado: $(base64 -w0 certificado.pfx)" ...
ou
curl -H "certificado: /etc/certs/empresa.pfx" ...
Erro: "Falha na assinatura digital (cStat 225)"
Causa: Certificado inválido, expirado ou senha incorreta.

Solução:
• Verificar validade do certificado (.pfx)
• Confirmar senha do certificado
• Testar com: openssl pkcs12 -info -in certificado.pfx
Erro: "CNPJ do certificado diverge do emitente (cStat 218)"
Causa: O CNPJ no XML não corresponde ao CNPJ do certificado.

Solução:
• Verificar campo CNPJ no config.json
• Garantir que o certificado .pfx pertence à empresa emitente
Erro: "Codigo Identificador do CSC no QR-Code nao cadastrado na SEFAZ (cStat 462)"
Causa: A configuração está usando QRcode: "2" (formato antigo, baseado em hash de CSC/Token). Muitas SEFAZ (confirmado na SEFAZ-PR) não aceitam mais esse formato, e retornam cStat 462 mesmo com TokenNFCe/IdTokenNFCe corretos e cadastrados.

Solução:
• Trocar para "QRcode": "3" no config.json (formato atual, não depende de CSC)
• Reenviar a NFC-e (não precisa reconfigurar TokenNFCe/IdTokenNFCe, eles simplesmente não são usados no QR Code v3)
Erro: "tls: failed to find any PEM data in certificate input"
Causa: Mensagem genérica que aparecia quando o certificado não tinha a cadeia de CA/intermediários embutida (comum em exportações de PFX que trazem só o certificado + chave privada). Já corrigido — a cadeia de CA agora é opcional.

Solução: Se o erro persistir, confirme que está usando uma versão atualizada da API (pós-correção do parsing de PFX sem cadeia de CA).
Erro: "NFC-e autorizada ha mais de 30 minutos" ao cancelar (cStat 501)
Causa: A SEFAZ só permite cancelamento de NFC-e dentro de uma janela de tempo após a autorização (tipicamente 30 minutos, pode variar por UF).

Solução: Não há como cancelar após esse prazo — é necessário emitir uma NFC-e de ajuste/estorno conforme a legislação do estado.
Erro: "Serviço Paralisado (cStat 108/109)"
Causa: SEFAZ está em manutenção.

Solução:
• Aguardar retorno do serviço
• Consultar status: POST /status
• Notas salvas automaticamente em contingência
PDF não gerado após processar-nfce
Causa: NFC-e rejeitada pela SEFAZ (cStat != 100/150).

Solução:
• Verificar logs em log{CNPJ}/{chave}-ret.log
• Corrigir erro reportado pela SEFAZ
• PDF só é gerado quando cStat = 100 ou 150
QR Code não aparece no PDF
Causa: TokenNFCe ou IdTokenNFCe não configurados.

Solução: Adicionar no config.json:
{"NFE": {"TokenNFCe": "ABC123", "IdTokenNFCe": "000001"}}

Segurança

Boas Práticas de Segurança:
Nunca versione certificados (adicione *.pfx ao .gitignore)
Use HTTPS em produção (configure proxy reverso nginx/Apache)
Rotacione certificados (expiram em 1 ano)
Proteja senhas (use variáveis de ambiente)
Valide CNPJ antes de processar requisições
Prefira passar certificado via header separado em vez de inline no JSON

Recursos Adicionais

Manual SEFAZ

spdNFCe API - Desenvolvido pela Tecnospeed

Copyright © 2025-2026 - Todos os direitos reservados

Artigos relacionados

Comentários

0 comentário

Por favor, entre para comentar.