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).

Arquitetura de Referência do Codebase

Camada	Padrão Atual	Arquivos-chave
API Focus	Factory + Contracts (`third_party/NotaFiscal/`)	`Notafiscal.php`, `CreateNfe.php`, `CancelNfe.php`
Controllers	CodeIgniter + `Ws.php` como hub de operações	`Ws.php`, `Nfes_manual.php`, `Dados_fiscais_v.php`
Models	`Generic_model` com enums internos	`Notas_fiscais_model.php`, `Empresa_model.php`
Helpers	Funções procedurais por domínio	`my_nota_fiscal_helper.php`, `my_webhook_nfe_helper.php`
Frontend	Vue 3 (Composition API) + Mixins + Materialize CSS	`DadosFiscaisController_v.js`, `Mixin_nota_fiscal.js`
Permissões	Constantes no `Permissao_model` (430–433 usados)	`Permissao_model.php`
Rotas	`routes.php` + controllers nomeados	`$route['nfes-manual/(:num)']`

Seleção de Ambiente pelo Usuário

Na tela de Dados Fiscais, um dropdown permite escolher entre dois ambientes de emissão:

Opção	Flags na API de Empresas Focus	Endpoint de emissão
Ambiente Nacional	`habilita_nfsen_producao: true`, `habilita_nfse: false`	`/v2/nfsen`
Ambiente Próprio	`habilita_nfsen_producao: false`, `habilita_nfse: true`	`/v2/nfse`

A escolha do ambiente é manual e direta: o usuário seleciona o dropdown, o sistema persiste a configuração 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 Estrutura de Dados Base

Escopo: Migrações de banco, models, enums, constantes de permissão. Pré-requisito para tudo.

Novas colunas — tabela `empresas`

Coluna	Tipo	Descrição
`ativar_nfse`	tinyint(1) default 0	Switch habilitar NFSe
`is_nfse_prod`	tinyint(1) default 0	Ambiente: 0=homolog, 1=prod
`nfse_ambiente`	enum('nacional','proprio')	Tipo de ambiente
`nfse_numero_rps`	int unsigned	Próximo número RPS
`nfse_login_prefeitura`	varchar(100)	Login prefeitura
`nfse_senha_prefeitura`	text	Senha prefeitura (encriptada)
`nfse_codigo_ibge`	varchar(7)	Código IBGE do município
`nfse_info_adicionais`	text	Informações adicionais padrão

Campos reutilizados (já existentes): inscricao_municipal (varchar 30).

Novas colunas — tabela `notas_fiscais`

Coluna	Tipo	Descrição
`nfse_numero`	varchar(20)	Número oficial da NFSe
`nfse_numero_rps`	int	Número RPS usado
`nfse_codigo_verificacao`	varchar(50)	Código de verificação
`nfse_url`	text	URL da nota na prefeitura
`xml_nfse`	longtext	XML armazenado localmente
`nfse_natureza_operacao`	tinyint	Enum 1–6
`nfse_data_competencia`	date	Data de competência
`nfse_discriminacao`	text	Discriminação dos serviços
`nfse_substituida_id`	int unsigned null	FK nota substituída
`nfse_valor_pis`	decimal(15,2)	Retenção PIS
`nfse_valor_cofins`	decimal(15,2)	Retenção COFINS
`nfse_valor_ir`	decimal(15,2)	Retenção IR
`nfse_valor_csll`	decimal(15,2)	Retenção CSLL
`nfse_valor_inss`	decimal(15,2)	Retenção INSS
`nfse_valor_iss`	decimal(15,2)	Valor ISS
`nfse_valor_iss_retido`	decimal(15,2)	ISS retido

Campos reutilizados (já existentes): numero (número sequencial interno), is_prod (ambiente de emissão), valor_total, status, tipo (adicionar alias NFSE ao enum), justificativa_cancelamento.

Novas colunas — tabela `nota_fiscal_itens`

