NFS-e Avulsa — Plano de Implementação
Visão Geral
Nova funcionalidade no Módulo Fiscal da SMB Store para emissão manual de Notas Fiscais de Serviço Eletrônicas (NFSe). O prestador seleciona um tomador, seleciona o serviço, preenche dados fiscais e transmite a nota à prefeitura — tudo dentro do sistema.
Estado atual: o Módulo Fiscal suporta apenas NFe e NFCe (produtos). Esta release adiciona cobertura para serviços.
Integração: API Focus NFe — endpoints /v2/nfse (próprio) e /v2/nfsen (nacional).
Seleção de Ambiente pelo Usuário
Na tela de Dados Fiscais, um dropdown permite escolher entre dois ambientes de emissão:
| Opção | Comportamento na Focus | Endpoint de emissão |
|---|---|---|
| Ambiente Nacional | Habilita NFSe Nacional, desabilita NFSe própria | /v2/nfsen |
| Ambiente Próprio | Habilita NFSe própria, desabilita NFSe Nacional | /v2/nfse |
A escolha é manual e direta: o usuário seleciona o dropdown, o sistema persiste e aplica o endpoint correspondente em toda emissão subsequente.
Regra MEI: empresas com regime tributário MEI (código 4) obrigatoriamente usam Ambiente Nacional, independente da configuração manual.
Fase 1 — Configuração e Cadastros
Entrega: A empresa está configurada para emitir NFSe. Serviços e clientes possuem dados fiscais completos. Permissões estão ativas.
1.1 Configuração NFSe da Empresa
Na tela de Dados Fiscais da Empresa, aba Configuração de Notas, será adicionada uma nova seção NFS-e com os seguintes campos e regras:
Wireframe — Seção NFSe em Dados Fiscais
Fluxo de busca do Município
Regras de validação
- Ativar switch: Inscrição Municipal deve estar preenchida. Caso contrário, alerta com link para o campo.
- Número RPS: inteiro positivo, mínimo 1, obrigatório.
- Senha da prefeitura: armazenada de forma encriptada.
- Tipo de Ambiente: ao salvar, atualiza a configuração da empresa na Focus com as flags corretas.
1.2 Catálogo LC 116 e Dados Fiscais do Serviço
No cadastro de Produtos e Serviços, quando o item for do tipo Serviço e o Módulo Fiscal estiver ativo, uma nova aba Dados Fiscais será exibida. O catálogo da LC 116/2003 (~200 itens) será pré-carregado no sistema para facilitar o preenchimento.
Wireframe — Aba Dados Fiscais do Serviço
Regras
- Campos são opcionais no cadastro — obrigatoriedade validada apenas no momento da emissão da NFSe.
- Serviços sem dados fiscais completos recebem indicador visual "Pendente" ao serem selecionados no formulário de emissão.
- O campo Código LC 116 possui autocomplete com busca por código ou descrição no catálogo pré-carregado.
1.3 Dados Fiscais do Cliente (Tomador)
O cadastro de cliente precisa do Código IBGE do Município para emissão de NFSe. Um novo campo será adicionado ao bloco de endereço, com auto-preenchimento via CEP.
Wireframe — Campo IBGE no Cadastro de Cliente
Regras
- Ao preencher o CEP, o sistema tenta buscar o Código IBGE automaticamente.
- Para validação na emissão: cliente deve ter CPF/CNPJ, endereço completo e Código IBGE preenchidos.
- Sinalização visual quando cadastro está incompleto para NFSe.
1.4 Permissões de Usuário
Três novas permissões controlam o acesso ao módulo NFSe:
| Permissão | Descrição |
|---|---|
| Emitir NFSe Manual | Acesso ao módulo inteiro: menu, listagem, emissão |
| Cancelar NFSe | Permite cancelar notas autorizadas |
| Gerenciar Configuração NFSe | Acesso à configuração da seção NFSe em Dados Fiscais |
- Checkboxes na tela de permissões, visíveis apenas quando NFSe habilitada no tenant.
- Usuários sem permissão de emissão não veem o item no menu, inclusive por acesso direto via URL.
1.5 Cache de Municípios Suportados
O sistema mantém um cache local da lista de municípios suportados pela Focus, atualizado a cada 30 dias. Esse cache alimenta o autocomplete de município na configuração NFSe e armazena dados como:
- Se o município suporta NFSe
- Se exige certificado digital
- Se possui ambiente de homologação
- Se suporta cancelamento via API
- Quais campos são obrigatórios (CNAE, código LC 116, código tributário municipal)
Entrega da Fase 1
- Tela de Dados Fiscais com seção NFSe funcional
- Autocomplete de município com cache
- Catálogo LC 116 disponível para busca
- Aba Dados Fiscais no cadastro de serviço
- Campo Código IBGE no cadastro de cliente
- Permissões de NFSe registradas e funcionais
Fase 2 — Emissão de NFSe Manual
Entrega: Usuário pode emitir NFSe selecionando tomador e serviço. Nota transmitida de forma assíncrona com retorno automático de status. XML armazenado localmente.
2.1 Integração com Focus NFSe
O sistema comunica com a API Focus para as seguintes operações:
| Operação | Método | Endpoint Focus |
|---|---|---|
| Emitir NFSe (próprio) | POST | /v2/nfse |
| Emitir NFSe (nacional) | POST | /v2/nfsen |
| Consultar status | GET | /v2/nfse/{ref} |
| Cancelar | DELETE | /v2/nfse/{ref} |
| Substituir | POST | /v2/nfse/{ref}/substitucao |
| Download PDF | GET | URL retornada pela Focus |
| Download XML | GET | URL retornada pela Focus |
| Listar municípios | GET | /v2/municipios |
Importante: o ambiente de emissão NFSe (homologação/produção) é independente do ambiente da NFe.
Resolução de endpoint na emissão
- Ambiente Nacional → endpoint
/v2/nfsen - Ambiente Próprio → endpoint
/v2/nfse - Exceção MEI: regime tributário MEI sempre usa
/v2/nfsen, independente da configuração.
2.2 Retorno Automático de Status (Webhook)
Após a transmissão, a Focus processa a nota de forma assíncrona e notifica o sistema via webhook quando há mudança de status.
Regras
- Obrigatório: ao receber autorização, baixar e armazenar o XML localmente (a Focus só gera backups mensais).
- Idempotência: se o webhook for recebido mais de uma vez para a mesma nota, ignorar se o status já foi processado.
2.3 Formulário de Emissão — Dados Gerais e Tomador
A página NFSe Manual será acessível pelo menu do Módulo Fiscal (visível apenas com permissão). Contém a listagem de notas emitidas e o botão "Nova NFSe" que abre o formulário em 4 etapas.
Wireframe — Listagem de NFSe (página principal)
Wireframe — Modal de Emissão: Etapa 1 (Dados Gerais)
Wireframe — Modal de Emissão: Etapa 2 (Tomador)
Regras do Tomador
- Busca inteligente por nome, CPF ou CNPJ.
- Se o cliente não possui Código IBGE, exibe alerta com link para corrigir cadastro (abre em nova aba).
- O alerta não bloqueia o preenchimento do formulário, mas bloqueia a transmissão da nota.
- Botão "Revalidar tomador" após correção em outra aba.
- Opção de cadastrar novo cliente sem sair do fluxo.
2.4 Formulário de Emissão — Serviço e Retenções
Wireframe — Modal de Emissão: Etapa 3 (Serviço)
Regras do Serviço
- Cada NFSe permite um único serviço.
- O serviço pode ser selecionado do catálogo (dados fiscais preenchidos automaticamente) ou adicionado manualmente (dados fiscais obrigatórios no formulário).
- Serviço do catálogo: se os dados fiscais estiverem incompletos (LC 116, alíquota ISS), exibe badge "Pendente" com link para completar o cadastro (abre nova aba).
- Serviço manual: dados efêmeros (não salva no catálogo). LC 116 e alíquota ISS são obrigatórios.
- Campos editáveis: descrição da linha, quantidade e valor unitário.
- A transmissão é bloqueada se o serviço tiver pendências fiscais.
2.5 Transmissão e Acompanhamento de Status
Wireframe — Modal de Emissão: Etapa 4 (Revisão)
Fluxo completo de emissão
Regras da transmissão
- Retenções (ISS, PIS, COFINS, IR, CSLL, INSS) são editáveis manualmente na etapa de revisão (sem cálculo automático no MVP).
- Banner MEI exibido quando aplicável.
- NFSe consome a mesma cota mensal do pacote (mesma franquia NFe/NFCe). Verificar saldo antes de emitir.
- Após transmitir: toast informativo, nota aparece na listagem com status "Processando".
- Botão "Consultar Status" como fallback manual caso o webhook demore.
Entrega da Fase 2
- Integração com Focus NFSe funcionando (emissão, consulta, cancelamento, substituição)
- Webhook processando autorizações e armazenando XML
- Formulário completo de emissão (4 etapas)
- Transmissão assíncrona com retorno de status
- Regra MEI forçando Ambiente Nacional
Fase 3 — Gestão de NFSe
Entrega: Usuário pode listar, filtrar, visualizar detalhes, baixar PDF/XML, cancelar e substituir notas.
3.1 Listagem e Filtros
Wireframe da listagem apresentado na Fase 2. Complementos:
- Filtros: período (data início/fim), status (dropdown), tomador (busca por nome/CPF/CNPJ)
- Busca textual: por número da nota, número RPS, nome do tomador
- Paginação: 20 itens por página
- Status possíveis: Em processamento, Autorizada, Erro, Cancelada, Substituída
3.2 Visualização Detalhada e Downloads
Wireframe — Modal de Detalhes da NFSe
Ações disponíveis por status
| Ação | Em processamento | Autorizada | Erro | Cancelada | Substituída |
|---|---|---|---|---|---|
| Baixar XML | — | ✓ | — | ✓ | ✓ |
| Baixar PDF | — | ✓ | — | — | — |
| Cancelar | — | ✓ | — | — | — |
| Substituir | — | — | ✓ | ✓ | — |
Regras de Downloads
- XML: prioriza o XML armazenado localmente; se indisponível, consulta a Focus.
- PDF: obtido via Focus. Se o município não suporta PDF, botão desabilitado com tooltip "Este município não suporta download de PDF via sistema."
3.3 Cancelamento
Wireframe — Modal de Cancelamento
Regras
- Município sem suporte a cancelamento: botão desabilitado com tooltip "Indisponível para este município. Entre em contato com a prefeitura."
- Justificativa obrigatória (máx 255 caracteres).
- Após cancelamento, status atualizado para "Cancelada".
3.4 Substituição
- Disponível para notas com status Erro ou Cancelada.
- Abre formulário de nova NFSe pré-preenchido com dados da nota original.
- Banner: "Você está substituindo a nota nº X. Revise e corrija as informações antes de transmitir."
- Após transmissão: nota original → status "Substituída"; nova nota → "Processando".
- Ambas as notas ficam vinculadas e visíveis na seção "Notas Vinculadas" dos detalhes.
Entrega da Fase 3
- Listagem com filtros e paginação
- Busca por número, RPS, tomador
- Modal de detalhes com todos os dados
- Download XML (local) e PDF (Focus)
- Cancelamento com justificativa
- Substituição com pré-preenchimento
- Cadeia de notas vinculadas
Fase 4 — Dashboard Fiscal Unificado
Entrega: Dashboard apresenta visão consolidada de NFe + NFCe + NFSe com métricas, filtros e exportação de XMLs.
4.1 Métricas e Contadores NFSe
Wireframe — Cards no Dashboard
Regras
- Card "NFSe" visível apenas com switch de NFSe ativo.
- NFSe autorizadas contam no total de "Notas emitidas no período".
- Cota mensal inclui NFSe na contagem total (mesma franquia).
- Nova opção "NFSe" no filtro de tipo de documento.
- Link rápido "Emitir NFSe" na barra de ações.
- Menu lateral: item "NFSe Manual" no grupo Módulo Fiscal.
4.2 Exportação de XMLs por Período
- Botão "Exportar XMLs" com seletor de período.
- Gera ZIP com os XMLs armazenados localmente.
- Não depende da Focus — tudo da base local.
Entrega da Fase 4
- Card contador "NFSe" no dashboard
- NFSe na cota mensal
- Filtro por tipo de documento incluindo NFSe
- Link rápido "Emitir NFSe"
- Exportação de XMLs em ZIP
Fase 5 — Testes, Validação e Rollout
Entrega: Módulo validado em homologação, regressão NFe/NFCe íntegra, rollout gradual para produção.
5.1 Testes Funcionais em Homologação
| Cenário | Descrição |
|---|---|
| Emissão básica | Empresa Simples Nacional, serviço simples, tomador PJ |
| Emissão MEI | Sistema força Ambiente Nacional |
| ISS retido + retenções | PIS, COFINS, CSLL, IR, INSS preenchidos |
| Bloqueio dados incompletos | Serviço sem LC 116 → orientação de preenchimento |
| Webhook autorização | Status atualizado + XML armazenado localmente |
| Webhook erro | Status erro + mensagem da prefeitura exibida |
| Consulta manual status | Fallback quando webhook demora |
| Cancelamento | Justificativa + confirmação na prefeitura |
| Substituição | Pré-preenchimento + vínculo entre notas |
| Download PDF | Município com e sem suporte |
| Download XML | Base local e via Focus |
| Cota | NFSe decrementa saldo do pacote mensal |
| Permissões | Sem permissão → menu oculto + rota bloqueada |
| Multi-tenant | NFSe da empresa A não aparece na empresa B |
| Tomador sem IBGE | Bloqueio na transmissão + orientação |
| Sem Inscrição Municipal | Bloqueio ao ativar switch |
| Município não suportado | Mensagem clara ao usuário |
5.2 Testes de Regressão
- NFe/NFCe continua emitindo normalmente
- Dashboard sem NFSe ativa não quebra
- Produto tipo mercadoria não exibe aba de dados fiscais de serviço
- Webhooks NFe/NFCe inalterados
5.3 Testes de Borda
- API Focus fora do ar → tratamento gracioso com mensagem ao usuário
- NFSe com valor zero → bloqueio
- Emissões simultâneas → sem duplicidade no número RPS
- Webhook duplicado → processamento idempotente
5.4 Rollout Gradual
| Fase | Escopo | Critério de entrada |
|---|---|---|
| Alpha | 3–5 clientes em municípios estáveis (SP, Curitiba) | Testes em homologação aprovados |
| Beta | Clientes em cidades homologadas como estáveis | Alpha sem bugs críticos |
| GA | Toda a base | Beta estável por 2 semanas |
Entrega da Fase 5
- Todos os cenários de teste aprovados em homologação
- Regressão NFe/NFCe sem impacto
- Payloads validados com consultoria fiscal
- Webhook NFSe configurado no painel Focus (homolog + prod)
- Alpha concluído com sucesso
- GA liberado
Fluxo Geral — Diagrama Completo
Funcionalidades Futuras (pós Release 1)
| Feature | Release |
|---|---|
| Emissão de NFSe a partir de Ordem de Serviço | Release 2 |
| Clonagem de NFSe recorrente | Futuro |
| Cálculo automático de retenções federais | Futuro |
| Envio automático de e-mail com nota | Futuro |
| Cálculo IBS/CBS (reforma tributária) | Quando obrigatório |