API atual/Referência completa/Impostos (ICMS, ISS, IPI)

Calculadoras de imposto

Simula os impostos de um pedido inteiro ou de um imposto isolado, sem criar nada.

As calculadoras usam as mesmas tabelas e regras do checkout, então servem para conferir a configuração antes de vender, ou para um sistema externo mostrar o imposto ao operador. Nada é gravado.

Calcular um pedido

Cálculo completo, incluindo frete, DIFAL e ICMS-ST. Valores em centavos.

POST/api/v1/admin/tax/calculateAdmin

Calcula os impostos de um pedido

Corpo da requisição

origin_statestringobrigatório

UF de origem.

dest_statestringobrigatório

UF de destino.

city_codestring

Código IBGE do município, para ISS.

tax_regimestring

simples_nacionalmeilucro_presumidolucro_real

Regime do vendedor.

shipping_costinteger

Frete em centavos.

is_contribuinteboolean

Comprador contribuinte de ICMS (B2B com inscrição estadual): suprime o DIFAL.

itemsarrayobrigatório

Itens do pedido.

product_idstring

Id do produto.

ncmstring

NCM, para o IPI.

unit_priceinteger

Preço unitário em centavos.

quantitynumber

Quantidade (aceita fração).

discountinteger

Desconto da linha em centavos.

is_serviceboolean

Serviço: incide ISS.

is_importedboolean

Importado.

is_digitalboolean

Digital: ISS, sem ICMS nem IPI.

category_iduuid

Categoria, para casar a regra.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/calculate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_state": "SP",
    "dest_state": "RJ",
    "tax_regime": "lucro_presumido",
    "shipping_cost": 1000,
    "items": [
      {
        "product_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
        "ncm": "61091000",
        "unit_price": 4990,
        "quantity": 2
      }
    ]
  }'

Resposta

200Detalhamento

json

{
  "subtotal": 9980,
  "shipping_cost": 1000,
  "shipping_tax": 0,
  "icms": 1198,
  "iss": 0,
  "ipi": 0,
  "pis": 65,
  "cofins": 299,
  "difal": 0,
  "icms_st": 0,
  "total_tax": 1562,
  "grand_total": 12542,
  "tax_regime": "lucro_presumido",
  "items": [
    {
      "product_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "amount": 9980,
      "icms": 1198,
      "iss": 0,
      "ipi": 0,
      "pis": 65,
      "cofins": 299,
      "difal": 0,
      "icms_st": 0,
      "total_tax": 1562,
      "icms_rate_bps": 1200,
      "ipi_rate_bps": 0,
      "iss_rate_bps": 0,
      "pis_rate_bps": 65,
      "cofins_rate_bps": 300
    }
  ]
}

Campos da resposta

subtotalinteger

Soma dos itens em centavos.

shipping_costinteger

Frete.

shipping_taxinteger

Imposto sobre o frete.

icmsinteger

ICMS total.

issinteger

ISS total.

ipiinteger

IPI total.

pisinteger

PIS total.

cofinsinteger

COFINS total.

difalinteger

DIFAL total.

icms_stinteger

ICMS-ST total.

total_taxinteger

Soma dos impostos.

grand_totalinteger

Subtotal + frete + impostos que se somam ao preço.

itemsarray

Detalhe por item, com as alíquotas aplicadas em pontos-base (icms_rate_bps...).

Erros

