Documentação completa da Pricing API

Cria uma simulação e uma memória auditável. Use o formato de entrada e os exemplos da seção Comece aqui.

Campos-chave da resposta: id, status, resultado, perguntas, classificacao, auditoria e alertas.

Resolve o preço-base necessário para preservar um preço final alvo. O endpoint nunca estima tributos: ele só conclui quando uma única regra HOMOLOGADA_E_ATIVA, íntegra, vigente e aplicável cobre o cenário fiscal declarado.

curl -sS -X POST "$BASE_URL/v1/simulacoes/preco-base" \
  -H 'content-type: application/json' \
  --data '{
    "produto": { "descricao": "Serviço de teste — cenário declarado", "natureza": "SERVICO" },
    "dataOperacao": "2026-08-09",
    "operacao": {
      "tipo": "INTERESTADUAL",
      "origem": { "uf": "SP" },
      "destino": { "uf": "RJ" }
    },
    "contribuinte": { "regime": "REGULAR" },
    "classificacao": { "sistema": "NBS", "codigo": "CODIGO-CONFIRMADO-TESTE" },
    "tratamentos": { "zonaFranca": false, "regimeDiferenciado": false },
    "objetivo": {
      "tipo": "PRESERVAR_PRECO_FINAL",
      "precoFinalAlvo": { "montante": "130.00", "moeda": "BRL" }
    }
  }'

O valor do exemplo somente demonstra o formato. Não é preço recomendado, alíquota, benefício ou qualquer parâmetro fiscal.

Campo ausente gera 201 DADOS_FISCAIS_INSUFICIENTES e uma pergunta. Campo presente, mas inválido — ou valor incluído por engano — gera 422 com CAMPO_AMBIGUO, OBJETIVO_INVALIDO, PRECO_FINAL_ALVO_INVALIDO ou MOEDA_NAO_SUPORTADA.

Quando não há regra aplicável

O status continua HTTP 201, mas o resultado é bloqueado para revisão:

{
  "status": "REVISAO_FISCAL_NECESSARIA",
  "resultado": {
    "elegivel": false,
    "codigoMotivo": "SEM_REGRA_HOMOLOGADA_APLICAVEL",
    "motivo": "Não existe regra homologada ativa aplicável ao produto, operação, vigência e tratamento declarados.",
    "precoFinalAlvo": { "montante": "130.00", "moeda": "BRL" },
    "componentes": []
  },
  "auditoria": { "memoria": "/v1/simulacoes/3fa85f64-5717-4562-b3fc-2c963f66afa6/memoria" }
}

CATALOGO_ATIVO_INCONSISTENTE, AMBIGUIDADE_DE_REGRAS_ATIVAS, FORMULA_NAO_SUPORTADA_PARA_PRECO_BASE e ARREDONDAMENTO_SEM_SOLUCAO_EXATA também são motivos de revisão. O motor não escolhe uma regra por aproximação, não combina regras e não força arredondamento.

Quando o cálculo é permitido

Somente CALCULO_DETERMINISTICO_CONCLUIDO entrega resultado.tipo: PRECO_BASE_PARA_PRECO_FINAL_ALVO, precoFinalAlvo, precoBaseNecessario, multiplicador, componentes e verificacao. multiplicador é o valor efetivo após arredondar cada componente; a verificação recompõe o preço final alvo em centavos.

Método, arredondamento e auditoria

GROSS_UP_SOBRE_PRECO_BASE_V1 é apenas o método declarado pela regra homologada; não é uma regra legal genérica. Em forma simbólica, ele procura uma base tal que precoFinalAlvo = precoBaseNecessario + soma(componentes declarados pela regra).

A regra deve declarar composição, componentes, base de cálculo, incidência, parâmetros e arredondamento. O motor aplica o arredondamento por componente e só retorna sucesso quando recompõe exatamente o alvo; sem solução exata, bloqueia com ARREDONDAMENTO_SEM_SOLUCAO_EXATA. O multiplicador teórico declarado e o efetivo com arredondamento ficam separados na memória.

