VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa/Regras de imposto

Regras de imposto

Define quais impostos incidem sobre cada tipo de produto, regime tributário, categoria e NCM.

O Brasil tem vários impostos sobre a venda (ICMS, ISS, IPI, PIS, COFINS), e quais incidem depende do regime tributário do vendedor, do tipo de produto e da classificação fiscal (NCM). Uma regra de imposto diz quais impostos se aplicam e com que alíquotas, e a plataforma escolhe a regra certa para cada item.

Listar regras

Lista as regras de imposto da loja (as do operador), da maior prioridade para a menor. Regras que cada seller cadastra para si ficam de fora.

GET/api/v1/admin/tax-rulesAdmin

Lista as regras de imposto da loja

Autenticação: Authorization: Bearer <token> de um administrador com manage_taxes ou manage_settings. Requer o módulo icms-tax ativo.

Sem parâmetros.

Exemplo de requisição

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

Resposta

200Regras devolvidas
json
{
  "rules": [
    {
      "id": 12,
      "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-05-20T10:00:00Z",
      "updated_at": "2026-05-20T10:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

rulesarray
Regras.
rules[].idinteger
Identificador numérico da regra (não é UUID).
rules[].namestring
Nome da regra.
rules[].product_typestring
Tipo de produto a que se aplica: goods (mercadoria), services, digital, imported. Vazio: qualquer.
rules[].tax_regimestring
Regime tributário do vendedor: simples_nacional, lucro_presumido, lucro_real ou mei. Vazio: qualquer.
rules[].apply_icmsboolean
Aplica ICMS.
rules[].apply_issboolean
Aplica ISS (serviços).
rules[].apply_ipiboolean
Aplica IPI.
rules[].apply_pisboolean
Aplica PIS.
rules[].apply_cofinsboolean
Aplica COFINS.
rules[].icms_override_bpsinteger
Fixa a alíquota de ICMS, em pontos-base, em vez de usar a tabela por estado. Omitido: usa a tabela.
rules[].iss_override_bpsinteger
Fixa a alíquota de ISS. Omitido: usa a consulta por município.
rules[].ipi_override_bpsinteger
Fixa a alíquota de IPI. Omitido: usa a consulta por NCM.
rules[].pis_rate_bpsinteger
Alíquota de PIS, em pontos-base (165 = 1,65%).
rules[].cofins_rate_bpsinteger
Alíquota de COFINS, em pontos-base (760 = 7,60%).
rules[].icms_st_enabledboolean
Aplica substituição tributária do ICMS (ICMS-ST).
rules[].icms_st_mva_bpsinteger
Margem de valor agregado (MVA) do ICMS-ST, em pontos-base.
rules[].difal_enabledboolean
Aplica o diferencial de alíquota (DIFAL) em vendas entre estados.
rules[].is_defaultboolean
Regra padrão: perde para uma específica de mesma prioridade.
rules[].priorityinteger
Quanto maior, mais cedo a regra é escolhida.
rules[].category_iduuid
Categoria à qual a regra se limita. Omitido: todas.
rules[].ncm_patternstring
Prefixo do NCM (classificação fiscal do produto) que a regra cobre, por exemplo 8517. Vazio: qualquer NCM.
rules[].is_activeboolean
Se a regra está valendo.
rules[].created_atstring
Criação, RFC 3339 em UTC.
rules[].updated_atstring
Última alteração.
totalinteger
Quantidade de regras.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"icms-tax"} / {"error":"insufficient privileges","required":"manage_taxes"}
500Falha na consulta{"error":"failed to list tax rules","detail":"..."}

Criar regra

Cria uma regra. A regra entra em vigor para os próximos cálculos de imposto do checkout e da emissão de nota fiscal.

POST/api/v1/admin/tax-rulesAdmin

Cria uma regra de imposto

Autenticação: Authorization: Bearer <token> de um administrador com manage_taxes ou manage_settings. Requer o módulo icms-tax ativo.

Corpo da requisição

namestringobrigatório
Nome da regra. Obrigatório.
product_typestring
goodsservicesdigitalimported
goods, services, digital ou imported. Omitido: vazio (qualquer tipo).
tax_regimestring
simples_nacionallucro_presumidolucro_realmei
simples_nacional, lucro_presumido, lucro_real ou mei. Omitido: vazio (qualquer regime).
apply_icmsbooleanpadrão: false
Aplica ICMS. Omitido vale false.
apply_issbooleanpadrão: false
Aplica ISS. Omitido vale false.
apply_ipibooleanpadrão: false
Aplica IPI. Omitido vale false.
apply_pisbooleanpadrão: false
Aplica PIS. Omitido vale false.
apply_cofinsbooleanpadrão: false
Aplica COFINS. Omitido vale false.
icms_override_bpsinteger
Fixa o ICMS em pontos-base.
iss_override_bpsinteger
Fixa o ISS em pontos-base.
ipi_override_bpsinteger
Fixa o IPI em pontos-base.
pis_rate_bpsinteger
PIS em pontos-base. Na criação, 0 ou omitido vira 165.
cofins_rate_bpsinteger
COFINS em pontos-base. Na criação, 0 ou omitido vira 760.
icms_st_enabledbooleanpadrão: false
Aplica ICMS-ST. Omitido vale false.
icms_st_mva_bpsintegerpadrão: 0
MVA do ICMS-ST. Omitido vale 0.
difal_enabledbooleanpadrão: false
Aplica DIFAL. Omitido vale false.
is_defaultbooleanpadrão: false
Regra padrão. Omitido vale false.
priorityintegerpadrão: 0
Prioridade. Omitido vale 0.
category_iduuid
Limita a uma categoria.
ncm_patternstring
Prefixo do NCM. Omitido: qualquer.
is_activeboolean
Se a regra vale. Na criação, omitido vale true; na alteração, omitido mantém o valor atual.

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": "Serviços - Simples Nacional",
    "product_type": "services",
    "tax_regime": "simples_nacional",
    "apply_iss": true,
    "priority": 20
  }'

Resposta

201Regra criada
json
{
  "id": 31,
  "name": "Serviços - Simples Nacional",
  "product_type": "services",
  "tax_regime": "simples_nacional",
  "apply_icms": false,
  "apply_iss": true,
  "apply_ipi": false,
  "apply_pis": true,
  "apply_cofins": true,
  "pis_rate_bps": 165,
  "cofins_rate_bps": 760,
  "icms_st_enabled": false,
  "icms_st_mva_bps": 0,
  "difal_enabled": false,
  "is_default": false,
  "priority": 20,
  "ncm_pattern": "",
  "is_active": true,
  "created_at": "2026-05-20T10:00:00Z",
  "updated_at": "2026-05-20T10:00:00Z"
}

Campos da resposta

idinteger
Identificador numérico da regra (não é UUID).
namestring
Nome da regra.
product_typestring
Tipo de produto a que se aplica: goods (mercadoria), services, digital, imported. Vazio: qualquer.
tax_regimestring
Regime tributário do vendedor: simples_nacional, lucro_presumido, lucro_real ou mei. Vazio: qualquer.
apply_icmsboolean
Aplica ICMS.
apply_issboolean
Aplica ISS (serviços).
apply_ipiboolean
Aplica IPI.
apply_pisboolean
Aplica PIS.
apply_cofinsboolean
Aplica COFINS.
icms_override_bpsinteger
Fixa a alíquota de ICMS, em pontos-base, em vez de usar a tabela por estado. Omitido: usa a tabela.
iss_override_bpsinteger
Fixa a alíquota de ISS. Omitido: usa a consulta por município.
ipi_override_bpsinteger
Fixa a alíquota de IPI. Omitido: usa a consulta por NCM.
pis_rate_bpsinteger
Alíquota de PIS, em pontos-base (165 = 1,65%).
cofins_rate_bpsinteger
Alíquota de COFINS, em pontos-base (760 = 7,60%).
icms_st_enabledboolean
Aplica substituição tributária do ICMS (ICMS-ST).
icms_st_mva_bpsinteger
Margem de valor agregado (MVA) do ICMS-ST, em pontos-base.
difal_enabledboolean
Aplica o diferencial de alíquota (DIFAL) em vendas entre estados.
is_defaultboolean
Regra padrão: perde para uma específica de mesma prioridade.
priorityinteger
Quanto maior, mais cedo a regra é escolhida.
category_iduuid
Categoria à qual a regra se limita. Omitido: todas.
ncm_patternstring
Prefixo do NCM (classificação fiscal do produto) que a regra cobre, por exemplo 8517. Vazio: qualquer NCM.
is_activeboolean
Se a regra está valendo.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"icms-tax"} / {"error":"insufficient privileges","required":"manage_taxes"}
400Corpo inválido ou name vazio{"error":"name is required"}
500category_id que não existe ou falha ao gravar{"error":"failed to create tax rule","detail":"..."}
Itens omitidos valem `false`

