NFSe · NT007 · versaoEsquema=RTC007

Retenções Federais:
PIS, COFINS e CSLL

Guia completo para preenchimento dos novos campos de retenção e apuração própria na NFSe Nacional e padrões municipais compatíveis, usando versaoEsquema=RTC007.

📅 Vigência NT007: 09/02/2026
🔑 Ativação: versaoEsquema=RTC007
🔧 NFSe Nacional v1.01 · IPM20 · PUBLICA
01 · Conceito

O que mudou com o RTC007?

Com versaoEsquema=RTC007, a API passa a separar explicitamente dois conceitos que antes ficavam misturados dentro de retencao:

🔒
retencao
O tomador retém na fonte — deduz o valor líquido da nota. Inclui PIS, COFINS, CSLL, IR, INSS, CPP.
📊
apuracaoPropria
Débito tributário do próprio prestador — não deduz o líquido. Cobre PIS e COFINS com CST e base de cálculo.
✦
A API calcula automaticamente: ao usar versaoEsquema=RTC007, o tpRetPisCofins e o vRetCSLL são calculados automaticamente pela API a partir dos valores informados. O cst usa o valor informado em apuracaoPropria.cstPisCofins — quando não informado, a API aplica o default "00".
⚠️
Sem versaoEsquema=RTC007 o comportamento anterior é mantido. Se não informar o campo ou informar RTC, a API continua funcionando exatamente como antes — nenhuma mudança obrigatória para quem não precisar da nova separação.
02 · Campos da API

Como preencher cada campo

Com versaoEsquema=RTC007, os campos se dividem em dois grupos dentro de servico.

── retencao

pisretencao.
→ vRetCSLL (somado)
Valor do PIS retido pelo tomador. Informe aliquota e valor.

A API soma automaticamente com COFINS e CSLL retidos para gerar o vRetCSLL.

Não confundir com apuracaoPropria.pis — são contextos diferentes.
cofinsretencao.
→ vRetCSLL (somado)
Valor da COFINS retida pelo tomador. Informe aliquota e valor.

Somada automaticamente com PIS e CSLL retidos para gerar o vRetCSLL.
csllretencao.
→ vRetCSLL (somado)
Valor da CSLL retida pelo tomador. Informe aliquota e valor.

A API soma os três retidos e preenche vRetCSLL automaticamente — não informe mais o valor somado manualmente.
tpRetPisCofinscalculado
→ tpRetPisCofins
Calculado automaticamente pela API. Derivado dos valores preenchidos em retencao — não é necessário informar. A API determina qual combinação de tributos está retida e preenche o tipo correto (0–9).

── apuracaoPropria

cstPisCofinsapuracaoPropria.
→ CST em piscofins
Código de Situação Tributária do PIS/COFINS.

Default: "00" quando não informado — a API preenche automaticamente quando há retenção mas não há apuração própria.

Valores: 00 a 99 conforme tabela CST PIS/COFINS.
baseCalculoPisCofinsapuracaoPropria.
→ vBCPisCofins
Base de cálculo da apuração própria (R$).

Normalmente igual ao valor do serviço. Se não informada, a API utiliza o valor bruto do serviço.
pisapuracaoPropria.
→ pAliqPis · vPis
Débito de PIS por apuração própria do prestador.

Informe aliquota — o valor é opcional: se não informado, a API calcula automaticamente como baseCalculoPisCofins × aliquota. Se informado, o valor fornecido é mantido sem recálculo.

Não deduz o valor líquido da nota — é o débito tributário do prestador, não uma retenção do tomador.
cofinsapuracaoPropria.
→ pAliqCofins · vCofins
Débito de COFINS por apuração própria do prestador.

Informe aliquota — o valor é opcional: se não informado, a API calcula automaticamente como baseCalculoPisCofins × aliquota. Se informado, o valor fornecido é mantido sem recálculo.

Assim como o PIS próprio, não impacta o valor líquido da nota.
03 · Tabela de decisão

O que preencher em cada situação?

Use a tabela abaixo para saber quais grupos informar com base no regime do prestador e no contrato com o tomador.