A memória registra entrada, regras consideradas, regra selecionada quando houver, fórmula, operandos em centavos, multiplicador teórico declarado, multiplicador efetivo com arredondamento, política de arredondamento, fonte, vigência, escopo, aprovação, hash e versão do catálogo. Para ativar uma regra, a fonte precisa usar HTTPS em host oficial permitido e a aprovação precisa ter assinatura Ed25519 válida para a chave pública confiável da identidade declarada. O resultado não substitui parecer tributário.

Use POST /v1/simulacoes/preco-base com modoCalculo: "CENARIO_ALIQUOTAS_DECLARADAS" quando você já possui uma matriz para testar. Esse modo pede somente item, natureza, data, preço final e uma matriz CBS/IBS/IS identificada; não pede classificação, origem/destino, regime ou tratamentos.

Fonte de exemplo oferecida na interface: Portal da Câmara dos Deputados, “Proposta do governo regulamenta impostos criados pela reforma tributária”, 26/04/2024. A página noticia a estimativa do governo de CBS 8,8% e IBS 17,7% (total 26,5%). A resposta a marca como ESTIMATIVA_PUBLICADA_NAO_VIGENTE; ela não inclui IS, que deve ser declarado aplicável ou não pelo usuário.

Essa marca só é usada se os percentuais enviados reproduzirem exatamente a referência (CBS 8.800000%, IBS 17.700000% e IS não aplicável). Se a empresa ajustar a hipótese, mesmo mantendo o link, a resposta informa MATRIZ_DECLARADA_DIVERGENTE_DA_REFERENCIA_PUBLICA: o link fica como contexto, sem atribuir os percentuais alterados à fonte pública.

curl -sS -X POST "$BASE_URL/v1/simulacoes/preco-base" \
  -H 'content-type: application/json' \
  --data '{
    "modoCalculo": "CENARIO_ALIQUOTAS_DECLARADAS",
    "produto": { "descricao": "Serviço mensal de consultoria", "natureza": "SERVICO" },
    "dataOperacao": "2033-01-01",
    "objetivo": { "tipo": "PRESERVAR_PRECO_FINAL", "precoFinalAlvo": { "montante": "100.00", "moeda": "BRL" } },
    "tributacaoAtual": { "componentes": [
      { "tributo": "ISS", "aliquotaPercentual": "5.000000" },
      { "tributo": "PIS", "aliquotaPercentual": "1.650000" },
      { "tributo": "COFINS", "aliquotaPercentual": "7.600000" }
    ] },
    "cenarioAliquotas": {
      "identificacao": "Estimativa do governo 2024 — referência pública da Câmara",
      "versao": "2024-04-24",
      "fonte": {
        "referencia": "Portal da Câmara dos Deputados, 26/04/2024 — estimativa do governo, não vigente.",
        "url": "https://www.camara.leg.br/noticias/1056840-proposta-do-governo-regulamenta-impostos-criados-pela-reforma-tributaria",
        "verificadaEm": "2026-08-10"
      },
      "componentes": [
        { "tributo": "CBS", "aliquotaPercentual": "8.800000" },
        { "tributo": "IBS", "aliquotaPercentual": "17.700000" },
        { "tributo": "IS", "aplicavel": false, "aliquotaPercentual": "0.000000" }
      ]
    }
  }'

{
  "status": "CENARIO_DE_PRECIFICACAO_CONCLUIDO",
  "resultado": {
    "precoFinalAlvo": { "montante": "100.00", "moeda": "BRL" },
    "precoBaseNecessario": { "montante": "79.05", "moeda": "BRL" },
    "componentes": [
      { "tributo": "CBS", "aliquotaPercentual": "8.800000", "montante": "6.96" },
      { "tributo": "IBS", "aliquotaPercentual": "17.700000", "montante": "13.99" },
      { "tributo": "IS", "aliquotaPercentual": "0.000000", "montante": "0.00", "aplicavel": false }
    ],
    "comparativoTributario": {
      "tributosAtuais": { "cargaNominalSomaPercentual": "14.250000" },
      "tributosFuturos": { "cargaNominalSomaPercentual": "26.500000" },
      "comparacao": { "diferencaCargaNominalPontosPercentuais": "12.250000" }
    },
    "verificacao": { "precoFinalRecalculado": "100.00", "preservaPrecoFinalAlvo": true }
  }
}

