Tributos federais na NFS-e

Esta seção explica como informar os tributos federais — PIS, COFINS, CSLL, IR e INSS — na emissão de NFS-e pela API da NFE.io, e como a plataforma os traduz para o layout de cada ambiente.

Página	Para quem	O que responde
Visão geral (esta)	Fiscal, produto e integração	Próprio × retido, cálculo automático, valor líquido
Campos no payload	Integração	Cada campo da API, formato e exemplos
Layout por ambiente	Integração e suporte	Como cada campo sai no XML do Ambiente Nacional e de São Paulo

O essencial

PIS e COFINS aparecem de duas formas diferentes na nota, e não se confundem:
- próprio (devido): o tributo que o prestador apura sobre a operação — pisAmount, cofinsAmount;
- retido: o valor que o tomador desconta do pagamento e recolhe no lugar do prestador — pisAmountWithheld, cofinsAmountWithheld, csllAmountWithheld.
IR e INSS só existem como retenção na NFS-e: irAmountWithheld e inssAmountWithheld.
Alíquotas vão sempre como fração: 0,65% = 0.0065; 3% = 0.03.
Você informa os valores da sua operação; a tradução para a regra de cada ambiente é feita pela plataforma — inclusive o tipo de retenção e a soma das retenções exigidos pela NT 007.

Tributo próprio × tributo retido

	Próprio (devido)	Retido
Quem recolhe	O prestador	O tomador, no lugar do prestador
Reduz o valor líquido da nota?	Não	Sim
Campos da API	`pisAmount`, `cofinsAmount` (+ `pisRate`, `cofinsRate`, `pisCofinsBaseTax`, `cstPisCofins`)	`pisAmountWithheld`, `cofinsAmountWithheld`, `csllAmountWithheld`, `irAmountWithheld`, `inssAmountWithheld`
Tem alíquota na API?	Sim	Não — retenção é informada só pelo valor

Para decidir, pergunte quem paga o tributo: se é a própria empresa emissora, use os campos próprios; se é o cliente que retém no pagamento, use os campos de retenção. Os dois grupos podem coexistir na mesma nota.

Não informe o valor retido no campo próprio

pisAmount e cofinsAmount representam o débito próprio do prestador. Colocar ali o valor retido altera o valor líquido e, nos ambientes da Reforma Tributária, a base de cálculo do IBS/CBS.

O que mudou com a NT 007

A Nota Técnica SE/CGNFS-e nº 007, em vigor no Ambiente Nacional desde 09/02/2026, separou no layout o valor devido do valor retido:

vPis e vCofins passaram a representar somente o débito próprio. Antes, muitos emissores usavam esses campos para o valor retido — e, como o PIS/COFINS não compõe a base do IBS/CBS (LC 214/2025, art. 12, § 2º, V), isso reduzia a base desses tributos indevidamente.
A retenção passou a ser indicada pelo tipo de retenção (tpRetPisCofins), um código que diz quais das três contribuições (PIS, COFINS, CSLL) foram retidas.
Os valores retidos de PIS, COFINS e CSLL passaram a ser somados num único campo, vRetCSLL.

A Prefeitura de São Paulo adotou a mesma sistemática (campos RetencaoPisCofins e ValorCSLL).

O que muda na integração com a NFE.io: nada. Você continua informando os valores próprios e retidos nos campos de sempre; a plataforma deriva o tipo de retenção e a soma a partir dos três campos ...AmountWithheld. Os detalhes estão em Layout por ambiente.

Cálculo automático das retenções

Quando a nota é enviada sem nenhum valor de imposto, a plataforma calcula as retenções federais com base nas alíquotas cadastradas para o código de serviço.

Quando o cálculo automático acontece

O cálculo automático só roda se a requisição não trouxer:

issRate nem issTaxAmount; e
nenhum dos campos de retenção (irAmountWithheld, pisAmountWithheld, cofinsAmountWithheld, csllAmountWithheld, inssAmountWithheld, issAmountWithheld).

Informar uma retenção desliga o cálculo de todas

A decisão é tudo ou nada. Basta enviar um único campo de retenção — mesmo com valor 0 — para que a plataforma não calcule as demais. Nesse caso, informe todas as retenções que se aplicam à nota; as que não forem enviadas ficam sem retenção. Informar issRate ou issTaxAmount desliga todo o cálculo automático.

Há duas exceções:

Prestador do Simples Nacional ou MEI: se a nota não trouxer issRate nem issTaxAmount, a plataforma zera IR, PIS, COFINS e CSLL retidos — inclusive valores que você tenha informado.
Algumas prefeituras calculam o ISS retido mesmo quando as retenções federais são informadas.

Regras aplicadas

Prestador	Tomador	IRRF	INSS	ISS retido	PIS/COFINS/CSLL
Simples Nacional ou MEI	qualquer	zerado	não calcula	não calcula	zerados
Lucro Presumido ou Real	Pessoa física	não retém	não retém	não retém	não retém
Lucro Presumido ou Real	PJ optante pelo Simples ou MEI	retém	não retém	não retém	não retém
Lucro Presumido ou Real	PJ do Lucro Presumido ou Real	retém	retém	retém	retém
Lucro Presumido ou Real	PJ de outro regime ou sem regime informado	retém	retém	não retém	retém

No Simples Nacional e no MEI, "zerado" vale mesmo quando o valor foi informado na requisição.

Além do quadro:

Base de cálculo das retenções = valor dos serviços − (deduções + desconto incondicionado).
Cada retenção depende de alíquota maior que zero cadastrada para o imposto no código de serviço.
Limite de dispensa de R$ 10,00: o IRRF (Lei 9.430/1996, art. 67) e a soma de PIS, COFINS e CSLL (Lei 10.833/2003, art. 31) não são retidos quando o valor fica abaixo de R$ 10,00. Para PIS, COFINS e CSLL o limite vale para a soma das três — se a soma ficar abaixo, as três ficam zeradas. INSS e ISS retido não têm limite mínimo.
Para prestador de outros regimes, nenhuma retenção é calculada.

Valor líquido da nota

valor líquido = valor dos serviços
              − desconto incondicionado
              − desconto condicionado
              − (IR + PIS + COFINS + CSLL + INSS + ISS + outras retenções)

Os tributos próprios (pisAmount, cofinsAmount) não reduzem o valor líquido.

O essencial​

Tributo próprio × tributo retido​

O que mudou com a NT 007​

Cálculo automático das retenções​

Quando o cálculo automático acontece​

Regras aplicadas​

Valor líquido da nota​

Veja também​

NFE.io