Endpoints NF-e / NFC-e

Referência completa e detalhada de todos os endpoints REST da NFER. A API permite emitir notas fiscais (NF-e modelo 55, NFC-e modelo 65 e DC-e), gerar arquivos XML e DANFE PDF, gerenciar devoluções de e-commerce, cancelamentos e cartas de correção com sincronização direta na SEFAZ.

Ciclo de Vida da NF-e (Como Emitir)

A emissão na NFER é projetada para ser rápida, resiliente e imune a lentidões da SEFAZ. O fluxo é dividido em 3 etapas simples:

Tabela Geral de Endpoints

1. Criar Rascunho de NF-e (POST /v1/nfe)

Você pode passar o destinatário de duas formas: diretamente no corpo da requisição (customer) ou usando o ID de um cliente previamente cadastrado (customerId).

{
  "customer": {
    "cpfCnpj": "12345678000199",
    "nome": "Cliente Exemplo LTDA",
    "email": "fiscal@cliente.com",
    "telefone": "4430000000",
    "endereco": {
      "logradouro": "Rua das Flores",
      "numero": "100",
      "complemento": "Sala 2",
      "bairro": "Centro",
      "xMun": "Cianorte",
      "UF": "PR",
      "CEP": "87200000"
    }
  },
  "naturezaOperacao": "VENDA DE MERCADORIA",
  "tipoOperacao": "1",
  "finalidade": 1,
  "serie": 1,
  "indFinal": 1,
  "indPres": 2,
  "valorFrete": 15.94,
  "transporte": { "modFrete": 0 },
  "informacoesAdicionais": "Pedido 3306 - Integracao API",
  "itens": [
    {
      "codigo": "SKU-001",
      "descricao": "Camiseta 100% Algodao",
      "ncm": "61091000",
      "unidade": "UN",
      "quantidade": 1,
      "valorUnitario": 259.90,
      "fiscalProfileId": "0e8a719f-..."
    }
  ],
  "pagamentos": [
    { "forma": "17", "valor": 275.84 }
  ]
}

Tabela de Parâmetros Principais (POST /v1/nfe)

2. Transmitir para a SEFAZ (POST /v1/nfe/:id/send)

Dispara a assinatura digital com certificado A1 e o envio do lote para os servidores da SEFAZ estadual.

curl -s -X POST https://api.nfer.me/v1/nfe/8f21ac-uuid/send \
  -H "X-API-Key: $NFER_KEY" \
  -H "Content-Type: application/json"

Resposta imediata da fila:

{
  "id": "8f21ac-uuid",
  "status": "processando",
  "numero": 1042,
  "serie": 1,
  "message": "Nota fiscal enviada para a fila de processamento da SEFAZ"
}

3. Consultar Status e Dados (GET /v1/nfe/:id)

Retorna todos os dados da nota fiscal, incluindo chave de acesso de 44 dígitos, protocolo de autorização, valores calculados e mensagens de erro da SEFAZ caso tenha sido rejeitada.

curl -s https://api.nfer.me/v1/nfe/8f21ac-uuid \
  -H "X-API-Key: $NFER_KEY"

4. Corrigir e Reenviar Nota com Erro (PUT /v1/nfe/:id)

Se a SEFAZ rejeitar a nota (ex: cStat 321 ou 539), nunca gere um novo rascunho. Atualize os dados da mesma nota usando PUT /v1/nfe/:id e chame /send novamente. Isso garante que o mesmo número sequencial seja utilizado, sem furos de numeração.

# 1. Atualiza os dados com o body corrigido
curl -s -X PUT https://api.nfer.me/v1/nfe/8f21ac-uuid \
  -H "X-API-Key: $NFER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ ...body corrigido... }'

# 2. Reenvia a mesma nota para a SEFAZ
curl -s -X POST https://api.nfer.me/v1/nfe/8f21ac-uuid/send \
  -H "X-API-Key: $NFER_KEY"

5. Download de XML e DANFE PDF

Após a autorização na SEFAZ, o NFER armazena o XML protocolado e gera o DANFE em PDF de alta qualidade para impressão.