Coluna	Tipo	Descrição
`servico_codigo_lc116`	varchar(10)	Código LC 116
`servico_codigo_cnae`	varchar(10)	CNAE (snapshot)
`servico_aliquota_iss`	decimal(5,2)	Alíquota ISS (snapshot)
`servico_iss_retido`	tinyint(1) default 0	ISS retido (snapshot)
`servico_codigo_tributario_municipio`	varchar(20)	CTM (snapshot)
`servico_descricao_manual`	text	Descrição (serviço manual)
`is_servico_manual`	tinyint(1) default 0	Flag serviço avulso

Nota: Estes campos são snapshots dos dados fiscais do produto/serviço no momento da emissão, garantindo integridade histórica.

Novas colunas — tabela `produtos`

Coluna	Tipo	Descrição
`servico_codigo_lc116`	varchar(10)	Código LC 116
`servico_nbs`	varchar(20)	NBS
`servico_reter_pis`	tinyint(1) default 0	Reter PIS
`servico_reter_cofins`	tinyint(1) default 0	Reter COFINS
`servico_reter_ir`	tinyint(1) default 0	Reter IR
`servico_reter_csll`	tinyint(1) default 0	Reter CSLL
`servico_reter_inss`	tinyint(1) default 0	Reter INSS

Campos reutilizados (já existentes): codigo_cnae, servico_aliquota (alíquota ISS), iss_retido, codigo_tributario_municipio.

Novas colunas — tabela `clientes`

Coluna	Tipo	Descrição
`codigo_ibge_municipio`	varchar(7)	Código IBGE do município

Campos reutilizados (já existentes): inscricao_municipal.

Nova tabela — `servicos_lc116`

Coluna	Tipo
`id`	int PK auto_increment
`codigo`	varchar(10) unique
`descricao`	text

Nova tabela — `municipios_nfse`

Coluna	Tipo
`id`	int PK auto_increment
`codigo_municipio`	varchar(7) unique
`nome_municipio`	varchar(100)
`sigla_uf`	char(2)
`nfse_habilitada`	tinyint(1)
`requer_certificado_nfse`	tinyint(1)
`possui_ambiente_homologacao_nfse`	tinyint(1)
`possui_cancelamento_nfse`	tinyint(1)
`provedor_nfse`	varchar(50)
`codigo_cnae_obrigatorio_nfse`	tinyint(1) null
`item_lista_servico_obrigatorio_nfse`	tinyint(1) null
`codigo_tributario_municipio_obrigatorio_nfse`	tinyint(1) null
`status_nfse`	varchar(20)
`atualizado_em`	datetime

Colunas reservadas — Reforma Tributária (IBS/CBS)

Adicionar nas tabelas notas_fiscais e nota_fiscal_itens sem lógica:

Coluna	Tipo
`ibs_valor`	decimal(15,2) null
`cbs_valor`	decimal(15,2) null

Enums

class NfseNaturezaOperacaoEnum {
    const TRIBUTACAO_MUNICIPIO = 1;
    const TRIBUTACAO_FORA_MUNICIPIO = 2;
    const ISENCAO = 3;
    const IMUNE = 4;
    const EXIGIBILIDADE_SUSPENSA_JUDICIAL = 5;
    const EXIGIBILIDADE_SUSPENSA_ADMINISTRATIVA = 6;
}

class NfseRegimeTributacaoEnum {
    const MICROEMPRESA_MUNICIPAL = 1;
    const ESTIMATIVA = 2;
    const SOCIEDADE_PROFISSIONAIS = 3;
    const COOPERATIVA = 4;
    const MEI_SIMPLES_NACIONAL = 5;
    const ME_EPP_SIMPLES_NACIONAL = 6;
}

Adicionar alias NFSE = 'nfse' no NotaFiscalTipoEnum. Adicionar status SUBSTITUIDO = '7' no NotaFiscalStatusEnum.

Constantes de Permissão

const PERMISSAO_EMITIR_NFSE = 435;
const PERMISSAO_CANCELAR_NFSE = 436;
const PERMISSAO_GERENCIAR_CONF_NFSE = 437;

1.2 Configuração NFSe da Empresa

Escopo: Backend + Frontend para a tela de Dados Fiscais.

Wireframe — Seção NFSe em Dados Fiscais

DADOS FISCAIS DA EMPRESA

Empresa

Config Notas

Certificado

Backup Fiscal

NFe / NFCe (existente)

