VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Impostos (ICMS, ISS, IPI)

Regras fiscais

Lista, cria, altera e remove as regras que dizem quais impostos incidem sobre cada tipo de produto.

As regras fiscais respondem a perguntas como "mercadoria no lucro presumido paga ICMS e IPI?" ou "produto digital paga ISS e não ICMS?". Só entram regras ativas e sem vendor_id (as do operador); regras criadas por sellers não aparecem nem podem ser alteradas por aqui.

Listar regras

GET/api/v1/admin/tax/rulesAdmin

Lista regras fiscais

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/tax/rules" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regras
json
{
  "rules": [
    {
      "id": 5,
      "name": "Mercadorias Lucro Presumido",
      "product_type": "goods",
      "tax_regime": "lucro_presumido",
      "apply_icms": true,
      "apply_iss": false,
      "apply_ipi": true,
      "apply_pis": true,
      "apply_cofins": true,
      "pis_rate_bps": 65,
      "cofins_rate_bps": 300,
      "icms_st_enabled": false,
      "icms_st_mva_bps": 0,
      "difal_enabled": true,
      "is_default": false,
      "priority": 10,
      "ncm_pattern": "",
      "is_active": true,
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

totalinteger
Quantidade.
rulesarray
Regras, com os campos do corpo mais id, created_at e updated_at.

Erros

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

Criar uma regra

POST/api/v1/admin/tax/rulesAdmin

Cria uma regra fiscal

Corpo da requisição

namestringobrigatório
Nome da regra (obrigatório na criação).
product_typestring
Tipo de produto ao qual vale, por exemplo goods, service, digital. Vazio = qualquer.
tax_regimestring
simples_nacionalmeilucro_presumidolucro_real
Regime ao qual vale. Vazio = qualquer.
apply_icmsboolean
Calcula ICMS.
apply_issboolean
Calcula ISS.
apply_ipiboolean
Calcula IPI.
apply_pisboolean
Calcula PIS.
apply_cofinsboolean
Calcula COFINS.
icms_override_bpsinteger
Alíquota fixa de ICMS; ausente = usa a tabela.
iss_override_bpsinteger
Alíquota fixa de ISS.
ipi_override_bpsinteger
Alíquota fixa de IPI.
pis_rate_bpsinteger
PIS em pontos-base. 0 na criação vira 165 (1,65%).
cofins_rate_bpsinteger
COFINS em pontos-base. 0 na criação vira 760 (7,60%).
icms_st_enabledboolean
Liga a substituição tributária.
icms_st_mva_bpsinteger
Margem de valor agregado (MVA) da ST, em pontos-base.
difal_enabledboolean
Liga o DIFAL.
is_defaultboolean
Regra padrão (perde o desempate para a específica).
priorityinteger
Maior vence.
category_iduuid
Restringe a uma categoria.
ncm_patternstring
Prefixo de NCM ao qual vale. Vazio = qualquer.
is_activeboolean
Padrão true.

Exemplo de requisição

bash
curl -X POST "$BASE_URL/api/v1/admin/tax/rules" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mercadorias Lucro Presumido",
    "product_type": "goods",
    "tax_regime": "lucro_presumido",
    "apply_icms": true,
    "apply_ipi": true,
    "apply_pis": true,
    "apply_cofins": true,
    "pis_rate_bps": 65,
    "cofins_rate_bps": 300,
    "difal_enabled": true,
    "priority": 10
  }'

Resposta

201Regra criada
json
{
  "id": 5,
  "name": "Mercadorias Lucro Presumido",
  "product_type": "goods",
  "tax_regime": "lucro_presumido",
  "apply_icms": true,
  "apply_iss": false,
  "apply_ipi": true,
  "apply_pis": true,
  "apply_cofins": true,
  "pis_rate_bps": 65,
  "cofins_rate_bps": 300,
  "icms_st_enabled": false,
  "icms_st_mva_bps": 0,
  "difal_enabled": true,
  "is_default": false,
  "priority": 10,
  "ncm_pattern": "",
  "is_active": true,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Erros

StatusQuandoCorpo de exemplo
400name ausente ou corpo inválido.{"error":"name is required"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_taxes nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}
403O módulo icms-tax está desligado na loja.{"error":"module_disabled","module":"icms-tax"}
500Falha ao gravar.{"error":"failed to create tax rule","detail":"..."}

Alterar uma regra

Substitui os campos da regra: envie o corpo completo, como na criação. Campos omitidos voltam ao valor zero (por exemplo apply_icms: false).

PUT/api/v1/admin/tax/rules/{id}Admin

Altera uma regra fiscal

Parâmetros de caminho

idintegerobrigatório
Id numérico da regra.

Corpo da requisição

namestringobrigatório
Nome da regra (obrigatório na criação).
product_typestring
Tipo de produto ao qual vale, por exemplo goods, service, digital. Vazio = qualquer.
tax_regimestring
simples_nacionalmeilucro_presumidolucro_real
Regime ao qual vale. Vazio = qualquer.
apply_icmsboolean
Calcula ICMS.
apply_issboolean
Calcula ISS.
apply_ipiboolean
Calcula IPI.
apply_pisboolean
Calcula PIS.
apply_cofinsboolean
Calcula COFINS.
icms_override_bpsinteger
Alíquota fixa de ICMS; ausente = usa a tabela.
iss_override_bpsinteger
Alíquota fixa de ISS.
ipi_override_bpsinteger
Alíquota fixa de IPI.
pis_rate_bpsinteger
PIS em pontos-base. 0 na criação vira 165 (1,65%).
cofins_rate_bpsinteger
COFINS em pontos-base. 0 na criação vira 760 (7,60%).
icms_st_enabledboolean
Liga a substituição tributária.
icms_st_mva_bpsinteger
Margem de valor agregado (MVA) da ST, em pontos-base.
difal_enabledboolean
Liga o DIFAL.
is_defaultboolean
Regra padrão (perde o desempate para a específica).
priorityinteger
Maior vence.
category_iduuid
Restringe a uma categoria.
ncm_patternstring
Prefixo de NCM ao qual vale. Vazio = qualquer.
is_activeboolean
Se omitido, mantém o valor atual.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/tax/rules/5" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mercadorias Lucro Presumido",
    "product_type": "goods",
    "tax_regime": "lucro_presumido",
    "apply_icms": true,
    "apply_ipi": true,
    "apply_pis": true,
    "apply_cofins": true,
    "pis_rate_bps": 65,
    "cofins_rate_bps": 300,
    "difal_enabled": true,
    "priority": 20
  }'

Resposta

200Regra alterada
json
{
  "id": 5,
  "name": "Mercadorias Lucro Presumido",
  "product_type": "goods",
  "tax_regime": "lucro_presumido",
  "apply_icms": true,
  "apply_iss": false,
  "apply_ipi": true,
  "apply_pis": true,
  "apply_cofins": true,
  "pis_rate_bps": 65,
  "cofins_rate_bps": 300,
  "icms_st_enabled": false,
  "icms_st_mva_bps": 0,
  "difal_enabled": true,
  "is_default": false,
  "priority": 20,
  "ncm_pattern": "",
  "is_active": true,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Erros

StatusQuandoCorpo de exemplo
400id não numérico ou corpo inválido.{"error":"invalid id"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_taxes nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}
403O módulo icms-tax está desligado na loja.{"error":"module_disabled","module":"icms-tax"}
500Regra inexistente (sim, 500) ou falha ao gravar.{"error":"failed to update tax rule","detail":"tax rule 5 not found"}

Remover uma regra

DELETE/api/v1/admin/tax/rules/{id}Admin

Remove uma regra fiscal

Parâmetros de caminho

idintegerobrigatório
Id numérico da regra.

Exemplo de requisição

bash
curl -X DELETE "$BASE_URL/api/v1/admin/tax/rules/5" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removida
json
{
  "status": "deleted"
}

Erros

StatusQuandoCorpo de exemplo
400id não numérico.{"error":"invalid id"}
401Sem token ou token inválido.{"error":"missing authorization header"}
403O usuário não tem manage_taxes nem manage_settings.{"error":"insufficient privileges","privilege_required_any":["manage_taxes","manage_settings"]}
403O módulo icms-tax está desligado na loja.{"error":"module_disabled","module":"icms-tax"}
500Regra inexistente (sim, 500) ou não é do operador.{"error":"failed to delete tax rule","detail":"tax rule 5 not found"}

Veja também

  • Impostos
Anterior
Alíquotas de IPI
Próxima
Calculadoras de imposto
Nesta página
  • Listar regras
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar uma regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Alterar uma regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Remover uma regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também