NT007 — PIS/COFINS/CSLL · PlugNotas NFSe Nacional

01 · Conceito

O que mudou com a NT007?

Antes da NT007, muitos sistemas usavam os campos vPis e vCofins para informar valores retidos na fonte. Isso estava errado — esses campos existem exclusivamente para apuração própria.

O erro causava redução indevida da base de cálculo do IBS e da CBS, contrariando a Lei Complementar 214/2025. A NT007 corrige isso formalmente com três mudanças:

①

pis.valor e cofins.valor

São exclusivos de apuração própria. Nunca informe retenções aqui.

②

tipoRetencaoPisCofinsCSLL

Novo campo que você informa. Indica a combinação de tributos retidos (códigos 0–9).

③

csll.valor

Agrega todos os valores retidos (PIS + COFINS + CSLL) conforme o tipo.

⚠️

A API não calcula mais automaticamente. O tipo de retenção e a soma dos valores retidos são de responsabilidade do cliente (ou do seu contador). Isso garante que a classificação fiscal esteja sempre correta para cada operação.

02 · Campos da API

Como preencher cada campo

Todos os campos ficam dentro de servico.retencao.

tipoRetencaoPisCofinsCSLL retencao.

→ tpRetPisCofins

O principal campo novo. Você informa qual combinação de tributos está sendo retida. A API envia direto para o XML como tpRetPisCofins, sem modificar.

Se não informado, o campo não é enviado no XML.

⚠️ Consulte a tabela de decisão para escolher o código correto.

pis.valor retencao.pis.

→ vPis

Somente apuração própria — quando o PIS não é retido.

Se o PIS for retido, não preencha este campo. Informe o valor retido somado em csll.valor e use tipoRetencaoPisCofinsCSLL.

cofins.valor retencao.cofins.

→ vCofins

Somente apuração própria — quando a COFINS não é retida.

Se a COFINS for retida, não preencha este campo. Informe o valor retido somado em csll.valor e use tipoRetencaoPisCofinsCSLL.

csll.valor retencao.csll.

→ vRetCSLL

Agregador de retenções sociais. Apesar do nome no XML (vRetCSLL), este campo recebe a soma de todos os tributos retidos conforme o tipoRetencaoPisCofinsCSLL.

Exemplos:
• tpRet=3: vPIS retido + vCOFINS retido + vCSLL retido
• tpRet=4: vPIS retido + vCOFINS retido
• tpRet=8: apenas vCSLL retido

Se não houver retenção, não informe este campo.

pis.retido retencao.pis.

Ignorado na NFSe Nacional. Este campo continua existindo para compatibilidade com outros padrões municipais, mas não é considerado no preenchimento do XML nacional. Use tipoRetencaoPisCofinsCSLL.

cofins.retido retencao.cofins.

Ignorado na NFSe Nacional. Mesmo comportamento do pis.retido — mantido para outros padrões, sem efeito no XML nacional.

03 · Tabela de decisão

Qual código usar?

Escolha o tipoRetencaoPisCofinsCSLL com base em quais tributos são retidos na fonte.

💡

A definição de quais tributos são retidos depende do contrato e da legislação aplicável. Em caso de dúvida, consulte seu contador antes de emitir.

Código	PIS	COFINS	CSLL	csll.valor contém
0	não retido	não retido	não retido	não informar
3	retido	retido	retido	PIS + COFINS + CSLL
4	retido	retido	não retido	PIS + COFINS
5	retido	não retido	não retido	PIS
6	não retido	retido	não retido	COFINS
7	não retido	retido	retido	COFINS + CSLL
8	não retido	não retido	retido	CSLL
9	retido	não retido	retido	PIS + CSLL
1	PIS/COFINS Retidos legado			comportamento antigo
2	PIS/COFINS Não Retidos legado			comportamento antigo

⚠️

Os códigos 1 e 2 são legados e serão removidos quando o grupo IBSCBS se tornar obrigatório na NFSe Nacional. Evite usá-los em novas integrações.

04 · Cenários práticos

Exemplos de preenchimento

Veja como preencher o JSON da API para cada situação. Serviço de R$ 1.000,00 em todos os exemplos. Note que apuração própria e retenção podem coexistir com alíquotas diferentes.