Campos existentes de NFe/NFCe permanecem inalterados...

NFS-e

Habilitar emissão de NFSe

ℹPré-requisito: Inscrição Municipal preenchida na aba Empresa.

Inscrição Municipal *

123456789

Máx 30 chars, numérico

Número Inicial do RPS *

Inteiro positivo, mín 1

Município (Código IBGE) *

🔍 Buscar município...

Autocomplete via cache de municípios Focus

Ambiente de Emissão

▾ Homologação

Homologação / Produção

Tipo de Ambiente

▾ Ambiente Próprio

Nacional / Próprio

Dados para Autenticação

ℹNem todas as prefeituras exigem login/senha. Em algumas, apenas um token é necessário (informar no campo Senha).

usuario_prefeitura

Opcional (máx 100)

Senha da Prefeitura

•••••••• 👁

Opcional (máx 100, mascarado)

Informações Adicionais Padrão

Texto padrão incluído em todas as NFSe...

Opcional

⚠Município sem homologação: "O município configurado não possui ambiente de homologação. Notas em modo teste serão transmitidas para produção."

Fluxo de preenchimento do Código IBGE

Validações

Ativar switch: Inscrição Municipal deve estar preenchida. Caso contrário, alerta com link.
Número RPS: inteiro positivo, mínimo 1, obrigatório.
Senha da prefeitura: encriptada no backend antes de persistir.
Tipo de Ambiente: ao salvar, dispara UpdateCompany na Focus com flags corretas conforme tabela de ambientes.

Backend

Endpoints em Ws.php: set/salvar_config_nfse, get/config_nfse
Validação em my_nfse_helper.php: validar_empresa_nfse()
Encriptação da senha via helper existente do CodeIgniter

Frontend

Nova seção no DadosFiscaisController_v.js
Novo mixin Mixin_nfse.js com métodos de API
Campos condicionais vinculados ao switch ativar_nfse

1.3 Catálogo LC 116 e Dados Fiscais do Serviço

Escopo: Seed da LC 116, autocomplete, aba fiscal no cadastro de serviço.

Wireframe — Aba Dados Fiscais do Serviço

CADASTRO DE PRODUTO/SERVIÇO

Geral

Preços

Dados Fiscais

ℹ Aba visível APENAS quando Tipo = Serviço E Módulo Fiscal ativo.

Código do Serviço (LC 116) *

🔍 Buscar código ou descrição...

Autocomplete do catálogo (~200 itens). Ex: 17.06 - Propaganda e publicidade

CNAE

6201501

Formato CNAE 2.0

Alíquota ISS (%)

5.00

0–100, 2 decimais

Código Tributário Municipal

123

Máx 20 chars

NBS

1.0101.10.00

Nomenclatura Brasileira de Serviços

Retenções

☐ Reter ISS ☐ Reter PIS ☐ Reter COFINS ☐ Reter IR ☐ Reter CSLL ☐ Reter INSS

Backend

Seed script: popular servicos_lc116 com ~200 itens da LC 116/2003
Endpoint: ws/get/ac_servicos_lc116?q= — busca por código ou texto
Método cadastro_completo_nfse() no model de produto: valida LC 116 + alíquota ISS preenchidos
Campos opcionais no cadastro — obrigatoriedade validada apenas na emissão

Frontend

Nova aba condicional no formulário de produto (visível quando is_servico = '1' e módulo fiscal ativo)
Autocomplete para LC 116 consumindo endpoint do catálogo
Indicador visual de cadastro fiscal incompleto (badge "Pendente")

1.4 Dados Fiscais do Cliente (Tomador)

Escopo: Campo Código IBGE no cadastro de cliente + auto-preenchimento via CEP.

Wireframe — Campo IBGE no Cadastro de Cliente

CADASTRO DE CLIENTE — Endereço

CEP

60000-000

Logradouro

Rua das Flores

Bairro

Centro

Cidade

Fortaleza

Número

100

Código IBGE do Município *

NOVO CAMPO

2304400 (auto-preenchido via CEP)

Obrigatório para emissão de NFSe

Backend

