Calculadora de Tributos

Ao integrar a Calculadora você torna o processo de faturamento (cálculo de tributos) instantâneo e confiável.

Calculo do Tributo Regime Geral

Objetivo: Executar o cálculo completo dos tributos.

Explicação: É o serviço central (principal) da calculadora. Ele recebe os dados de uma operação e retorna os valores detalhados dos tributos (IS, CBS, IBS) devidos, aplicando todas as regras fiscais, alíquotas e regimes de crédito.

URL

https://piloto-cbs.tributos.gov.br/servico/calculadora-consumo/api/calculadora/regime-geral

Parameters: No parameters
Tipo: POST

Dados de entrada

Exemplo de requisição

Para envio dos dados o Content-Type da requisição deverá ser definido como application/json.

{
    "id": "6194602ea71cbf9431c236de4409d920",
    "versao": "0.0.1",
    "dataHoraEmissao": "2026-01-01T09:50:05-03:00",
    "municipio": 4314902,
    "uf": "RS",
    "itens": [
        {
            "numero": 1,
            "ncm": "24021000",
            "cst": "000",
            "baseCalculo": 200,
            "quantidade": 1,
            "unidade": "LT",
            "impostoSeletivo": {
                "cst": "000",
                "baseCalculo": 200,
                "quantidade": 1,
                "unidade": "LT",
                "impostoInformado": 12,
                "cClassTrib": "000000"
            },
            "tributacaoRegular": {
                "cst": "000",
                "cClassTrib": "000000"
            },
            "cClassTrib": "000001"
        }
    ]
}

Exemplos de retorno

Retorno com sucesso

Code	Description
200	Cálculo realizado com sucesso

Exemplo de retorno

{
    "objetos": [
        {
            "nObj": 1,
            "tribCalc": {
                "IBSCBS": {
                    "CST": "000",
                    "cClassTrib": "000001",
                    "gIBSCBS": {
                        "vBC": "200.00",
                        "gIBSUF": {
                            "pIBSUF": "0.10",
                            "vIBSUF": "0.20",
                            "memoriaCalculo": "Operação de consumo com enquadramento legal em Regime Geral, tributada conforme Regime Geral. A base de cálculo utilizada é de R$ 200.00, com alíquota de 0.10%."
                        },
                        "gIBSMun": {
                            "pIBSMun": "0.00",
                            "vIBSMun": "0.00",
                            "memoriaCalculo": "Operação de consumo com enquadramento legal em Regime Geral, tributada conforme Regime Geral. A base de cálculo utilizada é de R$ 200.00, com alíquota de 0.00%."
                        },
                        "gCBS": {
                            "pCBS": "0.90",
                            "vCBS": "1.80",
                            "memoriaCalculo": "Operação de consumo com enquadramento legal em Regime Geral, tributada conforme Regime Geral. A base de cálculo utilizada é de R$ 200.00, com alíquota de 0.90%."
                        }
                    }
                }
            }
        }
    ],
    "total": {
        "tribCalc": {
            "IBSCBSTot": {
                "vBCIBSCBS": "200.00",
                "gIBS": {
                    "gIBSUF": {
                        "vDif": "0.00",
                        "vDevTrib": "0.00",
                        "vIBSUF": "0.20"
                    },
                    "gIBSMun": {
                        "vDif": "0.00",
                        "vDevTrib": "0.00",
                        "vIBSMun": "0.00"
                    },
                    "vIBS": "0.20",
                    "vCredPres": "0.00",
                    "vCredPresCondSus": "0.00"
                },
                "gCBS": {
                    "vDif": "0.00",
                    "vDevTrib": "0.00",
                    "vCBS": "1.80",
                    "vCredPres": "0.00",
                    "vCredPresCondSus": "0.00"
                }
            }
        }
    }
}

Retorno com erro de dados

Code	Description
400	Estrutura e/ou dados informados em formato não reconhecido
404	Erro na URL da requisição
422	Erro de validação
500	Erro interno na API

Exemplo de retorno