Situação retencao apuracaoPropria tpRetPisCofins gerado
Simples Nacional — sem retenção, sem apuração própria — — não enviado
Lucro Real — apuração própria, tomador não retém — ✓ 0 — nenhum retido
Tomador retém PIS, COFINS e CSLL — sem apuração própria ✓ (pis + cofins + csll) — 3 — todos retidos
Lucro Real — apuração própria E tomador retém PIS/COFINS/CSLL ✓ (pis + cofins + csll) ✓ 3 — todos retidos
Tomador retém PIS e COFINS — CSLL não retida ✓ (pis + cofins) — 4 — PIS/COFINS retidos
Tomador retém somente PIS — COFINS e CSLL não retidas ✓ (pis) — 5 — só PIS retido
Tomador retém somente COFINS — PIS e CSLL não retidos ✓ (cofins) — 6 — só COFINS retida
Tomador retém COFINS e CSLL — PIS não retido ✓ (cofins + csll) — 7 — COFINS/CSLL retidos
Tomador retém somente CSLL — PIS e COFINS não retidos ✓ (csll) — 8 — só CSLL retida
Tomador retém PIS e CSLL — COFINS não retida ✓ (pis + csll) — 9 — PIS/CSLL retidos
💡
O tpRetPisCofins é sempre calculado automaticamente a partir dos valores preenchidos em retencao. Você não precisa calcular nem informar esse campo — informe apenas os valores de cada tributo no grupo correto.
04 · Cenários práticos

Exemplos de preenchimento

Serviço de R$ 1.000,00 em todos os exemplos. Todos usam versaoEsquema: "RTC007".

A
Lucro Real — apuração própria, sem retenção
tpRetPisCofins = "0" (calculado)
API · JSON
"versaoEsquema": "RTC007",
"servico": [{
  "apuracaoPropria": {
    "cstPisCofins": "01",
    "baseCalculoPisCofins": 1000.00,
    "pis": {
      "aliquota": 1.65
      // valor omitido: API calcula 1000 × 1.65% = 16.50
    },
    "cofins": {
      "aliquota": 7.60
      // valor omitido: API calcula 1000 × 7.60% = 76.00
    }
  }
  // retencao: não informado
}]
XML gerado
<piscofins>
  <Cst>01</Cst>
  <vBCPisCofins>1000.00</vBCPisCofins>
  <pAliqPis>1.65</pAliqPis>
  <vPis>16.50</vPis>
  <pAliqCofins>7.60</pAliqCofins>
  <vCofins>76.00</vCofins>
  <tpRetPisCofins>0</tpRetPisCofins>
</piscofins>
<!-- vRetCSLL: omitido -->
💡 Sem retenção, apenas apuração própria. A API calcula tpRetPisCofins=0 automaticamente.
B
Tomador retém PIS, COFINS e CSLL — sem apuração própria
tpRetPisCofins = "3" (calculado)
API · JSON
"versaoEsquema": "RTC007",
"servico": [{
  "retencao": {
    "pis": {
      "aliquota": 0.65,
      "valor": 6.50
    },
    "cofins": {
      "aliquota": 3.00,
      "valor": 30.00
    },
    "csll": {
      "aliquota": 1.00,
      "valor": 10.00
    }
  }
  // apuracaoPropria: não informado
  // API usa cstPisCofins="00" automaticamente
}]
XML gerado
<piscofins>
  <Cst>00</Cst>
  <tpRetPisCofins>3</tpRetPisCofins>
</piscofins>
<vRetCSLL>46.50</vRetCSLL>
<!-- 6.50 + 30.00 + 10.00, calculado pela API -->
💡 Sem apuração própria. A API calcula tpRetPisCofins=3 e soma vRetCSLL=46.50 automaticamente. CST padrão "00".
C
Apuração própria E retenção simultâneas — cenário mais comum no Lucro Real
tpRetPisCofins = "3" (calculado)
API · JSON
"versaoEsquema": "RTC007",
"servico": [{
  "retencao": {
    "pis":   { "aliquota": 0.65, "valor": 6.50  },
    "cofins": { "aliquota": 3.00, "valor": 30.00 },
    "csll":  { "aliquota": 1.00, "valor": 10.00 }
  },
  "apuracaoPropria": {
    "cstPisCofins": "01",
    "baseCalculoPisCofins": 1000.00,
    "pis":    { "aliquota": 1.65, "valor": 16.50 }, // valor informado: mantido
    "cofins": { "aliquota": 7.60, "valor": 76.00 }  // valor informado: mantido
  }
}]
XML gerado
<piscofins>
  <Cst>01</Cst>
  <vBCPisCofins>1000.00</vBCPisCofins>
  <pAliqPis>1.65</pAliqPis>
  <vPis>16.50</vPis>
  <pAliqCofins>7.60</pAliqCofins>
  <vCofins>76.00</vCofins>
  <tpRetPisCofins>3</tpRetPisCofins>