Método cadastro_completo_nfse() no model de cliente: valida CPF/CNPJ + endereço + código IBGE
Lógica: ao receber CEP, buscar código IBGE via tabela municipios_nfse ou fonte externa
Referência: municipios-brasileiros JSON

Frontend

Novo campo no bloco de endereço do ClienteController_v.js
Auto-preenchimento do IBGE ao completar CEP
Sinalização visual quando cadastro incompleto para NFSe

1.5 Permissões de Usuário

Escopo: 3 novas permissões no sistema existente.

ID	Constante	Descrição
435	`PERMISSAO_EMITIR_NFSE`	Emitir NFSe Manual
436	`PERMISSAO_CANCELAR_NFSE`	Cancelar NFSe
437	`PERMISSAO_GERENCIAR_CONF_NFSE`	Gerenciar Configuração NFSe

Checkboxes na tela de permissões, visíveis apenas quando NFSe habilitada no tenant.
Permissão 435 controla acesso ao módulo inteiro (menu, listagem, emissão).
Validação no backend via $this->session->permissoes.

1.6 Cache de Municípios Suportados

Escopo: Integração com GET /v2/municipios da Focus + cache local.

Backend

Nova classe ListMunicipios.php em third_party/NotaFiscal/ seguindo padrão factory
Contrato ListMunicipiosContract.php
Novo método listMunicipios() na Notafiscal.php
Sincronização: cache com validade de 30 dias na tabela municipios_nfse
Endpoint: ws/get/ac_municipios_nfse para autocomplete

Dados do endpoint de municípios da Focus

{
  "codigo_municipio": "2304400",
  "nome_municipio": "Fortaleza",
  "sigla_uf": "CE",
  "nfse_habilitada": true,
  "requer_certificado_nfse": true,
  "possui_ambiente_homologacao_nfse": true,
  "possui_cancelamento_nfse": true,
  "provedor_nfse": "FortalezaRt",
  "codigo_cnae_obrigatorio_nfse": true,
  "item_lista_servico_obrigatorio_nfse": true,
  "codigo_tributario_municipio_obrigatorio_nfse": true,
  "status_nfse": "ativo"
}

Entrega da Fase 1

Migrações executadas e models atualizados
Tela de Dados Fiscais com seção NFSe funcional
Autocomplete de município com cache Focus
Catálogo LC 116 populado e endpoint de busca funcionando
Aba Dados Fiscais no cadastro de serviço
Campo Código IBGE no cadastro de cliente
Permissões 435/436/437 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 via webhook. XML armazenado localmente.

2.1 Integração com API Focus NFSe

Escopo: Classes de integração — backend puro, sem frontend.

Novos arquivos em `third_party/NotaFiscal/`

Arquivo	Contrato	Método HTTP	Endpoint Focus
`CreateNfse.php`	`CreateNfseContract.php`	POST	`/v2/nfse?ref={REF}`
`CreateNfsen.php`	`CreateNfsenContract.php`	POST	`/v2/nfsen?ref={REF}`
`DetailNfse.php`	`DetailNfseContract.php`	GET	`/v2/nfse/{REF}`
`CancelNfse.php`	`CancelNfseContract.php`	DELETE	`/v2/nfse/{REF}`
`SubstituteNfse.php`	`SubstituteNfseContract.php`	POST	`/v2/nfse/{REF}/substitucao`
`DownloadNfsePdf.php`	—	GET	URL retornada pela Focus
`DownloadNfseXml.php`	—	GET	URL retornada pela Focus
`ListMunicipios.php`	`ListMunicipiosContract.php`	GET	`/v2/municipios`

Factory — novos métodos em `Notafiscal.php`

// Novos métodos — usam is_nfse_prod em vez de is_nf_prod
public function createNfse($apiToken) { ... }
public function createNfsen($apiToken) { ... }
public function detailNfse($apiToken) { ... }
public function cancelNfse($apiToken) { ... }
public function substituteNfse($apiToken) { ... }
public function listMunicipios() { ... }

Importante: o ambiente NFSe (is_nfse_prod) é independente do ambiente NFe (is_nf_prod).

Resolução de endpoint na emissão

O endpoint utilizado é determinado pelo campo nfse_ambiente da empresa:

