Documentacao do sistema

NF API SaaS

Plataforma para cadastro de empresas, configuracao fiscal, clientes, creditos e emissao de documentos fiscais. O fluxo legado de NFS-e continua disponivel, e o sistema agora tambem prepara NF-e e NFC-e pelo fluxo generico.

Visao geral

Documentos fiscais

O sistema trabalha com NFS-e, NF-e e NFC-e. NFS-e usa o endpoint legado enquanto NF-e e NFC-e usam o fluxo generico de documentos fiscais.

Clientes

Clientes sao cadastros fiscais de destinatarios, tomadores ou consumidores identificados. Eles podem ser selecionados na tela de emissao para preencher os dados da nota.

Produtos e vendas

Produtos guardam os dados fiscais do item vendido. Vendas podem chegar por integracoes, como Asaas, ou ser criadas manualmente no painel.

Configuracoes fiscais

Cada empresa pode habilitar modelos fiscais, provider, ambiente, serie, proximo numero e dados especificos como inscricao estadual, CRT, endereco do emitente e CSC da NFC-e.

API Keys

Integracoes externas usam chaves de API por empresa. A autenticacao publica e feita pelo header `x-api-key`.

Painel do cliente

Emitir

`/dashboard/emitir` centraliza a emissao por abas: NFS-e, NF-e e NFC-e.

NF-e e NFC-e ainda dependem de homologacao real com certificado, configuracoes fiscais e XML/payload validos antes de producao.

Notas

`/dashboard/notas` lista notas legadas e documentos fiscais genericos.

Documentos NF-e/NFC-e abrem em `/dashboard/notas/fiscal/[id]` com payload, resposta, XML, eventos e rejeicoes.

Clientes

`/dashboard/clientes` permite criar, editar, buscar e excluir clientes fiscais.

O cadastro e intencionalmente simples: dados fiscais e endereco, sem CRM.

Produtos

`/dashboard/produtos` guarda produtos e servicos usados nas vendas.

Cada produto define o modelo fiscal: NFS-e, NF-e ou split.

Vendas

`/dashboard/vendas` concentra vendas do Asaas e vendas manuais.

A acao principal e criar um rascunho de nota, que abre a tela de revisao fiscal.

Configuracoes

`/dashboard/fiscal` habilita modelos fiscais por empresa.

`/dashboard/admin/configuracoes` concentra configuracoes administrativas, incluindo personalizacao de logo, nome e cor principal.

A aba administrativa `NFS-e Nacional` acompanha adesão municipal e parâmetros usados pelo Padrão Nacional.

Modelos fiscais

Modelo	Provider	Status no sistema
NFS-e	open-nfse	Fluxo legado ativo.
NF-e	nfewizard	Cadastro, configuracao, montagem de payload e enfileiramento.
NFC-e	nfewizard	Cadastro, configuracao, montagem de payload e enfileiramento.
CT-e	nfewizard	Planejado, ainda nao habilitado para emissao.

NFS-e Nacional

A emissão de NFS-e segue o Padrão Nacional via `open-nfse`, SEFIN e ADN. O admin mantém acompanhamento em `/dashboard/admin/configuracoes`, aba `NFS-e Nacional`, com código IBGE, UF, status de adesão e cache de parâmetros municipais.

Padrão Nacional

A empresa informa os padrões fiscais em `/dashboard/fiscal`; a emissão usa DPS e certificado A1 pelo fluxo nacional.

Parâmetros municipais

O sistema guarda dados de adesão, alíquotas, retenções e demais parâmetros consultáveis nas APIs oficiais da NFS-e Nacional.

Em `/dashboard/fiscal`, a empresa pode sincronizar convênio, alíquota, regimes especiais e retenções usando o certificado A1 cadastrado.

Integrações municipais antigas ficam apenas como fallback futuro para exceções. O caminho principal do SaaS é a NFS-e Padrão Nacional.

Clientes

O cadastro de clientes representa os dados fiscais usados no bloco de tomador, destinatario ou consumidor. Na emissao pelo painel, selecionar um cliente preenche automaticamente nome, CPF/CNPJ, inscricoes e endereco.

