Documentação da API

A Wizard-API é uma API REST para emissão e gestão de NF-e e NFC-e. Envie JSON e receba a nota autorizada — sem SOAP, XML manual, certificados ou protocolos da SEFAZ para lidar diretamente.

Todas as rotas estão prefixadas com /api e exigem autenticação por API key no header x-api-key. Cada rota declara um scope exigido pela chave. Gere sua chave no dashboard em /dashboard/api-keys.

Respostas seguem o formato { success, data, error }. Códigos 2xx indicam sucesso, 4xx erros de validação/rejeição da SEFAZ, 5xx erros internos.

Autenticação

Envie sua API key no header x-api-key. Requisições sem chave ou com scope insuficiente retornam 401 ou 403.

x-api-key: <sua-api-key>

Exemplo com curl:

curl -X POST https://api.sua-instancia.com/api/nfe/autorizar \
  -H "x-api-key: sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d @payload.json

Erros

Os campos cStat e xMotivo da SEFAZ aparecem dentro de error.sefaz quando a UF rejeita a operação (HTTP 422).

{
  "success": false,
  "data": null,
  "error": {
    "code": "NFE_REJEITADA",
    "sefaz": { "cStat": "204", "xMotivo": "Duplicidade de NF-e" }
  }
}

Códigos comuns em error.code:

VALIDATION_ERROR — payload JSON inválido
UNAUTHORIZED — chave de API ausente ou inválida
FORBIDDEN — chave não tem o scope exigido
NFE_REJEITADA — SEFAZ rejeitou a operação
NOT_FOUND — recurso não encontrado
INTERNAL_ERROR — falha inesperada

Endpoints

Rotas agrupadas por scope. Campos obrigatórios são validados por Zod no servidor.

Emissão nfe:emissao

POST /api/nfe/autorizar

Envia um lote de NF-e para autorização na SEFAZ (1 a 50 NF-e por lote). Aceita JSON (validado por Zod) ou XML.

Request:

{
  "idLote": 1,
  "indSinc": 1,
  "NFe": [{
    "infNFe": {
      "ide": { "cUF": 35, "natOp": "Venda de mercadoria", "mod": 55, "serie": "1", "nNF": 1, "tpNF": 1, "tpAmb": 2, "finNFe": 1, "indFinal": 1 },
      "emit": { "CNPJCPF": "12345678000199", "xNome": "Empresa Teste Ltda", "IE": "12345678901234", "CRT": 3 },
      "dest": { "CNPJCPF": "08723218000186", "xNome": "Cliente Exemplo SA", "indIEDest": 9 },
      "det": [{ "prod": { "cProd": "001", "xProd": "Produto Teste", "NCM": "84719090", "CFOP": 5102, "uCom": "UN", "qCom": 1, "vUnCom": "100.00", "vProd": "100.00", "indTot": 1 } }],
      "total": { "ICMSTot": { "vNF": "100.00" } },
      "transp": { "modFrete": 0 },
      "pag": { "detPag": [{ "tPag": "01", "vPag": "100.00" }] }
    }
  }]
}

Response (200):

{
  "success": true,
  "data": {
    "chave": "43210712345678000199550000000000011001234567",
    "nProt": "143260000012345",
    "cStat": "100",
    "xMotivo": "Autorizado o uso da NF-e",
    "xml": "<?xml ...>"
  },
  "error": null
}

Validação: idLote int ≥ 1; indSinc 0/1 (opcional); NFe array 1–50 itens. CNPJ/CPF normalizados automaticamente.

Eventos nfe:eventos

POST /api/nfe/cancelar

Cancela uma NF-e autorizada. O protocolo de autorização é exigido.

{
  "chave": "43210712345678000199550000000000011001234567",
  "nProt": "143260000012345",
  "xJust": "Erro na emissao da nota fiscal"
}

Validação: chave ≥ 44 chars; nProt ≥ 15 chars; xJust 15–255 chars.

POST /api/nfe/carta-correcao

Registro de Carta de Correção Eletrônica (CC-e).

{
  "chave": "43210712345678000199550000000000011001234567",
  "xCorrecao": "Corrigir o endereco do destinatario para Rua B número 200"
}

Validação: chave ≥ 44 chars; xCorrecao 15–1000 chars.

POST /api/nfe/ciencia

Manifestação do destinatário: Ciência da Operação.

{ "chave": "43210712345678000199550000000000011001234567" }

POST /api/nfe/confirmacao

Manifestação do destinatário: Confirmação da Operação.

{ "chave": "43210712345678000199550000000000011001234567" }

POST /api/nfe/desconhecimento

Manifestação do destinatário: Desconhecimento da Operação.

{ "chave": "43210712345678000199550000000000011001234567" }

POST /api/nfe/operacao-nao-realizada

Manifestação do destinatário: Operação não Realizada.

