--- title: "Tributos federais no XML da NFS-e: Ambiente Nacional e São Paulo" description: "Como a NFE.io traduz PIS, COFINS, CSLL, IR e INSS para o XML do Ambiente Nacional e da Prefeitura de São Paulo: tpRetPisCofins, vRetCSLL, ValorCSLL e CST, conforme a NT 007." source_url: https://nfe.io/docs/documentacao/nota-fiscal-servico-eletronica/tributos-federais/layout-por-ambiente/ product: documentacao last_updated: 2026-09-30 tags: ["nfse", "impostos", "referencia", "reforma-tributaria"] --- # Tributos federais no XML da NFS-e Você informa os tributos federais nos campos da API (veja [Campos no payload](./campos-no-payload.md)). Esta página mostra **como a plataforma os traduz** para o XML enviado ao **Ambiente Nacional** e à **Prefeitura de São Paulo**, que seguem a sistemática da NT SE/CGNFS-e nº 007. Os demais layouts municipais (ABRASF e layouts próprios) têm campos diferentes, mas são alimentados pelos **mesmos campos da API**. ## Ambiente Nacional Grupo `valores/trib/tribFed` da DPS: | Tag | Origem na API | Observação | |---|---|---| | `piscofins/CST` | `cstPisCofins` | `00` quando não informado. | | `piscofins/vBCPisCofins` | `pisCofinsBaseTax` | Não é enviada com CST `00`, `08` ou `09`, nem quando a base é omitida. | | `piscofins/pAliqPis` | `pisRate` | Convertida para percentual (`0.0065` → `0.65`). | | `piscofins/pAliqCofins` | `cofinsRate` | Convertida para percentual (`0.03` → `3.00`). | | `piscofins/vPis` | `pisAmount` | **Débito próprio**, não o retido. | | `piscofins/vCofins` | `cofinsAmount` | **Débito próprio**, não o retido. | | `piscofins/tpRetPisCofins` | derivado de `pisAmountWithheld`, `cofinsAmountWithheld`, `csllAmountWithheld` | Tabela abaixo. | | `vRetCP` | `inssAmountWithheld` | | | `vRetIRRF` | `irAmountWithheld` | | | `vRetCSLL` | `pisAmountWithheld` + `cofinsAmountWithheld` + `csllAmountWithheld` | **Soma** das três retenções. | ### Tipo de retenção (`tpRetPisCofins`) O código diz **quais** das três contribuições foram retidas. Uma contribuição conta como retida quando o valor informado é **maior que zero**. | Código | PIS retido | COFINS retida | CSLL retida | |:---:|:---:|:---:|:---:| | `0` | não | não | não | | `3` | sim | sim | sim | | `4` | sim | sim | não | | `5` | sim | não | não | | `6` | não | sim | não | | `7` | não | sim | sim | | `8` | não | não | sim | | `9` | sim | não | sim | - O grupo `piscofins` — e com ele o `tpRetPisCofins` — só é emitido quando a nota traz algum dado de **PIS ou COFINS**: valor próprio ou retido, alíquota, base ou CST. Uma nota com **apenas CSLL retida** sai só com `vRetCSLL`, sem `piscofins` e sem tipo de retenção. - A NT 007 mantém temporariamente os códigos `1` (PIS/COFINS retido) e `2` (PIS/COFINS não retido) e prevê sua supressão quando os grupos de IBS/CBS se tornarem obrigatórios. Por padrão, a NFE.io emite no domínio `0` e `3` a `9`, que contempla a CSLL. ### Soma das retenções em `vRetCSLL` > **NT SE/CGNFS-e nº 007, item 2.c:** se houver valores de retenções de PIS, de COFINS e/ou de CSLL, eles deverão ser **somados** e informados no campo `vRetCSLL`, de acordo com o que foi informado no campo `tpRetPisCofins`. ```text vRetCSLL = PIS retido + COFINS retida + CSLL retida ``` O tipo de retenção e a soma são calculados a partir dos **mesmos** três campos da API, então os dois são sempre coerentes entre si. A agregação é específica do layout da NFS-e e não altera a forma de declarar as retenções na EFD-Reinf. :::info Prefeituras com layout nacional próprio Alguns municípios que adotaram o layout nacional por meio de um provedor próprio ainda seguem a regra anterior à NT 007: `vRetCSLL` leva apenas a CSLL retida, o PIS e a COFINS retidos vão em `vPis`/`vCofins`, e o tipo de retenção usa os códigos `1`/`2`. Nesses casos a plataforma segue a regra do provedor. Em caso de dúvida sobre um município específico, consulte a página dele em [Prefeituras integradas](/docs/prefeituras-integradas/) ou fale com o suporte. ::: ## Prefeitura de São Paulo Campos do RPS, conforme o Manual de Utilização do Web Service da SEFIN-SP (v3.3.6 e posteriores): | Campo | Origem na API | Observação | |---|---|---| | `ValorPIS` | `pisAmount` | Débito próprio. | | `ValorCOFINS` | `cofinsAmount` | Débito próprio. | | `ValorCSLL` | `pisAmountWithheld` + `cofinsAmountWithheld` + `csllAmountWithheld` | "Valor da retenção do CSLL, PIS e COFINS" — a soma das três. | | `RetencaoPisCofins` | derivado das três retenções | Mesma tabela do `tpRetPisCofins`. | | `ValorIR` | `irAmountWithheld` | | | `ValorINSS` | `inssAmountWithheld` | | Rejeições da SEFIN-SP ligadas a esses campos: | Código | Situação | |---|---| | `644` | Tipo de retenção `0` (nada retido) com `ValorCSLL` informado. | | `645` | Tipo de retenção diferente de `0` sem `ValorCSLL`. | | `646` | Tipo de retenção fora do domínio permitido. | Como a plataforma deriva o tipo e a soma da mesma origem, os dois ficam sempre coerentes entre si. ## Exemplo completo Prestador do Lucro Presumido, tomador pessoa jurídica não optante pelo Simples. Serviço de R$ 10.000,00, sem deduções. PIS 0,65%, COFINS 3%, CSLL 1% e IRRF 1,5%, todos retidos; PIS/COFINS próprio com as mesmas alíquotas. **Requisição (campos de tributos):** ```json { "servicesAmount": 10000.00, "cstPisCofins": "01", "pisCofinsBaseTax": 10000.00, "pisRate": 0.0065, "pisAmount": 65.00, "cofinsRate": 0.03, "cofinsAmount": 300.00, "irAmountWithheld": 150.00, "pisAmountWithheld": 65.00, "cofinsAmountWithheld": 300.00, "csllAmountWithheld": 100.00, "inssAmountWithheld": 0 } ``` **Ambiente Nacional:** ```xml 10000.00 0.65 3.00 65.00 300.00 3 150.00 465.00 ``` **São Paulo:** ```xml ``` Os trechos mostram apenas os campos de tributos federais. Variações: - **Só a CSLL retida:** no Ambiente Nacional, sai apenas `vRetCSLL` com o valor da CSLL, sem o grupo `piscofins`. Em São Paulo, `ValorCSLL` = valor da CSLL e `RetencaoPisCofins` = `8`. - **Nota pequena com cálculo automático** (serviço de R$ 150,00): a soma PIS + COFINS + CSLL daria R$ 6,98 e o IRRF R$ 2,25, ambos abaixo do limite de R$ 10,00 — a plataforma não retém nenhum deles. ## Quadro comparativo | Aspecto | Ambiente Nacional | São Paulo | |---|---|---| | PIS próprio | `vPis` | `ValorPIS` | | COFINS própria | `vCofins` | `ValorCOFINS` | | Soma das retenções de PIS, COFINS e CSLL | `vRetCSLL` | `ValorCSLL` | | Tipo de retenção | `tpRetPisCofins` | `RetencaoPisCofins` | | IRRF retido | `vRetIRRF` | `ValorIR` | | INSS retido | `vRetCP` | `ValorINSS` | ## Referências - Nota Técnica SE/CGNFS-e nº 007 (07/02/2026) — PIS, COFINS, CSLL, CST e `tpRetPisCofins`; soma em `vRetCSLL`. - Lei Complementar nº 214/2025, art. 12, § 2º, V — PIS/COFINS não compõem a base do IBS/CBS. - Manual de Utilização do Web Service de NFS-e da Prefeitura de São Paulo (SEFIN-SP), v3.3.6 e posteriores. - Lei nº 10.833/2003, art. 31 — retenção de PIS, COFINS e CSLL e limite de dispensa. - Lei nº 9.430/1996, art. 67 — limite de dispensa da retenção do IRRF.