Os tributos atuais são apenas taxas declaradas para auditoria; sem método de base, créditos ou incidência, a API não inventa seus montantes. Os tributos futuros incluem alíquota e valor usado na conta. O método registra HALF_UP por componente; se não existir resultado exato em centavos, a resposta declara a menor diferença encontrada.

Devolve a memória integral de uma simulação criada no mesmo processo. Substitua {id} pelo valor retornado no POST. Só as 100 solicitações mais recentes são retidas; uma memória antiga pode retornar 404 antes do reinício.

curl -sS "$BASE_URL/v1/simulacoes/SEU-ID/memoria"

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "criadoEm": "2026-08-09T15:00:00.000Z",
  "versaoMotor": "0.4.0",
  "versaoCatalogo": { "id": "catalogo-sem-release", "versao": "sem-versao", "hash": "sha256-..." },
  "status": "REVISAO_FISCAL_NECESSARIA",
  "entradaNormalizada": { "...": "payload enviado" },
  "perguntasPendentes": [],
  "regrasConsideradas": [],
  "memoriaDeCalculo": { "elegivel": false, "...": "resultado da simulação" },
  "premissas": ["O motor usa somente dados declarados na entrada."],
  "fontes": [{ "id": "EC-132-2023", "url": "https://www.planalto.gov.br/..." }],
  "alertas": ["Este resultado não é parecer tributário..."],
  "reprocessamento": { "permitido": true, "motivo": "Nova versão de regra homologada ou correção de dados de entrada." }
}

Recebe uma descrição e, opcionalmente, um código declarado. Não consulta tabela fiscal, não estima confiança e não habilita cálculo.

curl -sS -X POST "$BASE_URL/v1/classificacoes" \
  -H 'content-type: application/json' \
  --data '{
    "descricao": "Serviço de consultoria — cenário de teste",
    "sistema": "NBS",
    "codigo": "CODIGO-CONFIRMADO-TESTE"
  }'

{
  "status": "CLASSIFICACAO_DECLARADA_NAO_HOMOLOGADA",
  "sugestao": { "sistema": "NBS", "codigo": "CODIGO-CONFIRMADO-TESTE" },
  "confianca": "NAO_DETERMINADA",
  "explicacao": "Código declarado recebido; o MVP não o valida nem o usa para cálculo sem homologação.",
  "fontes": [
    {
      "id": "EC-132-2023",
      "titulo": "Emenda Constitucional nº 132, de 20 de dezembro de 2023",
      "url": "https://www.planalto.gov.br/ccivil_03/constituicao/emendas/emc/emc132.htm",
      "verificadaEm": "2026-08-09"
    },
    {
      "id": "LC-214-2025",
      "titulo": "Lei Complementar nº 214, de 16 de janeiro de 2025 — texto compilado",
      "url": "https://www.planalto.gov.br/ccivil_03/leis/lcp/lcp214compilado.htm",
      "verificadaEm": "2026-08-09"
    }
  ],
  "alerta": "Qualquer IA futura só poderá sugerir classificação, nunca ativar uma regra de cálculo."
}

Sem descricao, retorna DADOS_FISCAIS_INSUFICIENTES. Com descrição mas sem código, retorna REVISAO_FISCAL_NECESSARIA.

Lista regras homologadas ativas carregadas na release atual e regras importadas pendentes. Os filtros são opcionais e cumulativos: vigenciaEm, origem e destino. vigenciaEm deve ser uma data real canônica; origem e destino aceitam UF brasileira ou país ISO 3166-1 alfa-2 conforme o tipo da operação.

curl -sS "$BASE_URL/v1/regras?vigenciaEm=2027-01-01&origem=SP&destino=RJ"

{
  "regras": [],
  "estadoCatalogo": "SEM_REGRA_HOMOLOGADA_ATIVA",
  "releaseCatalogo": { "id": "catalogo-sem-release", "versao": "sem-versao", "hash": "sha256-..." },
  "diagnosticos": [],
  "fontes": [
    { "id": "EC-132-2023", "titulo": "Emenda Constitucional nº 132...", "url": "https://www.planalto.gov.br/..." },
    { "id": "LC-214-2025", "titulo": "Lei Complementar nº 214...", "url": "https://www.planalto.gov.br/..." }
  ]
}