{ "chave": "43210712345678000199550000000000011001234567" }

POST /api/nfe/epec

Evento Prévio de Emissão em Contingência (EPEC).

{
  "chave": "43210712345678000199550000000000011001234567",
  "cOrgaoAutor": "35"
}

Validação: chave ≥ 44 chars; cOrgaoAutor ≥ 2 chars (código IBGE da UF).

NFC-e nfce:emissao / nfce:eventos

POST /api/nfce/autorizar

Envia uma NFC-e (mod=65) para autorização na SEFAZ (1 a 50 por lote). Exige indFinal=1, indPres=1 e destinatário.

Request:

{
  "idLote": 1,
  "indSinc": 1,
  "NFe": [{
    "infNFe": {
      "ide": { "cUF": 35, "natOp": "Venda varejo", "mod": 65, "serie": "1", "nNF": 1, "tpNF": 1, "tpAmb": 2, "finNFe": 1, "indFinal": 1, "indPres": 1 },
      "emit": { "CNPJCPF": "12345678000199", "xNome": "Loja Teste Ltda", "IE": "12345678901234", "CRT": 3 },
      "dest": { "CNPJCPF": "08723218000186", "xNome": "Cliente Final", "indIEDest": 9 },
      "det": [{ "prod": { "cProd": "001", "xProd": "Produto Varejo", "NCM": "84719090", "CFOP": 5102, "uCom": "UN", "qCom": 1, "vUnCom": "50.00", "vProd": "50.00", "indTot": 1 } }],
      "total": { "ICMSTot": { "vNF": "50.00" } },
      "transp": { "modFrete": 9 },
      "pag": { "detPag": [{ "tPag": "01", "vPag": "50.00" }] }
    }
  }]
}

Response (200):

{
  "success": true,
  "data": {
    "chave": "43210712345678000199650000000000011001234567",
    "nProt": "143260000012345",
    "cStat": "100",
    "xMotivo": "Autorizado o uso da NFC-e",
    "xml": "<?xml ...>"
  },
  "error": null
}

Validação: mod deve ser 65; indFinal=1; indPres=1; dest obrigatório.

POST /api/nfce/cancelar

Cancela uma NFC-e autorizada.

{
  "chave": "43210712345678000199650000000000011001234567",
  "nProt": "143260000012345",
  "xJust": "Erro na emissao da nota fiscal do consumidor"
}

Validação: chave ≥ 44 chars; nProt ≥ 15 chars; xJust 15–255 chars.

Consultas nfe:consultas

GET /api/nfe/status-sefaz

Consulta o status do serviço da SEFAZ da UF configurada.

{
  "success": true,
  "data": { "cStat": "107", "xMotivo": "Servico em Operacao", "dhRecbto": "...", "tMed": 1 },
  "error": null
}

GET /api/nfe/consulta/:chave

Consulta o protocolo de uma NF-e pela chave de acesso (44 dígitos).

curl -X GET https://api.sua-instancia.com/api/nfe/consulta/43210712345678000199550000000000011001234567 \
  -H "x-api-key: sk_live_abc123"

POST /api/nfe/distribuicao/nsu

Distribuição de DFe por NSU específico.

{
  "cUFAutor": "35",
  "CNPJ": "12345678000199",
  "ultNSU": "000000000001234"
}

Validação: cUFAutor 2 chars; CNPJ 14 dígitos; ultNSU ≥ 1 char.

POST /api/nfe/distribuicao/chave

Distribuição de DFe por chave de NF-e específica.

{
  "cUFAutor": "35",
  "CNPJ": "12345678000199",
  "chNFe": "43210712345678000199550000000000011001234567"
}

Validação: cUFAutor 2 chars; CNPJ 14 dígitos; chNFe ≥ 44 chars.

POST /api/nfe/distribuicao/ult-nsu

Distribuição de DFe usando o último NSU (consulta incremental).

{
  "cUFAutor": "35",
  "CNPJ": "12345678000199",
  "ultNSU": "000000000001234"
}

Validação: cUFAutor 2 chars; CNPJ 14 dígitos; ultNSU ≥ 1 char.

POST /api/nfe/inutilizar

Inutiliza uma faixa de numeração de NF-e não usada.

{
  "cnpj": "12345678000199",
  "ano": "2026",
  "modelo": "55",
  "serie": "1",
  "nNFIni": "101",
  "nNFFin": "110",
  "xJust": "Falha no sistema emitiu fora da sequencia"
}

Validação: cnpj 14 dígitos; ano 4 dígitos; xJust 15–255 chars.

POST /api/nfe/validar-xml

Valida um XML de NF-e ou NFC-e contra o schema XSD correspondente.

{
  "xml": "<nfeProc versao=\"4.00\">...</nfeProc>"
}

Validação: xml obrigatório; versão detectada automaticamente.