← Voltar ao Guia

🛒 Guia de Integração - NFC-e

Passo a passo completo para emitir NFC-e

📋 Passo 1: Obter CSC na SEFAZ

O CSC (Código de Segurança do Contribuinte) é obrigatório para NFC-e.

Acesse o portal da SEFAZ do seu estado
Vá em "Serviços" → "NFC-e" → "Gerenciar CSC"
Gere um novo CSC ou use um existente
Anote o CSC e o ID do CSC

⚠️ Importante

O CSC deve estar ATIVO no portal. CSC revogado gera erro 463.

🔑 Passo 2: Preparar JSON de Emissão

Use o template abaixo ou copie de exemplos_json/nfce_emissao_completa.json:

JSON Template

{
    "empresa": {
        "nome": "SUA EMPRESA LTDA",
        "nome_fantasia": "Sua Loja",
        "cnpj": "12345678000190",
        "inscricao_estadual": "123456789",
        "regime_tributario": 1,
        "estado": "PE",
        "cidade": "Recife",
        "endereco": "Rua Exemplo",
        "numero": "100",
        "bairro": "Centro",
        "cep": "50000000",
        "email": "contato@empresa.com.br",
        "telefone": "(81) 99999-9999",
        "senha_certificado": "SUA_SENHA_CERTIFICADO_A1"
    },
    "nfce": {
        "numero": "1",
        "serie": "001",
        "ambiente": 2,
        "csc": "SEU_CSC_AQUI",
        "csc_id": "000001"
    },
    "cliente": {
        "cpf": "05138670409",
        "nome": "João da Silva",
        "email": "joao@email.com",
        "telefone": "(81) 98888-7777"
    },
    "itens": [
        {
            "codigo": "PROD001",
            "descricao": "Produto Exemplo",
            "ncm": "49111090",
            "cfop": "5102",
            "unidade": "UN",
            "quantidade": 1,
            "valor_unitario": 10.00,
            "valor_total": 10.00
        }
    ],
    "pagamentos": [
        {
            "forma_pagamento": "01",
            "valor": 10.00
        }
    ],
    "desconto": 0,
    "informacoes_complementares": "Venda realizada no PDV",
    "responsavel_tecnico": {
        "cnpj": "12345678000190",
        "contato": "TI",
        "email": "ti@empresa.com.br",
        "telefone": "11999999999"
    }
}

✅ Dica

Cliente opcional: Para vendas sem identificação do consumidor, remova todo o bloco "cliente"

📤 Passo 3: Enviar Requisição

Faça uma requisição POST para o endpoint:

Endpoint

POST http://localhost/pontti_nfe/api/nfce/emitir.php
Content-Type: application/json

Exemplo com cURL:

cURL

curl -X POST http://localhost/pontti_nfe/api/nfce/emitir.php \
  -H "Content-Type: application/json" \
  -d '{
    "empresa": {...},
    "nfce": {...},
    "itens": [...],
    "pagamentos": [...]
  }'

Exemplo com JavaScript/Fetch:

JavaScript

fetch('http://localhost/pontti_nfe/api/nfce/emitir.php', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        empresa: {...},
        nfce: {...},
        itens: [...],
        pagamentos: [...]
    })
})
.then(response => response.json())
.then(data => console.log(data));

📥 Passo 4: Processar Resposta

✅ Sucesso (cStat = 100):

Response

{
    "success": true,
    "numero": "1",
    "serie": "001",
    "chave_acesso": "26251021497109000156650010000000011182804582",
    "protocolo": "226250936821623",
    "cStat": "100",
    "xml_path": "/pontti_nfe/arquivos/.../nfce/xml/...",
    "pdf_path": "/pontti_nfe/arquivos/.../nfce/pdf/...",
    "data_emissao": "2025-10-21 16:09:31",
    "valor_total": 10.00,
    "message": "NFC-e emitida com sucesso"
}

✅ NFC-e Autorizada!

Guarde a chave_acesso e o protocolo para futuras operações (cancelamento, consulta).

O pdf_path contém o DANFCE com QR Code para impressão.

❌ Erro (cStat ≠ 100):

Response

{
    "success": false,
    "numero": "1",
    "serie": "001",
    "cStat": "463",
    "error": "NFe rejeitada [463]: Rejeição: Codigo identificador do CSC no QR-Code foi revogado"
}

❌ NFC-e Rejeitada

Verifique o código de erro (cStat) e a mensagem (error).

Consulte a seção de erros comuns abaixo.

⚠️ Erros Comuns e Soluções

Código	Erro	Solução
`463`	CSC revogado	Gere um novo CSC no portal da SEFAZ e atualize no JSON
`704`	Data/hora atrasada	Sistema corrige automaticamente - não informe data_emissao
`778`	NCM inexistente	Use um NCM válido (ex: 49111090)
`972`	Falta responsável técnico	Inclua o bloco "responsavel_tecnico" no JSON

