---
title: "NFS-e de São Paulo: Valor Total Recebido e mudanças dos manuais 3.3.7, 3.3.8 e 3.3.9"
description: "Como a NFE.io atende as mudanças da NFS-e Paulistana publicadas nos manuais 3.3.7, 3.3.8 e 3.3.9, com o tratamento do paidAmount, documentos de reembolso, Valor Inicial Cobrado, tributos federais e caracteres permitidos."
source_url: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/sao-paulo-valor-total-recebido-manual-3-3-9/
product: documentacao
last_updated: 2026-10-05
tags: ["reforma-tributaria", "nfse", "sao-paulo", "paulistana", "valor-total-recebido", "layout-rtc"]
---

# NFS-e de São Paulo: o que mudou nos manuais 3.3.7, 3.3.8 e 3.3.9 e como a NFE.io atende

:::info Vigência
O comportamento descrito nesta página vale a partir de **[DATA DA IMPLANTAÇÃO]**. Quer só o essencial? Veja o [resumo das mudanças](./sao-paulo-resumo-valor-total-recebido.md).
:::

## 1. Resumo

A Prefeitura de São Paulo publicou três versões do manual do web service da NFS-e Paulistana entre junho e outubro de 2026. A 3.3.9 foi publicada em **01/10/2026**, já valendo. As mudanças que afetam a sua integração:

| Manual | Data | O que mudou | O que você precisa fazer |
|---|---|---|---|
| 3.3.6 e 3.3.7 | Maio e junho/2026 | Nova sistemática dos tributos federais (PIS, COFINS e CSLL), em vigor desde 14/05/2026. A retenção passa a ser indicada no elemento `RetencaoPisCofins`, do tipo `tpRetencaoPisCofins` (nome definido na 3.3.7). O Valor Inicial Cobrado não é mais aceito (erro 640, já presente na 3.3.7) | Informar corretamente os valores de PIS/COFINS próprios e retidos (seção 6). A NFE.io monta o campo de retenção automaticamente e converte o Valor Inicial Cobrado (seção 5) |
| 3.3.8 | Setembro/2026 | Campos de texto restritos ao conjunto de caracteres Latin-1 (novo XSD v02-6) | Evitar emojis e caracteres especiais fora do Latin-1 (seção 7) |
| 3.3.9 | 01/10/2026 | O **Valor Total Recebido** passa a ser preenchido pela prefeitura com o valor da nota. Novas validações | Para quem informa Valor Recebido: enviar o **total em `servicesAmount`** com os **documentos de reembolso** e deixar de usar o `paidAmount` (seções 3 e 4) |

**O ponto mais importante:** com a implantação da NFE.io em [DATA DA IMPLANTAÇÃO], **as notas enviadas sem documentos de reembolso continuam sendo emitidas como hoje, sem recusa nova.** A NFE.io só passa a recusar quando os documentos de reembolso são enviados com valores que não fecham a diferença ou com dados incompletos, mesmo que a prefeitura aceitasse a nota.

## 2. A quem se aplica

As regras do Valor Total Recebido (seção 3) valem só para notas emitidas no **leiaute com IBS e CBS**, o leiaute 2 da prefeitura.

| Leiaute | Quando a NFE.io usa | Valor Total Recebido |
|---|---|---|
| **Leiaute 2 (com IBS/CBS)** | Quando a nota traz o grupo `ibsCbs` com `classCode` (classificação tributária) | **Regra nova** (seção 3) |
| **Leiaute 1 (sem IBS/CBS)** | Quando a nota não traz `ibsCbs.classCode` | **Nada muda.** O `paidAmount` continua sendo enviado como Valor Total Recebido |

A prefeitura mantém os dois leiautes disponíveis (alerta 1651). Cabe ao emissor observar a data de obrigatoriedade do destaque de IBS e CBS, conforme o Ato Conjunto RFB/CGIBS nº 4/2026 ou posterior.

**Serviços mais afetados** são os que recebem valores repassados a terceiros, previstos na IN SF/SUREM nº 8/2018, na IN SF/SUREM nº 11/2025 e no leiaute nacional:

| Item (Lei 13.701/2003) | Serviço |
|---|---|
| 10.08 | Agenciamento de publicidade e propaganda (repasse de mídia e de produção externa) |
| 17.11 | Administração de vale-refeição, alimentação, transporte e congêneres |
| 33.01 | Desembaraço aduaneiro |
| 17.12 | Leilão e congêneres |
| 6.01 e 6.02 | Barbearia e estética, quando o salão-parceiro é do Simples Nacional |
| 10.05 | Intermediação de imóveis (repasse a corretores) |
| 9.02 | Agência de turismo (repasse a fornecedores) |