Status	Quando	Corpo de exemplo
400	UF ausente ou inválida.	`{"error":"invalid dest_state: must be a valid 2-letter Brazilian UF code"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_taxes` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`
403	O módulo `icms-tax` está desligado na loja.	`{"error":"module_disabled","module":"icms-tax"}`
500	Falha no cálculo.	`{"error":"tax calculation failed","detail":"..."}`

Prévia com resumo

Outra forma de simular. Aqui os itens trazem o total da linha em amount (não preço unitário e quantidade) e a resposta inclui um summary pronto para exibir, com a alíquota efetiva.

POST/api/v1/admin/tax/calculate-previewAdmin

Prévia de impostos com resumo

Corpo da requisição

origin_statestringobrigatório

UF de origem.

dest_statestringobrigatório

UF de destino.

city_codestring

Município, para ISS.

tax_regimestring

Regime.

is_contribuinteboolean

Comprador contribuinte (suprime DIFAL).

itemsarrayobrigatório

Itens.

product_idstring

Produto.

ncmstring

NCM.

amountinteger

Total da linha em centavos.

is_serviceboolean

Serviço.

is_importedboolean

Importado.

is_digitalboolean

Digital.

category_iduuid

Categoria.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/calculate-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_state": "SP",
    "dest_state": "RJ",
    "tax_regime": "lucro_presumido",
    "items": [
      {
        "product_id": "p1",
        "ncm": "61091000",
        "amount": 9980
      }
    ]
  }'

Resposta

200Prévia

json

{
  "calculation": {
    "icms": 1198,
    "iss": 0,
    "ipi": 0,
    "pis": 65,
    "cofins": 299,
    "difal": 0,
    "icms_st": 0,
    "total": 1562,
    "icms_rate": 1200,
    "tax_regime": "lucro_presumido",
    "rule_applied": "Mercadorias Lucro Presumido",
    "details": []
  },
  "summary": {
    "subtotal": 9980,
    "icms": 1198,
    "iss": 0,
    "ipi": 0,
    "pis": 65,
    "cofins": 299,
    "difal": 0,
    "icms_st": 0,
    "total_tax": 1562,
    "total": 11542,
    "effective_rate_bps": 1565,
    "icms_rate_bps": 1200,
    "tax_regime": "lucro_presumido",
    "rule_applied": "Mercadorias Lucro Presumido"
  }
}

Campos da resposta

calculationobject

Resultado detalhado: impostos, details por item e rule_applied.

summary.total_taxinteger

Soma dos impostos em centavos.

summary.totalinteger

subtotal + total_tax.

summary.effective_rate_bpsinteger

Carga efetiva: imposto sobre subtotal, em pontos-base.

summary.rule_appliedstring

Nome da regra fiscal escolhida.

Erros

Status	Quando	Corpo de exemplo
400	UF ausente ou inválida.	`{"error":"origin_state and dest_state are required"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_taxes` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`
403	O módulo `icms-tax` está desligado na loja.	`{"error":"module_disabled","module":"icms-tax"}`

Calcular só o ICMS

POST/api/v1/admin/tax/calculate-icmsAdmin

Calcula só o ICMS

Corpo da requisição

origin_statestringobrigatório

UF de origem.

dest_statestringobrigatório

UF de destino.

product_valueintegerobrigatório

Valor em centavos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/calculate-icms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_state": "SP",
    "dest_state": "RJ",
    "product_value": 10000
  }'

Resposta

200ICMS

json

{
  "rate_bps": 1200,
  "base_value": 10000,
  "tax_amount": 1200,
  "is_interstate": true,
  "difal_amount": 800,
  "difal_origin": 0,
  "difal_dest": 800,
  "st_amount": 0,
  "st_base_value": 0,
  "st_rate_bps": 0,
  "st_mva_bps": 0,
  "origin_state": "SP",
  "dest_state": "RJ"
}

Campos da resposta

rate_bpsinteger

Alíquota aplicada.

tax_amountinteger

ICMS em centavos.

is_interstateboolean

Origem diferente do destino.

difal_amountinteger

DIFAL em centavos (alíquota interna do destino menos a aplicada, quando maior).

difal_destinteger

Parcela do DIFAL para o estado de destino (100%).

difal_origininteger

Parcela do estado de origem (sempre 0).

Erros