</piscofins>
<vRetCSLL>46.50</vRetCSLL>
⚠️ Cenário mais comum no Lucro Real. O prestador tem débito de apuração própria (PIS 1,65% + COFINS 7,60%) e sofre retenção na fonte (PIS 0,65% + COFINS 3,00% + CSLL 1,00%). Valores informados explicitamente — API mantém sem recalcular. A API separa automaticamente e preenche todos os campos do XML.
D
PIS e COFINS retidos, CSLL não retida
tpRetPisCofins = "4" (calculado)
API · JSON
"versaoEsquema": "RTC007",
"servico": [{
  "retencao": {
    "pis":    { "aliquota": 0.65, "valor": 6.50  },
    "cofins": { "aliquota": 3.00, "valor": 30.00 }
    // csll: não retida
  }
}]
XML gerado
<piscofins>
  <Cst>00</Cst>
  <tpRetPisCofins>4</tpRetPisCofins>
</piscofins>
<vRetCSLL>36.50</vRetCSLL>
<!-- 6.50 + 30.00, calculado pela API -->
💡 PIS e COFINS retidos sem CSLL. O vRetCSLL contém apenas PIS + COFINS retidos (36,50), sem CSLL.
E
Somente PIS retido — COFINS e CSLL não retidas
tpRetPisCofins = "5" (calculado)
API · JSON
"versaoEsquema": "RTC007",
"servico": [{
  "retencao": {
    "pis": { "aliquota": 0.65, "valor": 6.50 }
    // cofins e csll: não retidas
  }
}]
XML gerado
<piscofins>
  <Cst>00</Cst>
  <tpRetPisCofins>5</tpRetPisCofins>
</piscofins>
<vRetCSLL>6.50</vRetCSLL>
💡 Apenas PIS retido. vRetCSLL contém somente o valor do PIS retido.
F
Somente COFINS retida — PIS e CSLL não retidos
tpRetPisCofins = "6" (calculado)
API · JSON
"versaoEsquema": "RTC007",
"servico": [{
  "retencao": {
    "cofins": { "aliquota": 3.00, "valor": 30.00 }
    // pis e csll: não retidos
  }
}]
XML gerado
<piscofins>
  <Cst>00</Cst>
  <tpRetPisCofins>6</tpRetPisCofins>
</piscofins>
<vRetCSLL>30.00</vRetCSLL>
💡 Apenas COFINS retida. vRetCSLL contém somente o valor da COFINS retida.
G
COFINS e CSLL retidas, PIS não retido
tpRetPisCofins = "7" (calculado)
API · JSON
"versaoEsquema": "RTC007",
"servico": [{
  "retencao": {
    "cofins": { "aliquota": 3.00, "valor": 30.00 },
    "csll":   { "aliquota": 1.00, "valor": 10.00 }
    // pis: não retido
  }
}]
XML gerado
<piscofins>
  <Cst>00</Cst>
  <tpRetPisCofins>7</tpRetPisCofins>
</piscofins>
<vRetCSLL>40.00</vRetCSLL>
<!-- 30.00 + 10.00, calculado pela API -->
💡 COFINS e CSLL retidas, PIS não. vRetCSLL = COFINS + CSLL retidos (40,00).
H
Tomador retém só CSLL — PIS e COFINS por apuração própria
tpRetPisCofins = "8" (calculado)
API · JSON
"versaoEsquema": "RTC007",
"servico": [{
  "retencao": {
    "csll": { "aliquota": 1.00, "valor": 10.00 }
  },
  "apuracaoPropria": {
    "cstPisCofins": "01",
    "baseCalculoPisCofins": 1000.00,
    "pis":    { "aliquota": 0.65, "valor": 6.50  },
    "cofins": { "aliquota": 3.00, "valor": 30.00 }
  }
}]
XML gerado
<piscofins>
  <Cst>01</Cst>
  <vBCPisCofins>1000.00</vBCPisCofins>
  <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 tributo retido é a CSLL. PIS e COFINS são de apuração própria — vão para vPis e vCofins, não para vRetCSLL.
I
PIS e CSLL retidos, COFINS não retida
tpRetPisCofins = "9" (calculado)
API · JSON
"versaoEsquema": "RTC007",
"servico": [{
  "retencao": {
    "pis":  { "aliquota": 0.65, "valor": 6.50  },
    "csll": { "aliquota": 1.00, "valor": 10.00 }
    // cofins: não retida
  }
}]
XML gerado
<piscofins>
  <Cst>00</Cst>
  <tpRetPisCofins>9</tpRetPisCofins>
</piscofins>
<vRetCSLL>16.50</vRetCSLL>
<!-- 6.50 + 10.00, calculado pela API -->
💡 PIS e CSLL retidos, COFINS não. vRetCSLL = PIS + CSLL retidos (16,50).
⚠️
Tipos 1 e 2 — legados, em transição: os códigos 1 (PIS/COFINS Retidos) e 2 (PIS/COFINS Não Retidos) são aceitos apenas durante o período de transição. Serão removidos quando o grupo IBS/CBS se tornar obrigatório. Use preferencialmente os códigos 0 e 3–9.
05 · Migração

