Endpoints de impostos

As URLs da API de impostos: a coleção (listar e criar) e um objeto de imposto individual (consultar, atualizar e excluir), com os códigos de resposta.

A API de impostos oferece endpoints para gerenciar as configurações de imposto do seu sistema. Com eles você cria, recupera, atualiza e exclui objetos de imposto que podem ser aplicados a produtos, serviços e transações. Todos usam credenciais HTTP Basic ($EMAIL:$API_KEY) e o endereço base da loja ($BASE_URL/api).

A coleção de impostos

O caminho /api/taxes acessa todos os objetos de imposto ou cria uma nova configuração de imposto.

Método	Descrição
GET	Recuperar todos os objetos de imposto
POST	Criar um novo objeto de imposto

Listar objetos de imposto

GET/api/taxesAdmin

Recupera todos os objetos de imposto

Parâmetros de consulta

pageintegerpadrão: 1

Página da lista, veja Paginação.

items_per_pageintegerpadrão: 10

Quantidade de registros de imposto por página.

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes"

200Exemplo de resposta do GET

json

{
  "data": [
    {
      "id": "tax_001",
      "name": "ICMS - São Paulo",
      "description": "State Tax for São Paulo",
      "rate": 18.0,
      "type": "percentage",
      "is_compound": false,
      "regions": ["SP"],
      "active": true,
      "created_at": "2024-12-10T08:15:30Z"
    },
    {
      "id": "tax_002",
      "name": "ISS - Serviços",
      "description": "Service Tax",
      "rate": 5.0,
      "type": "percentage",
      "is_compound": true,
      "product_categories": ["services"],
      "active": true,
      "created_at": "2024-12-15T10:30:45Z"
    }
  ],
  "meta": {
    "total": 6,
    "page": 1,
    "per_page": 10
  }
}

Criar um objeto de imposto

POST/api/taxesAdmin

Cria um novo objeto de imposto

Corpo da requisição

namestring

Nome do imposto.

descriptionstring

Descrição do imposto.

ratenumber

Alíquota do imposto.

typestring

Tipo da alíquota, por exemplo percentage.

is_compoundboolean

Indica se o imposto é composto.

priorityinteger

Ordem em que os impostos compostos são calculados. Valores menores são calculados primeiro.

activeboolean

Indica se o imposto está ativo.

exemptionsarray

Isenções, cada uma com um type (por exemplo customer_category) e uma lista de values.

bash

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "PIS/COFINS",
  "description": "Federal contribution taxes",
  "rate": 9.25,
  "type": "percentage",
  "is_compound": true,
  "priority": 1,
  "active": true,
  "exemptions": [
    {
      "type": "customer_category",
      "values": ["non_profit", "government"]
    }
  ]
}'

Um objeto de imposto

O caminho /api/taxes/{id} acessa, atualiza ou exclui um objeto de imposto pelo ID.

Parâmetros de caminho

idstringobrigatório

O identificador único do objeto de imposto.

Método	Descrição
GET	Recuperar um objeto de imposto
PUT	Atualizar um objeto de imposto
DELETE	Excluir um objeto de imposto

Consultar um objeto de imposto

GET/api/taxes/{id}Admin

Recupera um objeto de imposto

Parâmetros de caminho

idstringobrigatório

O identificador único do objeto de imposto.

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes/tax_001"

Atualizar um objeto de imposto

PUT/api/taxes/{id}Admin

Atualiza um objeto de imposto

Parâmetros de caminho

idstringobrigatório

O identificador único do objeto de imposto.

bash

curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes/tax_001" \
  -H "Content-Type: application/json" \
  -d '{
  "rate": 19.0,
  "description": "Updated State Tax for São Paulo",
  "active": true,
  "regions": ["SP", "RJ"]
}'

Excluir um objeto de imposto

DELETE/api/taxes/{id}Admin

Exclui um objeto de imposto

Parâmetros de caminho

idstringobrigatório

O identificador único do objeto de imposto.

bash

curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes/tax_001"

Códigos de status da resposta

Código de status	Descrição
`200 OK`	Operação concluída com sucesso
`400 Bad Request`	Parâmetros da requisição inválidos
`404 Not Found`	O objeto de imposto com o ID informado não existe
`409 Conflict`	Não é possível excluir um imposto que está em uso por produtos ou pedidos

Veja também

Impostos

As rotas das regras de imposto, com os filtros de consulta.

Campos