Status	Quando	Corpo de exemplo
400	UF ausente ou inválida.	`{"error":"invalid origin_state: must be a valid 2-letter Brazilian UF code"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_taxes` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`
403	O módulo `icms-tax` está desligado na loja.	`{"error":"module_disabled","module":"icms-tax"}`

Calcular só o ISS

POST/api/v1/admin/tax/calculate-issAdmin

Calcula só o ISS

Corpo da requisição

city_codestringobrigatório

Código IBGE do município.

service_valueintegerobrigatório

Valor do serviço em centavos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/calculate-iss" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "city_code": "3550308",
    "service_value": 10000
  }'

Resposta

200ISS

json

{
  "rate_bps": 500,
  "base_value": 10000,
  "tax_amount": 500,
  "city_code": "3550308",
  "service_code": ""
}

Campos da resposta

rate_bpsinteger

Alíquota; 0 se a cidade não está cadastrada.

tax_amountinteger

ISS em centavos.

Erros

Status	Quando	Corpo de exemplo
400	`city_code` ausente.	`{"error":"city_code is required"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_taxes` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`
403	O módulo `icms-tax` está desligado na loja.	`{"error":"module_disabled","module":"icms-tax"}`

Calcular só o IPI

POST/api/v1/admin/tax/calculate-ipiAdmin

Calcula só o IPI

Corpo da requisição

ncm_codestringobrigatório

NCM do produto.

product_valueintegerobrigatório

Valor em centavos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/calculate-ipi" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ncm_code": "61091000",
    "product_value": 10000
  }'

Resposta

200IPI

json

{
  "rate_bps": 0,
  "base_value": 10000,
  "tax_amount": 0,
  "ncm_code": "61091000"
}

Campos da resposta

rate_bpsinteger

Alíquota; 0 sem cadastro.

tax_amountinteger

IPI em centavos.

Erros