Como migrar do comportamento antigo (RTC → RTC007)

Se você já usava a API com o campo retido: true ou com tipoRetencaoPisCofinsCSLL informado manualmente, veja como adaptar para o novo contrato.

Antes — comportamento antigo (RTC)

❌ ANTES — cliente calcula tudo
"versaoEsquema": "RTC",
"retencao": {
  "tipoRetencaoPisCofinsCSLL": "3", // cliente calcula
  "pis": {
    "aliquota": 1.65,
    "valor": 16.50,  // apuração própria
    "retido": false
  },
  "cofins": {
    "aliquota": 7.60,
    "valor": 76.00,  // apuração própria
    "retido": false
  },
  "csll": {
    "valor": 46.50  // soma manual: 6.50+30.00+10.00
  }
}
✅ DEPOIS — RTC007, API calcula
"versaoEsquema": "RTC007",
"retencao": {
  "pis":    { "aliquota": 0.65, "valor": 6.50  },
  "cofins": { "aliquota": 3.00, "valor": 30.00 },
  "csll":   { "aliquota": 1.00, "valor": 10.00 }
},
"apuracaoPropria": {
  "cstPisCofins": "01",
  "baseCalculoPisCofins": 1000.00,
  "pis":    { "aliquota": 1.65, "valor": 16.50 },
  "cofins": { "aliquota": 7.60, "valor": 76.00 }
}
// tpRetPisCofins e vRetCSLL: calculados pela API
// cst: usa apuracaoPropria.cstPisCofins, ou "00" por default
✅
Regra de ouro para migrar:
1. Adicione versaoEsquema: "RTC007" na nota
2. Mova os valores retidos para retencao com cada tributo separado
3. Mova os valores de apuração própria para apuracaoPropria com cstPisCofins
4. Remova tipoRetencaoPisCofinsCSLL — a API calcula automaticamente
5. Remova csll.valor como agregador — informe apenas o valor real da CSLL retida
6. O campo retido será ignorado — pode remover
06 · FAQ

Perguntas frequentes

Preciso usar versaoEsquema=RTC007 obrigatoriamente?
Não. O versaoEsquema=RTC007 é opcional — se não informar ou informar RTC, o comportamento anterior é mantido integralmente. A migração é recomendada para quem tem apuração própria de PIS/COFINS ou quer simplificar o preenchimento, mas não é obrigatória.
Por que o tpRetPisCofins é calculado automaticamente agora?
Com o novo contrato, a API sabe exatamente quais tributos estão retidos — cada um é informado separadamente em retencao.pis, retencao.cofins e retencao.csll. A combinação desses três valores determina univocamente o tipo (0–9). Não há ambiguidade, então não faz sentido o cliente calcular algo que a API pode derivar com certeza.
O que acontece se eu informar apuracaoPropria sem versaoEsquema=RTC007?
O grupo apuracaoPropria será ignorado completamente. A API processa apenas os campos do contrato RTC — tipoRetencaoPisCofinsCSLL, pis.retido, cofins.retido e csll.valor como agregador.
Como fica o CST quando não há apuração própria?
Quando apuracaoPropria não é informado mas há retenção, a API preenche automaticamente cstPisCofins="00" no XML — obrigatório pelo layout da NFSe Nacional sempre que o grupo piscofins existir. Você não precisa se preocupar com isso.
A mudança afeta NFSe de padrão municipal (não nacional)?
Sim — além da NFSe Nacional, padrões municipais compatíveis como IPM20 e PUBLICA também utilizam o novo contrato quando versaoEsquema=RTC007 é informado. NFSes de outros padrões municipais sem suporte ao grupo apuracaoPropria simplesmente ignoram os novos campos — sem impacto.
Preciso informar o valor do PIS e COFINS em apuracaoPropria?
Não. O valor dentro de apuracaoPropria.pis e apuracaoPropria.cofins é opcional. Se não informado, a API calcula automaticamente usando baseCalculoPisCofins × aliquota. Se você informar o valor, ele é mantido como está — sem recálculo. Isso é útil quando há arredondamentos ou ajustes que diferem do cálculo simples.
Posso ainda usar os campos retido e tipoRetencaoPisCofinsCSLL?
Sim, no contrato RTC (sem versaoEsquema=RTC007) esses campos continuam funcionando normalmente. No contrato RTC007, pis.retido e cofins.retido são ignorados, e tipoRetencaoPisCofinsCSLL é calculado automaticamente pela API — não precisa informar.