Todas as propriedades de um objeto de imposto.

API legada/Referência completa/Impostos

Endpoints de impostos

As URLs da API de impostos: a coleção (listar e criar) e um objeto de imposto individual (consultar, atualizar e excluir), com os códigos de resposta.

A coleção de impostos

O caminho /api/taxes acessa todos os objetos de imposto ou cria uma nova configuração de imposto.

Método	Descrição
GET	Recuperar todos os objetos de imposto
POST	Criar um novo objeto de imposto

Listar objetos de imposto

GET/api/taxesAdmin

Recupera todos os objetos de imposto

Parâmetros de consulta

pageintegerpadrão: 1

Página da lista, veja Paginação.

items_per_pageintegerpadrão: 10

Quantidade de registros de imposto por página.

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes"

200Exemplo de resposta do GET

json

{
  "data": [
    {
      "id": "tax_001",
      "name": "ICMS - São Paulo",
      "description": "State Tax for São Paulo",
      "rate": 18.0,
      "type": "percentage",
      "is_compound": false,
      "regions": ["SP"],
      "active": true,
      "created_at": "2024-12-10T08:15:30Z"
    },
    {
      "id": "tax_002",
      "name": "ISS - Serviços",
      "description": "Service Tax",
      "rate": 5.0,
      "type": "percentage",
      "is_compound": true,
      "product_categories": ["services"],
      "active": true,
      "created_at": "2024-12-15T10:30:45Z"
    }
  ],
  "meta": {
    "total": 6,
    "page": 1,
    "per_page": 10
  }
}

Criar um objeto de imposto

POST/api/taxesAdmin

Cria um novo objeto de imposto

Corpo da requisição

namestring

Nome do imposto.

descriptionstring

Descrição do imposto.

ratenumber

Alíquota do imposto.

typestring

Tipo da alíquota, por exemplo percentage.

is_compoundboolean

Indica se o imposto é composto.

priorityinteger

Ordem em que os impostos compostos são calculados. Valores menores são calculados primeiro.

activeboolean

Indica se o imposto está ativo.

exemptionsarray

Isenções, cada uma com um type (por exemplo customer_category) e uma lista de values.

bash

curl -X POST -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes" \
  -H "Content-Type: application/json" \
  -d '{
  "name": "PIS/COFINS",
  "description": "Federal contribution taxes",
  "rate": 9.25,
  "type": "percentage",
  "is_compound": true,
  "priority": 1,
  "active": true,
  "exemptions": [
    {
      "type": "customer_category",
      "values": ["non_profit", "government"]
    }
  ]
}'

Um objeto de imposto

O caminho /api/taxes/{id} acessa, atualiza ou exclui um objeto de imposto pelo ID.

Parâmetros de caminho

idstringobrigatório

O identificador único do objeto de imposto.

Método	Descrição
GET	Recuperar um objeto de imposto
PUT	Atualizar um objeto de imposto
DELETE	Excluir um objeto de imposto

Consultar um objeto de imposto

GET/api/taxes/{id}Admin

Recupera um objeto de imposto

Parâmetros de caminho

idstringobrigatório

O identificador único do objeto de imposto.

bash

curl -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes/tax_001"

Atualizar um objeto de imposto

PUT/api/taxes/{id}Admin

Atualiza um objeto de imposto

Parâmetros de caminho

idstringobrigatório

O identificador único do objeto de imposto.

bash

curl -X PUT -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes/tax_001" \
  -H "Content-Type: application/json" \
  -d '{
  "rate": 19.0,
  "description": "Updated State Tax for São Paulo",
  "active": true,
  "regions": ["SP", "RJ"]
}'

Excluir um objeto de imposto

DELETE/api/taxes/{id}Admin

Exclui um objeto de imposto

Parâmetros de caminho

idstringobrigatório

O identificador único do objeto de imposto.

bash

curl -X DELETE -u "$EMAIL:$API_KEY" "$BASE_URL/api/taxes/tax_001"

Códigos de status da resposta

Código de status	Descrição
`200 OK`	Operação concluída com sucesso
`400 Bad Request`	Parâmetros da requisição inválidos
`404 Not Found`	O objeto de imposto com o ID informado não existe
`409 Conflict`	Não é possível excluir um imposto que está em uso por produtos ou pedidos

Veja também

Impostos

As rotas das regras de imposto, com os filtros de consulta.

Campos

Todas as propriedades de um objeto de imposto.