Nenhum tributo retido — apuração própria

tipoRetencaoPisCofinsCSLL = "0"

API · JSON

"retencao": {
  "tipoRetencaoPisCofinsCSLL": "0",
  "pis": {
    "aliquota": 0.65,
    "valor": 6.50  // apuração própria
  },
  "cofins": {
    "aliquota": 3.00,
    "valor": 30.00  // apuração própria
  }
  // csll.valor: não informar
}

XML gerado

<piscofins>
  <pAliqPis>0.65</pAliqPis>
  <vPis>6.50</vPis>
  <pAliqCofins>3.00</pAliqCofins>
  <vCofins>30.00</vCofins>
  <tpRetPisCofins>0</tpRetPisCofins>
</piscofins>
<!-- vRetCSLL: omitido -->

💡 vPis e vCofins são enviados pois não há retenção. csll.valor não é informado.

💡

Cenário mais comum para empresas do Lucro Real/Presumido:
O prestador tem débito de apuração própria (alíquotas do regime tributário) e também sofre retenção na fonte pelo tomador (alíquotas padrão de retenção). São alíquotas diferentes que devem ser informadas simultaneamente.

Apuração própria E retenção simultâneas (código 3) — exemplo real DANFSe

tipoRetencaoPisCofinsCSLL = "3"

API · JSON

"retencao": {
  "tipoRetencaoPisCofinsCSLL": "3",
  "pis": {
    "aliquota": 1.65,
    "valor": 16.50  // apuração própria (1,65% de 1000)
  },
  "cofins": {
    "aliquota": 7.60,
    "valor": 76.00  // apuração própria (7,60% de 1000)
  },
  "csll": {
    // soma das retenções: PIS 0,65% + COFINS 3,00% + CSLL 1,00%
    // = 6.50 + 30.00 + 10.00 = 46.50
    "valor": 46.50
  }
}

XML gerado

<piscofins>
  <pAliqPis>1.65</pAliqPis>
  <vPis>16.50</vPis>
  <pAliqCofins>7.60</pAliqCofins>
  <vCofins>76.00</vCofins>
  <tpRetPisCofins>3</tpRetPisCofins>
</piscofins>
<vRetCSLL>46.50</vRetCSLL>

⚠️ Exemplo baseado em DANFSe autorizado em homologação.
O prestador tem débito de apuração própria (alíquotas do regime: PIS 1,65% + COFINS 7,60%) e também sofre retenção na fonte (alíquotas padrão: PIS 0,65% + COFINS 3,00% + CSLL 1,00%).
Ambos devem ser informados. pis.valor e cofins.valor são de apuração própria. csll.valor contém a soma das retenções (46,50).

PIS + COFINS retidos, CSLL não retida

tipoRetencaoPisCofinsCSLL = "4"

API · JSON

"retencao": {
  "tipoRetencaoPisCofinsCSLL": "4",
  "pis": {
    "aliquota": 0.65
  },
  "cofins": {
    "aliquota": 3.00
  },
  "csll": {
    "valor": 36.50  // 6.50+30.00 (sem CSLL)
  }
}

XML gerado

<piscofins>
  <pAliqPis>0.65</pAliqPis>
  <pAliqCofins>3.00</pAliqCofins>
  <tpRetPisCofins>4</tpRetPisCofins>
</piscofins>
<vRetCSLL>36.50</vRetCSLL>

⚠️ Apesar do nome vRetCSLL no XML, o valor contém PIS + COFINS retidos (sem CSLL neste caso).

Somente CSLL retida — PIS e COFINS apuração própria

tipoRetencaoPisCofinsCSLL = "8"

API · JSON

"retencao": {
  "tipoRetencaoPisCofinsCSLL": "8",
  "pis": {
    "aliquota": 0.65,
    "valor": 6.50   // apuração própria
  },
  "cofins": {
    "aliquota": 3.00,
    "valor": 30.00  // apuração própria
  },
  "csll": {
    "valor": 10.00  // só CSLL retida
  }
}

XML gerado

