Impostos (ICMS, ISS, IPI)
Como a loja calcula os impostos brasileiros sobre a venda e onde ajustar alíquotas e regras.
Vender no Brasil envolve vários impostos sobre o mesmo pedido. Esta área guarda as tabelas de alíquotas e as regras que a plataforma usa para calcular cada um, e oferece calculadoras para simular antes de vender.
Os impostos
| Imposto | O que é | De quem depende |
|---|---|---|
| ICMS | Imposto estadual sobre circulação de mercadorias. | UF de origem e de destino. Venda entre estados usa a alíquota interestadual (7% ou 12%). |
| DIFAL | Diferença entre a alíquota interna do destino e a interestadual; vai para o estado de destino. | Venda interestadual a consumidor final não contribuinte. |
| ICMS-ST | Substituição tributária: o imposto da cadeia é recolhido antecipadamente, sobre uma margem (MVA). | Regra fiscal com icms_st_enabled. |
| ISS | Imposto municipal sobre serviços. | Município (código IBGE da cidade). |
| IPI | Imposto federal sobre produtos industrializados. | NCM do produto. |
| PIS e COFINS | Contribuições federais sobre o faturamento. | Regime tributário. |
Regimes tributários (tax_regime)
simples_nacional, mei, lucro_presumido e lucro_real. No Simples Nacional e no MEI, PIS e COFINS não são somados no pedido. Nos demais, valem os percentuais da regra ou, sem eles, os padrões: PIS 1,65% e COFINS 7,60% (lucro real); PIS 0,65% e COFINS 3,00% (lucro presumido).
Regra fiscal
Uma regra liga um tipo de produto, regime, categoria ou prefixo de NCM aos impostos que se aplicam (apply_icms, apply_iss...) e a valores fixos (icms_override_bps...). A plataforma escolhe a regra ativa mais específica; em empate vence a de maior priority. Regras de seller (vendor_id) são separadas e não aparecem aqui.
Quando não há tabela
Sem alíquota gravada para o par de UFs, a plataforma usa um padrão: a alíquota interna da UF (por exemplo 18% em SP) dentro do estado, 7% de Sul/Sudeste para Norte/Nordeste/Centro-Oeste, e 12% nos demais casos.
Endpoints
| Método | Caminho | Para quê |
|---|---|---|
| GET | /api/v1/admin/tax/icms-rates | Lista alíquotas de ICMS |
| PUT | /api/v1/admin/tax/icms-rates | Grava uma alíquota |
| PUT | /api/v1/admin/tax/icms-rates/bulk | Grava várias |
| GET | /api/v1/admin/tax/icms-matrix | Matriz UF x UF |
| GET | /api/v1/admin/tax/iss | Lista ISS |
| POST | /api/v1/admin/tax/iss | Grava ISS |
| DELETE | /api/v1/admin/tax/iss/{id} | Remove ISS |
| GET | /api/v1/admin/tax/ipi | Lista IPI |
| POST | /api/v1/admin/tax/ipi | Grava IPI |
| DELETE | /api/v1/admin/tax/ipi/{id} | Remove IPI |
| GET | /api/v1/admin/tax/rules | Lista regras |
| POST | /api/v1/admin/tax/rules | Cria regra |
| PUT | /api/v1/admin/tax/rules/{id} | Altera regra |
| DELETE | /api/v1/admin/tax/rules/{id} | Remove regra |
| POST | /api/v1/admin/tax/calculate | Cálculo completo do pedido |
| POST | /api/v1/admin/tax/calculate-preview | Prévia com resumo |
| POST | /api/v1/admin/tax/calculate-icms | Só ICMS |
| POST | /api/v1/admin/tax/calculate-iss | Só ISS |
| POST | /api/v1/admin/tax/calculate-ipi | Só IPI |
Erros comuns
- Confundir alíquota com percentual.
rate_bpsé em pontos-base: 18% é1800, não18. - Esperar 404 ao alterar ou apagar regra inexistente. Volta 500 (
failed to update tax rule/failed to delete tax rule). - Esperar que
DELETEde ISS/IPI avise quando o id não existe. Responde 200deletedmesmo assim. - Achar que
POSTde ISS ou IPI cria sempre um registro novo. Ele grava por chave: o par (cidade, serviço) no ISS e o NCM no IPI. Repetir a chave atualiza o registro e ainda responde 201. - Usar UF inválida nas calculadoras. Origem e destino precisam ser siglas válidas (400);
calculate-issecalculate-ipinão validam o código recebido.