## 3. Valor da nota e Valor Total Recebido (manual 3.3.9)

### 3.1 O que a prefeitura mudou

**Até 30/09/2026**, era possível enviar dois valores separados:
- o **valor do serviço** (a receita própria);
- o **Valor Total Recebido** (o total, incluindo o que é repassado a terceiros).

**Desde 01/10/2026**, no leiaute com IBS e CBS:
- o **valor da nota** deve ser o **total recebido**, inclusive os valores repassados a terceiros como reembolso, repasse ou ressarcimento;
- o **Valor Total Recebido** não deve mais ser informado. A prefeitura o preenche automaticamente com o valor da nota (alerta 1644 do manual). Quando ele é enviado, a prefeitura o **descarta**;
- os repasses saem da base de cálculo do ISS, do IBS e da CBS por meio de **documentos referenciados de reembolso**: o documento fiscal de cada terceiro.

Na prática, desde 01/10, a nota de quem enviava o Valor Recebido separado foi emitida pela prefeitura **apenas com o valor do serviço**. A prefeitura não recusa a nota: só emite um alerta.

### 3.2 Como enviar: o formato recomendado

**O formato correto, alinhado à regra da prefeitura,** é informar o **valor total da nota em `servicesAmount`** e os repasses em `ibsCbs.thirdPartyReimbursements.documents`, **sem usar o `paidAmount`**. Nesse formato, a prefeitura emite a nota com o valor total e tira os repasses da base de cálculo. Veja o exemplo na seção 3.4.

O `paidAmount` no leiaute com IBS e CBS é um **formato de transição**. A NFE.io continua aceitando-o (seção 3.3), para que nenhuma integração pare. Mas ele **pode deixar de ser considerado**, com aviso prévio. **Recomendamos migrar para o formato acima.**

### 3.3 Como a NFE.io trata o `paidAmount` a partir de [DATA DA IMPLANTAÇÃO]

#### Em resumo: o que acontece com o valor do `paidAmount`

Campos do layout de entrada da NFE.io usados neste resumo:

| Campo do layout de entrada | O que representa | Na NFS-e de São Paulo |
|---|---|---|
| `paidAmount` | Valor total recebido, incluindo repasses a terceiros | Valor Total Recebido (`ValorTotalRecebido`) |
| `servicesAmount` | Valor do serviço | Valor final cobrado (`ValorFinalCobrado`), quando não há valor mais específico |
| `serviceAmountDetails.finalChargedAmount` | Valor final cobrado, já com multa e juros | Valor final cobrado (`ValorFinalCobrado`) |
| `serviceAmountDetails.initialChargedAmount` | Valor inicial cobrado | Enviado como valor final cobrado (`ValorFinalCobrado`), quando não há `finalChargedAmount` (seção 5) |
| `serviceAmountDetails.fineAmount` | Multa | Valor da multa (`ValorMulta`) |
| `serviceAmountDetails.interestAmount` | Juros | Valor dos juros (`ValorJuros`) |
| `ibsCbs.classCode` | Classificação tributária de IBS/CBS. Define o leiaute 2 | Grupo IBS/CBS (`cClassTrib`) |
| `ibsCbs.thirdPartyReimbursements.documents` | Documentos de reembolso, um por repasse | Grupo de reembolso (`gReeRepRes`) |
| `ibsCbs.thirdPartyReimbursements.documents[].amount` | Valor de cada repasse | Valor do reembolso (`vlrReeRepRes`) |

**Nas notas sem IBS e CBS (leiaute 1, sem `ibsCbs.classCode`):** nada muda. O `paidAmount` continua sendo enviado à prefeitura como Valor Total Recebido (`ValorTotalRecebido`).

**Nas notas com IBS e CBS (leiaute 2, com `ibsCbs.classCode`):** o `paidAmount` **nunca é enviado à prefeitura como Valor Total Recebido**, porque desde 01/10/2026 a prefeitura descarta esse campo e o preenche com o valor da nota (`ValorFinalCobrado`). A NFE.io usa o `paidAmount` apenas para decidir o valor da nota:

| Situação (campos do layout de entrada) | O que a NFE.io faz com o `paidAmount` | Campo do layout de entrada cujo valor vai para o `ValorFinalCobrado` (valor da NFS-e) |
|---|---|---|
| `paidAmount` não informado | — | Valor do serviço ¹: `serviceAmountDetails.finalChargedAmount`, ou `serviceAmountDetails.initialChargedAmount`, ou `servicesAmount` |
| `paidAmount` menor ou igual ao valor do serviço ¹ | **Ignora** o `paidAmount` | Valor do serviço ¹: `serviceAmountDetails.finalChargedAmount`, ou `serviceAmountDetails.initialChargedAmount`, ou `servicesAmount` |
| `paidAmount` acima do valor do serviço ¹, mas **não acima da receita própria ²** (a diferença é só multa e juros) | **Transfere** o valor do `paidAmount` para o `ValorFinalCobrado`, **no lugar** do valor do serviço ¹ | **`paidAmount`** |
| `paidAmount` acima da receita própria ², **sem** `ibsCbs.thirdPartyReimbursements.documents` | **Ignora** o `paidAmount` | Valor do serviço ¹: `serviceAmountDetails.finalChargedAmount`, ou `serviceAmountDetails.initialChargedAmount`, ou `servicesAmount`, como a prefeitura já emite desde 01/10/2026 |
| `paidAmount` acima da receita própria ², **com** `ibsCbs.thirdPartyReimbursements.documents` cuja soma de `amount` é **exatamente** a diferença | **Transfere** o valor do `paidAmount` para o `ValorFinalCobrado`, **no lugar** do valor do serviço ¹. Os `amount` dos documentos vão para o `vlrReeRepRes` e tiram os repasses da base de cálculo | **`paidAmount`** |
| `paidAmount` acima da receita própria ², **com** `ibsCbs.thirdPartyReimbursements.documents` cuja soma de `amount` **não fecha** a diferença | Recusa a nota antes do envio à prefeitura, com `[E1003]` | — (nota não enviada) |

¹ **Valor do serviço** é o **primeiro campo informado** nesta ordem: `serviceAmountDetails.finalChargedAmount`, depois `serviceAmountDetails.initialChargedAmount`, depois `servicesAmount`. Exemplo: se a nota traz só `servicesAmount`, o valor do serviço é o `servicesAmount`. Se traz `servicesAmount` e `serviceAmountDetails.finalChargedAmount`, o valor do serviço é o `finalChargedAmount`.

² **Receita própria** é o `serviceAmountDetails.finalChargedAmount`, quando informado, porque ele já inclui multa e juros. Sem ele, é o valor do serviço ¹ + `serviceAmountDetails.fineAmount` + `serviceAmountDetails.interestAmount`. Atenção: com `finalChargedAmount` informado, multa e juros não são somados de novo, e o que o `paidAmount` passar do `finalChargedAmount` é tratado como repasse.

**Exemplo de transferência:** a nota traz `servicesAmount` = 27,59, `paidAmount` = 1.414,22 e documentos em `ibsCbs.thirdPartyReimbursements.documents` com `amount` somando 1.386,63. O valor do `paidAmount` (1.414,22) é transferido para o `ValorFinalCobrado`, e o `servicesAmount` (27,59) deixa de ser o valor da nota. O mesmo resultado se obtém, sem transferência, enviando `servicesAmount` = 1.414,22 com os mesmos documentos e sem `paidAmount`, que é o formato recomendado.

O mesmo fluxo, em diagrama:

```mermaid
flowchart TD
    A["Nota com ibsCbs.classCode?"] -->|Não| B["Leiaute 1: paidAmount vai como ValorTotalRecebido"]
    A -->|Sim| C["paidAmount informado e maior que o valor do serviço?"]
    C -->|Não| D["ValorFinalCobrado = valor do serviço"]
    C -->|Sim| E["paidAmount até a receita própria (só multa e juros)?"]
    E -->|Sim| F["ValorFinalCobrado = paidAmount"]
    E -->|Não| G["Há documentos em ibsCbs.thirdPartyReimbursements.documents?"]
    G -->|Não| D
    G -->|Sim| H["Soma de amount = paidAmount menos a receita própria?"]
    H -->|Sim| F
    H -->|Não| I["Recusa com E1003, sem envio à prefeitura"]
```

**Quando o tratamento do `paidAmount` for desligado** (com aviso prévio), o `paidAmount` passa a ser **totalmente ignorado** nas notas com `ibsCbs.classCode`. **Não há mais transferência:** o `ValorFinalCobrado` recebe sempre o valor do serviço ¹ (`serviceAmountDetails.finalChargedAmount`, ou `serviceAmountDetails.initialChargedAmount`, ou `servicesAmount`), e a conferência `[E1003]` deixa de existir.

**Recomendação:** nas notas com `ibsCbs.classCode`, não use o `paidAmount`. Envie o total da nota em `servicesAmount` e os repasses em `ibsCbs.thirdPartyReimbursements.documents` (seção 3.2). Esse formato funciona hoje e continuará funcionando depois que o tratamento do `paidAmount` for desligado.

#### Detalhamento

Os campos da API envolvidos:

| Campo da API | Significado |
|---|---|
| `servicesAmount` | Valor do serviço (a sua receita própria) |
| `paidAmount` | Valor total recebido, incluindo repasses a terceiros |
| `serviceAmountDetails.finalChargedAmount` | Valor final cobrado (opcional; inclui multa e juros) |
| `serviceAmountDetails.initialChargedAmount` | Valor inicial cobrado (opcional; ver seção 5) |
| `serviceAmountDetails.fineAmount` / `interestAmount` | Multa e juros (opcionais) |
| `ibsCbs.thirdPartyReimbursements.documents` | Documentos de reembolso (seção 4) |

Antes de aplicar a regra, a plataforma calcula dois valores:
- **Valor declarado** é o primeiro informado, nesta ordem: `finalChargedAmount` > `initialChargedAmount` > `servicesAmount`.
- **Receita própria** é o `finalChargedAmount`, quando informado, porque ele já inclui multa e juros. Sem ele, é o valor declarado + `fineAmount` + `interestAmount`.

**Comportamento no leiaute com IBS e CBS:**

| # | O que você envia | Valor da NFS-e | Valor Total Recebido | Resultado |
|---|---|---|---|---|
| 1 | Sem `paidAmount` | Valor declarado | Preenchido pela prefeitura com o valor da nota | Emitida, como hoje |
| 2 | `paidAmount` menor ou igual ao valor declarado | Valor declarado | Idem | Emitida, como hoje |
| 3 | `paidAmount` acima do valor declarado, mas **não acima da receita própria** (a diferença é só multa e juros) | `paidAmount` | Idem | Emitida com o total recebido |
| 4 | `paidAmount` acima da receita própria, **sem documentos de reembolso** | Valor declarado | Idem | **Emitida como a prefeitura já emite desde 01/10, sem recusa.** A nota não reflete o total recebido. Recomendamos enviar os documentos |
| 5 | `paidAmount` acima da receita própria, **com documentos que somam exatamente a diferença** | `paidAmount` | Idem | **Emitida com o total recebido.** Os repasses saem da base de cálculo. O resultado é o mesmo do formato recomendado (seção 3.2), mas ainda depende do `paidAmount`, que é de transição |
| 6 | Documentos que **não somam exatamente** a diferença | — | — | **Recusada pela NFE.io** com `[E1003]`, antes do envio à prefeitura |
| 7 | Documento com dados incompletos | — | — | **Recusada pela NFE.io** com `[E1004]`, antes do envio à prefeitura |

**Por que a soma dos documentos precisa ser exata:**
- **se faltar**, a prefeitura cobraria ISS sobre o valor repassado, que não é receita sua;
- **se sobrar**, a base de cálculo ficaria abaixo da sua receita própria e o imposto seria declarado a menor.

Quando a NFE.io recusa uma nota com `[E1003]` ou `[E1004]`, a nota **não é enviada à prefeitura**. Basta corrigir e reenviar.

**Quando o tratamento do `paidAmount` for desligado** (com aviso prévio):
- o `paidAmount` passa a ser **ignorado** no leiaute com IBS e CBS;
- o valor da nota vem só do campo próprio: `finalChargedAmount`, `initialChargedAmount` ou `servicesAmount`;
- os casos 3 e 5 deixam de usar o `paidAmount`, e a conferência `[E1003]` deixa de existir.

⚠️ Quem estiver no caso 5 (com `paidAmount` e documentos) precisa migrar **antes** do desligamento, passando o total para `servicesAmount`. Senão, os documentos ficam maiores que o valor do serviço, e a prefeitura recusa a nota com o erro 1646.

### 3.4 Exemplo: administração de vale-refeição

O cliente cobra R$ 1.414,22. Desse total, R$ 27,59 são a taxa de administração (receita própria) e R$ 1.386,63 são repasse aos estabelecimentos credenciados.

**Antes (até a implantação):** a nota é emitida com valor de R$ 27,59, e o total de R$ 1.414,22 é descartado pela prefeitura.

**Sem documentos (caso 4):** o envio abaixo continua emitindo a nota com R$ 27,59, sem recusa.

```json
{
  "servicesAmount": 27.59,
  "paidAmount": 1414.22,
  "ibsCbs": { "classCode": "000001" }
}
```

**Com documentos (caso 5):** a nota sai com valor de **R$ 1.414,22**, e os R$ 1.386,63 saem da base de cálculo.

```json
{
  "servicesAmount": 27.59,
  "paidAmount": 1414.22,
  "ibsCbs": {
    "classCode": "000001",
    "thirdPartyReimbursements": {
      "documents": [
        {
          "otherNationalDfe": {
            "dfeType": "1",
            "dfeKey": "35503081234567890001230000000000123426101234567890"
          },
          "supplier": {
            "type": "LegalEntity",
            "name": "RESTAURANTE CREDENCIADO LTDA",
            "federalTaxNumber": 12345678000190
          },
          "issueDate": "2026-10-01",
          "accrualOn": "2026-10-01",
          "reimbursementType": "OtherReimbursement",
          "reimbursementTypeText": "Repasse a estabelecimentos credenciados",
          "amount": 1386.63
        }
      ]
    }
  }
}
```

