Click NFS-e

Emissão de NFS-e no padrão nacional para Laravel.
DPS assinada em XMLDSIG, envio com mTLS à Sefin Nacional, cancelamento, análise fiscal e dados do DANFSe.

Desde 1º/09/2026 a Resolução CGSN nº 189/2026 obriga ME e EPP do Simples Nacional a emitir NFS-e pelo Emissor Nacional. Integrar-se a ele é menos sobre HTTP e mais sobre detalhe fiscal: a DPS precisa sair na ordem exata do xs:sequence, assinada com parâmetros que não se negociam, com campos que são obrigatórios num regime tributário e proibidos em outro — e cada erro só aparece depois do envio, com o número da DPS já queimado.

Esta lib empacota esse conhecimento. O núcleo veio de um sistema em produção e foi extraído com as regras que ele aprendeu na prática, cada uma comentada com o código de rejeição que a motivou.

[!WARNING] Pré-lançamento. O núcleo fiscal é rodado em produção, mas a API de integração ainda está sendo definida e pode mudar antes do 1.0. Emissão de documento fiscal tem efeito legal e quase sempre irreversível: homologue em produção restrita e valide com a sua contabilidade antes de habilitar.

Sumário

• Recursos
• Como funciona
• Requisitos
• Instalação
• Configuração
• Uso
  • 1. Implemente os contratos
  • 2. Emita
  • 3. Acompanhe
  • Cancelamento
  • Nota INAPTA
  • DANFSe
• Comandos
• Tratamento de erros
• Rejeições cobertas
• Referência da API
• Esquemas XSD
• Antes de ir para produção
• Testes
• Roadmap
• Contribuindo
• Segurança
• Licença

Recursos

Como funciona

O ponto central: o número da DPS é reservado e a nota é persistida antes de qualquer chamada HTTP. A regra E0014 proíbe reutilizar um número, mas a legislação admite lacunas na sequência — então, se o envio falhar, a retentativa reaproveita o mesmo número em vez de queimar outro. Gerar número novo a cada tentativa arriscaria emitir duas notas para a mesma cobrança quando a Sefin processou o documento e apenas a resposta se perdeu.

Requisitos

[!NOTE] Laravel 11 ficou fora do range: todas as versões 11.x estão sob um aviso de segurança sem correção publicada, e o próprio Composer se recusa a instalá-las por padrão.

Instalação

Coloque o .pfx fora do diretório público e fora do versionamento:

Confira a instalação antes de qualquer emissão:

Configuração

O mínimo para começar:

Uso

1. Implemente os contratos

A lib não conhece as suas tabelas. Implemente Faturavel no model que representa o que gera a nota — um pagamento, uma cobrança, uma fatura — e a nota guarda uma relação polimórfica com ele:

E Tomador em quem recebe o serviço — não precisa ser um model:

Tudo o que esses métodos devolvem é congelado na nota no momento da preparação: alterar o model depois não altera um documento já emitido, que é o comportamento correto para efeito fiscal.

2. Emita

Na fila, com retry e backoff próprios (fila nfse, 5 tentativas, backoff de 1 min a 3 h, ShouldBeUnique por faturável):

Ou de forma síncrona, quando você quer o desfecho na hora:

prepararNota() é idempotente por design: chamadas repetidas para o mesmo faturável devolvem sempre a mesma nota, o que protege contra webhook reentregue.

3. Acompanhe

Cancelamento

Códigos aceitos pelo schema: MOTIVO_ERRO_EMISSAO (1), MOTIVO_SERVICO_NAO_PRESTADO (2), MOTIVO_OUTROS (9). A justificativa exige 15 caracteres — textos curtos são complementados em vez de derrubar o pedido.

O serviço tenta o evento 101101 e, se o prazo municipal já expirou, escala para solicitação de análise fiscal (101103), agendando o acompanhamento do deferimento (105104) ou indeferimento (105105).

[!IMPORTANT] O escalonamento só ocorre para os códigos de rejeição listados em NFSE_CODIGOS_PRAZO_EXPIRADO. A Sefin não publica um código único para esse cenário, e abrir pedido de análise indevido cria trabalho para a fiscalização municipal — por isso o padrão é não escalar.

Quando o estorno ocorre antes de a nota ter sido autorizada, use cancelarLocalmente(): não há documento fiscal a cancelar, mas o número reservado continua queimado.