Diferente do que a tela mostra, um corpo sem apply_icms cria uma regra que não aplica ICMS, e sem apply_pis/apply_cofins cria uma que não aplica PIS/COFINS. Envie todos os apply_* que quiser ligados.

Como a regra é escolhida

Para um item, vale a regra ativa da loja cujo tax_regime é o do vendedor (ou vazio), cuja categoria e prefixo de NCM casam (ou estão vazios), com maior priority; no empate, a que não é is_default.

Substituir regra

Grava a regra inteira com o corpo enviado. Apesar de ser uma edição, não é parcial: todo campo omitido volta ao valor vazio. Por isso, leia a regra, altere o que precisa e devolva o objeto completo.

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

Substitui os dados de uma regra de imposto

Autenticação: Authorization: Bearer <token> de um administrador com manage_taxes ou manage_settings. Requer o módulo icms-tax ativo.

Parâmetros de caminho

idintegerobrigatório
Identificador numérico da regra.

Corpo da requisição

namestringobrigatório
Nome da regra. Obrigatório.
product_typestring
goodsservicesdigitalimported
goods, services, digital ou imported. Omitido: vazio (qualquer tipo).
tax_regimestring
simples_nacionallucro_presumidolucro_realmei
simples_nacional, lucro_presumido, lucro_real ou mei. Omitido: vazio (qualquer regime).
apply_icmsbooleanpadrão: false
Aplica ICMS. Omitido vale false.
apply_issbooleanpadrão: false
Aplica ISS. Omitido vale false.
apply_ipibooleanpadrão: false
Aplica IPI. Omitido vale false.
apply_pisbooleanpadrão: false
Aplica PIS. Omitido vale false.
apply_cofinsbooleanpadrão: false
Aplica COFINS. Omitido vale false.
icms_override_bpsinteger
Fixa o ICMS em pontos-base.
iss_override_bpsinteger
Fixa o ISS em pontos-base.
ipi_override_bpsinteger
Fixa o IPI em pontos-base.
pis_rate_bpsinteger
PIS em pontos-base. Na criação, 0 ou omitido vira 165.
cofins_rate_bpsinteger
COFINS em pontos-base. Na criação, 0 ou omitido vira 760.
icms_st_enabledbooleanpadrão: false
Aplica ICMS-ST. Omitido vale false.
icms_st_mva_bpsintegerpadrão: 0
MVA do ICMS-ST. Omitido vale 0.
difal_enabledbooleanpadrão: false
Aplica DIFAL. Omitido vale false.
is_defaultbooleanpadrão: false
Regra padrão. Omitido vale false.
priorityintegerpadrão: 0
Prioridade. Omitido vale 0.
category_iduuid
Limita a uma categoria.
ncm_patternstring
Prefixo do NCM. Omitido: qualquer.
is_activeboolean
Se a regra vale. Na criação, omitido vale true; na alteração, omitido mantém o valor atual.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/tax-rules/12" \
  -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": 15
  }'

