Tributos federais no payload da NFS-e

Esta página descreve o que enviar, em qual formato e qual o efeito de cada campo de tributo federal na emissão de NFS-e. Para os conceitos de próprio × retido e as regras do cálculo automático, veja a visão geral.

Formato dos valores

A API é JSON: use ponto como separador decimal, sem separador de milhar, sem símbolo de moeda e sem sinal de porcentagem.

Alíquotas (...Rate): sempre fração

A alíquota é o percentual dividido por 100.

Percentual	Enviar
0,65%	0.0065
1,65%	0.0165
3,00%	0.03
7,60%	0.076

Não envie a alíquota em percentual

Enviar 1.65 para representar 1,65% não é seguro: parte dos layouts municipais multiplica a alíquota por 100 e emitiria 165%. A fração (0.0165) é o único formato interpretado da mesma forma em todos os ambientes.

Valores (...Amount, ...AmountWithheld): reais

O valor é o montante em reais, com duas casas decimais: R$ 4,50 = 4.50; R$ 1.520,30 = 1520.30.

Campos

PIS e COFINS próprios (débito do prestador)

Campo	Formato	Significado
pisAmount	reais	Valor do PIS devido pelo prestador.
pisRate	fração	Alíquota do PIS.
cofinsAmount	reais	Valor da COFINS devida pelo prestador.
cofinsRate	fração	Alíquota da COFINS.
pisCofinsBaseTax	reais	Base de cálculo do PIS/COFINS.
cstPisCofins	texto, 2 dígitos	Código de Situação Tributária do PIS/COFINS (tabela abaixo).

• Envie valor e alíquota de forma coerente (valor ≈ base × alíquota). No Ambiente Nacional a plataforma não deriva um a partir do outro; alguns layouts municipais completam o campo que faltar.
• Informe pisCofinsBaseTax sempre que houver PIS/COFINS próprio. Quando omitido, o Ambiente Nacional emite a nota sem a base (vBCPisCofins), e alguns layouts municipais usam o valor dos serviços como base.
• Os tributos próprios não reduzem o valor líquido da nota.

Retenções (descontadas do pagamento pelo tomador)

Campo	Formato	Significado
pisAmountWithheld	reais	PIS retido pelo tomador.
cofinsAmountWithheld	reais	COFINS retida pelo tomador.
csllAmountWithheld	reais	CSLL retida pelo tomador.
irAmountWithheld	reais	IRRF retido pelo tomador.
inssAmountWithheld	reais	Contribuição previdenciária (INSS) retida.
issAmountWithheld	reais	ISS retido (tributo municipal, citado aqui porque entra no valor líquido).
othersAmountWithheld	reais	Outras retenções.

• Retenção não tem alíquota na API: informe apenas o valor retido.
• A soma de todas as retenções é descontada do valor líquido da nota.
• Uma retenção conta como "retida" quando o valor é maior que zero. Informe os valores já arredondados a duas casas.
• Ao informar qualquer retenção, a plataforma não calcula as demais automaticamente — veja Cálculo automático das retenções.

CSLL própria (csllAmount, csllRate)

A API aceita csllAmount e csllRate, mas o Ambiente Nacional e a Prefeitura de São Paulo não têm campo para CSLL própria — nesses ambientes os dois campos não são enviados. Na prática, a CSLL aparece na NFS-e apenas como retida (csllAmountWithheld).

CST do PIS/COFINS (cstPisCofins)

Faixa	Códigos
Operações de saída	00 Nenhum · 01 Alíquota básica · 02 Alíquota diferenciada · 03 Alíquota por unidade de medida · 04 Monofásica, revenda a alíquota zero · 05 Substituição tributária · 06 Alíquota zero · 07 Isenta · 08 Sem incidência · 09 Com suspensão
Outras saídas e créditos	49 Outras operações de saída · 50 a 56 Operações com direito a crédito · 60 a 67 Crédito presumido
Entradas e demais	70 a 75 Aquisições sem direito a crédito (isenção, suspensão, alíquota zero, sem incidência, substituição tributária) · 98 Outras operações de entrada · 99 Outras operações

• Envie o código como texto de dois dígitos ("01", não 1).
• No Ambiente Nacional, se o CST não for informado, a nota sai com 00.
• Com CST 00, 08 ou 09, a base de cálculo (vBCPisCofins) não é enviada, mesmo que pisCofinsBaseTax tenha sido informado — o Ambiente Nacional rejeita a base nesses casos.

Exemplos de requisição

Os exemplos mostram apenas os campos de tributos federais. Uma requisição real inclui também tomador, código de serviço e descrição — veja Emissão de NFS-e com retenções.

A — Somente PIS/COFINS próprios

Serviço de R$ 1.000,00, PIS 0,65% e COFINS 3%, sem retenção:

{
  "servicesAmount": 1000.00,
  "cstPisCofins": "01",
  "pisCofinsBaseTax": 1000.00,
  "pisRate": 0.0065,
  "pisAmount": 6.50,
  "cofinsRate": 0.03,
  "cofinsAmount": 30.00
}

O valor líquido continua R$ 1.000,00.

B — Somente retenções

Serviço de R$ 1.000,00 com PIS, COFINS e CSLL retidos (0,65%, 3% e 1%):

{
  "servicesAmount": 1000.00,
  "irAmountWithheld": 0,
  "pisAmountWithheld": 6.50,
  "cofinsAmountWithheld": 30.00,
  "csllAmountWithheld": 10.00,
  "inssAmountWithheld": 0
}

A soma das retenções (R$ 46,50) é descontada: o valor líquido é R$ 953,50. Como uma retenção foi informada, a plataforma não calcula nenhuma outra — por isso o exemplo informa 0 nas que não se aplicam.

C — Próprios e retidos na mesma nota

{
  "servicesAmount": 1000.00,
  "cstPisCofins": "01",
  "pisCofinsBaseTax": 1000.00,
  "pisRate": 0.0065,
  "pisAmount": 6.50,
  "cofinsRate": 0.03,
  "cofinsAmount": 30.00,
  "irAmountWithheld": 15.00,
  "pisAmountWithheld": 6.50,
  "cofinsAmountWithheld": 30.00,
  "csllAmountWithheld": 10.00,
  "inssAmountWithheld": 0
}

Valor líquido: R$ 1.000,00 − R$ 61,50 de retenções = R$ 938,50. Os R$ 36,50 de PIS/COFINS próprios não entram na conta.

Erros comuns

Erro	Efeito	Correção
Alíquota em percentual (1.65)	Parte dos layouts emite 165%	Envie a fração: 0.0165
Valor retido em pisAmount/cofinsAmount	Valor líquido errado; base do IBS/CBS reduzida	Use pisAmountWithheld/cofinsAmountWithheld
Vírgula como separador (3,00)	JSON inválido	Use ponto: 3.00
Procurar o campo de alíquota da retenção	Ele não existe	Informe só o valor retido
Informar uma retenção e esperar o cálculo das outras	As demais ficam sem retenção	Informe todas as retenções que se aplicam