nfse_ambiente = 'nacional' → createNfsen() → POST /v2/nfsen
nfse_ambiente = 'proprio' → createNfse() → POST /v2/nfse

Exceção MEI: se regime tributário = 4 (MEI), sempre usa createNfsen() independente da configuração.

2.2 Webhook de Autorização NFSe

Escopo: Receber callback da Focus e atualizar status + armazenar XML.

Fluxo do Webhook

Backend

Novo helper: my_webhook_nfse_helper.php seguindo padrão de my_webhook_nfe_helper.php
Novo case em Ws.php: case "webhook_nfse":
Obrigatório: ao receber autorização, fazer GET no XML e armazenar na coluna xml_nfse (Focus só gera backups mensais)
Armazenar: nfse_url, nfse_codigo_verificacao, nfse_numero
Idempotência: verificar se já processou o webhook (status já AUTORIZADO → ignorar)

2.3 Formulário de Emissão — Dados Gerais e Tomador

Escopo: Página de NFSe Manual + etapas 1 e 2 do formulário.

Wireframe — Listagem de NFSe (página principal)

NFSe Manual

Status

▾ Todos

Tomador

🔍 Nome, CPF ou CNPJ

01/04/2026

Até

30/04/2026

Nº	RPS	Data	Tomador	Valor	Status
42	15	01/04/2026	Empresa ABC	R$ 1.500	Autorizada
—	16	01/04/2026	João Silva	R$ 200	Processando
41	14	31/03/2026	Maria LTDA	R$ 1.000	Erro
40	13	30/03/2026	Tech Corp	R$ 750	Cancelada

← 1 2 3 ... → · 20 itens por página

Nova NFSe ✕

Dados Gerais

Tomador

Serviço

Revisão

Número RPS

Automático, somente leitura

Data de Competência *

📅 01/04/2026

Não pode ser futura

Natureza da Operação *

▾ 1 - Tributação no município

1=Trib. município, 2=Fora, 3=Isenção, 4=Imune, 5=Susp. judicial, 6=Susp. administrativa

Regime Especial de Tributação

▾ 5 - MEI - Simples Nacional

1=Microempresa, 2=Estimativa, 3=Soc. prof., 4=Cooperativa, 5=MEI-SN, 6=ME EPP-SN

Discriminação dos Serviços

Descrição geral dos serviços prestados...

Máx 2000 caracteres. Opcional.

Nova NFSe ✕

Dados Gerais

Tomador

Serviço

Revisão

Buscar tomador *

🔍 Nome, CPF ou CNPJ...

Autocomplete no cadastro de clientes

✓ Tomador selecionado

Nome: Empresa ABC LTDA

CNPJ: 12.345.678/0001-90

Município: Fortaleza - CE (IBGE: 2304400)

Endereço: Rua X, 100 - Centro

⚠ Cadastro incompleto para NFSe.

Campos faltantes: Código IBGE do Município

Corrigir cadastro ↗ (abre nova aba) ·

Backend

Controller: Nfse_manual.php + rota nfse-manual
Helper: my_nfse_helper.php com validar_empresa_nfse(), validar_tomador_nfse()
Endpoint: ws/get/dados_iniciais_nfse (empresa, enums, próximo RPS)

Frontend

Nova página: application/views/paginas/nfse-manual.php
Controller Vue: NfseManualController.js
Modal Controller: ModalEmitirNfseController.js
Mixin: Mixin_nfse.js
Item no menu: sidebar abaixo de "NF-e Manual", visível com permissão 435

2.4 Formulário de Emissão — Serviço e Retenções

Escopo: Etapa 3 do formulário de emissão.

Nova NFSe ✕

Dados Gerais

Tomador

Serviço

Revisão

Buscar serviço do catálogo

🔍 Nome ou código do serviço...

Apenas itens com Tipo = Serviço

Serviço selecionado

Serviço	LC 116	Qtd	V. Unit.	Total
Consultoria TI ISS: 5% · ISS Retido: Não	17.06	10h	R$ 150	R$ 1.500	✏ 🗑

Total: R$ 1.500,00

Regras de negócio — Serviço

