Pular para o conteúdo principal
Ver como MarkdownDocs para agentes

Emissão de NFS-e em São Paulo: Valor Total Recebido e documentos de reembolso

Desde 01/10/2026 (manual 3.3.9 da Prefeitura de São Paulo), nas notas com IBS e CBS (ibsCbs.classCode informado):

  • o valor da nota deve ser o total recebido, inclusive o que é repassado a terceiros;
  • o Valor Total Recebido não é mais aceito separado: a prefeitura o preenche com o valor da nota;
  • os repasses saem da base de cálculo por documentos de reembolso (ibsCbs.thirdPartyReimbursements.documents).

Cada cenário abaixo é o payload base da matriz de cenários com o grupo ibsCbs e os campos do eixo. O código de serviço, o NBS e o indicador de operação são de exemplo: use os da sua operação.

Formato recomendado

Informe o total da nota em servicesAmount e os repasses em ibsCbs.thirdPartyReimbursements.documents, sem paidAmount (primeiro cenário). O paidAmount nas notas com IBS e CBS é um formato de transição e pode deixar de ser considerado, com aviso prévio.

O que acontece com o paidAmount (notas com IBS e CBS)​

SituaçãoO que a NFE.io faz com o paidAmountCampo que vira o valor da NFS-e (ValorFinalCobrado)
paidAmount não informado—Valor do serviço ¹
paidAmount menor ou igual ao valor do serviço ¹IgnoraValor do serviço ¹
paidAmount acima do valor do serviço ¹, mas não acima da receita própria ² (só multa e juros)Transfere para o valor da notapaidAmount
paidAmount acima da receita própria ², sem documentos de reembolsoIgnoraValor do serviço ¹
paidAmount acima da receita própria ², com documentos cuja soma de amount é exatamente a diferençaTransfere para o valor da notapaidAmount
paidAmount acima da receita própria ², com documentos que não fecham a diferençaRecusa antes do envio, com [E1003]—

¹ Valor do serviço = o primeiro campo informado entre serviceAmountDetails.finalChargedAmount, serviceAmountDetails.initialChargedAmount e servicesAmount.

² Receita própria = serviceAmountDetails.finalChargedAmount, quando informado (já inclui multa e juros); sem ele, o valor do serviço ¹ + serviceAmountDetails.fineAmount + serviceAmountDetails.interestAmount.

Nas notas sem IBS e CBS (sem ibsCbs.classCode), nada muda: o paidAmount continua indo como Valor Total Recebido.

Total com documentos de reembolso (recomendado)​

Agência de publicidade que recebe R$ 1.000,00, dos quais R$ 800,00 são repasse a um veículo de mídia. O total vai em servicesAmount, e o repasse em um documento do tipo AdAgencyMediaReimbursement, identificado pela chave da NFS-e do veículo.

Resultado: NFS-e de R$ 1.000,00, com base de cálculo de R$ 200,00.

{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "[email protected]",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "6394",
  "description": "Serviço de propaganda e publicidade com repasse de mídia (cenário exemplo).",
  "servicesAmount": 1000.0,
  "nbsCode": "114062000",
  "ibsCbs": {
    "operationIndicator": "100301",
    "classCode": "000001",
    "thirdPartyReimbursements": {
      "documents": [
        {
          "otherNationalDfe": {
            "dfeType": "1",
            "dfeKey": "35503081211444777000161000000000123426101234567890"
          },
          "supplier": {
            "type": "LegalEntity",
            "name": "VEICULO DE MIDIA EXEMPLO LTDA",
            "federalTaxNumber": 11444777000161
          },
          "issueDate": "2026-10-01",
          "accrualOn": "2026-10-01",
          "reimbursementType": "AdAgencyMediaReimbursement",
          "amount": 800.0
        }
      ]
    }
  }
}

Um documento por comprovante de repasse, até 100 por nota. Cada amount deve ser menor ou igual ao valor do serviço prestado (erros 625 e 1646 da prefeitura).

Valor recebido em paidAmount com documentos de reembolso (transição)​

O mesmo caso, com a receita própria em servicesAmount e o total em paidAmount. A diferença (R$ 800,00) precisa ser exatamente a soma dos documentos.

Resultado: o valor do paidAmount é transferido para o valor da nota: NFS-e de R$ 1.000,00, com base de cálculo de R$ 200,00.