<piscofins>
  <pAliqPis>0.65</pAliqPis>
  <vPis>6.50</vPis>
  <pAliqCofins>3.00</pAliqCofins>
  <vCofins>30.00</vCofins>
  <tpRetPisCofins>8</tpRetPisCofins>
</piscofins>
<vRetCSLL>10.00</vRetCSLL>

💡 Único cenário onde vRetCSLL contém apenas o valor da CSLL.

05 · Migração

Como migrar do comportamento antigo

Se você já usava a API antes da NT007 com o campo retido: true, veja o que precisa mudar.

Antes — comportamento antigo (não use mais)

❌ ANTES — todos retidos

"retencao": {
  "pis": {
    "aliquota": 0.65,
    "valor": 6.50,
    "retido": true
  },
  "cofins": {
    "aliquota": 3.00,
    "valor": 30.00,
    "retido": true
  },
  "csll": {
    "valor": 10.00,
    "retido": true
  }
}

✅ DEPOIS — todos retidos (NT007)

"retencao": {
  "tipoRetencaoPisCofinsCSLL": "3",
  "pis": {
    "aliquota": 0.65
    // valor: não informar
  },
  "cofins": {
    "aliquota": 3.00
    // valor: não informar
  },
  "csll": {
    // soma: 6.50+30.00+10.00
    "valor": 46.50
  }
}

✅

Regra de ouro para migrar:
1. Identifique quais tributos são retidos com seu contador
2. Escolha o código correto na tabela de decisão
3. Some os valores retidos e informe em csll.valor
4. Informe em pis.valor / cofins.valor apenas os de apuração própria
5. O campo retido será ignorado — pode remover

06 · FAQ

Perguntas frequentes

Por que o campo se chama csll.valor se guarda PIS e COFINS também?

O nome vRetCSLL no XML é herança histórica — antes da NT007 esse campo guardava apenas a CSLL retida. Com a NT007, ele foi reutilizado como agregador de todas as retenções sociais (PIS + COFINS + CSLL), dependendo do tipoRetencaoPisCofinsCSLL. Na nossa API usamos csll.valor para manter consistência com os outros campos, mas o comportamento segue a NT007.

E se eu informar pis.valor com o tributo retido?

A API não bloqueia, mas o XML ficará incorreto segundo a NT007 — o valor irá para vPis (apuração própria) ao invés de ser agregado em vRetCSLL. Isso pode causar inconsistência na base de cálculo do IBS/CBS e eventual rejeição pela SEFAZ. Não informe pis.valor quando o PIS for retido.

Se não houver retenção de nenhum tributo, devo informar tipoRetencaoPisCofinsCSLL?

É opcional. Se não informado, o campo não é enviado no XML. Se quiser ser explícito, informe "0" (PIS/COFINS/CSLL Não Retidos). Nesse caso o csll.valor não deve ser informado.

Os campos retido do PIS e COFINS foram removidos?

Não foram removidos — eles continuam existindo porque são utilizados em outros padrões de NFSe municipal. Na NFSe Nacional, eles são simplesmente ignorados. Para indicar retenções na NFSe Nacional, use exclusivamente o tipoRetencaoPisCofinsCSLL.

Como saber qual tipoRetencaoPisCofinsCSLL usar?

Isso depende do seu contrato e da legislação aplicável à operação. A regra geral é: empresas do Lucro Real ou Presumido sujeitas a retenção na fonte geralmente têm PIS, COFINS e CSLL retidos ("3"). Empresas do Simples Nacional geralmente não têm retenção ("0" ou não informar). Consulte seu contador para definir o código correto para cada tipo de operação.

Essa mudança afeta NFSe de padrão municipal (não nacional)?

Não. A NT007 aplica-se exclusivamente à NFSe Nacional (padrão SEFAZ/SE/CGNFS-e). NFSes de padrão municipal continuam funcionando com o comportamento anterior, inclusive usando o campo retido normalmente.

Posso ainda usar os códigos 1 e 2?

Sim, por enquanto. Os códigos 1 e 2 são legados e ainda são aceitos pela SEFAZ durante o período de transição. Porém, serão removidos quando o grupo IBSCBS se tornar obrigatório na NFSe Nacional. Recomendamos migrar para os novos códigos (0 e 3–9) o quanto antes para evitar problemas futuros.