Como Emitir IBS e CBS na NFS-e Nacional via API: Guia do Schema DPS v1.01 (TCRTCInfoIBSCBS) e Payload JSON

A transição para a Reforma Tributária sobre o Consumo (Lei Complementar nº 214/2025 e Emenda Constitucional nº 132/2023) atingiu seu ponto mais crítico para a engenharia de software brasileira: a exigência formal do preenchimento das informações do Imposto sobre Bens e Serviços (IBS) e da Contribuição sobre Bens e Serviços (CBS) na Declaração de Prestação de Serviços (DPS) do Sistema Nacional da NFS-e (SNNFSE).

Para equipes técnicas que mantêm sistemas de gestão (ERPs), plataformas SaaS, marketplaces e software houses, lidar diretamente com os arquivos de schema XSD da Receita Federal (DPS_v1.01.xsd, tiposComplexos_v1.01.xsd e tiposSimples_v1.01.xsd) tornou-se um pesadelo de complexidade. O novo grupo <IBSCBS> (tipo complexo TCRTCInfoIBSCBS) introduziu mais de 25 novas tags, múltiplos blocos condicionais (xs:choice) e regras de validação estritas que rejeitam a nota fiscal ao menor deslize de formatação.

Neste guia técnico completo, dissecamos a anatomia exata do Schema XML da DPS Nacional v1.01, revelamos as pegadinhas que os geradores automáticos de XML cometem (como no grupo <imovel>), explicamos por que a DPS Nacional não exige cálculo de base no envio e demonstramos como a Notaas abstrai toda essa burocracia tributária em um payload JSON limpo e direto via REST API.

📐 1. A Estrutura do Grupo <IBSCBS> na DPS Nacional (SNNFSE v1.01)

No padrão nacional oficial da Receita Federal e do Comitê Gestor da NFS-e (SE/CGNFS-e), o elemento <IBSCBS> é o último filho do elemento <infDPS>, posicionado obrigatoriamente logo após o fechamento de </valores>:

⚡ Posicionamento Hierárquico no XML da DPS:

• 1. <infDPS>: Raiz dos dados da declaração (identificador, data, emitente).
• 2. <prest> e <toma>: Dados do prestador e tomador do serviço.
• 3. <serv>: Discriminação do serviço, código de tributação municipal e NBS.
• 4. <valores>: Valores monetários tradicionais (serviço, desconto, retenções, ISSQN).
• 5. <IBSCBS> (minOccurs="0"): Elemento exclusivo do Regime de Transição do Consumo (RTC) com TCRTCInfoIBSCBS.

🔍 2. Elementos e Campos do TCRTCInfoIBSCBS

O tipo complexo TCRTCInfoIBSCBS possui uma sequência rígida de elementos filhos. A tabela abaixo detalha cada um deles conforme o XSD oficial da versão 1.01:

⚠️ 3. A Grande Diferença: DPS Nacional vs. Padrões Municipais (GISS/ABRASF)

Um dos erros mais comuns cometidos por desenvolvedores que estão adaptando seus ERPs para a Reforma Tributária é tentar aplicar a mesma lógica de cálculo de provedores municipais (como GISSOnline ou ABRASF v2.04) na DPS Nacional:

1. Nos provedores municipais RTC (GISS): O XML do RPS exige que o sistema emissor calcule e envie a base de cálculo (vBC), o código de localidade de incidência (cLocalidadeIncid) e o percentual de redução (pRedutor).
2. Na DPS Nacional (SNNFSE): O emitente NÃO envia vBC, pRedutor nem cLocalidadeIncid no XML de envio.

Por que isso acontece? Porque no Sistema Nacional, a SEFIN Nacional apura e calcula as alíquotas e bases de IBS e CBS centralizadamente, devolvendo os tributos liquidados no XML da NFS-e autorizada e no DANFSe v2.0 local (NT-008).

Isso simplifica drasticamente a montagem da requisição: o emitente só precisa declarar a classificação e o indicador da operação.

🚨 4. As Pegadinhas Técnicas de Schema que Travam os Desenvolvedores

A. A Armadilha do Endereço em <imovel> (TCEnderObraEvento vs. TCEndereco)

No XSD da DPS Nacional, existem dois tipos de endereço com estruturas completamente distintas:

• Endereço do Tomador/Prestador (TCEndereco): Exige o bloco <endNac> contendo <cMun> e <CEP>.
• Endereço do Imóvel/Obra (TCEnderObraEvento): NÃO aceita <endNac> e NÃO aceita <cMun>. O elemento <CEP> deve ser filho direto de <end>.

Se o seu gerador de XML reaproveitar a mesma função de endereço para preencher o <imovel>, o parser da Receita Federal rejeitará a DPS com erro imediato de validação de schema.

B. Regras Estritas de Fornecedor em Reembolso (gReeRepRes)

No grupo de reembolso e repasse de despesas (<gReeRepRes> / TCRTCListaDoc), cada documento vinculado aceita um fornecedor (<fornec>), mas com uma regra inviolável: deve haver exatamente um identificador (CNPJ, CPF, NIF ou cNaoNIF). Enviar campos vazios ou múltiplos identificadores causa rejeição fatal.

💻 5. Como a Notaas Resolve: JSON Limpo vs. XML Complexo