A fórmula não é exposta por esta rota. Uma regra ativa mostra identidade, escopo, vigência, fonte e resumo da aprovação; uma regra importada aparece como PENDENTE_HOMOLOGACAO. A release ativa é controlada na publicação, não pela importação pública: ela exige fontes HTTPS em hosts oficiais exatos, aprovações Ed25519 verificáveis e uma aprovacaoRelease assinada. O pin independente PRICING_RELEASE_ATIVA_HOMOLOGADA_JSON_B64 precisa coincidir com releaseCatalogo.id, releaseCatalogo.versao e releaseCatalogo.hash; isso bloqueia replay de uma release antiga assinada. CATALOGO_ATIVO_DISPONIVEL ainda não prova que uma regra é aplicável ao cenário enviado.

Importa regras como registros pendentes. A rota exige id, vigencia.inicio, escopo como objeto JSON, fonte.url HTTPS em host oficial permitido e fonte.referencia. O host precisa coincidir exatamente com um destes: planalto.gov.br, www.planalto.gov.br, gov.br, www.gov.br, cgibs.gov.br, www.cgibs.gov.br, legis.senado.gov.br, nfe.fazenda.gov.br ou www.nfe.fazenda.gov.br; subdomínio, espelho ou outro host HTTPS é recusado. A URL não pode conter usuário, senha ou porta explícita. versao, quando enviada, precisa ser texto não vazio; se omitida assume "1". formula, quando enviada, deve ser objeto JSON. Se informada, fonte.verificadaEm precisa ser data real não futura. Se vigencia.fim for enviado, deve ser data real não anterior ao início; valor inválido rejeita a regra inteira.

curl -sS -X POST "$BASE_URL/v1/catalogos/importacao" \
  -H 'content-type: application/json' \
  -H "x-pricing-catalog-token: $PRICING_CATALOGO_IMPORT_TOKEN" \
  --data '{
    "regras": [{
      "id": "regra-exemplo-1",
      "versao": "1",
      "vigencia": { "inicio": "2027-01-01" },
      "escopo": { "origem": "SP", "destino": "RJ" },
      "fonte": {
        "referencia": "Referência oficial conferida pelo responsável tributário",
        "url": "https://www.planalto.gov.br/",
        "verificadaEm": "2026-08-09"
      },
      "formula": { "descricao": "estrutura interna de teste" }
    }]
  }'

{
  "importadas": [
    { "id": "regra-exemplo-1", "versao": "1", "situacao": "PENDENTE_HOMOLOGACAO" }
  ],
  "erros": [],
  "alerta": "Nenhuma regra importada está ativa para cálculo."
}

Se ao menos uma regra for aceita, a resposta é 201, inclusive quando houver erros em outros itens. Se nenhuma regra for aceita, a resposta é 422 IMPORTACAO_INVALIDA. O processo mantém no máximo 250 regras pendentes; ao atingir o limite, a nova inclusão aparece em erros e não substitui uma regra anterior. A autenticação administrativa é verificada antes do lote:

{
  "erro": {
    "code": "IMPORTACAO_INVALIDA",
    "mensagem": "Nenhuma regra foi importada.",
    "details": ["Envie o array regras com pelo menos uma regra."]
  },
  "meta": {
    "versaoMotor": "0.4.0",
    "estadoVerificacao": "SEM_REGRA_HOMOLOGADA_ATIVA"
  }
}

Use no monitoramento técnico. Não prova que há regra fiscal ativa. releaseSha identifica o SHA Git e deploymentId identifica a transação única da instância publicada; ambos são null localmente sem as variáveis de runtime. Juntos distinguem uma nova publicação do mesmo SHA e não são o hash do catálogo. Se o catálogo estiver inconsistente, retorna HTTP 503 com status: "blocked" para impedir publicação silenciosa nesse estado.

curl -sS "$BASE_URL/healthz"
{ "status": "ok", "versaoMotor": "0.4.0", "estadoCatalogo": "SEM_REGRA_HOMOLOGADA_ATIVA", "releaseSha": "sha-git-da-release-em-execucao", "deploymentId": "id-da-publicacao-em-execucao" }

Especificação OpenAPI 3.1 com servidores, schemas, request bodies, parâmetros, exemplos e respostas. Importe-a em Postman, Insomnia ou outro cliente compatível.