Download the PHP package danielbbarcelos/laravel-notas-fiscais without Composer

laravel-notas-fiscais

Repositório: github.com/danielbbarcelos/laravel-notas-fiscais

Emissão de notas fiscais de serviço (NFS-e) sob um contrato único, com drivers por provedor. Laravel 11+.

Hoje implementa o provedor IPM Atende.Net (NFS-e municipal) em dois padrões. A arquitetura de contracts é genérica para acomodar novos provedores — e, futuramente, outros tipos de documento (NF-e, NFC-e).

Qual driver usar (IPM)

O Atende.Net expõe a NFS-e em dois padrões diferentes, por município:

Ambos autenticam por login/senha (Basic) — sem certificado. Para descobrir qual o município usa, teste o endpoint: se o REST responder 503 "Serviço não disponível" e o SOAP responder, use ipm-abrasf. Note que o ABRASF identifica o município pelo código IBGE (7 dígitos), enquanto o REST usa o código TOM.

Notas práticas do ABRASF (validado em produção — Pouso Alegre/MG)

Emissão e cancelamento reais já validados ponta a ponta. Pontos que costumam barrar:

• Autenticação: a senha é a específica do WebService (pode diferir da senha do portal). 401 "Acesso Negado" = credencial/login rejeitado.
• Competência (NotaServico::competencia): use a data atual; competência retroativa é recusada (L1029) salvo autorização do município.
• ItemServico::codigoItemListaServico: deve estar no formato pontuado (99.99, 99.99.99 ou 99.99.99.999) e vinculado ao cadastro econômico do prestador. Ex.: o código 10101 do portal vira 01.01.01 (zero à esquerda). Em formato errado → L1099; código não vinculado → L1003.
• CNAE (ItemServico::codigoCnae) e item devem ser coerentes entre si.
• Modo teste: o <EnvioTeste> exige a operação de lote síncrono, que em alguns municípios (Pouso Alegre) tem bug no servidor. Para validar, prefira **emitir real
  • cancelar** (a operação GerarNfse, usada na emissão padrão, é a estável).
• Link do PDF: o GerarNfseResposta desses municípios não retorna o link. Configure link_template (config notas-fiscais.drivers.ipm-abrasf.link_template, env IPM_ABRASF_LINK_TEMPLATE) com a URL de consulta/autenticidade do Atende.Net e o placeholder {codigo} (e opcionalmente {numero}); o driver preenche NotaEmitida::link automaticamente. Para achar a URL e o {ID} do serviço, abra uma NFS-e na consulta de autenticidade do portal e copie a URL, trocando o código por {codigo}. Ex.: https://{cidade}.atende.net/?pg=autoatendimento#!/tipo/servico/valor/213/padrao/1/load/1/identificador/{codigo} (valor/213 é o serviço de autenticidade de NFS-e, global no Atende.Net). Confirmado para Pouso Alegre/MG (abre a nota com botões XML IPM / XML Abrasf / Imprimir): https://pousoalegre.atende.net/autoatendimento/servicos/consulta-de-autenticidade-de-nota-fiscal-eletronica-nfse/detalhar/1/identificador/{codigo}

Instalação

Integrando numa API? Veja o Guia de integração Laravel — passo a passo multi-tenant/SaaS com endpoints REST, service, persistência e PDF.

Configuração

config/notas-fiscais.php (ou via .env):

A URL do Web Service varia por município. Solicite acesso no Portal do Cidadão da prefeitura ("Emissão de NFS-e por WebService").

Proxy de saída (servidor fora do Brasil)

Alguns municípios só respondem a requisições vindas de um IP brasileiro. Se a aplicação roda fora do país, aponte o driver para um proxy no Brasil:

Sem a variável, nada muda: a requisição sai direto do servidor. O valor é repassado ao Guzzle, então vale qualquer esquema que o cURL suporte (http://, https://, socks5://).

Dois avisos antes de montar essa infra:

• Confirme que o bloqueio é geográfico. Um 401 "Acesso Negado" é problema de credencial e nenhum proxy resolve — veja a seção ABRASF acima.
• O proxy vira ponto único de falha no caminho da emissão. Se ele cair, as notas param e cada requisição fica pendurada até o timeout do driver. Hospedar a aplicação no Brasil elimina o problema em vez de contorná-lo.

Uso

Cancelamento e consulta:

Erros do provedor lançam NotaFiscalApiException (com ->codigo e ->corpo); documento não suportado lança OperacaoNaoSuportadaException. Ambas estendem NotaFiscalException.

Exportação de arquivos (XML e TXT)

Reproduz o menu Download do Atende.Net (XML IPM / XML Abrasf / TXT). Como o Web Service não devolve esses arquivos prontos, o package os gera localmente a partir da nota enviada (NotaServico) e do retorno da emissão (NotaEmitida). Os gateways que suportam isso implementam o contrato ExportaArquivos:

• xmlNota() — no ABRASF, se $emitida trouxer o XML oficial assinado pela prefeitura (no bruto['xml_response'] do retorno de emissão/consulta), ele é devolvido; senão monta o <Rps>/declaração a partir de $nota. No REST proprietário sempre gera o <nfse> do IPM (esse padrão não tem XML assinado).
• txtExportacao() — gera o layout posicional do IPM (Nota Técnica 65/2020: registros 10 documento, 20 por item, 30 tomador). Formato único do IPM, idêntico nos dois drivers.

O PDF e a Impressão do menu correspondem ao NotaEmitida::link (ver abaixo). Já E-mail, Anexos e Consulta Nota Nacional são recursos do portal sem endpoint no Web Service — fora do escopo do package.

Comprovante da NFS-e em PDF

O PDF oficial do município (link /ged/r/{hash} do Atende.Net) é gerado por um endpoint protegido por captcha (Cloudflare Turnstile) na via pública — então não é automatizável. Para anexar em e-mail / download, o pacote gera um comprovante próprio em PDF a partir dos dados canônicos, sem captcha. O PDF deixa explícito que não é o documento fiscal oficial e aponta, no topo, o link de autenticidade onde a NFS-e oficial pode ser consultada e impressa (e que reflete o status atual):

Se a emissão usou o prestador da config (NotaServico sem prestador), passe-o no 3º argumento. O 4º argumento (Emitente) coloca logo e nome da empresa no cabeçalho — ambos opcionais (sem eles, o comprovante usa placeholders):

Requer dompdf (dependência opcional, PHP puro, sem binário):

Multi-tenant / SaaS (credenciais em runtime)

O .env é só o default opcional (single-tenant). Não guarde credenciais de clientes no .env/config num SaaS: a aplicação armazena com segurança (ex.: coluna criptografada por tenant) e injeta em runtime.

Instâncias resolvidas em runtime não são cacheadas pelo nome (sem vazamento entre tenants), e a sessão (PHPSESSID) é isolada por credencial. Para uso fixo single-tenant, NotaFiscal::nfse() segue lendo a config nomeada normalmente.

Playground (validação visual)

Para validar campos e retornos numa tela, ligue a demo (mantenha desligada em produção):

Isso registra a rota GET/POST /notas-fiscais/demo com um formulário que monta o NotaServico, mostra o XML gerado e o NotaEmitida parseado (ou o erro). Um toggle alterna entre:

• Faked — devolve os XMLs de exemplo dos docs (sucesso/erro/cancelada); valida o fluxo inteiro sem credenciais nem prefeitura;
• IPM real — usa as credenciais do .env (com <nfse_teste> por padrão).

Dentro do próprio repositório do pacote, sirva via Testbench:

A demo vive em routes/demo.php + resources/views/demo.blade.php e só é carregada quando notas-fiscais.demo é true.

Novos provedores

Implemente Contracts\Provedor + Contracts\NfseGateway e registre no boot:

Testes

Contribuindo

Issues e pull requests são bem-vindos em github.com/danielbbarcelos/laravel-notas-fiscais.

Licença

Distribuído sob a licença MIT. Veja LICENSE.