Status	Quando	Corpo de exemplo
400	`ncm_code` ausente.	`{"error":"ncm_code is required"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_taxes` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`
403	O módulo `icms-tax` está desligado na loja.	`{"error":"module_disabled","module":"icms-tax"}`

Veja também

Impostos

API atual/Referência completa/Impostos (ICMS, ISS, IPI)

Calculadoras de imposto

Simula os impostos de um pedido inteiro ou de um imposto isolado, sem criar nada.

As calculadoras usam as mesmas tabelas e regras do checkout, então servem para conferir a configuração antes de vender, ou para um sistema externo mostrar o imposto ao operador. Nada é gravado.

Calcular um pedido

Cálculo completo, incluindo frete, DIFAL e ICMS-ST. Valores em centavos.

POST/api/v1/admin/tax/calculateAdmin

Calcula os impostos de um pedido

Corpo da requisição

origin_statestringobrigatório

UF de origem.

dest_statestringobrigatório

UF de destino.

city_codestring

Código IBGE do município, para ISS.

tax_regimestring

simples_nacionalmeilucro_presumidolucro_real

Regime do vendedor.

shipping_costinteger

Frete em centavos.

is_contribuinteboolean

Comprador contribuinte de ICMS (B2B com inscrição estadual): suprime o DIFAL.

itemsarrayobrigatório

Itens do pedido.

product_idstring

Id do produto.

ncmstring

NCM, para o IPI.

unit_priceinteger

Preço unitário em centavos.

quantitynumber

Quantidade (aceita fração).

discountinteger

Desconto da linha em centavos.

is_serviceboolean

Serviço: incide ISS.

is_importedboolean

Importado.

is_digitalboolean

Digital: ISS, sem ICMS nem IPI.

category_iduuid

Categoria, para casar a regra.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/calculate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_state": "SP",
    "dest_state": "RJ",
    "tax_regime": "lucro_presumido",
    "shipping_cost": 1000,
    "items": [
      {
        "product_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
        "ncm": "61091000",
        "unit_price": 4990,
        "quantity": 2
      }
    ]
  }'

Resposta

200Detalhamento

json

{
  "subtotal": 9980,
  "shipping_cost": 1000,
  "shipping_tax": 0,
  "icms": 1198,
  "iss": 0,
  "ipi": 0,
  "pis": 65,
  "cofins": 299,
  "difal": 0,
  "icms_st": 0,
  "total_tax": 1562,
  "grand_total": 12542,
  "tax_regime": "lucro_presumido",
  "items": [
    {
      "product_id": "3f73310d-bfdd-4713-a664-305c08eda58b",
      "amount": 9980,
      "icms": 1198,
      "iss": 0,
      "ipi": 0,
      "pis": 65,
      "cofins": 299,
      "difal": 0,
      "icms_st": 0,
      "total_tax": 1562,
      "icms_rate_bps": 1200,
      "ipi_rate_bps": 0,
      "iss_rate_bps": 0,
      "pis_rate_bps": 65,
      "cofins_rate_bps": 300
    }
  ]
}

Campos da resposta

subtotalinteger

Soma dos itens em centavos.

shipping_costinteger

Frete.

shipping_taxinteger

Imposto sobre o frete.

icmsinteger

ICMS total.

issinteger

ISS total.

ipiinteger

IPI total.

pisinteger

PIS total.

cofinsinteger

COFINS total.

difalinteger

DIFAL total.

icms_stinteger

ICMS-ST total.

total_taxinteger

Soma dos impostos.

grand_totalinteger

Subtotal + frete + impostos que se somam ao preço.

itemsarray

Detalhe por item, com as alíquotas aplicadas em pontos-base (icms_rate_bps...).

Erros

Status	Quando	Corpo de exemplo
400	UF ausente ou inválida.	`{"error":"invalid dest_state: must be a valid 2-letter Brazilian UF code"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_taxes` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`
403	O módulo `icms-tax` está desligado na loja.	`{"error":"module_disabled","module":"icms-tax"}`
500	Falha no cálculo.	`{"error":"tax calculation failed","detail":"..."}`

Prévia com resumo

Outra forma de simular. Aqui os itens trazem o total da linha em amount (não preço unitário e quantidade) e a resposta inclui um summary pronto para exibir, com a alíquota efetiva.

POST/api/v1/admin/tax/calculate-previewAdmin

Prévia de impostos com resumo

Corpo da requisição

origin_statestringobrigatório

UF de origem.

dest_statestringobrigatório

UF de destino.

city_codestring

Município, para ISS.

tax_regimestring

Regime.

is_contribuinteboolean

Comprador contribuinte (suprime DIFAL).

itemsarrayobrigatório

Itens.

product_idstring

Produto.

ncmstring

NCM.

amountinteger

Total da linha em centavos.

is_serviceboolean

Serviço.

is_importedboolean

Importado.

is_digitalboolean

Digital.

category_iduuid

Categoria.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/calculate-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_state": "SP",
    "dest_state": "RJ",
    "tax_regime": "lucro_presumido",
    "items": [
      {
        "product_id": "p1",
        "ncm": "61091000",
        "amount": 9980
      }
    ]
  }'

Resposta

200Prévia

json

{
  "calculation": {
    "icms": 1198,
    "iss": 0,
    "ipi": 0,
    "pis": 65,
    "cofins": 299,
    "difal": 0,
    "icms_st": 0,
    "total": 1562,
    "icms_rate": 1200,
    "tax_regime": "lucro_presumido",
    "rule_applied": "Mercadorias Lucro Presumido",
    "details": []
  },
  "summary": {
    "subtotal": 9980,
    "icms": 1198,
    "iss": 0,
    "ipi": 0,
    "pis": 65,
    "cofins": 299,
    "difal": 0,
    "icms_st": 0,
    "total_tax": 1562,
    "total": 11542,
    "effective_rate_bps": 1565,
    "icms_rate_bps": 1200,
    "tax_regime": "lucro_presumido",
    "rule_applied": "Mercadorias Lucro Presumido"
  }
}

Campos da resposta

calculationobject

Resultado detalhado: impostos, details por item e rule_applied.

summary.total_taxinteger

Soma dos impostos em centavos.