{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "[email protected]",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "6394",
  "description": "Serviço de propaganda e publicidade com repasse de mídia (cenário exemplo).",
  "servicesAmount": 200.0,
  "paidAmount": 1000.0,
  "nbsCode": "114062000",
  "ibsCbs": {
    "operationIndicator": "100301",
    "classCode": "000001",
    "thirdPartyReimbursements": {
      "documents": [
        {
          "otherNationalDfe": {
            "dfeType": "1",
            "dfeKey": "35503081211444777000161000000000123426101234567890"
          },
          "supplier": {
            "type": "LegalEntity",
            "name": "VEICULO DE MIDIA EXEMPLO LTDA",
            "federalTaxNumber": 11444777000161
          },
          "issueDate": "2026-10-01",
          "accrualOn": "2026-10-01",
          "reimbursementType": "AdAgencyMediaReimbursement",
          "amount": 800.0
        }
      ]
    }
  }
}

Se a soma dos documentos fosse R$ 500,00, a nota seria recusada antes do envio:

[E1003] Desde 01/10/2026 a Prefeitura de São Paulo preenche o Valor Total Recebido com o valor da nota e não aceita mais o paidAmount separado no leiaute com IBS/CBS. O valor da nota passa a ser o total recebido (R$ 1.000,00). A diferença de R$ 800,00 em relação ao valor do serviço, com multa e juros (R$ 200,00), precisa ser informada como reembolso, repasse ou ressarcimento a terceiros em ibsCbs.thirdPartyReimbursements.documents, com os documentos que comprovam o repasse. Os documentos enviados somam R$ 500,00; faltam R$ 300,00. Depois, reenvie a nota.

Quando a soma passa da diferença, a mensagem diz quanto sobra, o que reduziria a base de cálculo abaixo do valor do serviço.

Valor recebido em paidAmount sem documentos de reembolso​

paidAmount acima do valor do serviço, sem thirdPartyReimbursements.

Resultado: o paidAmount é ignorado. A NFS-e sai com o valor do serviço (R$ 200,00), como a prefeitura já emite desde 01/10/2026, sem recusa. A nota não reflete o total recebido: para isso, use o cenário recomendado.

{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "[email protected]",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "6394",
  "description": "Serviço de propaganda e publicidade (cenário exemplo).",
  "servicesAmount": 200.0,
  "paidAmount": 1000.0,
  "nbsCode": "114062000",
  "ibsCbs": {
    "operationIndicator": "100301",
    "classCode": "000001"
  }
}

Multa e juros no valor recebido​

Serviço de R$ 1.000,00 pago com atraso: multa de R$ 7,00 e juros de R$ 3,00, total de R$ 1.010,00. Multa e juros fazem parte da receita própria e não precisam de documento de reembolso.

Resultado: o paidAmount é transferido para o valor da nota: NFS-e de R$ 1.010,00.

{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "[email protected]",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria pago com atraso (cenário exemplo).",
  "servicesAmount": 1000.0,
  "paidAmount": 1010.0,
  "serviceAmountDetails": {
    "fineAmount": 7.0,
    "interestAmount": 3.0
  },
  "nbsCode": "101010100",
  "ibsCbs": {
    "operationIndicator": "050101",
    "classCode": "000001"
  }
}
nota

Com serviceAmountDetails.finalChargedAmount informado, ele já é a receita própria (inclui multa e juros), e a multa e os juros não são somados de novo. Nesse caso, o que o paidAmount passar do finalChargedAmount é tratado como repasse: só vai para o valor da nota com documentos de reembolso que somem exatamente essa diferença. Sem documentos, o paidAmount é ignorado e a nota sai com o finalChargedAmount.

Valor Inicial Cobrado (erro 640)​

A prefeitura não aceita mais o campo Valor Inicial Cobrado (erro 640). Quem informa serviceAmountDetails.initialChargedAmount sem finalChargedAmount não precisa mudar a integração.

Resultado: o valor do initialChargedAmount é enviado como valor final cobrado: NFS-e de R$ 1.000,00.

{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "[email protected]",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "4444",
  "description": "Serviço de consultoria (cenário exemplo).",
  "servicesAmount": 1000.0,
  "serviceAmountDetails": {
    "initialChargedAmount": 1000.0
  },
  "nbsCode": "101010100",
  "ibsCbs": {
    "operationIndicator": "050101",
    "classCode": "000001"
  }
}

Outros reembolsos (tipo 99) com documento não fiscal​

Administração de vale-refeição: R$ 1.000,00 recebidos, dos quais R$ 950,00 são repasse a estabelecimentos credenciados. O tipo OtherReimbursement exige reimbursementTypeText (até 150 caracteres). O comprovante é um documento não fiscal (otherDoc).

Resultado: NFS-e de R$ 1.000,00, com base de cálculo de R$ 50,00.

