Semana passada recebi, no mesmo dia, duas mensagens de desenvolvedores diferentes no grupo do NFePHP relatando o mesmo problema: a lib que eles usam para emitir CT-e e outros documentos fiscais já tem suporte a IBS/CBS no código, mas não tem uma versão publicada no Composer com essa mudança. A saída que os dois encontraram foi apontar o composer.json para dev-master.
Se você trabalha com emissão de nota fiscal em PHP, essa história provavelmente já bateu na sua porta, ou vai bater nas próximas semanas.
O que mudou de fato no leiaute
A Lei Complementar 214/2025 criou o IBS (Imposto sobre Bens e Serviços) e a CBS (Contribuição sobre Bens e Serviços), substituindo parte do sistema tributário atual. Isso não ficou só no campo jurídico: a SEFAZ alterou o leiaute da NF-e e da NFC-e para acomodar os novos tributos, através da Nota Técnica 2025.002 (com ajustes posteriores na 2026.002).
Na prática, isso significa novos grupos dentro do XML da nota. O principal é o grupo de tributos IBS/CBS/Imposto Seletivo, que carrega três subgrupos:
gIBSUF: alíquota, diferimento e devolução de tributos do IBS na parte que cabe ao estado.gIBSMun: mesma lógica do IBS, mas na parte municipal.gCBS: os dados da contribuição federal.
Existe ainda o gIBSCBSMono, usado em cenários de tributação monofásica, e um grupo de ajuste de competência (gAjusteCompet). Se você já mexeu com o leiaute da NF-e antes, a lógica é parecida com a de outros grupos de imposto: cada tributo tem seu próprio bloco, com base de cálculo, alíquota e valor.
Os prazos não são flexíveis
Aqui está o que torna esse assunto urgente e não apenas mais uma atualização de leiaute:
- 1º de julho de 2026: homologação com os campos de IBS/CBS já era obrigatória para empresas do regime normal (CRT 3).
- 3 de agosto de 2026: os campos passam a ser obrigatórios também em produção, para o mesmo grupo de empresas.
- 4 de janeiro de 2027: prazo estendido para Simples Nacional, MEI e empresas no sublimite.
Ou seja: se você emite nota para uma empresa do regime normal, o prazo de produção já está batendo na porta. Não é uma mudança “quando puder implementar”: é uma mudança “implemente até a data ou pare de emitir nota válida”.
O problema que ninguém fala em bootcamp: sua dependência pode não estar pronta
É aqui que a conversa sai do leiaute e vai para gestão de dependência.
No grupo do NFePHP, um desenvolvedor relatou que o suporte a IBS/CBS (o grupo gIBSCBS e os métodos correspondentes na lib) já estava mergeado no branch master de um dos pacotes de emissão de CT-e havia meses, incluindo ajustes de notas técnicas recentes. O problema: a última versão publicada no Packagist/Composer era anterior a essa mudança. Ou seja, quem instalasse a lib pelo caminho normal (composer require numa versão estável) simplesmente não tinha o recurso.
Outro desenvolvedor, no mesmo grupo, relatou um problema equivalente em outra biblioteca da mesma família: um PR que adiciona funcionalidade importante ficou mergeado no master sem nunca virar uma tag de release.
A saída que os dois adotaram foi usar dev-master diretamente em produção. Funciona, mas é uma aposta: dev-master não passa pelo mesmo processo de estabilização de uma tag, e qualquer commit novo que entrar no branch principal do dia para a noite passa a valer no seu ambiente sem aviso.
É o mesmo tipo de armadilha que discuti em Quando a API do parceiro mente: validação defensiva de payload em integração externa: confiar que uma dependência externa está no estado que você espera, sem validar isso de forma explícita, é onde a maioria dos incidentes fiscais começa.
Um caso real de rejeição
Um terceiro participante do mesmo grupo relatou, na mesma semana, um incidente em produção: um cliente do setor de autopeças, no regime de lucro real presumido, configurado com alíquotas padrão de IBS e CBS, começou a receber rejeição da SEFAZ classificada como “alíquota do IBS da UF inválida”.
Vale um adendo de honestidade aqui: não encontrei, nas fontes oficiais que consultei, uma listagem que confirme o código exato de rejeição citado pelo desenvolvedor. As notas técnicas que revisei documentam rejeições relacionadas a tributação monofásica e regras de obrigatoriedade por cClassTrib, mas não me foi possível validar de forma independente o número exato do código relatado. Trato esse dado como relato de campo, não como fato confirmado em documentação oficial. O que fica confirmado é o padrão do problema: alíquota de IBS por UF é um campo sensível a erro de configuração, e é exatamente o tipo de erro que aparece quando o leiaute muda e a lib que gera o XML não foi atualizada, ou foi atualizada só parcialmente. Se você já lidou com rejeição de XML em integração fiscal antes, essa dor vai soar familiar, tratei um caso parecido em Copiei o XML igualzinho e mesmo assim deu erro: o pesadelo das integrações SOAP/governamentais.
O que fazer com isso agora
Se você mantém ou depende de uma lib PHP para emissão fiscal, três ações práticas:
- Audite se sua lib já suporta IBS/CBS antes de precisar dela em produção. Não espere o prazo de agosto para descobrir que a versão estável instalada é anterior à mudança de leiaute.
- Se precisar usar
dev-mastercomo ponte, fixe um commit específico, não a branch solta. Isso evita que uma mudança nova nomaster, depois que você já testou e homologou, quebre seu ambiente sem aviso. - Acompanhe as notas técnicas da SEFAZ diretamente, não apenas a documentação da sua lib. O leiaute muda por publicação oficial; a lib só reflete essa mudança depois, com atraso variável dependendo da disponibilidade de quem mantém o projeto.
Quando essa abordagem faz sentido, e quando não faz
Usar uma branch de desenvolvimento como workaround temporário é aceitável quando o prazo é inegociável e o código em questão já passou por revisão de PR e está sendo usado por outros desenvolvedores do mesmo ecossistema, como no caso relatado. Não é uma prática que eu recomendaria fora dessa pressão: em qualquer outro cenário, vale esperar a tag oficial ou, se a urgência for real, aplicar o patch localmente via fork controlado, em vez de apontar para uma branch que você não controla.
Perguntas frequentes
A partir de quando o IBS/CBS é obrigatório na NF-e?
Homologação com os campos de IBS/CBS já é obrigatória desde 1º de julho de 2026 para empresas do regime normal (CRT 3). Em produção, a obrigatoriedade passa a valer em 3 de agosto de 2026. Simples Nacional, MEI e empresas no sublimite têm prazo estendido até 4 de janeiro de 2027.
O que são os grupos gIBSUF, gIBSMun e gCBS?
São os novos blocos do XML da NF-e/NFC-e criados pela Nota Técnica 2025.002 (com ajustes na 2026.002) para registrar, respectivamente, a parte estadual do IBS, a parte municipal do IBS e a CBS federal, cada um com sua própria base de cálculo e alíquota.
É seguro usar dev-master de uma lib fiscal em produção?
Só como medida temporária e sob pressão real de prazo, e ainda assim fixando um commit específico, não a branch inteira. Fora dessa urgência, o recomendado é esperar a tag de release oficial da biblioteca.
Minha lib de NFe/CTe já suporta IBS/CBS?
Não assuma que sim só porque o projeto está ativo. Verifique se a funcionalidade está na última versão publicada no Packagist, e não apenas mergeada no branch principal do repositório.