summary.totalinteger

subtotal + total_tax.

summary.effective_rate_bpsinteger

Carga efetiva: imposto sobre subtotal, em pontos-base.

summary.rule_appliedstring

Nome da regra fiscal escolhida.

Erros

Status	Quando	Corpo de exemplo
400	UF ausente ou inválida.	`{"error":"origin_state and dest_state are required"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_taxes` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`
403	O módulo `icms-tax` está desligado na loja.	`{"error":"module_disabled","module":"icms-tax"}`

Calcular só o ICMS

POST/api/v1/admin/tax/calculate-icmsAdmin

Calcula só o ICMS

Corpo da requisição

origin_statestringobrigatório

UF de origem.

dest_statestringobrigatório

UF de destino.

product_valueintegerobrigatório

Valor em centavos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/calculate-icms" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_state": "SP",
    "dest_state": "RJ",
    "product_value": 10000
  }'

Resposta

200ICMS

json

{
  "rate_bps": 1200,
  "base_value": 10000,
  "tax_amount": 1200,
  "is_interstate": true,
  "difal_amount": 800,
  "difal_origin": 0,
  "difal_dest": 800,
  "st_amount": 0,
  "st_base_value": 0,
  "st_rate_bps": 0,
  "st_mva_bps": 0,
  "origin_state": "SP",
  "dest_state": "RJ"
}

Campos da resposta

rate_bpsinteger

Alíquota aplicada.

tax_amountinteger

ICMS em centavos.

is_interstateboolean

Origem diferente do destino.

difal_amountinteger

DIFAL em centavos (alíquota interna do destino menos a aplicada, quando maior).

difal_destinteger

Parcela do DIFAL para o estado de destino (100%).

difal_origininteger

Parcela do estado de origem (sempre 0).

Erros

Status	Quando	Corpo de exemplo
400	UF ausente ou inválida.	`{"error":"invalid origin_state: must be a valid 2-letter Brazilian UF code"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_taxes` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`
403	O módulo `icms-tax` está desligado na loja.	`{"error":"module_disabled","module":"icms-tax"}`

Calcular só o ISS

POST/api/v1/admin/tax/calculate-issAdmin

Calcula só o ISS

Corpo da requisição

city_codestringobrigatório

Código IBGE do município.

service_valueintegerobrigatório

Valor do serviço em centavos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/calculate-iss" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "city_code": "3550308",
    "service_value": 10000
  }'

Resposta

200ISS

json

{
  "rate_bps": 500,
  "base_value": 10000,
  "tax_amount": 500,
  "city_code": "3550308",
  "service_code": ""
}

Campos da resposta

rate_bpsinteger

Alíquota; 0 se a cidade não está cadastrada.

tax_amountinteger

ISS em centavos.

Erros

Status	Quando	Corpo de exemplo
400	`city_code` ausente.	`{"error":"city_code is required"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_taxes` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`
403	O módulo `icms-tax` está desligado na loja.	`{"error":"module_disabled","module":"icms-tax"}`

Calcular só o IPI

POST/api/v1/admin/tax/calculate-ipiAdmin

Calcula só o IPI

Corpo da requisição

ncm_codestringobrigatório

NCM do produto.

product_valueintegerobrigatório

Valor em centavos.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/calculate-ipi" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "ncm_code": "61091000",
    "product_value": 10000
  }'

Resposta

200IPI

json

{
  "rate_bps": 0,
  "base_value": 10000,
  "tax_amount": 0,
  "ncm_code": "61091000"
}

Campos da resposta

rate_bpsinteger

Alíquota; 0 sem cadastro.

tax_amountinteger

IPI em centavos.

Erros

Status	Quando	Corpo de exemplo
400	`ncm_code` ausente.	`{"error":"ncm_code is required"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_taxes` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}`
403	O módulo `icms-tax` está desligado na loja.	`{"error":"module_disabled","module":"icms-tax"}`

Veja também

Impostos