Serviço único: cada NFSe permite apenas um único serviço
Serviço manual: dados efêmeros (não salva no catálogo), mas LC 116 e alíquota são obrigatórios
Pendência fiscal: serviço do catálogo sem LC 116 ou alíquota → badge de pendência + link para edição

Backend

validar_servico_nfse(): valida dados fiscais completos do serviço (LC 116 e alíquota ISS obrigatórios)
Validação: codigo_servico_lc116 e servico_aliquota_iss obrigatórios

2.5 Transmissão e Acompanhamento de Status

Escopo: Etapa 4 (revisão), envio à Focus, polling de status.

Nova NFSe ✕

Dados Gerais

Tomador

Serviço

Revisão

Resumo

Tomador: Empresa ABC LTDA (12.345.678/0001-90)

RPS: 16 · Competência: 04/2026 · Nat. Op.: Tributação no município

Serviço

Serviço	LC 116	Detalhe	Total
Consultoria TI	17.06	10h × R$150	R$ 1.500,00

Subtotal: R$ 1.500,00

Retenções (editáveis)

ISS (R$)

75,00

PIS (R$)

0,00

COFINS (R$)

0,00

IR (R$)

0,00

CSLL (R$)

0,00

INSS (R$)

0,00

ℹ Esta nota será transmitida pelo Ambiente Nacional NFSe, conforme obrigatoriedade para emitentes MEI.

VALOR TOTAL

R$ 1.425,00

Serviço − Retenções = Líquido

Fluxo completo de emissão

Backend — Funções principais

Função	Responsabilidade
`set_emitir_nfse()`	Orquestra validação → gravação → transmissão
`montar_payload_nfse()`	JSON conforme formato Focus
`get_consultar_nfse()`	Consulta manual de status (fallback ao webhook)

Payload da Focus — Formato (endpoint /v2/nfse)

{
  "data_emissao": "2026-04-01T10:00:00-03:00",
  "prestador": {
    "cnpj": "07504505000132",
    "inscricao_municipal": "12345",
    "codigo_municipio": "2304400"
  },
  "tomador": {
    "cnpj": "12345678000190",
    "razao_social": "Empresa ABC LTDA",
    "endereco": { "..." : "..." },
    "codigo_municipio": "3550308"
  },
  "servico": {
    "aliquota": 5.0,
    "discriminacao": "Consultoria em TI...",
    "iss_retido": false,
    "item_lista_servico": "1706",
    "codigo_cnae": "6201501",
    "codigo_tributario_municipio": "123",
    "valor_servicos": 1500.00
  },
  "natureza_operacao": "1",
  "regime_especial_tributacao": "5",
  "valor_pis": 0,
  "valor_cofins": 0,
  "valor_ir": 0,
  "valor_csll": 0,
  "valor_inss": 0
}

Cota mensal

NFSe consome a mesma franquia do pacote mensal (mesma contagem de NFe/NFCe). Verificar saldo antes de emitir.

Entrega da Fase 2

Classes Focus NFSe criadas e funcionais (Create, Detail, Cancel, Substitute)
Webhook NFSe processando autorizações e armazenando XML
Formulário completo de emissão (4 etapas)
Transmissão assíncrona com retorno de status
Polling + consulta manual 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 (seção 2.3). 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

3.2 Visualização Detalhada e Downloads

Detalhes da NFSe #42 ✕

Status: Autorizada

Nº NFSe: 42 · RPS: 15 · Cód. Verificação: ABC123
Data Emissão: 01/04/2026 · Competência: 04/2026

Prestador

SMB Store LTDA · CNPJ: 07.504.505/0001-32 · IM: 12345

Tomador

Empresa ABC LTDA · CNPJ: 12.345.678/0001-90 · Fortaleza - CE (IBGE: 2304400)

Serviço

Serviço	LC 116	CNAE	ISS	Detalhe	Total
Consultoria TI	17.06	6201501	5%	10h × R$150	R$ 1.500

Retenções

ISS: R$75,00 · PIS: R$0 · COFINS: R$0 · IR: R$0 · CSLL: R$0 · INSS: R$0

Valor Total: R$ 1.425,00

Notas Vinculadas

NFSe #41 · 31/03/2026 · Substituído Ver ↗

🔗 Ver na prefeitura