{
  "name": "Cliente Exemplo Ltda",
  "legalName": "Cliente Exemplo Ltda",
  "federalTaxNumber": "12345678000195",
  "stateTaxNumber": "123456789",
  "cityTaxNumber": "98765",
  "email": "fiscal@cliente.com.br",
  "phoneNumber": "31999999999",
  "street": "Rua Exemplo",
  "number": "100",
  "district": "Centro",
  "postalCode": "30100000",
  "cityCode": "3106200",
  "cityName": "Belo Horizonte",
  "state": "MG",
  "country": "BR"
}

A Spedy usa `receiver` dentro da nota. No SaaS, guardamos o cliente localmente e copiamos os dados para o payload de emissao quando necessario.

Produtos

Produtos representam o catálogo fiscal da empresa. Eles são usados para vincular vendas recebidas por integrações, criar vendas manuais e montar rascunhos de notas.

NFS-e

Use `serviceInvoice` para serviços. O produto guarda descrição fiscal, códigos de serviço, CNAE, NBS e dados de numeração específica quando necessário.

NF-e

Use `productInvoice` para mercadorias. O produto guarda NCM, CFOP, CEST, GTIN, unidades e informações adicionais.

Split

Use `split` quando uma venda deve virar parte serviço e parte produto. A divisão fina ainda será evoluída nas próximas etapas.

{
  "code": "CURSO-QUIMICA",
  "name": "Quimica para Concursos Militares",
  "price": 137.9,
  "invoiceModel": "serviceInvoice",
  "warrantyDays": 7,
  "serviceInvoiceSettings": {
    "fiscalDescription": "Curso online preparatorio de quimica.",
    "cityServiceCode": "0802",
    "federalServiceCode": "08.02",
    "nationalTaxationCode": "080201",
    "cnaeCode": "8599604"
  }
}

Vendas

Vendas são o ponto de entrada operacional antes da emissão fiscal. Elas podem chegar por webhook do Asaas ou ser criadas manualmente no painel em `Vendas > Nova venda`.

Venda manual

Informe cliente, forma de pagamento, data da venda, garantia, produtos, desconto e preferência de transmissão fiscal.

Rascunho fiscal

A ação `Criar rascunho` gera um documento fiscal com status `draft`, vincula a venda e abre a tela de revisão da nota.

{
  "customerId": "123",
  "paymentMethod": "PIX",
  "saleDate": "2026-06-11",
  "warrantyDate": "2026-06-18",
  "discount": 0,
  "transmitMode": "manual",
  "sendEmail": false,
  "items": [
    {
      "productId": "10",
      "quantity": 1,
      "unitAmount": 137.9
    }
  ]
}

O usuário comum não precisa copiar payload. O payload fica disponível apenas como detalhe técnico dentro da nota fiscal, no botão `Payload`.

Vendas recebidas por integração tentam vincular produto por código explícito e, quando ele não existe, por descrição. Se ainda não existir, o sistema cria um produto de serviço com base na descrição da venda para permitir revisão fiscal posterior.

Emissão

NFS-e pelo painel ou API legada

Use o fluxo NFS-e atual para serviços. Rascunhos NFS-e criados por vendas são convertidos para o emissor legado e enviados pela fila `nfse-emission` após validação fiscal.

{
  "emitente": {
    "cnpj": "12345678000195",
    "codMunicipio": "3550308",
    "regime": { "opSimpNac": 1, "regEspTrib": 0 }
  },
  "serie": "1",
  "servico": {
    "cTribNac": "010101",
    "cNBS": "100000000",
    "descricao": "Desenvolvimento de software"
  },
  "valores": {
    "vServ": 1500,
    "aliqIss": 2
  },
  "tomador": {
    "documento": { "CNPJ": "98765432000110" },
    "nome": "Empresa Tomadora Ltda",
    "email": "fiscal@tomadora.com.br"
  },
  "dryRun": true
}

NF-e e NFC-e pelo fluxo generico

Use `model: "nfe"` ou `model: "nfce"` e envie o payload esperado pelo provider configurado. O documento e enfileirado e processado pelo worker.

{
  "model": "nfe",
  "requestId": "pedido-1001",
  "payload": {
    "nfe": {
      "indSinc": 1,
      "idLote": 1001,
      "NFe": []
    },
    "config": {
      "uf": "MG",
      "versaoDF": "4.00"
    }
  }
}

API publica

Autenticacao

Envie a chave da empresa no header `x-api-key` em todas as chamadas publicas.

