--- title: "Layout RTC - Documentação Funcional" description: "Documentação funcional detalhada do layout RTC para emissão de NFS-e, incluindo campos, regras e exemplos." source_url: https://nfe.io/docs/documentacao/reforma-tributaria/conceitos-funcionais/nota-fiscal-de-servico/documentacao-layout-nfse-rtc last_updated: 2026-06-25 --- # Documentação Funcional do Layout de Emissão de NFS-e (RTC) ## Introdução Esta documentação descreve de forma funcional todos os campos disponíveis para a emissão de uma Nota Fiscal de Serviço Eletrônica (NFS-e) através da nossa API. O layout RTC foi desenvolvido para ser compatível com o **padrão nacional da NFS-e** e já incorpora as mudanças da **Reforma Tributária**, como os novos tributos IBS e CBS. O objetivo é fornecer um guia claro para usuários e desenvolvedores sobre a finalidade de cada campo, as regras de preenchimento e o impacto de cada informação na nota fiscal gerada. --- ## Estrutura Geral da Requisição A emissão de uma nota é realizada através de uma requisição JSON que contém todas as informações necessárias. Os campos podem ser divididos nos seguintes grupos principais: 1. **Informações Gerais da Nota**: Dados essenciais que identificam a operação. 2. **Participantes**: Informações sobre o tomador, intermediário e outros envolvidos. 3. **Valores e Tributos (Legado)**: Campos relacionados ao cálculo de impostos do sistema antigo (ISS, PIS, COFINS, etc.). 4. **Grupo da Reforma Tributária (`ibsCbs`)**: O grupo central e obrigatório para os novos tributos (IBS e CBS). 5. **Regras de Validação e Comportamentos**: Detalhes sobre as validações aplicadas aos dados. 5. **Grupos para Cenários Específicos**: Estruturas opcionais para detalhar operações como construção civil, locação, comércio exterior, etc. A seguir, detalhamos cada campo. --- ## 1. Informações Gerais da Nota Estes são os campos que definem os dados básicos do serviço prestado. `externalId` (string, opcional) > Identificador único definido pelo seu sistema para associar a nota fiscal a um registro interno (ex: ID do pedido, contrato). Facilita a conciliação e a busca. `cityServiceCode` (string, **obrigatório**) > Código do serviço conforme a tabela do município do prestador. `federalServiceCode` (string, **obrigatório**) > Código do serviço conforme a Lista de Serviços da Lei Complementar 116. É um código federal padronizado. `description` (string, **obrigatório**) > Descrição detalhada dos serviços prestados. Este texto aparecerá no corpo da nota fiscal. Máximo de 2000 caracteres. `servicesAmount` (número, **obrigatório**) > Valor total dos serviços prestados, antes de descontos ou impostos. `nbsCode` (string, **opcional**) > Código da **Nomenclatura Brasileira de Serviços (NBS)**. Esta é uma nova classificação obrigatória para padronização nacional dos serviços. `cnaeCode` (string, opcional) > Código CNAE (Classificação Nacional de Atividades Econômicas) relacionado ao serviço, se exigido pelo município. `ncmCode` (string, opcional) > Código NCM (Nomenclatura Comum do Mercosul), utilizado quando o serviço está atrelado a um bem ou mercadoria. `paidAmount` (número, opcional) > Valor total efetivamente pago pelo serviço. `issuedOn` (data-hora, opcional) > Data e hora de emissão da nota no formato `YYYY-MM-DDTHH:MM:SS-03:00`. Se não for informado, o sistema usará a data e hora do processamento. `accrualOn` (data, opcional) > Data de competência do serviço (quando o serviço foi efetivamente prestado) no formato `AAAA-MM-DD`. Se não for informada, será considerada a data de `issuedOn`. `rpsSerialNumber` (string, opcional) > Série do Recibo Provisório de Serviços (RPS). Se não informado, o sistema usará o valor padrão cadastrado para a empresa. `rpsNumber` (número, opcional) > Número do RPS. Se não informado, o sistema gerará o próximo número da sequência automática. `location` (objeto, opcional) > Endereço onde o serviço foi prestado. É crucial para determinar o município onde o ISSQN é devido. Contém os campos do `addressDefinition`. `additionalInformation` (string, opcional) > **Informações Adicionais: Simples vs. Estruturado (`additionalInformation` vs. `additionalInformationGroup`)** > > O layout oferece duas formas de enviar informações complementares, visando flexibilidade e completude. > > * **`additionalInformation` (Texto Simples):** > Um campo de `string` para adicionar qualquer observação em formato de texto livre. É ideal para anotações rápidas e genéricas. > > * **`additionalInformationGroup` (Objeto Estruturado):** > Um objeto que organiza dados complementares em campos específicos, como `responsibilityDocumentIdentifier` (ART/RRT), `order` (Pedido), etc. É a forma mais completa e padronizada de enviar esses dados. > > **Comportamento e Relação:** > Para facilitar a integração, o campo `additionalInformation` funciona como um atalho. Se você preencher apenas este campo, seu conteúdo será automaticamente copiado para `additionalInformationGroup.otherInformation`. Isso garante que todas as informações adicionais fiquem consolidadas na estrutura mais completa, mantendo a consistência interna dos dados. > > **Recomendação:** > * Para observações simples, use `additionalInformation`. > * Para dados específicos como ART, Pedido, etc., use os campos dedicados dentro de `additionalInformationGroup`. `additionalInformationGroup` (objeto, opcional) > Grupo estruturado para organizar dados complementares em campos específicos, como `responsibilityDocumentIdentifier` (ART/RRT), `order` (Pedido), etc. É a forma mais completa e padronizada de enviar esses dados. `isEarlyInstallmentPayment` (booleano, opcional) > Indique `true` se a nota se refere a um pagamento de parcela antecipada, ou seja, um pagamento realizado antes da prestação do serviço. --- ## 2. Participantes da Operação Define as pessoas ou empresas envolvidas na prestação de serviço. `borrower` (objeto, **obrigatório**) > Representa o **Tomador do Serviço** (cliente). Utiliza a estrutura `partyDefinition`. `intermediary` (objeto, opcional) > Representa o **Intermediário do Serviço** (ex: um marketplace, agência). Utiliza a estrutura `partyDefinition`. `recipient` (objeto, opcional) > Representa o **Destinatário Final do Serviço**, quando ele é diferente do tomador. Utiliza a estrutura `partyDefinition`. Este campo só deve ser informado quando `ibsCbs.destinationIndicator` estiver definido como `DifferentFromBuyer`. Nessa situação, o preenchimento de `recipient` passa a ser **obrigatório**. ### Estrutura `partyDefinition` (Tomador, Intermediário, Destinatário) Esta estrutura é usada para identificar qualquer participante. * `type` (string, opcional): Tipo de pessoa (`NaturalPerson` para Física, `LegalEntity` para Jurídica). * `name` (string, **obrigatório**): Nome completo ou Razão Social. * `federalTaxNumber` (número, **obrigatório**): CPF ou CNPJ. * `municipalTaxNumber` (string, opcional): Inscrição Municipal. * `stateTaxNumber` (string, opcional): Inscrição Estadual. * `taxRegime` (string, opcional): Regime tributário do participante (ex: `SimplesNacional`, `LucroReal`). * `caepf` (string, opcional): Cadastro de Atividade Econômica da Pessoa Física. * `phoneNumber` (string, opcional): Telefone de contato. * `email` (string, opcional): E-mail para contato e envio da nota. * `address` (objeto, **obrigatório**): Endereço do participante, utilizando a estrutura `addressDefinition`. ### Estrutura `addressDefinition` (Endereço) * `country` (string, **obrigatório**): Sigla do país (padrão: `BRA`). * `postalCode` (string, **obrigatório**): CEP. * `street` (string, **obrigatório**): Logradouro. * `number` (string, **obrigatório**): Número. * `additionalInformation` (string, opcional): Complemento. * `district` (string, **obrigatório**): Bairro. * `city` (objeto, **obrigatório**): Contém `code` (código IBGE) e `name` (nome da cidade, para exterior). * `state` (string, **obrigatório**): Sigla do estado (UF). --- ## 3. Valores e Tributos (Sistema Legado - ISSQN e Retenções) Estes campos são usados para o cálculo do ISSQN e das retenções federais (IR, PIS, COFINS, CSLL, INSS), que coexistem com o novo modelo durante a transição. `taxationType` (string, opcional) > **Tipo de Tributação (taxationType)** > > O campo `taxationType` define o regime de tributação do **ISSQN (Imposto Sobre Serviços de Qualquer Natureza)**. Ele é um campo legado, mantido para compatibilidade com os layouts municipais existentes e continua sendo fundamental para o cálculo do ISS durante o período de transição da Reforma Tributária. > > **Finalidade Principal (Contexto do ISSQN):** > Este campo indica ao sistema como o ISSQN deve ser tratado na operação. Com base no valor selecionado (ex: `WithinCity`, `OutsideCity`, `Immune`), o sistema determina se o ISSQN é devido, se a tributação ocorrerá dentro ou fora do município, ou se a operação é isenta ou imune a este imposto específico. > > **Relação com a Reforma Tributária (IBS/CBS):** > É crucial entender que o `taxationType` **não se aplica aos novos tributos (IBS e CBS)**. Para a apuração do IBS e da CBS, as regras de tributação e o local de incidência são definidos exclusivamente pelos campos dentro do grupo `ibsCbs`, como o `operationIndicator` e o `classCode`. > > **Em resumo:** > * **`taxationType`**: Governa o comportamento do **ISSQN**. > * **`ibsCbs`**: Governa o comportamento do **IBS e da CBS**. > > Durante o período de transição, ambos os sistemas de tributação coexistirão, tornando o preenchimento correto de todos esses campos essencial para a conformidade fiscal da nota. `immunityType` (string, opcional) > **Tipo de Imunidade (immunityType)** > > O campo `immunityType` é condicional e deve ser utilizado **exclusivamente quando o campo `taxationType` for definido como `Immune`**. > > Sua finalidade é especificar a base legal que fundamenta a imunidade tributária do **ISSQN (Imposto Sobre Serviços de Qualquer Natureza)** para a operação. Cada valor disponível no campo corresponde a uma alínea específica do Artigo 150, Inciso VI, da Constituição Federal, que trata das limitações ao poder de tributar. > > **Relação com a Reforma Tributária (IBS/CBS):** > É fundamental destacar que este campo se refere **apenas à imunidade do ISSQN**. As regras de imunidade para os novos tributos (IBS e CBS) são tratadas de forma separada, dentro do grupo `ibsCbs`, através de códigos específicos no campo `classCode` (ex: códigos iniciados com `41xxxx`). > > A correta especificação do `immunityType` é essencial para validar a justificativa legal da não incidência do ISSQN na nota fiscal, garantindo a conformidade perante as autoridades fiscais municipais. `retentionType` (string, opcional) > **Tipo de Retenção do ISSQN (retentionType)** > > O campo `retentionType` determina quem é o responsável pelo recolhimento do **ISSQN (Imposto Sobre Serviços de Qualquer Natureza)**. Ele define a transferência da responsabilidade de pagamento do imposto do prestador para outra parte na operação. > > **Finalidade e Opções:** > * **`NotWithheld` (Não Retido):** Esta é a situação padrão. O **prestador** do serviço é o responsável por calcular e recolher o ISSQN devido. > * **`WithheldByBuyer` (Retido pelo Tomador):** A responsabilidade pelo recolhimento do ISSQN é transferida para o **tomador** (cliente) do serviço. > * **`WithheldByIntermediary` (Retido pelo Intermediário):** Em operações com um intermediário (como marketplaces), a responsabilidade pelo recolhimento do ISSQN é transferida para este **intermediário**. > > **Comportamento Automático vs. Manual:** > Se um valor for explicitamente enviado na requisição, ele será utilizado. Se o campo não for enviado, o sistema aplicará as regras de cálculo automáticas (baseadas na legislação, local da prestação e cadastro dos envolvidos) para definir se a retenção é aplicável e quem é o responsável. > > **Relação com a Reforma Tributária (IBS/CBS):** > Assim como outros campos legados, o `retentionType` aplica-se **exclusivamente ao ISSQN**. As regras de retenção para os novos tributos (IBS e CBS) serão definidas por legislação complementar específica e tratadas em outros campos do layout. `issRate` (número, opcional) > Alíquota do ISSQN (pAliq, tpAliquota). Se não informada, o sistema usa a alíquota cadastrada para o serviço. `issTaxAmount` (número, opcional) > Valor do ISSQN. Se não informado, é calculado automaticamente. `issAmountWithheld` (número, opcional) > Valor do ISSQN retido (vISSQN). Calculado automaticamente se houver retenção. `deductionsAmount` (número, opcional) > **Deduções: Simples vs. Estruturado (`deductionsAmount` vs. `deduction`)** > > O layout oferece duas formas de registrar deduções da base de cálculo do ISSQN, visando flexibilidade e conformidade com os diferentes padrões (municipal legado vs. nacional). > > * **`deductionsAmount` (Valor Simples):** > Um campo numérico para informar o **valor total consolidado** das deduções (vDR, tpValor). É uma abordagem direta, compatível com layouts mais antigos que não exigem o detalhamento dos documentos que comprovam a dedução. > > * **`deduction` (Grupo Estruturado):** > Um objeto complexo que permite justificar cada dedução com base em documentos fiscais, alinhando-se ao **padrão da NFS-e Nacional**. Ele detalha a origem de cada valor (chave do documento, tipo, valor, fornecedor). > > **Relação e Recomendação:** > A coexistência dos campos oferece compatibilidade. `deductionsAmount` é uma opção simplificada, enquanto o grupo `deduction` é a forma mais completa e recomendada para garantir rastreabilidade e conformidade fiscal com o padrão nacional. O sistema de emissão priorizará os dados detalhados do grupo `deduction`, se fornecidos. > > **Recomendação de Uso:** > * Use `deductionsAmount` para integrações simples ou quando não há detalhamento dos documentos. > * Use o grupo `deduction` sempre que a informação detalhada dos documentos estiver disponível para garantir a máxima conformidade. `deduction` (objeto, opcional) > **Finalidade**: Justificar deduções da base de cálculo do **ISSQN** com base em documentos fiscais (ex: subempreitadas). É a versão estruturada e mais completa do campo `deductionsAmount`. `discountUnconditionedAmount` (número, opcional) > Valor do desconto incondicionado (que não depende de evento futuro) (vDescIncond, tpValor). `discountConditionedAmount` (número, opcional) > Valor do desconto condicionado (ex: desconto por pagamento antecipado) (vDescCond, tpValor). ### Campos de Retenções Federais e Valores Destacados Para cada tributo federal (IR, PIS, COFINS, CSLL, INSS), existem campos para o valor retido (`...AmountWithheld`). * `irAmountWithheld` (vRetIRRF, tpValor) * `pisAmountWithheld` (vPis, tpValor) * `cofinsAmountWithheld` (vCofins, tpValor) * `csllAmountWithheld` (vRetCSLL, tpValor) * `inssAmountWithheld` (vRetCP, tpValor) **Nota:** Os campos de alíquota (`pisRate`, `cofinsRate` e `csllRate`) são utilizados apenas para cálculos automáticos internos do sistema quando os valores retidos não são informados. Além dos campos de retenção, existem campos específicos para informar os valores de PIS e COFINS quando **não há retenção**, mas o valor deve ser destacado na nota: * `pisAmount`: Valor do PIS (sem retenção) (vPis, tpValor). * `cofinsAmount`: Valor do COFINS (sem retenção) (vCofins, tpValor). * `csllAmount`: Valor do CSLL (sem retenção) (vCSLL, tpValor). * `pisCofinsBaseTax`: Base de cálculo para o Pis e Cofins (vBCPisCofins, tpValor). * `ipiRate`: SP - Alíquota IPI (pAliqIPI, tpAliquota). * `ipiAmount`: SP - Valor IPI (vIPI, tpValor). `othersAmountWithheld` (número, opcional) > Valor de outras retenções não especificadas (vOutrasRet, tpValor). --- ## 4. Grupo Principal: `ibsCbs` (Reforma Tributária) Este é o grupo **obrigatório** mais importante do novo layout. Ele centraliza todas as informações para o cálculo dos novos tributos: **IBS** (Imposto sobre Bens e Serviços) e **CBS** (Contribuição sobre Bens e Serviços). `purpose` (string, opcional, padrão: `regular`) > **Finalidade**: Indica a finalidade da emissão da NFS-e. Atualmente, o único valor suportado é para uma emissão regular. > >| Valor | Descrição | >|:----------|:---------------| >| `regular` | Emissão Regular | `personalUse` (booleano, opcional) > **Finalidade**: Indique `true` se o serviço for destinado a uso ou consumo pessoal do tomador. Este campo é relevante para regras específicas da Reforma Tributária, como o *cashback*. `operationIndicator` (string, **obrigatório**) > **Finalidade**: Código que define a natureza da operação e determina o **local de incidência** (onde o imposto é devido) para o IBS e a CBS. A escolha correta é fundamental para o recolhimento do imposto no município/estado correto. > **Exemplo**: Um serviço de construção (`020201`) terá o imposto devido no local do imóvel. Um serviço de consultoria (`100301`) terá o imposto devido no domicílio do adquirente. > * A lista completa de valores possíveis está disponível na **Tabela de `operationIndicator`** no Apêndice. `operationType` (string, opcional) > **Finalidade**: Tipo de Operação com Entes Governamentais ou outros serviços sobre bens imóveis. > > * `SupplyFirstPayLater`: Fornecimento com pagamento posterior. > * `PayForPastSupply`: Recebimento do pagamento com fornecimento já realizado. > * `SupplyForPastPay`: Fornecimento com pagamento já realizado. > * `PayFirstSupplyLater`: Recebimento do pagamento com fornecimento posterior. > * `SupplyPayTogether`: Fornecimento e recebimento do pagamento concomitantes. `situationCode` (string, opcional) > **Finalidade**: Código de Situação Tributária (CST) do IBS/CBS. Este campo é opcional, pois se não for preenchido, o sistema o derivará automaticamente dos 3 primeiros dígitos do `classCode`. > **Exemplo**: Se o `classCode` for `200028` (serviços de educação com alíquota reduzida), o `situationCode` derivado será `200` (Alíquota zero ou com redução de alíquota). > * A lista completa de valores possíveis está disponível na **Tabela de `situationCode`** no Apêndice. `classCode` (string, **obrigatório**) > **Finalidade**: Código de Classificação Tributária que define o tratamento fiscal da operação para IBS/CBS (ex: tributação integral, alíquota zero, isenção, etc.). Este código determina as alíquotas e regimes aplicáveis. > **Exemplo**: `000001` para tributação integral, `410004` para exportação (imunidade). > * A lista completa de valores possíveis está disponível na **Tabela de `classCode`** no Apêndice. `isDonation` (booleano, opcional) > Indique `true` se a operação for uma doação. `destinationIndicator` (string, opcional) > Indica se o destinatário do serviço é o mesmo que o tomador (`SameAsBuyer`) ou diferente (`DifferentFromBuyer`). Se for diferente, o grupo `recipient` se torna obrigatório. `basis` (número, opcional) > Base de cálculo para o IBS/CBS, antes de quaisquer reduções. `reimbursedResuppliedAmount` (número, opcional) > Valor de reembolsos ou repasses que não compõem a base de cálculo. Para detalhar a origem, use o subgrupo `thirdPartyReimbursements`. `ibscbsDeductionReductionAmount` (número, opcional) > Valor total de deduções e reduções específicas da base de cálculo do IBS/CBS, aplicáveis a operações como locação de imóveis e serviços médicos, conforme legislação. ### 4.1. Subgrupo `ibs` (Opcional) Detalha o cálculo do **IBS**, o imposto subnacional (estadual e municipal). `totalAmount` (número): Valor total do IBS na operação. `state` (objeto): Detalhes da parcela **estadual** do IBS. - `rate`: Alíquota de referência do estado. - `effectiveRate`: Alíquota efetiva após reduções. - `amount`: Valor do IBS devido ao estado. `municipal` (objeto): Detalhes da parcela **municipal** do IBS, com estrutura similar à estadual. ### 4.2. Subgrupo `cbs` (Opcional) Detalha o cálculo da **CBS**, o tributo federal. `rate` (número): Alíquota de referência da CBS. `effectiveRate` (número): Alíquota efetiva após reduções. `amount` (número): Valor da CBS devida. ### 4.3. Outros Subgrupos Opcionais no `ibsCbs` Estes grupos tratam de cenários fiscais mais complexos. * `relatedDocs` (objeto): Permite referenciar até 99 chaves de outras NFS-e. * `leasedMovableAssets` (array): Para detalhar bens móveis em uma operação de locação. * `regularTaxation` (objeto): Para informar o cálculo hipotético do imposto no regime padrão. * `presumedCredits` (objeto): Para detalhar créditos presumidos de IBS e CBS. * `governmentPurchase` (objeto): Para especificar detalhes de operações com entidades governamentais. * `creditTransfer` (objeto): Para casos de transferência de créditos de IBS/CBS. * `thirdPartyReimbursements` (objeto): Para declarar e justificar valores de reembolso que não compõem a base de cálculo, com detalhamento dos documentos de origem. > O detalhamento completo de cada Subgrupo está disponível no **Apêndice**. --- ## Regras de Validação e Comportamentos Para garantir a integridade e a conformidade das notas fiscais emitidas, diversas validações são aplicadas. Abaixo estão as principais regras de negócio e comportamentos do sistema. ### Validações Gerais * **Geração da NFS-e**: Uma vez gerada, uma NFS-e não pode ser alterada. As únicas ações permitidas são o **cancelamento** ou a **substituição**, mantendo-se o vínculo entre a nota original e a nova. * **Identificação do Serviço**: O serviço prestado deve ser identificado em conformidade com a **Lista de Serviços anexa à Lei Complementar n°116/03**. * **Identificação do Prestador**: A identificação do prestador de serviços é realizada através do CNPJ ou CPF. O uso da Inscrição Municipal é opcional. * **Identificação do Tomador**: A informação do CNPJ do tomador do serviço é obrigatória para pessoas jurídicas, exceto quando se tratar de um tomador no exterior. * **Competência**: A competência da NFS-e corresponde à data da ocorrência do fato gerador e deve ser informada pelo contribuinte. ### Validações do ISSQN * **Código do Município de Incidência**: Este campo deve ser informado quando a exigibilidade do ISS for "Exigível", "Isenção", "Imunidade", "Exigibilidade Suspensa por Decisão Judicial" ou "Exigibilidade Suspensa por Processo Administrativo". Nos demais casos, se informado, será considerado um erro. * **Número do Processo**: Deve ser informado quando a exigibilidade do ISS for "Suspensa por Decisão Judicial" ou "Suspensa por Processo Administrativo". * **Base de Cálculo**: A base de cálculo da NFS-e é o `Valor Total de Serviços`, subtraindo-se o `Valor de Deduções` previstas em lei e o `Desconto Incondicionado`. * **Valor do ISS Devido**: O cálculo é realizado com base na exigibilidade do ISS, no código do município de incidência, na opção pelo Simples Nacional, no regime especial de tributação e se o ISS foi retido. O valor será sempre calculado, exceto em cenários específicos, como para microempresas municipais ou quando a tributação ocorre fora do município (nesse caso, o prestador deve indicar a alíquota e o valor). * **Alíquota do ISS**: A alíquota é definida pela legislação municipal. Se for informada pelo contribuinte fora das exceções permitidas (como tributação fora do município ou retenção para optantes do Simples Nacional), será considerada um erro. ### Processos Síncronos e Assíncronos **Nota Importante sobre a Comunicação com a Nossa API:** Do ponto de vista do sistema do cliente, **toda comunicação com a nossa API é assíncrona**. Isso significa que, ao enviar uma requisição (como uma emissão de nota), o cliente recebe uma confirmação imediata de que a solicitação foi aceita e enfileirada. O resultado final do processamento (sucesso ou erro) será informado posteriormente através de um **webhook**. A distinção abaixo entre "síncrono" e "assíncrono" descreve o **mecanismo interno** de comunicação entre o **nosso sistema e o sistema da prefeitura**, e não a comunicação entre o cliente e a nossa API. --- * **Serviços Síncronos**: * **O que são (Comunicação API ↔ Prefeitura)**: Solicitações que nosso sistema envia para a prefeitura e que são processadas imediatamente, com o resultado retornado na mesma conexão. * **Exemplos**: `Geração de NFS-e`, `Cancelamento de NFS-e`, `Substituição de NFS-e`, `Consulta de Lote de RPS`, `Consulta de NFS-e por RPS`, `Consulta de NFS-e – Serviços Prestados` e `Consulta de NFS-e por Faixa`. * **Ideal para**: Operações que exigem uma resposta rápida e processamento de baixo volume. * **Serviços Assíncronos**: * **O que são (Comunicação API ↔ Prefeitura)**: Solicitações que nosso sistema envia para a prefeitura e que envolvem um processamento mais intenso. O resultado é obtido em uma segunda conexão, através de uma consulta posterior que nosso sistema realiza automaticamente. * **Exemplo**: `Recepção e Processamento de Lote de RPS`. * **Ideal para**: Processamento de grandes volumes de informação, como o envio de lotes de RPS, para não sobrecarregar o sistema e garantir a estabilidade. ### XML do Evento de Cancelamento (Ambiente Nacional) No **Ambiente Nacional (ADN)**, o cancelamento de uma NFS-e é registrado como o **evento `e110001`**, que possui um XML próprio (distinto do XML de emissão da nota). Após o cancelamento, esse XML fica disponível para download: `GET /v1/companies/{company_id}/serviceinvoices/{id}/cancellation-xml` * **Disponibilidade**: apenas para notas emitidas no **Ambiente Nacional** e que estejam efetivamente **canceladas** (`status = Cancelled`). Provedores de layout municipal/ABRASF **não** geram evento de cancelamento próprio e, portanto, o endpoint retorna **`404`**. * **Priorização**: quando existem o XML enviado (request do `e110001`) e o XML do **evento autorizado** retornado pelo ADN (`procEventoNFSe`), o **retorno autorizado é priorizado** na resposta. * **Diferença em relação ao `/xml`**: o endpoint `/{id}/xml` retorna o XML de **emissão** da nota; o `/{id}/cancellation-xml` retorna o XML do **evento de cancelamento**. São documentos distintos e armazenados separadamente. > **Observação**: assim como nos demais downloads, a resposta é um redirecionamento para uma URL assinada e temporária do arquivo. ### Testes de Integração (Ambiente de Homologação) Para facilitar a integração, é importante entender a distinção entre os ambientes e as responsabilidades: * **Responsabilidade do Cliente**: A única configuração necessária é definir se a empresa está operando em ambiente de **Produção** ou **Homologação** no cadastro da empresa em nosso sistema. * **Responsabilidade da Nossa API**: Com base no ambiente configurado, nosso sistema gerencia internamente o fluxo de testes. O controle sobre o envio para o ambiente real da prefeitura ou para um *mockup* interno de validação é feito por nós. Dentro do ambiente de **Homologação**, nosso sistema oferece dois comportamentos distintos, gerenciados internamente pela nossa API: * **Fluxo de Validação (Mockup)**: Para validar a estrutura da requisição sem gerar um documento fiscal, a API realiza todas as validações de regras de negócio e da estrutura dos dados. Se a requisição for válida, o sistema retorna sucesso; caso contrário, retorna uma lista de erros. Neste fluxo, a nota **não é emitida** e não é enviada à prefeitura, o que é ideal para testes de integração iniciais. * **Fluxo de Emissão em Homologação**: Para testar o fluxo completo de ponta a ponta, a requisição é enviada para o ambiente de homologação da prefeitura. Neste caso, a nota fiscal é efetivamente emitida no ambiente de testes do município. * **Importante**: Contribuintes optantes pelo Simples Nacional/MEI, em um primeiro momento, não poderão realizar testes utilizando as novas tags da Reforma Tributária. --- ## 5. Detalhamento de Valores Cobrados * `serviceAmountDetails` (objeto, opcional) > **Finalidade**: Fornecer uma decomposição clara dos valores cobrados, separando o valor original do serviço de multas e juros. Garante maior precisão na base de cálculo. > > * `initialChargedAmount` (número): Valor original do serviço, antes de acréscimos. > * `finalChargedAmount` (número): Valor final total, incluindo impostos, multas e juros. > * `fineAmount` (número): Valor específico de multas. > * `interestAmount` (número): Valor específico de juros. --- ## 6. Grupos para Cenários Específicos (Opcionais) Estes grupos foram adicionados para acomodar casos de uso específicos previstos no padrão nacional. `ReferenceSubstitution` (objeto) > Usado quando uma nota está sendo emitida para **substituir** uma nota anterior. Requer o `id` (chave da nota a ser substituída) e o `reason` (motivo). `lease` (objeto) > Para serviços de locação, sublocação ou direito de passagem de infraestrutura (ferrovias, postes, cabos, etc.). `construction` (objeto) > Para serviços de construção civil. Exige a identificação da obra (CNO/CEI), o código CIB ou o endereço do local da obra. (obra) `realEstate` (objeto) > Para operações relacionadas a bens imóveis, exceto obras. (imovel) > **Diferença entre `construction` e `realEstate`**: > A estrutura `realEstate` não possui o campo `workId` (identificação da obra), pois se refere a operações em imóveis que não são obras de construção civil. > * Use **`construction`** para serviços que envolvem efetivamente uma **obra de construção civil** (ex: construção, reforma, demolição). > * Use **`realEstate`** para outras operações relacionadas a imóveis que **não são obras** (ex: administração de imóveis, limpeza, vigilância, quando o local da prestação é o imóvel). `foreignTrade` (objeto) > Para operações de importação/exportação de serviços. Detalha o modo de prestação, moeda, mecanismos de fomento, etc. `benefit` (objeto) > Para aplicar um benefício fiscal municipal que reduz a base de cálculo do **ISSQN**. `suspension` (objeto) > Para indicar que a exigibilidade do **ISSQN** está suspensa por processo judicial ou administrativo. `activityEvent` (objeto) > Para detalhar informações sobre eventos (shows, feiras, congressos), como nome, datas e local. `approximateTax` (objeto, opcional) > **Finalidade**: Atender à "Lei De Olho no Imposto", informando a carga tributária aproximada. > > **Estrutura Simplificada vs. Detalhada (`approximateTax` vs. `approximateTotals`)** > > * **`approximateTax` (Estrutura Simplificada):** > Permite informar a carga tributária de forma consolidada, através de um percentual (`totalRate`) ou valor monetário (`totalAmount`) totais. É ideal para sistemas que não possuem a decomposição dos tributos por esfera governamental. > > * **`approximateTotals` (Estrutura Detalhada):** > Permite um detalhamento completo, separando os valores por esfera: `federal`, `state` e `municipal`. É a escolha ideal quando o sistema possui essa informação decomposta, oferecendo maior transparência. > > **Importante:** Se nenhum dos grupos for preenchido, o sistema realizará o cálculo automático e preencherá o grupo `approximateTax`. `approximateTotals` (objeto, opcional) > Versão detalhada para atender à "Lei De Olho no Imposto", permitindo informar a carga tributária aproximada com valores separados por esfera (federal, estadual, municipal). > O detalhamento completo está disponível no **Apêndice**. --- ## Boas Práticas de Integração Para garantir uma integração eficiente, segura e escalável com a nossa API, recomendamos que os desenvolvedores sigam as seguintes boas práticas: ### 1. Utilize Chaves de Idempotência Para evitar a emissão de notas fiscais em duplicidade devido a falhas de rede ou timeouts, sempre utilize o campo `externalId`. * **Como funciona**: Envie um identificador único gerado pelo seu sistema (como um UUID ou o ID do seu registro interno) no campo `externalId`. Se recebermos uma nova requisição com um `externalId` que já foi processado com sucesso, em vez de criarmos uma nova nota, retornaremos os dados da nota fiscal original. * **Benefício**: Garante que uma mesma operação não seja processada mais de uma vez, trazendo segurança e consistência para a sua aplicação. ### 2. Deixe os Cálculos Complexos para a API Nosso sistema é projetado para simplificar a sua vida. Campos como `rpsNumber`, `issTaxAmount`, `irAmountWithheld`, e os valores dentro dos grupos `ibs` e `cbs` podem ser calculados automaticamente. * **Recomendação**: Envie apenas as informações essenciais da operação (valores, serviços, participantes) e deixe que a API realize os cálculos de impostos e preencha os campos automáticos. * **Benefício**: Reduz a complexidade do seu lado, garante que os cálculos estarão sempre em conformidade com a legislação vigente e diminui a chance de erros por arredondamento ou regras de negócio incorretas. ### 3. Prefira Campos Estruturados O layout oferece campos simples (como `deductionsAmount`) e grupos estruturados (como `deduction`). * **Recomendação**: Sempre que possível, utilize os grupos estruturados (`deduction`, `additionalInformationGroup`, `approximateTotals`). Eles permitem um detalhamento maior das informações, alinhado ao padrão nacional. * **Benefício**: Garante maior conformidade fiscal, melhora a rastreabilidade dos dados e prepara sua integração para futuras exigências do fisco sem a necessidade de grandes refatorações. ### 4. Entenda o Grupo `ibsCbs` O grupo `ibsCbs` é o coração da Reforma Tributária. O preenchimento incorreto dos seus campos pode levar a apurações de impostos erradas. * **Foco principal**: Dedique atenção especial aos campos `operationIndicator` (que define o local de incidência do imposto) e `classCode` (que define o regime e as alíquotas). * **Recomendação**: Não fixe esses valores no código. Crie um mecanismo (ou utilize um motor fiscal) que determine os códigos corretos com base na natureza do serviço, no local da prestação e nos regimes tributários dos participantes. ### 5. Utilize o Ambiente de Homologação de Forma Inteligente O ambiente de homologação é seu aliado para garantir que tudo funcione antes de ir para produção. * **Validação sem Emissão**: Utilize o fluxo de emissão no ambiente de testes para validar a estrutura e as regras da sua requisição sem gerar um documento fiscal. A API retornará sucesso se estiver tudo certo ou uma lista de erros a corrigir. * **Benefício**: Permite realizar testes completos de validação de forma rápida e segura, sem poluir o ambiente de homologação com notas fiscais de teste. ### 6. Tratamento de Erros e Rejeições A API retornará mensagens de erro claras e estruturadas. * **Recomendação**: Configure seu sistema para registrar (logar) a resposta completa da API em caso de erro. Isso inclui códigos de erro, mensagens e o campo específico que causou a falha. * **Benefício**: Facilita enormemente a depuração e a resolução de problemas, tanto para sua equipe de desenvolvimento quanto para o nosso time de suporte. * **Logs Detalhados:** Nosso sistema mantém um histórico completo e detalhado de todas as requisições (JSON enviado) e respostas (JSON recebido) por um longo período. Em caso de erros, esses logs são uma ferramenta poderosa para análise e depuração, facilitando a identificação da causa raiz do problema e agilizando o suporte técnico. * **Mecanismo de Retentativa:** Para erros de rede ou instabilidade momentânea da SEFAZ (ex: timeouts, erros 5xx), nosso sistema já possui um mecanismo de retentativa com *exponential backoff*. Isso evita que o cliente precise se preocupar em implementar essa lógica, pois gerenciamos as tentativas de reenvio automaticamente em caso de falhas temporárias. ### 7. Validação de Dados Pré-Envio * **Reduza Chamadas Desnecessárias:** Antes de enviar os dados para a API, realize o máximo de validações possível no seu sistema. Isso inclui: * **Validação de Dados Cadastrais e Endereço:** Para garantir a validade dos dados cadastrais do emitente e do destinatário, recomendamos o uso de nossas APIs de consulta. Elas permitem verificar se CNPJs e CPFs são válidos, se a Inscrição Estadual está ativa e vinculada ao CNPJ correto, e também consultar endereços a partir do CEP. A utilização dessas APIs evita rejeições por dados cadastrais ou de endereço incorretos. * Garantir que campos obrigatórios estão preenchidos de acordo com a operação (ex: CFOP, NCM). --- ## Conclusão A transição para o layout RTC é impulsionada pela Reforma Tributária. O principal esforço de implementação está no preenchimento correto do grupo `ibsCbs`, que exige um entendimento das novas regras fiscais. Os demais campos garantem a compatibilidade com os sistemas legados e acomodam uma vasta gama de cenários de negócio, alinhando a emissão da NFS-e ao padrão nacional. Recomendamos revisar cuidadosamente esta documentação e os exemplos na especificação OpenAPI para garantir uma integração bem-sucedida. --- ## Apêndice: Tabelas de Referência ### Tabela de Referência - Indicador da Operação (indOp) Para detalhes sobre os códigos, consulte o documento Apêndice: [Tabela de Referência - Indicador da Operação (indOp)](https://nfe.io/docs/documentacao/reforma-tributaria/tabelas-de-referencia/doc-ref-operation-indicator-table/) ### Tabela de Referência - CST e Classificação Tributária (IBS/CBS) Para detalhes sobre os códigos, consulte o documento Apêndice: [Tabela de Referência - CST e Classificação Tributária (IBS/CBS)](https://nfe.io/docs/documentacao/reforma-tributaria/Tabelas%20de%20referencia/doc-ref-classcode-situationcode-table-pt-br/) ### Tabela de Correlação: LC 116, NBS, Indicador de Operação e Classificação Tributária Para detalhes sobre a correlação sugerida entre o Item da Lista de Serviço (LC 116), o código NBS, o Indicador de Operação (indOp) e a Classificação Tributária (cClassTrib) para diversos serviços, consulte o documento Apêndice: [Tabela de Correlação: LC 116, NBS, Indicador de Operação e Classificação Tributária](https://nfe.io/docs/documentacao/reforma-tributaria/Tabelas%20de%20referencia/lc116-nbs-correlation-table-pt-br/) ### Tabela de Referência - Comércio Exterior (`foreignTrade`) Para detalhes sobre os códigos, consulte o documento Apêndice: [Tabela de Referência - Comércio Exterior (`foreignTrade`)](https://nfe.io/docs/documentacao/reforma-tributaria/Tabelas%20de%20referencia/doc_ref_foreign_trade_table_pt-br/) ### Tabela de `destinationIndicator` | Valor | Descrição | |:-----------------------|:------------------------------------------------| | `SameAsBuyer` | O destinatário é o mesmo que o tomador (padrão). | | `DifferentFromBuyer` | O destinatário é diferente do tomador. | ## Apêndice: Estruturas de Dados Detalhadas ### `deduction` Permite detalhar os documentos que justificam uma dedução/redução da base de cálculo do **ISSQN** (`vDedRed`, tipo `TCInfoDedRed` do layout nacional). Deve ser enviada **apenas uma** das três alternativas: `rate`, `amount` ou `documents`. O envio de mais de uma dessas propriedades no mesmo objeto `deduction` não é suportado. **Propriedades Principais:** - `rate` (número): Percentual padrão de dedução/redução (`pDR`, %). - `amount` (número): Valor monetário padrão de dedução/redução (`vDR`, R$). - `documents` (array de objetos, até 1000 itens): Lista de documentos que comprovam a dedução. Cada item segue o tipo `TCDocDedRed` do XSD nacional. **Campos de cada `document`:** Cada item exige **pelo menos um** identificador do documento de origem — `nfseKey`, `nfeKey`, `municipalNfse`, `fiscalDocumentNumber` ou `nonFiscalDocumentNumber`. Quando mais de um é enviado, a precedência aplicada é nessa ordem. - `nfseKey` (string, 50 dígitos): Chave de acesso de uma NFS-e padrão nacional (`chNFSe`). - `nfeKey` (string, 44 dígitos): Chave de acesso de uma NF-e produto (`chNFe`). - `municipalNfse` (objeto): Referência a uma NFS-e municipal no padrão legado (`NFSeMun`). Os três campos internos são obrigatórios. - `cityCode` (string): Código IBGE do município emissor (`cMunNFSeMun`). - `number` (string): Número da NFS-e municipal (`nNFSeMun`). - `verificationCode` (string): Código de verificação da NFS-e municipal (`cVerifNFSeMun`). - `fiscalDocumentNumber` (string): Identificador de outro documento fiscal não eletrônico (`nDocFisc`). - `nonFiscalDocumentNumber` (string): Identificador de um documento não fiscal, ex: nota de débito interna (`nDoc`). - `deductionType` (string, obrigatório): Tipo da dedução/redução (`tpDedRed`). Valores aceitos (nome — código — descrição): - `FoodAndBeverages` (1) — Alimentação e bebidas/frigobar - `Materials` (2) — Materiais - `ConsortiumPassThrough` (5) — Repasse consorciado - `HealthPlanPassThrough` (6) — Repasse plano de saúde - `Services` (7) — Serviços - `Subcontracting` (8) — Subempreitada de mão de obra - `Other` (99) — Outras deduções (exige `otherDeductionDescription`) - `otherDeductionDescription` (string): Descrição obrigatória quando `deductionType = "Other"` (`xDescOutDed`). - `issueDate` (data, obrigatório): Data de emissão do documento de origem (`dtEmiDoc`, `AAAA-MM-DD`). - `deductibleTotal` (número, obrigatório): Valor total dedutível/redutível no documento de origem (`vDedutivelRedutivel`, R$). - `usedAmount` (número, obrigatório): Valor efetivamente utilizado como dedução nesta NFS-e (`vDeducaoReducao`, R$). Deve ser ≤ `deductibleTotal`. - `supplier` (objeto, opcional): Fornecedor do documento (`fornec`), usando a estrutura `partyDefinition`. ### `thirdPartyReimbursements` (dentro de `ibsCbs`) Permite detalhar os documentos que justificam um reembolso/repasse que não integra a base de cálculo do IBS/CBS. **Propriedades Principais:** - `documents` (array de objetos): Lista de documentos comprobatórios. - `nfseKey` (string): Chave de uma NFS-e padrão nacional. - `nfeKey` (string): Chave de uma NF-e. - `cteKey` (string): Chave de um CT-e. - `otherNationalDfe` (objeto): Para outros Documentos Fiscais Eletrônicos (DF-e) do repositório nacional. - `dfeKey` (string): Chave do DF-e. - `dfeTypeText` (string): Descrição do tipo de DF-e. - `otherFiscalDoc` (objeto): Para documentos fiscais que não estão no repositório nacional. - `issuerCityCode` (string): Código IBGE do município emissor. - `fiscalDocNumber` (string): Número do documento. - `fiscalDocDescription` (string): Descrição do documento. - `otherDoc` (objeto): Para documentos não fiscais. - `docNumber` (string): Número do documento. - `docDescription` (string): Descrição do documento. - `supplier` (objeto): Identificação do fornecedor (estrutura `partyDefinition`). - `issueDate` (data): Data de emissão do documento (`AAAA-MM-DD`). - `accrualOn` (data): Data de competência do documento (`AAAA-MM-DD`). - `reimbursementType` (string): Motivo do reembolso (ex: `TravelAgencySupplierPassThrough`, `OtherReimbursement`). - `reimbursementTypeText` (string): Descrição obrigatória se `reimbursementType` for `OtherReimbursement`. - `amount` (número): Valor do reembolso/repasse. ### `governmentPurchase` (dentro de `ibsCbs`) Detalha a composição dos tributos em operações com o governo. **Propriedades Principais:** - `entityType` (string): Tipo de entidade governamental (`Union`, `State`, `Municipality`). - `ibs` (objeto): Detalhes do IBS para a compra governamental. - `totalAmount` (número): Valor total do IBS. - `state` (objeto): Parcela estadual. - `rate` (número): Alíquota do estado. - `amount` (número): Valor do IBS estadual. - `municipal` (objeto): Parcela municipal. - `rate` (número): Alíquota do município. - `amount` (número): Valor do IBS municipal. - `cbs` (objeto): Detalhes da CBS para a compra governamental. - `rate` (número): Alíquota da CBS. - `amount` (número): Valor da CBS. ### `regularTaxation` (dentro de `ibsCbs`) Informa como seria a tributação se a operação não estivesse em um regime especial (suspensivo, etc.). **Propriedades Principais:** - `situationCode` (string): Código de Situação Tributária (CST) que seria aplicado. - `classCode` (string): Código de Classificação Tributária que seria aplicado. - `ibs` (objeto): Detalhes do IBS no regime regular. - `totalAmount` (número): Valor total do IBS. - `state` (objeto): Parcela estadual. - `effectiveRate` (número): Alíquota efetiva do estado. - `amount` (número): Valor do IBS estadual. - `municipal` (objeto): Parcela municipal. - `effectiveRate` (número): Alíquota efetiva do município. - `amount` (número): Valor do IBS municipal. - `cbs` (objeto): Detalhes da CBS no regime regular. - `effectiveRate` (número): Alíquota efetiva da CBS. - `amount` (número): Valor da CBS. ### `presumedCredits` (dentro de `ibsCbs`) Detalha os créditos presumidos de IBS e CBS que o adquirente pode ter direito. **Propriedades Principais:** - `ibs` (objeto): - `code` (string): Código do crédito presumido. - `rate` (número): Percentual do crédito. - `amount` (número): Valor do crédito. - `conditionalAmount` (número): Valor do crédito sob condição suspensiva. - `cbs` (objeto): Estrutura similar para a CBS. - `code` (string): Código do crédito presumido. - `rate` (número): Percentual do crédito. - `amount` (número): Valor do crédito. - `conditionalAmount` (número): Valor do crédito sob condição suspensiva. ### `creditTransfer` (dentro de `ibsCbs`) Usado em operações específicas que envolvem a transferência de saldo credor de IBS/CBS. **Propriedades Principais:** - `ibsAmount` (número): Valor do crédito de IBS a ser transferido. - `cbsAmount` (número): Valor do crédito de CBS a ser transferido. ### `foreignTrade` Detalha operações de comércio exterior de serviços. **Propriedades Principais:** - `serviceMode` (string): Modo de prestação (ex: `CrossBorder`, `ConsumptionInBrazil`). - `relationShip` (string): Vínculo entre as partes (ex: `HeadOffice`, `Branch`). - `currency` (string): Moeda da transação (tabela de moedas do Banco Central do Brasil) (ex: `220`). - `serviceAmountInCurrency` (número): Valor do serviço na moeda estrangeira. - `supportMechanismProvider` (string): Mecanismo de fomento usado pelo prestador. - `supportMechanismReceiver` (string): Mecanismo de fomento usado pelo tomador. - `temporaryGoods` (string): Vínculo com movimentação temporária de bens. - `importDeclaration` (string): Número da Declaração de Importação (DI). - `exportRegistration` (string): Número do Registro de Exportação (RE). - `mdicDelivery` (booleano): Indicador de envio da NFS-e ao MDIC. ### `lease` Para serviços de locação de infraestrutura. **Propriedades Principais:** - `category` (string): Categoria (`lease`, `sublease`, etc.). - `objectType` (string): Objeto (`Railway`, `Poles`, `Cables`, etc.). - `totalLength` (número): Comprimento total (para ferrovias, cabos, etc.). - `polesCount` (número): Número total de postes. ### `construction` Para serviços de construção civil. **Propriedades Principais:** - `workId` (objeto): Identificação da obra via CNO ou CEI. - `scheme` (string): Tipo de cadastro (`bra.cno` ou `bra.cei`). - `value` (string): Número da obra no cadastro. - `cibCode` (string): Código do Cadastro Imobiliário Brasileiro. - `siteAddress` (objeto): Endereço da obra. - `encapsulationNumber` (string, 1–12 dígitos): Número do encapsulamento da obra (`NumeroEncapsulamento`). Atualmente utilizado apenas pelo serializador do município de São Paulo (Paulistana); emitido como `` nos blocos `` e `` do XML. Zeros à esquerda são preservados. ### `realEstate` Para operações relacionadas a bens imóveis, exceto obras. **Propriedades Principais:** - `propertyFiscalRegistration` (string): Inscrição imobiliária fiscal. - `cibCode` (string): Código do Cadastro Imobiliário Brasileiro. - `siteAddress` (objeto): Endereço do imóvel. ### `ReferenceSubstitution` Para substituir uma nota fiscal emitida anteriormente. **Propriedades Principais:** - `id` (string): Chave da NFS-e que será substituída. - `reason` (string): Motivo da substituição (ex: `RejectionBuyerOrIntermediary`). - `reasonText` (string): Descrição do motivo, se `reason` for `other`. ### `benefit` Para aplicar benefícios fiscais municipais ao ISSQN. **Propriedades Principais:** - `id` (string): Identificador do benefício. - `amount` ou `rate`: Valor ou percentual da redução na base de cálculo. ### `suspension` Para suspender a exigibilidade do ISSQN. **Propriedades Principais:** - `reason` (string): Motivo (`Judicial` ou `Administrative`). - `processNumber` (string): Número do processo. ### `activityEvent` Para serviços relacionados a eventos. **Propriedades Principais:** - `name` (string): Nome do evento. - `beginOn` / `endOn` (data-hora): Início e fim do evento. - `Code` (string): Código da atividade do evento (se aplicável). - `address` (objeto): Endereço do evento. ### `approximateTotals` Estrutura detalhada para informar a carga tributária aproximada. **Propriedades Principais:** - `federal` (objeto): Tributos federais (`rate`, `amount`). - `state` (objeto): Tributos estaduais (`rate`, `amount`). - `municipal` (objeto): Tributos municipais (`rate`, `amount`). - `rate` (número): Valor percentual total aproximado dos tributos. - `amount` (número): Valor monetário total aproximado dos tributos.