Resposta

200Regra substituída
json
{
  "id": 12,
  "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": 15,
  "ncm_pattern": "",
  "is_active": true,
  "created_at": "2026-05-20T10:00:00Z",
  "updated_at": "2026-05-20T10:00:00Z"
}

Campos da resposta

idinteger
Identificador numérico da regra (não é UUID).
namestring
Nome da regra.
product_typestring
Tipo de produto a que se aplica: goods (mercadoria), services, digital, imported. Vazio: qualquer.
tax_regimestring
Regime tributário do vendedor: simples_nacional, lucro_presumido, lucro_real ou mei. Vazio: qualquer.
apply_icmsboolean
Aplica ICMS.
apply_issboolean
Aplica ISS (serviços).
apply_ipiboolean
Aplica IPI.
apply_pisboolean
Aplica PIS.
apply_cofinsboolean
Aplica COFINS.
icms_override_bpsinteger
Fixa a alíquota de ICMS, em pontos-base, em vez de usar a tabela por estado. Omitido: usa a tabela.
iss_override_bpsinteger
Fixa a alíquota de ISS. Omitido: usa a consulta por município.
ipi_override_bpsinteger
Fixa a alíquota de IPI. Omitido: usa a consulta por NCM.
pis_rate_bpsinteger
Alíquota de PIS, em pontos-base (165 = 1,65%).
cofins_rate_bpsinteger
Alíquota de COFINS, em pontos-base (760 = 7,60%).
icms_st_enabledboolean
Aplica substituição tributária do ICMS (ICMS-ST).
icms_st_mva_bpsinteger
Margem de valor agregado (MVA) do ICMS-ST, em pontos-base.
difal_enabledboolean
Aplica o diferencial de alíquota (DIFAL) em vendas entre estados.
is_defaultboolean
Regra padrão: perde para uma específica de mesma prioridade.
priorityinteger
Quanto maior, mais cedo a regra é escolhida.
category_iduuid
Categoria à qual a regra se limita. Omitido: todas.
ncm_patternstring
Prefixo do NCM (classificação fiscal do produto) que a regra cobre, por exemplo 8517. Vazio: qualquer NCM.
is_activeboolean
Se a regra está valendo.
created_atstring
Criação, RFC 3339 em UTC.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"icms-tax"} / {"error":"insufficient privileges","required":"manage_taxes"}
400id que não é número ou corpo inválido{"error":"invalid id"}
500Regra inexistente (ou do seller, não da loja) ou falha ao gravar{"error":"failed to update tax rule","detail":"tax rule 12 not found"}
Omitir `pis_rate_bps`/`cofins_rate_bps` zera as alíquotas