Diferença a comprovar = 1.414,22 − 27,59 = **1.386,63**, igual à soma dos documentos. A nota é emitida.

**Com documentos que não fecham (caso 6):** se o documento acima tivesse `amount` de 1.000,00, a NFE.io recusaria a nota com:

> [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.414,22). A diferença de R$ 1.386,63 em relação ao valor do serviço, com multa e juros (R$ 27,59), 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$ 1.000,00; faltam R$ 386,63. Depois, reenvie a nota.

Quando a soma passa da diferença, a mensagem diz quanto **sobra**.

**Formato recomendado (sem `paidAmount`):** o total vai em `servicesAmount`, com os mesmos documentos de reembolso.

```json
{
  "servicesAmount": 1414.22,
  "ibsCbs": {
    "classCode": "000001",
    "thirdPartyReimbursements": {
      "documents": [
        {
          "otherNationalDfe": { "dfeType": "1", "dfeKey": "35503081234567890001230000000000123426101234567890" },
          "supplier": { "type": "LegalEntity", "name": "RESTAURANTE CREDENCIADO LTDA", "federalTaxNumber": 12345678000190 },
          "issueDate": "2026-10-01",
          "accrualOn": "2026-10-01",
          "reimbursementType": "OtherReimbursement",
          "reimbursementTypeText": "Repasse a estabelecimentos credenciados",
          "amount": 1386.63
        }
      ]
    }
  }
}
```

A nota sai com R$ 1.414,22, e os R$ 1.386,63 saem da base de cálculo, que fica em R$ 27,59. Nesse formato, a NFE.io não confere a soma dos documentos, porque não há valor recebido para comparar. Quem confere é a prefeitura: cada documento deve ser menor ou igual ao valor do serviço (erro 1646). As validações de documento incompleto (`[E1004]`) continuam valendo. **Esse formato funciona com o tratamento do `paidAmount` ligado ou desligado.**

### 3.5 Exemplo: agência de publicidade com repasse de mídia

Uma agência recebe R$ 319.233,64, todo ele repasse a veículos de mídia, e envia `servicesAmount` = 0. Ela deve informar um documento para cada nota fiscal do veículo, com `reimbursementType` = `AdAgencyMediaReimbursement`. A soma dos `amount` deve ser **R$ 319.233,64**.

Sem os documentos, a nota continua sendo emitida pela prefeitura com valor zero (caso 4).

### 3.6 Exemplo: multa e juros

O serviço custa R$ 100,00, e o cliente pagou R$ 110,00 por atraso (multa de R$ 7,00 e juros de R$ 3,00).

```json
{
  "servicesAmount": 100.00,
  "paidAmount": 110.00,
  "serviceAmountDetails": { "fineAmount": 7.00, "interestAmount": 3.00 },
  "ibsCbs": { "classCode": "000001" }
}
```

A nota é emitida com **R$ 110,00**. Multa e juros não são repasse a terceiros, então **não** é preciso enviar documento de reembolso (caso 3).

## 4. Documentos de reembolso, repasse e ressarcimento

### 4.1 Estrutura

Os documentos vão em `ibsCbs.thirdPartyReimbursements.documents`, uma lista com até 100 documentos por nota. Cada documento:

| Campo | Obrigatório | Descrição |
|---|---|---|
| **Identificação** (um dos três abaixo) | Sim | O documento que comprova o repasse |
| `otherNationalDfe` | — | Documento do ambiente nacional: NFS-e, NF-e, CT-e ou outro |
| `otherFiscalDoc` | — | Documento fiscal fora do ambiente nacional. **Só para competência anterior a 31/12/2025** (erro 622 da prefeitura) |
| `otherDoc` | — | Documento não fiscal |
| `supplier` | Não | Fornecedor do documento (o terceiro que recebeu o repasse) |
| `issueDate` | **Sim** | Data de emissão do documento (AAAA-MM-DD) |
| `accrualOn` | Recomendado | Data de competência do documento (AAAA-MM-DD). Se não for informada, a NFE.io usa a data de emissão |
| `reimbursementType` | **Sim** | Tipo de reembolso (tabela 4.2) |
| `reimbursementTypeText` | **Só no tipo `OtherReimbursement`** | Descrição do reembolso, até 150 caracteres |
| `amount` | **Sim** | Valor repassado, maior que zero |