curl https://api.seudominio.com/v1/fiscal/models \
  -H "x-api-key: nf_live_sk_..."

GET/v1/fiscal/providers

Listar providers fiscais

Retorna os providers registrados no backend fiscal.

Response

{ "success": true, "data": [ { "name": "nfewizard" } ] }

GET/v1/fiscal/models

Listar modelos da empresa

Lista configuracoes fiscais por modelo para a empresa da API key.

PUT/v1/fiscal/models/:model

Salvar configuracao de modelo

Habilita ou altera configuracao de NFS-e, NF-e ou NFC-e.

Request

{
  "enabled": true,
  "provider": "nfewizard",
  "environment": 2,
  "serie": "1",
  "nextNumber": 1,
  "config": { "uf": "MG", "crt": 1 }
}

GET/v1/fiscal/documents?model=nfe

Listar NF-e

Lista documentos fiscais do modelo NF-e. Aceita filtros adicionais como status, limit e offset.

POST/v1/fiscal/documents

Criar NF-e

Enfileira uma NF-e usando o provider configurado para a empresa.

Request

{
  "model": "nfe",
  "requestId": "pedido-1001",
  "payload": {
    "nfe": {
      "indSinc": 1,
      "idLote": 1001,
      "NFe": []
    },
    "config": {
      "uf": "MG",
      "versaoDF": "4.00"
    }
  }
}

Response

{
  "success": true,
  "data": {
    "requestId": "pedido-1001",
    "documentId": "123",
    "status": "pending"
  }
}

GET/v1/fiscal/documents/:id

Obter NF-e

Consulta um documento fiscal NF-e pelo ID interno retornado na criacao.

GET/v1/fiscal/documents?model=nfce

Listar NFC-e

Lista documentos fiscais do modelo NFC-e. Aceita filtros adicionais como status, limit e offset.

POST/v1/fiscal/documents

Criar NFC-e

Enfileira uma NFC-e usando o provider configurado para a empresa.

Request

{
  "model": "nfce",
  "requestId": "venda-1001",
  "payload": {
    "nfce": {
      "indSinc": 1,
      "idLote": 1001,
      "NFe": []
    },
    "config": {
      "uf": "MG",
      "versaoDF": "4.00"
    }
  }
}

GET/v1/fiscal/documents/:id

Obter NFC-e

Consulta um documento fiscal NFC-e pelo ID interno retornado na criacao.

GET/v1/nfse

Listar NFS-e

Lista NFS-e autorizadas da empresa autenticada.

POST/v1/nfse

Criar NFS-e

Fluxo atual para notas de servico.

Request

{
  "emitente": {
    "cnpj": "12345678000195",
    "codMunicipio": "3550308",
    "regime": { "opSimpNac": 1, "regEspTrib": 0 }
  },
  "serie": "1",
  "servico": {
    "cTribNac": "010101",
    "cNBS": "100000000",
    "descricao": "Desenvolvimento de software"
  },
  "valores": {
    "vServ": 1500,
    "aliqIss": 2
  },
  "tomador": {
    "documento": { "CNPJ": "98765432000110" },
    "nome": "Empresa Tomadora Ltda",
    "email": "fiscal@tomadora.com.br"
  },
  "dryRun": true
}

GET/v1/nfse/:chave

Obter NFS-e

Consulta uma NFS-e pela chave de acesso.

POST/v1/nfse/:chave/cancelar

Cancelar NFS-e

Solicita cancelamento da NFS-e informando a justificativa fiscal.

Request

{
  "justificativa": "Cancelamento solicitado pelo cliente"
}

Erros

Codigo	HTTP	Quando acontece
validation_error	400	Payload invalido.
unauthorized	401	API key ausente ou invalida.
insufficient_credits	402	Saldo insuficiente para emissao.
model_not_configured	409	Modelo fiscal nao habilitado para a empresa.
legacy_endpoint_required	409	Tentativa de emitir NFS-e pelo fluxo generico.
model_not_enabled	501	Modelo ainda nao liberado para emissao.

Status atual

Importante para desenvolvimento

NF-e e NFC-e ja estao estruturadas no SaaS, mas ainda precisam de homologacao fiscal real antes de uso em producao. Nao trate o enfileiramento como autorizacao fiscal.

CT-e permanece fora do escopo atual. Clientes sao locais ao SaaS e nao sincronizam com Spedy neste momento.