O padrão de 165 e 760 só vale na criação. Na substituição, omitir os dois grava 0, e a regra passa a calcular PIS e COFINS com alíquota zero.

Excluir regra

Apaga a regra. Cálculos futuros passam a usar a próxima regra aplicável (ou nenhuma). Impostos já gravados em pedidos não mudam.

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

Exclui uma regra de imposto

Autenticação: Authorization: Bearer <token> de um administrador com manage_taxes ou manage_settings. Requer o módulo icms-tax ativo.

Parâmetros de caminho

idintegerobrigatório
Identificador numérico da regra.

Exemplo de requisição

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

Resposta

200Regra excluída
json
{
  "status": "deleted"
}

Erros

StatusQuandoCorpo
401Sem token ou token inválido{"error":"missing authorization header"}
403Sem o privilégio exigido, ou módulo desligado{"error":"module_disabled","module":"icms-tax"} / {"error":"insufficient privileges","required":"manage_taxes"}
400id que não é número{"error":"invalid id"}
500Regra inexistente ou do seller{"error":"failed to delete tax rule","detail":"tax rule 12 not found"}
Desative em vez de excluir

Para tirar uma regra de uso sem perder a configuração, grave-a com is_active: false pela rota de substituir.

Veja também

  • Visão geral dos impostos
  • IDs, dinheiro e datas
Anterior
Regras de imposto
Próxima
Promoções e cupons
Nesta página
  • Listar regras
  • Exemplo de requisição
  • Resposta
  • Erros
  • Criar regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Substituir regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Excluir regra
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também