{
  "type": "https://example.com/",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "https://example.com/",
  "properties": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

Geração de XML

Converte os dados tributários já calculados em Json (CBS/IBS/IS) em um XML.

Objetivo: Criar um arquivo XML de saída.

Explicação: Gera um XML padronizado contendo o resultado do cálculo ou os dados de uma operação, útil para interoperabilidade entre sistemas e para arquivamento fiscal.

URL

https://piloto-cbs.tributos.gov.br/servico/calculadora-consumo/api/calculadora/gerar-xml

Parameters: No parameters
Tipo: POST

Dados de entrada

Exemplo de requisição

Para envio dos dados o Content-Type da requisição deverá ser definido como application/json.

{
    "objetos": [
        {
            "nObj": 0,
            "tribCalc": {
                "IS": {
                    "CSTIS": 0,
                    "cClassTribIS": "string",
                    "vBCIS": 0,
                    "pIS": 0,
                    "pISEspec": 0,
                    "uTrib": "string",
                    "qTrib": 0,
                    "vIS": 0,
                    "memoriaCalculo": "string"
                },
                "IBSCBS": {
                    "CST": 0,
                    "cClassTrib": "string",
                    "gIBSCBS": {
                        "vBC": 0,
                        "gIBSUF": {
                            "pIBSUF": 0,
                            "gDif": {
                                "pDif": 0,
                                "vDif": 0
                            },
                            "gDevTrib": {
                                "vDevTrib": 0
                            },
                            "gRed": {
                                "pRedAliq": 0,
                                "pAliqEfet": 0
                            },
                            "vIBSUF": 0,
                            "memoriaCalculo": "string"
                        },
                        "gIBSMun": {
                            "pIBSMun": 0,
                            "gDif": {
                                "pDif": 0,
                                "vDif": 0
                            },
                            "gDevTrib": {
                                "vDevTrib": 0
                            },
                            "gRed": {
                                "pRedAliq": 0,
                                "pAliqEfet": 0
                            },
                            "vIBSMun": 0,
                            "memoriaCalculo": "string"
                        },
                        "gCBS": {
                            "pCBS": 0,
                            "gDif": {
                                "pDif": 0,
                                "vDif": 0
                            },
                            "gDevTrib": {
                                "vDevTrib": 0
                            },
                            "gRed": {
                                "pRedAliq": 0,
                                "pAliqEfet": 0
                            },
                            "vCBS": 0,
                            "memoriaCalculo": "string"
                        },
                        "gTribRegular": {
                            "CSTReg": 0,
                            "cClassTribReg": "string",
                            "pAliqEfetRegIBSUF": 0,
                            "vTribRegIBSUF": 0,
                            "pAliqEfetRegIBSMun": 0,
                            "vTribRegIBSMun": 0,
                            "pAliqEfetRegCBS": 0,
                            "vTribRegCBS": 0
                        },
                        "gIBSCredPres": {
                            "cCredPres": 0,
                            "pCredPres": 0,
                            "vCredPres": 0,
                            "vCredPresCondSus": 0
                        },
                        "gCBSCredPres": {
                            "cCredPres": 0,
                            "pCredPres": 0,
                            "vCredPres": 0,
                            "vCredPresCondSus": 0
                        },
                        "gTribCompraGov": {
                            "pAliqIBSUF": 0,
                            "vTribIBSUF": 0,
                            "pAliqIBSMun": 0,
                            "vTribIBSMun": 0,
                            "pAliqCBS": 0,
                            "vTribCBS": 0
                        }
                    },
                    "gIBSCBSMono": {
                        "qBCMono": 0,
                        "adRemIBS": 0,
                        "adRemCBS": 0,
                        "vIBSMono": 0,
                        "vCBSMono": 0,
                        "qBCMonoReten": 0,
                        "adRemIBSReten": 0,
                        "vIBSMonoReten": 0,
                        "adRemCBSReten": 0,
                        "vCBSMonoReten": 0,
                        "qBCMonoRet": 0,
                        "adRemIBSRet": 0,
                        "vIBSMonoRet": 0,
                        "adRemCBSRet": 0,
                        "vCBSMonoRet": 0,
                        "pDifIBS": 0,
                        "vIBSMonoDif": 0,
                        "pDifCBS": 0,
                        "vCBSMonoDif": 0,
                        "vTotIBSMonoItem": 0,
                        "vTotCBSMonoItem": 0
                    },
                    "gTransfCred": {
                        "vIBS": 0,
                        "vCBS": 0
                    },
                    "gCredPresIBSZFM": {
                        "tpCredPresIBSZFM": 0,
                        "vCredPresIBSZFM": 0
                    }
                }
            }
        }
    ],
    "total": {
        "tribCalc": {
            "ISTot": {
                "vIS": 0
            },
            "IBSCBSTot": {
                "vBCIBSCBS": 0,
                "gIBS": {
                    "gIBSUF": {
                        "vDif": 0,
                        "vDevTrib": 0,
                        "vIBSUF": 0
                    },
                    "gIBSMun": {
                        "vDif": 0,
                        "vDevTrib": 0,
                        "vIBSMun": 0
                    },
                    "vIBS": 0,
                    "vCredPres": 0,
                    "vCredPresCondSus": 0
                },
                "gCBS": {
                    "vDif": 0,
                    "vDevTrib": 0,
                    "vCBS": 0,
                    "vCredPres": 0,
                    "vCredPresCondSus": 0
                },
                "gMono": {
                    "vIBSMono": 0,
                    "vCBSMono": 0,
                    "vIBSMonoReten": 0,
                    "vCBSMonoReten": 0,
                    "vIBSMonoRet": 0,
                    "vCBSMonoRet": 0
                }
            }
        }
    }
}

Exemplos de retorno

Retorno com sucesso

Code	Description
200	Cálculo realizado com sucesso

Exemplo de retorno

<?xml version="1.0" encoding="UTF-8"?>
<ROC>
	<objetos>
		<nObj>0</nObj>
		<tribCalc>
			<IS>
				<CSTIS>0</CSTIS>
				<cClassTribIS>string</cClassTribIS>
				<vBCIS>0</vBCIS>
				<pIS>0</pIS>
				<pISEspec>0</pISEspec>
				<uTrib>string</uTrib>
				<qTrib>0</qTrib>
				<vIS>0</vIS>
				<memoriaCalculo>string</memoriaCalculo>
			</IS>
			<IBSCBS>
				<CST>0</CST>
				<cClassTrib>string</cClassTrib>
				<gIBSCBS>
					<vBC>0</vBC>
					<gIBSUF>
						<pIBSUF>0</pIBSUF>
						<gDif>
							<pDif>0</pDif>
							<vDif>0</vDif>
						</gDif>
						<gDevTrib>
							<vDevTrib>0</vDevTrib>
						</gDevTrib>
						<gRed>
							<pRedAliq>0</pRedAliq>
							<pAliqEfet>0</pAliqEfet>
						</gRed>
						<vIBSUF>0</vIBSUF>
						<memoriaCalculo>string</memoriaCalculo>
					</gIBSUF>
					<gIBSMun>
						<pIBSMun>0</pIBSMun>
						<gDif>
							<pDif>0</pDif>
							<vDif>0</vDif>
						</gDif>
						<gDevTrib>
							<vDevTrib>0</vDevTrib>
						</gDevTrib>
						<gRed>
							<pRedAliq>0</pRedAliq>
							<pAliqEfet>0</pAliqEfet>
						</gRed>
						<vIBSMun>0</vIBSMun>
						<memoriaCalculo>string</memoriaCalculo>
					</gIBSMun>
					<gCBS>
						<pCBS>0</pCBS>
						<gDif>
							<pDif>0</pDif>
							<vDif>0</vDif>
						</gDif>
						<gDevTrib>
							<vDevTrib>0</vDevTrib>
						</gDevTrib>
						<gRed>
							<pRedAliq>0</pRedAliq>
							<pAliqEfet>0</pAliqEfet>
						</gRed>
						<vCBS>0</vCBS>
						<memoriaCalculo>string</memoriaCalculo>
					</gCBS>
					<gTribRegular>
						<CSTReg>0</CSTReg>
						<cClassTribReg>string</cClassTribReg>
						<pAliqEfetRegIBSUF>0</pAliqEfetRegIBSUF>
						<vTribRegIBSUF>0</vTribRegIBSUF>
						<pAliqEfetRegIBSMun>0</pAliqEfetRegIBSMun>
						<vTribRegIBSMun>0</vTribRegIBSMun>
						<pAliqEfetRegCBS>0</pAliqEfetRegCBS>
						<vTribRegCBS>0</vTribRegCBS>
					</gTribRegular>
					<gIBSCredPres>
						<cCredPres>0</cCredPres>
						<pCredPres>0</pCredPres>
						<vCredPres>0</vCredPres>
						<vCredPresCondSus>0</vCredPresCondSus>
					</gIBSCredPres>
					<gCBSCredPres>
						<cCredPres>0</cCredPres>
						<pCredPres>0</pCredPres>
						<vCredPres>0</vCredPres>
						<vCredPresCondSus>0</vCredPresCondSus>
					</gCBSCredPres>
					<gTribCompraGov>
						<pAliqIBSUF>0</pAliqIBSUF>
						<vTribIBSUF>0</vTribIBSUF>
						<pAliqIBSMun>0</pAliqIBSMun>
						<vTribIBSMun>0</vTribIBSMun>
						<pAliqCBS>0</pAliqCBS>
						<vTribCBS>0</vTribCBS>
					</gTribCompraGov>
				</gIBSCBS>
				<gIBSCBSMono>
					<qBCMono>0</qBCMono>
					<adRemIBS>0</adRemIBS>
					<adRemCBS>0</adRemCBS>
					<vIBSMono>0</vIBSMono>
					<vCBSMono>0</vCBSMono>
					<qBCMonoReten>0</qBCMonoReten>
					<adRemIBSReten>0</adRemIBSReten>
					<vIBSMonoReten>0</vIBSMonoReten>
					<adRemCBSReten>0</adRemCBSReten>
					<vCBSMonoReten>0</vCBSMonoReten>
					<qBCMonoRet>0</qBCMonoRet>
					<adRemIBSRet>0</adRemIBSRet>
					<vIBSMonoRet>0</vIBSMonoRet>
					<adRemCBSRet>0</adRemCBSRet>
					<vCBSMonoRet>0</vCBSMonoRet>
					<pDifIBS>0</pDifIBS>
					<vIBSMonoDif>0</vIBSMonoDif>
					<pDifCBS>0</pDifCBS>
					<vCBSMonoDif>0</vCBSMonoDif>
					<vTotIBSMonoItem>0</vTotIBSMonoItem>
					<vTotCBSMonoItem>0</vTotCBSMonoItem>
				</gIBSCBSMono>
				<gTransfCred>
					<vIBS>0</vIBS>
					<vCBS>0</vCBS>
				</gTransfCred>
				<gCredPresIBSZFM>
					<tpCredPresIBSZFM>0</tpCredPresIBSZFM>
					<vCredPresIBSZFM>0</vCredPresIBSZFM>
				</gCredPresIBSZFM>
			</IBSCBS>
		</tribCalc>
	</objetos>
	<total>
		<tribCalc>
			<ISTot>
				<vIS>0</vIS>
			</ISTot>
			<IBSCBSTot>
				<vBCIBSCBS>0</vBCIBSCBS>
				<gIBS>
					<gIBSUF>
						<vDif>0</vDif>
						<vDevTrib>0</vDevTrib>
						<vIBSUF>0</vIBSUF>
					</gIBSUF>
					<gIBSMun>
						<vDif>0</vDif>
						<vDevTrib>0</vDevTrib>
						<vIBSMun>0</vIBSMun>
					</gIBSMun>
					<vIBS>0</vIBS>
					<vCredPres>0</vCredPres>
					<vCredPresCondSus>0</vCredPresCondSus>
				</gIBS>
				<gCBS>
					<vDif>0</vDif>
					<vDevTrib>0</vDevTrib>
					<vCBS>0</vCBS>
					<vCredPres>0</vCredPres>
					<vCredPresCondSus>0</vCredPresCondSus>
				</gCBS>
				<gMono>
					<vIBSMono>0</vIBSMono>
					<vCBSMono>0</vCBSMono>
					<vIBSMonoReten>0</vIBSMonoReten>
					<vCBSMonoReten>0</vCBSMonoReten>
					<vIBSMonoRet>0</vIBSMonoRet>
					<vCBSMonoRet>0</vCBSMonoRet>
				</gMono>
			</IBSCBSTot>
		</tribCalc>
	</total>
</ROC>

Retorno com erro de dados

Code	Description
400	Estrutura e/ou dados informados em formato não reconhecido
404	Erro na URL da requisição
422	Erro de validação
500	Erro interno na API

Exemplo de retorno

{
  "type": "https://example.com/",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "https://example.com/",
  "properties": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

Validação de XML

Com essa função é possível valida os dados no formato XML.

Objetivo: Verificar a conformidade de um arquivo XML.

Explicação: Antes de realizar um cálculo, este endpoint é usado para checar se o arquivo XML de entrada (que contém os dados da operação) está no layout correto e atende aos requisitos estruturais da API, prevenindo erros de processamento.

URL

https://piloto-cbs.tributos.gov.br/servico/calculadora-consumo/api/calculadora/validar-xml?tipo=nfe&subtipo=grupo

Parameters (Query Params):

tipo (string, required)
Exemplo: nfe
subtipo (string, required)
Exemplo: grupo

Tipo: POST

Dados de entrada

Exemplo de requisição

Para envio dos dados o Content-Type da requisição deverá ser definido como application/xml.

<infNFe>
  <det nItem="1">
    <imposto>
      <IBSCBS>
        <CST>000</CST>
        <cClassTrib>000001</cClassTrib>
        <gIBSCBS>
          <vBC>200.00</vBC>
          <gIBSUF>
            <pIBSUF>0.10</pIBSUF>
            <vIBSUF>0.20</vIBSUF>
          </gIBSUF>
          <gIBSMun>
            <pIBSMun>0.00</pIBSMun>
            <vIBSMun>0.00</vIBSMun>
          </gIBSMun>
          <gCBS>
            <pCBS>0.90</pCBS>
            <vCBS>1.80</vCBS>
          </gCBS>
        </gIBSCBS>
      </IBSCBS>
    </imposto>
  </det>
  <total>
    <IBSCBSTot>
      <vBCIBSCBS>200.00</vBCIBSCBS>
      <gIBS>
        <gIBSUF>
          <vDif>0.00</vDif>
          <vDevTrib>0.00</vDevTrib>
          <vIBSUF>0.20</vIBSUF>
        </gIBSUF>
        <gIBSMun>
          <vDif>0.00</vDif>
          <vDevTrib>0.00</vDevTrib>
          <vIBSMun>0.00</vIBSMun>
        </gIBSMun>
        <vIBS>0.20</vIBS>
        <vCredPres>0.00</vCredPres>
        <vCredPresCondSus>0.00</vCredPresCondSus>
      </gIBS>
      <gCBS>
        <vDif>0.00</vDif>
        <vDevTrib>0.00</vDevTrib>
        <vCBS>1.80</vCBS>
        <vCredPres>0.00</vCredPres>
        <vCredPresCondSus>0.00</vCredPresCondSus>
      </gCBS>
    </IBSCBSTot>
  </total>
</infNFe>

Exemplos de retorno

Retorno com sucesso

Code	Description
200	Cálculo realizado com sucesso

Exemplo de retorno

true

Retorno com erro de dados

Code	Description
400	Estrutura e/ou dados informados em formato não reconhecido
404	Erro na URL da requisição
422	Erro de validação
500	Erro interno na API

Exemplo de retorno

{
  "type": "https://example.com/",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "https://example.com/",
  "properties": {
    "additionalProp1": "string",
    "additionalProp2": "string",
    "additionalProp3": "string"
  }
}

Integração via API Calculadora da Reforma Tributária

Calculo do Tributo Regime Geral

Dados de entrada

Exemplos de retorno

Geração de XML

Dados de entrada

Exemplos de retorno

Validação de XML

Dados de entrada

Exemplos de retorno

How can we help?