Matriz de ações por status

Ação	Em processamento	Autorizado	Erro	Cancelado	Substituído
Baixar XML	—	✓	—	✓	✓
Baixar PDF	—	✓	—	—	—
Cancelar	—	✓	—	—	—
Substituir	—	—	✓	✓	—

Backend — Downloads

XML: prioriza coluna xml_nfse (local); fallback via DetailNfse.php + GET
PDF: chama Focus API; se município não suporta PDF, redireciona para nfse_url
Cases em Ws.php: nfse_pdf, nfse_xml

3.3 Cancelamento

Cancelar NFSe #42 ✕

Tomador: Empresa ABC LTDA

Valor: R$ 1.425,00

Data: 01/04/2026

⚠ Esta ação é irreversível.

Justificativa de cancelamento *

Informe o motivo do cancelamento...

Máx 255 caracteres

Município sem suporte a cancelamento: botão desabilitado com tooltip "Indisponível para este município. Entre em contato com a prefeitura."
Backend: CancelNfse.php → DELETE /v2/nfse/REF com justificativa.
Case Ws.php: cancelar_nfse

3.4 Substituição

Disponível para notas com status Erro ou Cancelado.
Abre formulário de nova NFSe pré-preenchido com dados da nota original.
Banner: "Você está substituindo a nota nº X."
Após transmissão: nota original → status SUBSTITUÍDO; nova nota → PROCESSANDO.
Backend: SubstituteNfse.php → POST /v2/nfse/REF/substitucao
Vínculo: nfse_substituida_id na nova nota.
Case Ws.php: substituir_nfse

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

DASHBOARD FISCAL

NFCe

142

NFe Normal

NFe Dev.

NFe Ajuste

NFSe

NOVO

Notas no período

186

(inclui NFSe)

Cota mensal: 186/500 (37%)

NFe + NFCe + NFSe

Tipo

▾ Todas (inclui NFSe)

Card "NFSe" visível apenas com switch ativo.
NFSe autorizadas contam no total de "Notas emitidas no período".
Cota mensal inclui NFSe na contagem total.

4.2 Filtros e Navegação

Nova opção "NFSe" no seletor de tipo de documento no dashboard.
Link rápido "Emitir NFSe" na barra de ações.
Menu lateral: item "NFSe Manual" no grupo Módulo Fiscal.

4.3 Exportação de XMLs por Período

Botão "Exportar XMLs" com seletor de período.
Consulta coluna xml_nfse local, gera ZIP, serve para download.
Não depende da API Focus.

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 SN, 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
Webhook autorização	Status atualizado + XML armazenado
Webhook erro	Status erro + mensagem da Focus
Consulta manual status	Fallback ao webhook
Cancelamento	Justificativa + Focus API
Substituição	Pré-preenchimento + vínculo
Download PDF	Município com e sem suporte
Download XML	Base local e via API
Cota	NFSe decrementa saldo do pacote
Permissões	Sem permissão → menu oculto + rota bloqueada
Multi-tenant	NFSe empresa A ≠ empresa B
Tomador sem IBGE	Bloqueio + orientação
Sem Inscrição Municipal	Bloqueio ao ativar switch
Município não suportado	Mensagem clara

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 serviço
Webhooks NFe/NFCe inalterados

5.3 Testes de Borda

Timeout da Focus → tratamento gracioso
NFSe com valor zero → bloqueio
Emissões simultâneas → sem duplicidade no RPS (lock/transação atômica)
Webhook duplicado → idempotência

5.4 Rollout Gradual

Fase	Escopo	Critério de entrada
Alpha	3–5 clientes em municípios estáveis (SP, CWB)	Testes em homolog aprovados
Beta	Clientes em cidades homologadas como estáveis	Alpha sem bugs críticos
GA (Disponibilidade Geral)	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

Dependências e Paralelismo