❌ Cancelamento de NFC-e

Para cancelar uma NFC-e autorizada, use o endpoint abaixo dentro do prazo de 24 horas após a emissão.

📝 Endpoint de Cancelamento

Endpoint

POST http://localhost/pontti_nfe/api/nfce/cancelar.php
Content-Type: application/json

🔑 JSON de Cancelamento

Use o template abaixo ou copie de exemplos_json/nfce_cancelamento.json:

JSON Template

{
    "chave_acesso": "26251021497109000156650010000000011182804582",
    "protocolo": "226250936821623",
    "cnpj": "21497109000156",
    "senha_certificado": "SUA_SENHA_CERTIFICADO_A1",
    "justificativa": "Erro no valor - cancelamento solicitado pelo cliente"
}

⚠️ Atenção

A justificativa deve ter mínimo 15 caracteres
O cancelamento só pode ser feito em até 24 horas após a autorização
Use a chave_acesso e o protocolo retornados na emissão

📥 Resposta de Cancelamento

✅ Cancelamento Autorizado:

Response

{
    "success": true,
    "chave_acesso": "26251021497109000156650010000000011182804582",
    "protocolo": "226250936821625",
    "cStat": "135",
    "message": "Cancelamento homologado"
}

❌ Erro no Cancelamento:

Response

{
    "success": false,
    "chave_acesso": "26251021497109000156650010000000011182804582",
    "cStat": "573",
    "error": "Rejeição: Duplicidade de Evento"
}

💳 Formas de Pagamento

Código	Forma de Pagamento
`01`	Dinheiro
`02`	Cheque
`03`	Cartão de Crédito
`04`	Cartão de Débito
`05`	Crédito Loja
`10`	Vale Alimentação
`11`	Vale Refeição
`12`	Vale Presente
`13`	Vale Combustível
`15`	Boleto Bancário
`16`	Depósito Bancário
`17`	PIX
`90`	Sem Pagamento
`99`	Outros

📝 Exemplos Práticos

Exemplo 1: Venda com CPF do Cliente

Arquivo: nfce_emissao_completa.json

{
    "empresa": {...},
    "nfce": {
        "numero": "1",
        "serie": "001",
        "ambiente": 2,
        "csc": "1A8F6141-B4E9-4F46-BE82-1AA462EDA8B5",
        "csc_id": "000002"
    },
    "cliente": {
        "cpf": "05138670409",
        "nome": "João da Silva"
    },
    "itens": [...],
    "pagamentos": [...]
}

Exemplo 2: Venda SEM Identificação

Arquivo: nfce_emissao_sem_cliente.json

{
    "empresa": {...},
    "nfce": {
        "numero": "2",
        "serie": "001",
        "ambiente": 2,
        "csc": "1A8F6141-B4E9-4F46-BE82-1AA462EDA8B5",
        "csc_id": "000002"
    },
    "itens": [...],
    "pagamentos": [...]
}

Nota: Sem o bloco "cliente", a NFC-e será emitida para "Consumidor Não Identificado"

Exemplo 3: Múltiplas Formas de Pagamento

Arquivo: nfce_emissao_multiplas_formas_pagamento.json

{
    "empresa": {...},
    "nfce": {...},
    "itens": [...],
    "pagamentos": [
        {
            "forma_pagamento": "01",
            "valor": 50.00
        },
        {
            "forma_pagamento": "03",
            "valor": 50.00
        }
    ]
}

Total da venda: R$ 100,00 (R$ 50 em dinheiro + R$ 50 no cartão de crédito)

❌ Cancelar NFC-e

Para cancelar uma NFC-e autorizada (prazo: até 24 horas):

POST /api/nfce/cancelar.php

{
    "chave_acesso": "26251021497109000156650010000000011182804582",
    "protocolo": "226250936821623",
    "justificativa": "Erro no preenchimento dos dados da NFC-e"
}

⚠️ Atenção

• Justificativa mínima: 15 caracteres

• Prazo: até 24 horas após autorização

• Após cancelamento, não pode ser revertido

💡 Dicas e Boas Práticas

🔢

Numeração

Controle rigoroso da numeração sequencial por série

⏰

Data/Hora

Não informe data_emissao, o sistema usa a data/hora atual automaticamente

💰

Valores

Use valores com 2 casas decimais (10.00 e não 10)

🔐

CSC Ativo

Verifique periodicamente se o CSC está ativo no portal SEFAZ

📱

QR Code

Sempre impresso automaticamente no DANFCE para consulta

🧪

Homologação

Teste sempre em homologação (ambiente: 2) antes de produção