Enquanto uma montagem manual de XML exige assinar digitalmente com certificado A1 e gerar mais de 50 linhas de tags aninhadas, na API NFS-e Nacional da Notaas você envia um payload JSON simples:

Exemplo de Payload JSON para Emissão com IBS/CBS:

{
  "provedor": "snnfse",
  "prestador": {
    "cnpj": "12345678000199"
  },
  "tomador": {
    "cnpj": "98765432000188",
    "razao_social": "EMPRESA ADQUIRENTE LTDA",
    "endereco": {
      "logradouro": "Av. Paulista",
      "numero": "1000",
      "bairro": "Bela Vista",
      "codigo_municipio": "3550308",
      "cep": "01310100",
      "uf": "SP"
    }
  },
  "servico": {
    "descricao": "Desenvolvimento e licenciamento de software SaaS corporativo.",
    "valor_servicos": 5000.00,
    "codigo_tributacao_municipio": "010701",
    "item_lista_servico": "01.07",
    "nbs": "115011100"
  },
  "valores": {
    "ibscbs": {
      "cst": "000",
      "classificacao_tributaria": "000001",
      "indicador_operacao": "100301",
      "consumidor_final": false,
      "indicador_destino": "0"
    }
  }
}

⚡ 6. Integração Prática em Código

Exemplo de Integração em Node.js / TypeScript:

import axios from 'axios';

async function emitirNfseNacionalIbscbs() {
  const payload = {
    provedor: 'snnfse',
    prestador: { cnpj: '12345678000199' },
    tomador: {
      cnpj: '98765432000188',
      razao_social: 'EMPRESA CLIENTE S.A.',
      endereco: {
        logradouro: 'Rua das Flores',
        numero: '123',
        bairro: 'Centro',
        codigo_municipio: '3550308',
        cep: '01001000',
        uf: 'SP'
      }
    },
    servico: {
      descricao: 'Consultoria em arquitetura de microsserviços e nuvem.',
      valor_servicos: 12500.00,
      item_lista_servico: '17.01',
      nbs: '114012100'
    },
    valores: {
      ibscbs: {
        cst: '000',
        classificacao_tributaria: '000001',
        indicador_operacao: '100301'
      }
    }
  };

  try {
    const response = await axios.post('https://api.notaas.com.br/api/v1/emitir', payload, {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });

    console.log('✅ DPS Transmitida e Autorizada:', response.data);
    console.log('📄 Link do DANFSe PDF:', response.data.danfe_url);
    console.log('📦 Link do XML Nacional:', response.data.xml_url);
  } catch (error: any) {
    console.error('❌ Erro na emissão:', error.response?.data || error.message);
  }
}

emitirNfseNacionalIbscbs();

⚙️ 7. Defaults de Projeto: Adequação sem Alterar o ERP

Se você já possui centenas de clientes faturando em um ERP legado ou aplicativo móvel e não deseja alterar todas as chamadas de API, a Notaas oferece o recurso de Defaults de Projeto via Org API:

Você cadastra as propriedades padrão da empresa:

• default_cst_ibscbs: "000"
• default_classificacao_tributaria: "000001"
• default_indicador_operacao: "100301"
• default_nbs: "115011100"

Quando seu sistema envia apenas o valor do serviço e os dados do cliente, o motor da Notaas mescla os defaults automaticamente e gera o XML da DPS Nacional 100% compatível com as regras de Reforma Tributária IBS e CBS (Anexo VIII).

❓ FAQ — Dúvidas Frequentes sobre IBS/CBS na DPS Nacional

1. O que é o grupo <IBSCBS> no XML da DPS Nacional?

É o bloco de dados estruturados definido pela NT-004 e NT-007 da Receita Federal que declara o enquadramento do serviço prestado sob as novas regras do IBS e da CBS, contendo o CST, o código de classificação tributária (cClassTrib) e o indicador da operação (cIndOp).

2. O que acontece se eu enviar uma DPS sem o grupo <IBSCBS>?

Para empresas enquadradas no Regime Normal (Lucro Presumido e Lucro Real), o Sistema Nacional da NFS-e rejeita a declaração no momento do envio por não conformidade com as regras da Reforma Tributária.

3. A DPS Nacional exige o envio da base de cálculo (vBC) do IBS?

Não. Diferente de alguns layouts municipais, no padrão nacional da Receita Federal o emitente declara os códigos de enquadramento e a SEFIN Nacional realiza a apuração e o cálculo das bases e alíquotas centralizadamente.

4. Como funciona o endereço do grupo <imovel> na DPS?

O endereço de imóveis ou obras vinculadas utiliza o tipo TCEnderObraEvento, onde o <CEP> é filho direto da tag <end>, não contendo os subgrupos <endNac> e <cMun>.

5. A Notaas suporta IBS e CBS em todas as cidades brasileiras?

Sim. A Notaas suporta emissão tanto no padrão SNNFSE Nacional quanto nos provedores municipais legados com cobertura em mais de 4.781 cidades brasileiras.

🚀 Simplifique sua emissão de NFS-e Nacional com a Notaas:

• Crie sua conta gratuitamente com direito a 50 notas fiscais por mês em produção real.
• Acesse a documentação da API para explorar todos os schemas e SDKs.