Atividade	Depende de	Pode rodar em paralelo com
1.1 Estrutura de dados	—	—
1.2 Config empresa	1.1	1.3, 1.4, 1.5, 1.6
1.3 Catálogo LC 116	1.1	1.2, 1.4, 1.5, 1.6
1.4 Dados cliente	1.1	1.2, 1.3, 1.5, 1.6
1.5 Permissões	1.1	1.2, 1.3, 1.4, 1.6
1.6 Cache municípios	1.1	1.2, 1.3, 1.4, 1.5
2.1 Classes Focus	1.1	2.2
2.2 Webhook	1.1	2.1
2.3 Form (dados/tomador)	1.2–1.6	—
2.4 Form (serviço)	2.3	—
2.5 Transmissão	2.1, 2.2, 2.4	—
3.1–3.4	2.5	3.3 ∥ 3.4
4.1–4.3	3.1	4.1 ∥ 4.2 ∥ 4.3
5.x	4.x	—

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

NFS-e Avulsa — Plano de Implementação

Visão Geral

Arquitetura de Referência do Codebase

Seleção de Ambiente pelo Usuário

Fase 1 — Configuração e Cadastros

1.1 Estrutura de Dados Base

Novas colunas — tabela empresas

Novas colunas — tabela notas_fiscais

Novas colunas — tabela nota_fiscal_itens

Novas colunas — tabela produtos

Novas colunas — tabela clientes

Nova tabela — servicos_lc116

Nova tabela — municipios_nfse

Colunas reservadas — Reforma Tributária (IBS/CBS)

Enums

Constantes de Permissão

1.2 Configuração NFSe da Empresa

Wireframe — Seção NFSe em Dados Fiscais

Fluxo de preenchimento do Código IBGE

Validações

Backend

Frontend

1.3 Catálogo LC 116 e Dados Fiscais do Serviço

Wireframe — Aba Dados Fiscais do Serviço

Backend

Frontend

1.4 Dados Fiscais do Cliente (Tomador)

Wireframe — Campo IBGE no Cadastro de Cliente

Backend

Frontend

1.5 Permissões de Usuário

1.6 Cache de Municípios Suportados

Backend

Dados do endpoint de municípios da Focus

Entrega da Fase 1

Fase 2 — Emissão de NFSe Manual

2.1 Integração com API Focus NFSe

Novos arquivos em third_party/NotaFiscal/

Factory — novos métodos em Notafiscal.php

Resolução de endpoint na emissão

2.2 Webhook de Autorização NFSe

Fluxo do Webhook

Backend

2.3 Formulário de Emissão — Dados Gerais e Tomador

Wireframe — Listagem de NFSe (página principal)

Wireframe — Modal de Emissão: Etapa 1 (Dados Gerais)

Wireframe — Modal de Emissão: Etapa 2 (Tomador)

Backend

Frontend

2.4 Formulário de Emissão — Serviço e Retenções

Wireframe — Modal de Emissão: Etapa 3 (Serviço)

Regras de negócio — Serviço

Backend

2.5 Transmissão e Acompanhamento de Status

Wireframe — Modal de Emissão: Etapa 4 (Revisão)

Fluxo completo de emissão

Backend — Funções principais

Payload da Focus — Formato (endpoint /v2/nfse)

Cota mensal

Entrega da Fase 2

Fase 3 — Gestão de NFSe

3.1 Listagem e Filtros

3.2 Visualização Detalhada e Downloads

Wireframe — Modal de Detalhes da NFSe

Matriz de ações por status

Backend — Downloads

3.3 Cancelamento

Wireframe — Modal de Cancelamento

3.4 Substituição

Entrega da Fase 3

Fase 4 — Dashboard Fiscal Unificado

4.1 Métricas e Contadores NFSe

Wireframe — Cards no Dashboard

4.2 Filtros e Navegação

4.3 Exportação de XMLs por Período

Entrega da Fase 4

Fase 5 — Testes, Validação e Rollout

5.1 Testes Funcionais em Homologação

5.2 Testes de Regressão

5.3 Testes de Borda

Novas colunas — tabela `empresas`

Novas colunas — tabela `notas_fiscais`

Novas colunas — tabela `nota_fiscal_itens`

Novas colunas — tabela `produtos`

Novas colunas — tabela `clientes`

Nova tabela — `servicos_lc116`

Nova tabela — `municipios_nfse`

Novos arquivos em `third_party/NotaFiscal/`

Factory — novos métodos em `Notafiscal.php`