### 4.2 Tipos de reembolso

| `reimbursementType` | Código na prefeitura | Uso |
|---|---|---|
| `RealEstateBrokerPassThrough` | 1 | Repasse de remuneração por intermediação de imóveis a demais corretores |
| `TravelAgencySupplierPassThrough` | 2 | Repasse a fornecedor, por agência de turismo |
| `AdAgencyExternalProductionReimbursement` | 3 | Reembolso a agência de publicidade por produção externa por conta e ordem de terceiro |
| `AdAgencyMediaReimbursement` | 4 | Reembolso a agência de publicidade por mídia por conta e ordem de terceiro |
| `OtherReimbursement` | 99 | Outros reembolsos ou ressarcimentos. **Exige `reimbursementTypeText`** |

A descrição (`reimbursementTypeText`) só é enviada à prefeitura no tipo `OtherReimbursement`. Nos demais tipos, ela é ignorada, porque a prefeitura recusa a descrição fora do tipo 99 (erros 624 e 1645). Textos acima de 150 caracteres são cortados.

### 4.3 Identificação do documento

**Documento do ambiente nacional (`otherNationalDfe`):**

| Campo | Descrição |
|---|---|
| `dfeType` | `1` = NFS-e, `2` = NF-e, `3` = CT-e, `9` = outro |
| `dfeKey` | Chave de acesso do documento (até 50 caracteres) |
| `dfeTypeText` | Descrição do documento. **Só no `dfeType` = 9**; nos outros tipos, deixe vazio |

**Documento fiscal fora do ambiente nacional (`otherFiscalDoc`):** só para documentos com competência anterior a 31/12/2025.

| Campo | Descrição |
|---|---|
| `issuerCityCode` | Código IBGE do município emissor (7 dígitos) |
| `fiscalDocNumber` | Número do documento |
| `fiscalDocDescription` | Descrição do documento |

**Documento não fiscal (`otherDoc`):**

| Campo | Descrição |
|---|---|
| `docNumber` | Número do documento |
| `docDescription` | Descrição do documento |

### 4.4 Fornecedor (`supplier`)

| Situação | Como a NFE.io envia |
|---|---|
| `federalTaxNumber` com `type` = `NaturalPerson` | CPF |
| `federalTaxNumber` com outro `type` ou sem `type` | CNPJ |
| `address.country` estrangeiro informado (diferente de BRA/Brasil) | NIF (identificação fiscal estrangeira) |
| Sem `federalTaxNumber` | "Não informado na nota de origem" |
| `name` | Razão social, até 75 caracteres |

### 4.5 Validações da prefeitura sobre os documentos

Estas validações são feitas pela prefeitura. Se o envio não respeitar, a nota volta com o erro dela:

| Erro | Regra |
|---|---|
| 617 / 618 | O tipo e o valor do documento são obrigatórios |
| 622 | `otherFiscalDoc` só para competência anterior a 31/12/2025 |
| 623 | A data de emissão do documento deve ser igual ou posterior à data de competência |
| 624 / 1645 | Descrição do tipo só quando o tipo for 99 (a NFE.io já trata) |
| 625 / 1646 | O valor de cada reembolso deve ser menor ou igual ao valor do serviço prestado |
| 1643 | Para alguns serviços, o grupo de reembolso não é permitido |
| 1653 / 1654 | A data de emissão ou de competência do documento não pode ser posterior à data atual nem à data do fato gerador |

## 5. Valor Inicial Cobrado (manual 3.3.7, erro 640)

A prefeitura não aceita mais o campo **Valor Inicial Cobrado** (erro 640). O valor da nota deve ir sempre no **Valor Final Cobrado**.

**Como a NFE.io atende:** se você informa `serviceAmountDetails.initialChargedAmount` sem informar o `finalChargedAmount`, o valor do inicial é enviado como valor final cobrado. **Não é preciso alterar a integração**, e as notas que eram recusadas com o erro 640 passam a ser emitidas.

| `finalChargedAmount` | `initialChargedAmount` | Valor enviado como valor final cobrado |
|---|---|---|
| informado | qualquer | `finalChargedAmount` |
| não informado | informado | `initialChargedAmount` |
| não informado | não informado | `servicesAmount` |

## 6. Tributos federais: PIS, COFINS e CSLL (manuais 3.3.5 a 3.3.7)

A sistemática nova vale desde **14/05/2026** para os leiautes 1 e 2. A NFE.io já está adequada. O que você precisa informar:

| Campo da API | O que informar | Vai para a prefeitura como |
|---|---|---|
| `pisAmount` | PIS de apuração própria (sem retenção) | `ValorPIS` |
| `cofinsAmount` | COFINS de apuração própria (sem retenção) | `ValorCOFINS` |
| `pisAmountWithheld` | PIS retido pelo tomador | Somado em `ValorCSLL` |
| `cofinsAmountWithheld` | COFINS retida pelo tomador | Somado em `ValorCSLL` |
| `csllAmountWithheld` | CSLL retida pelo tomador | Somado em `ValorCSLL` |
| `irAmountWithheld` | IR retido | `ValorIR` |
| `inssAmountWithheld` | INSS retido | `ValorINSS` |

O campo `ValorCSLL` passa a representar o total das contribuições sociais retidas: PIS + COFINS + CSLL. A NFE.io indica à prefeitura quais delas foram retidas, pelo elemento **Retenção PIS/COFINS** (`RetencaoPisCofins`), calculado automaticamente:

| Retidos | Código |
|---|---|
| Nenhum | 0 |
| PIS, COFINS e CSLL | 3 |
| PIS e COFINS | 4 |
| Só PIS | 5 |
| Só COFINS | 6 |
| COFINS e CSLL | 7 |
| Só CSLL | 8 |
| PIS e CSLL | 9 |

O campo **Pagamento Parcelado Antecipado** (`isEarlyInstallmentPayment`) deixou de ser obrigatório no leiaute 2. A NFE.io só o envia quando ele é `true`.

## 7. Caracteres e tamanho dos campos de texto (manual 3.3.8, XSD v02-6)

### 7.1 Caracteres permitidos

Os campos de texto aceitam **apenas caracteres do conjunto Latin-1** (ISO-8859-1): letras com acento do português, números e a pontuação comum. **Não são aceitos:**
- emojis;
- travessão (–) e reticências (…) tipográficos;
- aspas curvas (“ ” ‘ ’);
- marcadores (•);
- caracteres invisíveis, como o WORD JOINER (U+2060).

