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

Alíquotas de ISS

Lista, grava e remove a alíquota do imposto municipal sobre serviços por cidade.

O ISS é cobrado pelo município onde o serviço é prestado, então a tabela é por cidade (código IBGE) e, opcionalmente, por tipo de serviço.

Listar alíquotas

GET/api/v1/admin/tax/issAdmin

Lista alíquotas de ISS

Parâmetros de consulta

city_codestring

Filtra por município.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/tax/iss?city_code=3550308" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Alíquotas

json

{
  "rates": [
    {
      "id": 7,
      "city_code": "3550308",
      "city_name": "São Paulo",
      "service_code": "",
      "description": "Serviços em geral",
      "rate_bps": 500,
      "is_active": true,
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

totalinteger

Quantidade.

ratesarray

Alíquotas.

idinteger

Id.

city_codestring

Código IBGE do município (7 dígitos).

city_namestring

Nome do município.

service_codestring

Código do serviço (vazio = alíquota geral da cidade).

descriptionstring

Descrição.

rate_bpsinteger

Alíquota em pontos-base.

is_activeboolean

Ativa.

created_atstring

Criação.

updated_atstring

Última alteração.

Erros

Status	Quando	Corpo de exemplo
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"}`

Gravar uma alíquota

Cria a alíquota ou, se já existir uma para o mesmo city_code e service_code, atualiza. Sempre responde 201.

POST/api/v1/admin/tax/issAdmin

Grava uma alíquota de ISS

Corpo da requisição

city_codestringobrigatório

Código IBGE do município.

city_namestring

Nome do município.

service_codestring

Código do serviço; vazio = geral.

descriptionstring

Descrição.

rate_bpsintegerobrigatório

Alíquota de 0 a 10000.

is_activebooleanpadrão: true

Padrão true.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/iss" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "city_code": "3550308",
    "city_name": "São Paulo",
    "description": "Serviços em geral",
    "rate_bps": 500
  }'

Resposta

201Alíquota gravada

json

{
  "id": 7,
  "city_code": "3550308",
  "city_name": "São Paulo",
  "service_code": "",
  "description": "Serviços em geral",
  "rate_bps": 500,
  "is_active": true,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger

Id.

city_codestring

Código IBGE do município (7 dígitos).

city_namestring

Nome do município.

service_codestring

Código do serviço (vazio = alíquota geral da cidade).

descriptionstring

Descrição.

rate_bpsinteger

Alíquota em pontos-base.

is_activeboolean

Ativa.

created_atstring

Criação.

updated_atstring

Última alteração.

Erros

Status	Quando	Corpo de exemplo
400	`city_code` ausente ou `rate_bps` fora de 0 a 10000.	`{"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"}`

Remover uma alíquota

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

Remove uma alíquota de ISS

Parâmetros de caminho

idintegerobrigatório

Id numérico da alíquota.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/tax/iss/7" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removida

json

{
  "status": "deleted"
}

Erros

Status	Quando	Corpo de exemplo
400	`id` não numérico.	`{"error":"invalid id"}`
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)

Alíquotas de ISS

Lista, grava e remove a alíquota do imposto municipal sobre serviços por cidade.

O ISS é cobrado pelo município onde o serviço é prestado, então a tabela é por cidade (código IBGE) e, opcionalmente, por tipo de serviço.

Listar alíquotas

GET/api/v1/admin/tax/issAdmin

Lista alíquotas de ISS

Parâmetros de consulta

city_codestring

Filtra por município.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/tax/iss?city_code=3550308" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Alíquotas

json

{
  "rates": [
    {
      "id": 7,
      "city_code": "3550308",
      "city_name": "São Paulo",
      "service_code": "",
      "description": "Serviços em geral",
      "rate_bps": 500,
      "is_active": true,
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

totalinteger

Quantidade.

ratesarray

Alíquotas.

idinteger

Id.

city_codestring

Código IBGE do município (7 dígitos).

city_namestring

Nome do município.

service_codestring

Código do serviço (vazio = alíquota geral da cidade).

descriptionstring

Descrição.

rate_bpsinteger

Alíquota em pontos-base.

is_activeboolean

Ativa.

created_atstring

Criação.

updated_atstring

Última alteração.

Erros

Status	Quando	Corpo de exemplo
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"}`

Gravar uma alíquota

Cria a alíquota ou, se já existir uma para o mesmo city_code e service_code, atualiza. Sempre responde 201.

POST/api/v1/admin/tax/issAdmin

Grava uma alíquota de ISS

Corpo da requisição

city_codestringobrigatório

Código IBGE do município.

city_namestring

Nome do município.

service_codestring

Código do serviço; vazio = geral.

descriptionstring

Descrição.

rate_bpsintegerobrigatório

Alíquota de 0 a 10000.

is_activebooleanpadrão: true

Padrão true.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/tax/iss" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "city_code": "3550308",
    "city_name": "São Paulo",
    "description": "Serviços em geral",
    "rate_bps": 500
  }'

Resposta

201Alíquota gravada

json

{
  "id": 7,
  "city_code": "3550308",
  "city_name": "São Paulo",
  "service_code": "",
  "description": "Serviços em geral",
  "rate_bps": 500,
  "is_active": true,
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger

Id.

city_codestring

Código IBGE do município (7 dígitos).

city_namestring

Nome do município.

service_codestring

Código do serviço (vazio = alíquota geral da cidade).

descriptionstring

Descrição.

rate_bpsinteger

Alíquota em pontos-base.

is_activeboolean

Ativa.

created_atstring

Criação.

updated_atstring

Última alteração.

Erros

Status	Quando	Corpo de exemplo
400	`city_code` ausente ou `rate_bps` fora de 0 a 10000.	`{"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"}`

Remover uma alíquota

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

Remove uma alíquota de ISS

Parâmetros de caminho

idintegerobrigatório

Id numérico da alíquota.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/tax/iss/7" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removida

json

{
  "status": "deleted"
}

Erros

Status	Quando	Corpo de exemplo
400	`id` não numérico.	`{"error":"invalid id"}`
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