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

Alíquotas de ICMS

Lista e grava a alíquota de ICMS de cada par de UFs e mostra a matriz completa.

A tabela tem uma linha por par (origem, destino): 27 x 27 UFs. A plataforma já traz valores iniciais; ao editar um par, ele passa a is_custom: true. Gravar um par que não existe o cria.

Listar alíquotas

GET/api/v1/admin/tax/icms-ratesAdmin

Lista alíquotas de ICMS

Parâmetros de consulta

originstring
Filtra pela UF de origem.

Exemplo de requisição

bash
curl "$BASE_URL/api/v1/admin/tax/icms-rates?origin=SP" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Alíquotas
json
{
  "rates": [
    {
      "id": 42,
      "origin_state": "SP",
      "destination_state": "RJ",
      "rate_bps": 1200,
      "is_internal": false,
      "is_custom": true,
      "created_at": "2026-06-01T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

totalinteger
Quantidade.
ratesarray
Alíquotas, ordenadas por origem e destino.
idinteger
Id da alíquota.
origin_statestring
UF de origem.
destination_statestring
UF de destino.
rate_bpsinteger
Alíquota em pontos-base.
is_internalboolean
true quando origem e destino são a mesma UF.
is_customboolean
true depois que alguém editou o par; false é o valor inicial da plataforma.
created_atstring
Criação.
updated_atstring
Última alteração.

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"}

Gravar uma alíquota

PUT/api/v1/admin/tax/icms-ratesAdmin

Grava uma alíquota de ICMS

Corpo da requisição

origin_statestringobrigatório
UF de origem.
destination_statestringobrigatório
UF de destino.
rate_bpsintegerobrigatório
Alíquota de 0 a 10000.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/tax/icms-rates" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "origin_state": "SP",
    "destination_state": "RJ",
    "rate_bps": 1200
  }'

Resposta

200Alíquota gravada
json
{
  "id": 42,
  "origin_state": "SP",
  "destination_state": "RJ",
  "rate_bps": 1200,
  "is_internal": false,
  "is_custom": true,
  "created_at": "2026-06-01T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger
Id da alíquota.
origin_statestring
UF de origem.
destination_statestring
UF de destino.
rate_bpsinteger
Alíquota em pontos-base.
is_internalboolean
true quando origem e destino são a mesma UF.
is_customboolean
true depois que alguém editou o par; false é o valor inicial da plataforma.
created_atstring
Criação.
updated_atstring
Última alteração.

Erros

StatusQuandoCorpo de exemplo
400UF ausente ou inválida, ou rate_bps fora de 0 a 10000.{"error":"rate_bps must be between 0 and 10000"}
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"}

Gravar várias alíquotas

Em uma transação, grava cada item da lista. Itens inválidos (UF vazia ou alíquota fora da faixa) são pulados e listados em skipped; os válidos são gravados.

PUT/api/v1/admin/tax/icms-rates/bulkAdmin

Grava várias alíquotas de ICMS

Corpo da requisição

ratesarrayobrigatório
Lista de {origin_state, destination_state, rate_bps}.

Exemplo de requisição

bash
curl -X PUT "$BASE_URL/api/v1/admin/tax/icms-rates/bulk" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "rates": [
      {
        "origin_state": "SP",
        "destination_state": "RJ",
        "rate_bps": 1200
      },
      {
        "origin_state": "SP",
        "destination_state": "MG",
        "rate_bps": 1200
      }
    ]
  }'

Resposta

200Resultado
json
{
  "rates": [
    {
      "id": 42,
      "origin_state": "SP",
      "destination_state": "RJ",
      "rate_bps": 1200,
      "is_internal": false,
      "is_custom": true,
      "created_at": "2026-06-01T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "updated": 1,
  "skipped": [
    {
      "index": 1,
      "reason": "rate_bps 20000 out of range [0, 10000]",
      "origin_state": "SP",
      "destination_state": "MG"
    }
  ]
}

Campos da resposta

ratesarray
Alíquotas gravadas.
updatedinteger
Quantas foram gravadas.
skippedarray
Itens pulados: index (posição na lista), reason, origin_state, destination_state.

Erros

StatusQuandoCorpo de exemplo
400Corpo inválido ou rates vazio.{"error":"rates array 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"}
Modo por filtro

O corpo também aceita filter, simulate, confirm_token e rate_bps para aplicar a mesma alíquota a todos os pares de um recorte (por exemplo {"filter":{"origin_state":"SP"},"rate_bps":1200}), com prévia antes de gravar. Esse modo é compartilhado com outras operações em lote e não é detalhado aqui.

UF inválida em itens não é conferida aqui

No lote, a lista de UFs válidas não é conferida item a item; só campo vazio e faixa da alíquota. Use PUT unitário quando precisar da validação de UF.

Ver a matriz

Mesmos dados da lista, em formato enxuto para desenhar uma grade UF x UF.

GET/api/v1/admin/tax/icms-matrixAdmin

Matriz de ICMS

Exemplo de requisição

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

Resposta

200Matriz
json
{
  "matrix": [
    {
      "origin_state": "SP",
      "destination_state": "RJ",
      "rate_bps": 1200,
      "rule_id": 42,
      "is_custom": true
    }
  ]
}

Campos da resposta

matrixarray
Uma entrada por par.
matrix[].rule_idinteger
Id da alíquota (campo id da lista).

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"}

Veja também

  • Impostos
Anterior
Impostos (ICMS, ISS, IPI)
Próxima
Alíquotas de ISS
Nesta página
  • Listar alíquotas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar uma alíquota
  • Exemplo de requisição
  • Resposta
  • Erros
  • Gravar várias alíquotas
  • Exemplo de requisição
  • Resposta
  • Erros
  • Ver a matriz
  • Exemplo de requisição
  • Resposta
  • Erros
  • Veja também