curl -s https://api.nfer.me/v1/nfe/$NFE_ID/xml \
  -H "X-API-Key: $NFER_KEY" -o nfe.xml

curl -s "https://api.nfer.me/v1/nfe/$NFE_ID/danfe?api_key=$NFER_KEY" \
  -o danfe.pdf

6. Nota de Devolução e Troca (E-commerce e Varejo)

Quando um cliente pede troca ou devolução de um pedido cujo prazo de cancelamento (24h) já expirou, a legislação fiscal brasileira exige a emissão de uma Nota Fiscal de Devolução de Entrada (finalidade 4).

# 1. Gera o rascunho de devolução a partir da nota autorizada
curl -s -X POST https://api.nfer.me/v1/nfe/$NFE_ORIGINAL_ID/devolucao \
  -H "X-API-Key: $NFER_KEY"

# 2. Envia para autorização na SEFAZ
curl -s -X POST https://api.nfer.me/v1/nfe/$NFE_DEVOLUCAO_ID/send \
  -H "X-API-Key: $NFER_KEY"

7. Cancelamento de NF-e (POST /v1/nfe/:id/cancel)

O cancelamento só pode ser solicitado se a mercadoria ainda não saiu para entrega e dentro do prazo legal da SEFAZ estadual (geralmente 24 horas). A justificativa deve conter no mínimo 15 caracteres.

curl -s -X POST https://api.nfer.me/v1/nfe/$NFE_ID/cancel \
  -H "X-API-Key: $NFER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "justificativa": "Cancelamento solicitado pelo cliente antes do envio"
  }'

8. Carta de Correção Eletrônica — CC-e (POST /v1/nfe/:id/correction-letter)

Usada para corrigir erros simples (ex.: erro de digitação no endereço de entrega, dados do transportador, informações complementares). Não permite alterar valores fiscais, alíquotas de impostos, data de emissão ou mudar completamente o destinatário.

curl -s -X POST https://api.nfer.me/v1/nfe/$NFE_ID/correction-letter \
  -H "X-API-Key: $NFER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "correcao": "Onde se le Rua das Flores 100, leia-se Rua das Flores 102 Sala 4"
  }'

9. Inutilização de Numeração (POST /v1/nfe/inutilizar)

Se houve uma quebra na sequência de numeração (ex: pulou do número 105 para o 110 por falha interna do ERP), você deve justificar a inutilização desses números perante a SEFAZ para evitar multas tributárias.

curl -s -X POST https://api.nfer.me/v1/nfe/inutilizar \
  -H "X-API-Key: $NFER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "serie": 1,
    "numeroInicial": 106,
    "numeroFinal": 109,
    "justificativa": "Numeros pulados por falha na integracao do software emissor",
    "modelo": "55"
  }'

10. Emissão em Lote (POST /v1/nfe/batch)

Permite enviar até 50 notas de uma única vez para processamento paralelo de alta velocidade. Ideal para fechamento de vendas diárias ou expedições de e-commerce.

curl -s -X POST https://api.nfer.me/v1/nfe/batch \
  -H "X-API-Key: $NFER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "notas": [
      { "naturezaOperacao": "VENDA", "itens": [...], "pagamentos": [...] },
      { "naturezaOperacao": "VENDA", "itens": [...], "pagamentos": [...] }
    ]
  }'

11. NFC-e — Cupom Fiscal Eletrônico (Modelo 65)

Para ponto de venda (PDV) e frente de caixa. O destinatário é opcional (venda anônima no balcão). Requer o CSC (nfceIdCsc e nfceTokenCsc) configurado no cadastro da empresa.

curl -s -X POST https://api.nfer.me/v1/nfce \
  -H "X-API-Key: $NFER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "naturezaOperacao": "VENDA AO CONSUMIDOR",
    "itens": [
      {
        "descricao": "Cafe Expresso 50ml",
        "ncm": "09012100",
        "unidade": "UN",
        "quantidade": 1,
        "valorUnitario": 7.50
      }
    ],
    "pagamentos": [
      { "forma": "01", "valor": 7.50 }
    ]
  }'