{
  "borrower": {
    "type": "LegalEntity",
    "name": "EMPRESA TOMADORA EXEMPLO LTDA",
    "federalTaxNumber": 11222333000181,
    "email": "[email protected]",
    "address": {
      "country": "BRA",
      "postalCode": "01311-000",
      "street": "Avenida Paulista",
      "number": "1000",
      "district": "Bela Vista",
      "city": {
        "code": "3550308",
        "name": "São Paulo"
      },
      "state": "SP"
    }
  },
  "cityServiceCode": "3205",
  "description": "Administração de vale-refeição (cenário exemplo).",
  "servicesAmount": 1000.0,
  "nbsCode": "117011200",
  "ibsCbs": {
    "operationIndicator": "100301",
    "classCode": "000001",
    "thirdPartyReimbursements": {
      "documents": [
        {
          "otherDoc": {
            "docNumber": "REPASSE-2026-10-001",
            "docDescription": "Relatório de repasse aos estabelecimentos credenciados"
          },
          "supplier": {
            "type": "LegalEntity",
            "name": "ESTABELECIMENTO CREDENCIADO EXEMPLO LTDA",
            "federalTaxNumber": 11444777000161
          },
          "issueDate": "2026-10-01",
          "accrualOn": "2026-10-01",
          "reimbursementType": "OtherReimbursement",
          "reimbursementTypeText": "Repasse a estabelecimentos credenciados",
          "amount": 950.0
        }
      ]
    }
  }
}

A descrição (reimbursementTypeText) só é enviada à prefeitura no tipo OtherReimbursement. Nos demais tipos, ela é ignorada (erros 624 e 1645 da prefeitura).

Documento de reembolso incompleto​

Todo documento precisa de identificação (otherNationalDfe, otherFiscalDoc ou otherDoc), issueDate, reimbursementType válido e amount maior que zero; no tipo OtherReimbursement, também reimbursementTypeText. Sem algum deles, a nota é recusada antes do envio, com o campo indicado:

[E1004] Documentos de reembolso incompletos em ibsCbs.thirdPartyReimbursements.documents: documento 1: informe otherNationalDfe, otherFiscalDoc ou otherDoc. Corrija e reenvie a nota.

Identificação do documento de reembolso​

GrupoQuando usarCampos
otherNationalDfeNFS-e, NF-e ou CT-e do ambiente nacionaldfeType (1 = NFS-e, 2 = NF-e, 3 = CT-e, 9 = outro), dfeKey (chave de acesso) e, só no tipo 9, dfeTypeText
otherFiscalDocDocumento fiscal fora do ambiente nacional, só com competência anterior a 31/12/2025 (erro 622)issuerCityCode (IBGE), fiscalDocNumber, fiscalDocDescription
otherDocDocumento não fiscaldocNumber, docDescription

Tipos de reembolso​

reimbursementTypeUso
RealEstateBrokerPassThroughRepasse de corretagem na intermediação de imóveis
TravelAgencySupplierPassThroughRepasse a fornecedor por agência de turismo
AdAgencyExternalProductionReimbursementReembolso de produção externa por agência de publicidade
AdAgencyMediaReimbursementReembolso de mídia por agência de publicidade
OtherReimbursementOutros reembolsos ou ressarcimentos (exige reimbursementTypeText)

Veja também​

NFE.io

A NFE.io é uma empresa de tecnologia que fornece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas. Com suas ferramentas, as empresas podem economizar tempo e reduzir erros, aumentando a eficiência e precisão do processo de emissão de notas fiscais.

Um dos principais cases de sucesso da NFE.io é a implementação da solução na empresa de transporte Rodonaves. Com a automatização da emissão e gestão de notas fiscais eletrônicas, a Rodonaves conseguiu reduzir em até 80% o tempo gasto nesse processo, o que se traduziu em uma significativa melhoria na eficiência operacional. Além disso, a empresa também conseguiu eliminar erros e atrasos na emissão de notas fiscais, o que melhorou a relação com seus clientes e aumentou a confiança dos órgãos fiscais.

Outro exemplo é a implementação da NFE.io na empresa de comércio eletrônico, a Loja Integrada. Com a automatização da emissão de notas fiscais, a Loja Integrada conseguiu aumentar a velocidade de emissão de notas em até 10 vezes, o que permitiu que a empresa atendesse a uma maior quantidade de clientes e, consequentemente, aumentar as suas vendas.

Além desses exemplos, a NFE.io também tem outros cases de sucesso com empresas de setores como indústria, construção, varejo e serviços, mostrando a versatilidade e eficácia da sua solução.

Em resumo, a NFE.io é uma empresa de tecnologia que oferece soluções para automatizar e simplificar a emissão e gestão de notas fiscais eletrônicas, ajudando as empresas a economizar tempo e reduzir erros, melhorando a eficiência e precisão do processo. Com cases de sucesso em diferentes setores, a NFE.io tem se destacado como uma empresa líder em automação fiscal.