Quando um desses caracteres aparece, a NFE.io recusa a nota **antes** do envio com `[E1002]`, informando o caractere e o campo. Basta trocá-lo por um equivalente: hífen (-), três pontos (...), aspas retas ("), ou removê-lo.

A regra vale para descrição do serviço, endereço (logradouro, número, complemento, bairro), série do RPS, descrição de evento e demais campos de texto.

### 7.2 Tamanho do endereço

| Campo | Limite da prefeitura | Como a NFE.io atende |
|---|---|---|
| Logradouro | 50 caracteres | Corta em 50 caracteres, preservando o início. O tipo do logradouro ("Rua", "Av" etc.) é enviado em campo próprio |
| Bairro | 30 caracteres | A primeira palavra é sempre abreviada (por exemplo, "Conjunto" vira "Cj." e palavras sem abreviação conhecida ficam com as 3 primeiras letras e ponto). As demais palavras só são abreviadas quando o bairro passa de 30 caracteres ("Habitacional" vira "Hab."). Se ainda passar de 30, é cortado em 30 |
| Número | 10 caracteres | Corta em 10 |
| Complemento | 30 caracteres | Corta em 30 |

Antes desse ajuste, logradouros e bairros longos eram recusados pela prefeitura com o erro 1001 (XML não compatível com o schema). Para que o endereço apareça completo na nota, recomendamos enviá-lo já dentro desses limites.

## 8. Novas validações da prefeitura no manual 3.3.9

Estas validações dependem dos dados enviados. Quando a regra não é atendida, a nota volta com o erro da prefeitura:

| Erro | Regra | O que fazer |
|---|---|---|
| 638 | O local da prestação, determinado pelo indicador de operação, deve ser informado | Informar o local da prestação compatível com o `cIndOp` |
| 649 / 650 | Obras: o CIB/Cadastro de Obras não pode ser usado no momento; informe o endereço do imóvel | Enviar o endereço do imóvel |
| 651 | Para a classificação tributária informada, o local de incidência do IBS deve ser um endereço nacional | Revisar a classificação tributária ou o local |
| 657 | Exportação de serviços exige local de prestação no exterior | Informar o local da prestação no exterior |
| 658 | O grupo de eventos só é aceito para serviços do item 12 da Lei 13.701/2003 | Não enviar o grupo de eventos para outros serviços |
| 659 | Classificação tributária com prefixo 550 (CST 550, suspensão) exige a classificação tributária regular | Informar a classificação tributária regular |
| 660 | O código NBS deve estar vinculado à classificação tributária, conforme o Anexo VIII | Revisar NBS e classificação tributária |
| 1647 | Contribuinte cadastrado no CNC deve emitir no ambiente nacional para fatos geradores a partir da data informada | Verificar o cadastro do contribuinte |

## 9. Mensagens da NFE.io

| Código | Quando | O que fazer |
|---|---|---|
| `[E1002]` | Caractere fora do conjunto Latin-1 em campo de texto | Trocar o caractere indicado e reenviar |
| `[E1003]` | Leiaute com IBS/CBS, documentos de reembolso enviados, mas a soma não é igual à diferença entre o valor recebido e a receita própria | Ajustar os valores dos documentos e reenviar |
| `[E1004]` | Documento de reembolso incompleto | Completar o campo indicado e reenviar |

Exemplo de `[E1004]`:

> [E1004] Documentos de reembolso incompletos em ibsCbs.thirdPartyReimbursements.documents: documento 1: informe otherNationalDfe, otherFiscalDoc ou otherDoc; documento 2: informe reimbursementTypeText para o tipo OtherReimbursement. Corrija e reenvie a nota.

O `[E1004]` aponta, por documento:
- a identificação ausente;
- `issueDate` ausente;
- `reimbursementType` inválido;
- a descrição ausente no tipo `OtherReimbursement`;
- `amount` ausente ou igual a zero.

Nos três casos, a nota **não é enviada à prefeitura**.

## 10. Perguntas frequentes

**Minhas notas vão parar de ser emitidas depois da implantação?**
As notas enviadas sem documentos de reembolso continuam sendo emitidas como hoje. A NFE.io só recusa quando os documentos de reembolso são enviados com valores que não fecham a diferença ou com dados incompletos. Nesse caso, a recusa vale mesmo que a prefeitura aceitasse a nota, para evitar imposto calculado sobre o repasse ou base de cálculo menor que a sua receita própria.

**Emito no leiaute sem IBS e CBS. Algo muda para mim?**
Não, no que diz respeito ao Valor Total Recebido. O `paidAmount` continua sendo enviado como hoje. As regras de caracteres (seção 7) e de tributos federais (seção 6) valem para os dois leiautes.

**Qual formato devo usar no leiaute com IBS e CBS?**
O total da nota em `servicesAmount`, com os repasses em `ibsCbs.thirdPartyReimbursements.documents`, sem `paidAmount` (seção 3.2). O `paidAmount` continua aceito durante a transição, mas pode deixar de ser considerado, com aviso prévio.

**Informo o Valor Recebido e não envio documentos. O que acontece?**
A nota é emitida com o valor do serviço, como a prefeitura já faz desde 01/10/2026. Ela não reflete o total recebido. Para atender à regra da prefeitura, passe a enviar o total em `servicesAmount`, com os documentos de reembolso.

**As notas emitidas desde 01/10 com Valor Recebido estão erradas?**
Elas foram emitidas pela prefeitura com o valor do serviço, e não com o total recebido. Avalie com a sua contabilidade se é necessário cancelá-las e emiti-las novamente com os documentos de reembolso. O suporte da NFE.io pode ajudar a identificar essas notas.

**Preciso enviar um documento para cada repasse?**
Sim, um documento para cada comprovante do repasse (por exemplo, uma nota fiscal por veículo de mídia), até 100 por nota. A soma dos valores deve ser igual à diferença entre o valor recebido e a sua receita própria.

**Posso informar uma NF-e ou NFS-e de terceiro como documento?**
Sim, em `otherNationalDfe`, com `dfeType` (1 = NFS-e, 2 = NF-e, 3 = CT-e) e a chave de acesso em `dfeKey`.

**Multa e juros precisam de documento de reembolso?**
Não, quando informados em `serviceAmountDetails.fineAmount` e `serviceAmountDetails.interestAmount`. Eles fazem parte da sua receita e entram no valor da nota sem documento. Se você usar `serviceAmountDetails.finalChargedAmount`, informe nele o valor já com multa e juros: o que o `paidAmount` passar disso é tratado como repasse.

**Uso o Valor Inicial Cobrado. Preciso mudar algo?**
Não. A NFE.io passa a enviar o mesmo valor como Valor Final Cobrado.

## 11. Referências

- [Notícia da Prefeitura de São Paulo de 01/10/2026: "Atenção às atualizações implementadas no sistema de emissão de NFS-e"](https://notadomilhao.sf.prefeitura.sp.gov.br/noticias/atencao-as-atualizacoes-implementadas-no-sistema-de-emissao-de-nfs-e/)
- [Manuais da NFS-e Paulistana (manual do web service 3.3.9)](https://notadomilhao.sf.prefeitura.sp.gov.br/manuais/)
- [Schemas XSD v02-6](https://notadomilhao.sf.prefeitura.sp.gov.br/schemas-reformatributaria-v02-6)
- Nota Técnica SE/CGNFS-e nº 004, versão 2.0 (documentos referenciados)
- IN SF/SUREM nº 8/2018 e nº 11/2025