Skip to Content
GuiasNFC-e (modelo 65)

NFC-e — modelo 65

A NFC-e (Nota Fiscal de Consumidor eletrônica) é o cupom fiscal eletrônico usado em vendas ao consumidor final (varejo, restaurante, delivery). É síncrona (autoriza na hora) e gera QR-code obrigatório pra leitura do consumidor.

O que você precisa antes de emitir

1. Issuer cadastrado

Um Issuer é o CNPJ emissor. Pelo dashboard ou via API:

curl -X POST https://api.zfiscoo.zek.app.br/v1/issuers \
  -H "Authorization: Bearer fk_live_..." \
  -d '{
    "cnpj": "11222333000181",
    "razao_social": "X Burger Comércio LTDA",
    "ie": "111222333444",
    "uf": "SP",
    "ambiente": "homologacao",
    "regime_tributario": "simples"
  }'

2. Certificado A1 (.pfx)

Upload do .pfx + senha. Guardado cifrado AES-256-GCM (envelope) no servidor.

curl -X POST https://api.zfiscoo.zek.app.br/v1/issuers/iss_.../certificate \
  -H "Authorization: Bearer fk_live_..." \
  -F "pfx=@cert.pfx" \
  -F "password=senha-do-cert"

3. CSC (Código de Segurança do Contribuinte)

Cada UF gera o CSC dela no portal SEFAZ. Necessário pro QR-code:

curl -X POST https://api.zfiscoo.zek.app.br/v1/issuers/iss_.../csc \
  -H "Authorization: Bearer fk_live_..." \
  -d '{ "id_csc": "000001", "csc": "ABCDEF1234567890..." }'

Emitindo

curl -X POST https://api.zfiscoo.zek.app.br/v1/nfce \
  -H "Authorization: Bearer fk_live_..." \
  -H "Idempotency-Key: pedido-2026-001" \
  -d '{
    "issuer_id": "iss_xburger_sp",
    "external_ref": "pedido-001",
    "items": [
      {
        "description": "X-Burger Combo",
        "quantity": 1,
        "unit_price": 32.90,
        "ncm": "21069090",
        "cfop": "5102",
        "unit": "UN",
        "cst_icms": "00",
        "vBC": 32.90,
        "pICMS": 7.0
      }
    ],
    "payment": {
      "method": "credito",
      "amount": 32.90,
      "card_brand": "visa"
    },
    "consumer": {
      "cpf": "12345678909"
    }
  }'

Resposta:

{
  "id": "nfce_01HXYZ...",
  "status": "processing"
}

Em ~1-3s (síncrona com SEFAZ-SP), webhook ou polling devolve:

{
  "id": "nfce_01HXYZ...",
  "status": "authorized",
  "access_key": "35260111222333000181650010000000011000000017",
  "protocolo": "135260000000001",
  "danfe_url": "https://api.zfiscoo.zek.app.br/v1/nfce/nfce_.../danfe.pdf",
  "xml_url": "https://...",
  "qrcode_url": "https://www.nfce.fazenda.sp.gov.br/qrcode?p=35260..."
}

Cancelamento

Janela: 30 minutos após autorização (regra SEFAZ-SP, varia por UF).

curl -X POST https://api.zfiscoo.zek.app.br/v1/nfce/nfce_.../cancel \
  -H "Authorization: Bearer fk_live_..." \
  -d '{ "reason": "Cliente desistiu da compra" }'

Mínimo 15 chars no reason (SEFAZ rejeita justificativa curta).

Inutilização de numeração

Quando o sistema gera um número mas a nota nunca é emitida (gap), você precisa inutilizar:

curl -X POST https://api.zfiscoo.zek.app.br/v1/issuers/iss_.../inutilization \
  -H "Authorization: Bearer fk_live_..." \
  -d '{
    "serie": 1,
    "numero_inicial": 1234,
    "numero_final": 1234,
    "justification": "Falha de sistema na emissão de pedido 0987"
  }'

UFs suportadas

UFStatusObservações
SPsupportedCliente piloto ativo, alta cobertura de teste
MG, RJ, RS, PR, BAconfiguredURLs + cUF prontos, aguardando smoke real com cert PJ daquela UF
Demais 21 UFsconfiguredIdem; promovem-se a supported conforme cliente piloto entra

Lista completa atualizada em GET /v1/ufs.

📚

Gotchas SEFAZ que o gateway resolve por você:

  • cNF (8 dígitos aleatórios) ≠ nNF — o gateway gera automaticamente
  • indSinc=1 é sempre setado (NFC-e é síncrona, diferente de NF-e mod 55)
  • tpNF=1 (saída) sempre — devolução é evento separado
  • RSA-SHA1 + xml-exc-c14n no XMLDigSig (SEFAZ não aceita SHA256)
GuiasNF-e (modelo 55)