Nota INAPTA

Quando o faturável não pode gerar nota — tomador sem CPF/CNPJ válido, código de serviço ausente — a lib registra o caso como INAPTA com o motivo, em vez de falhar em silêncio. A nota não reserva número nem gera DPS: é um marcador visível para correção.

A reavaliação reusa o mesmo registro, preservando o histórico e o id já visível ao operador.

DANFSe

DanfseService::dadosParaView() devolve o XML autorizado já achatado e formatado — prestador, tomador, valores, chave, URL para o QR Code. A renderização é sua:

A lib não depende de motor de PDF nem de gerador de QR Code — essa escolha é do seu projeto. Em examples/laravel-app/ há uma view Blade completa e um controller que a imprime com dompdf.

O documento com valor legal é o XML autorizado. O PDF é só uma representação: gere sob demanda, não armazene.

Comandos

Tratamento de erros

Duas exceções, e a distinção entre elas é o que decide se vale reenviar:

NfseRejeicaoException estende NfseException, então capturar só a segunda pega as duas — a ordem dos catch importa.

Rejeições cobertas

O que a lib faz para não esbarrar em cada uma. É a parte que custa caro descobrir sozinho:

Referência da API

Esquemas XSD

resources/schemas/nfse/ traz o pacote oficial publicado pela Secretaria-Executiva do CGNFS-e, versões 1.00 e 1.01, sem modificação — inclusive nas quebras de linha. O caminho fica exposto por ClickNfseServiceProvider::caminhoSchemas().

Veja o README daquele diretório para as particularidades, inclusive um defeito conhecido no TSSerieDPS da v1.01 que produz falso positivo na validação local.

Antes de ir para produção

• [ ] php artisan nfse:verificar-certificado passa, e o titular confere com NFSE_EMITENTE_CNPJ
• [ ] O município aparece como aderente ao Emissor Nacional (ConvenioMunicipalService::situacao())
• [ ] Emissão validada em NFSE_AMBIENTE=2 (produção restrita) de ponta a ponta
• [ ] Cancelamento testado — inclusive o caso do prazo expirado
• [ ] NFSE_P_TOT_TRIB_SN confirmado com a contabilidade (alíquota efetiva vigente)
• [ ] NFSE_EMITENTE_ENVIAR_IM só ligado depois que o município registrar o contribuinte no CNC
• [ ] NFSE_CODIGOS_PRAZO_EXPIRADO preenchido com o que você observou em produção restrita
• [ ] Worker da fila nfse rodando, e os três comandos agendados
• [ ] Alerta de expiração do certificado chegando a alguém que age

Testes

A suíte roda sem rede e sem certificado real: a DPS e os eventos são validados contra o pacote oficial de XSD que acompanha o repositório, e a assinatura XMLDSIG é exercitada com um par autoassinado gerado na hora do teste. Nenhum material de certificado é versionado.

O CI cobre PHP 8.2, 8.3 e 8.4 contra Laravel 12 e 13.

Roadmap

• [ ] Validação local contra o XSD antes do envio, ligável por configuração
• [ ] Confirmar o formato da URL do QR Code do DANFSe conforme a NT 008/2026
• [ ] Núcleo em PHP puro, sem Laravel, com o pacote atual como adaptador
• [ ] Eventos de domínio (NotaAutorizada, NotaRejeitada, NotaCancelada)

Contribuindo

Issues e pull requests são bem-vindos. Antes de abrir um PR:

1. composer test passando;
2. composer format aplicado;
3. mudança de comportamento acompanhada de teste.

Este é um pacote fiscal: alterações no caminho de emissão, assinatura ou cancelamento precisam citar a regra ou o código de rejeição que as justifica. "Achei mais limpo" não basta quando o custo de errar é um documento com efeito legal.

Segurança

• Nunca versione o .pfx — o .gitignore já cobre *.pfx, *.p12, *.pem e *.key.
• Os PEMs derivados para o mTLS são gravados com permissão 0600 num diretório 0700.
• Encontrou uma vulnerabilidade? Escreva para [email protected] em vez de abrir issue pública.

Licença

MIT — veja LICENSE.

O software é fornecido sem garantias. Emissão de documento fiscal produz efeito legal e, em boa parte dos casos, irreversível.

Feito por Manuel Bahamonde