API atual/Referência completa/Brasil: preço por UF e destinos

Regras de preço por UF

Lista, cria, altera e remove as regras que mudam o preço de um produto conforme a UF do comprador.

Use preço por UF quando o mesmo produto custa valores diferentes entre estados (por exemplo, por causa de impostos ou logística). Uma regra é uma faixa: UF + quantidade mínima. Várias faixas por UF permitem preço degrau (quanto mais unidades, menor o preço). A plataforma usa essas regras no carrinho e no checkout.

Listar regras de um produto

Devolve todas as regras do produto, ordenadas por UF e quantidade mínima. Produto sem regras (ou inexistente) volta lista vazia, não 404.

GET/api/v1/admin/brazil/state-pricing/{productID}Admin

Lista regras de um produto

Parâmetros de caminho

productIDuuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/brazil/state-pricing/d8a6c5e7-8e44-4055-a0e2-49014f5d17f6" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regras

json

{
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "rules": [
    {
      "id": 12,
      "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
      "state_code": "SP",
      "price_centavos": 15990,
      "min_qty": 1,
      "status": "A",
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

product_iduuid

Eco do produto pedido.

totalinteger

Quantidade de regras.

rulesarray

Regras, com os campos abaixo.

idinteger

Id numérico da regra.

product_iduuid

Produto.

state_codestring

UF em maiúsculas.

price_centavosinteger

Preço em centavos para quem compra a partir de min_qty.

min_qtyinteger

Quantidade mínima da faixa (mínimo 1).

statusstring

AD

A ativa, D desativada.

created_atstring

Criação (RFC 3339).

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_brazil` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}`

Criar uma regra

POST/api/v1/admin/brazil/state-pricingAdmin

Cria uma regra de preço

Corpo da requisição

product_iduuidobrigatório

Produto (UUID).

state_codestringobrigatório

UF, por exemplo SP.

price_centavosinteger

Preço em centavos, zero ou mais.

min_qtyintegerpadrão: 1

Quantidade mínima; menor que 1 vira 1.

statusstring

active/A ou disabled/D. Vazio = ativa.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/brazil/state-pricing" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
    "state_code": "SP",
    "price_centavos": 15990,
    "min_qty": 1
  }'

Resposta

201Regra criada

json

{
  "id": 12,
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "state_code": "SP",
  "price_centavos": 15990,
  "min_qty": 1,
  "status": "A",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger

Id numérico da regra.

product_iduuid

Produto.

state_codestring

UF em maiúsculas.

price_centavosinteger

Preço em centavos para quem compra a partir de min_qty.

min_qtyinteger

Quantidade mínima da faixa (mínimo 1).

statusstring

AD

A ativa, D desativada.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração.

Erros

Status	Quando	Corpo de exemplo
400	`product_id` ou `state_code` ausente, UF inexistente, preço negativo, ou regra repetida.	`{"error":"a rule for state SP with min_qty 1 already exists for this product"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_brazil` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}`

Alterar uma regra

Atualização parcial: só os campos enviados mudam.

PUT/api/v1/admin/brazil/state-pricing/{id}Admin

Altera uma regra de preço

Parâmetros de caminho

idintegerobrigatório

Id numérico da regra.

Corpo da requisição

state_codestring

Nova UF.

price_centavosinteger

Novo preço em centavos, zero ou mais.

min_qtyinteger

Nova quantidade mínima, pelo menos 1.

statusstring

A/active ou D/disabled.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/brazil/state-pricing/12" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price_centavos": 14990
  }'

Resposta

200Regra alterada

json

{
  "id": 12,
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "state_code": "SP",
  "price_centavos": 14990,
  "min_qty": 1,
  "status": "A",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger

Id numérico da regra.

product_iduuid

Produto.

state_codestring

UF em maiúsculas.

price_centavosinteger

Preço em centavos para quem compra a partir de min_qty.

min_qtyinteger

Quantidade mínima da faixa (mínimo 1).

statusstring

AD

A ativa, D desativada.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração.

Erros

Status	Quando	Corpo de exemplo
400	Id inválido, UF inexistente, preço negativo, `min_qty` menor que 1 ou status inválido.	`{"error":"min_qty must be at least 1"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_brazil` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}`
404	Regra inexistente.	`{"error":"state price rule 12 not found"}`

Remover uma regra

Apaga a regra de forma definitiva (não há lixeira). Para só pausar, mude o status para D.

DELETE/api/v1/admin/brazil/state-pricing/{id}Admin

Remove uma regra de preço

Parâmetros de caminho

idintegerobrigatório

Id numérico da regra.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/brazil/state-pricing/12" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removida

json

{
  "status": "deleted"
}

Erros

Status	Quando	Corpo de exemplo
400	Id inválido.	`{"error":"invalid rule ID"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_brazil` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}`
404	Regra inexistente.	`{"error":"state price rule 12 not found"}`

Veja também

API atual/Referência completa/Brasil: preço por UF e destinos

Regras de preço por UF

Lista, cria, altera e remove as regras que mudam o preço de um produto conforme a UF do comprador.

Listar regras de um produto

Devolve todas as regras do produto, ordenadas por UF e quantidade mínima. Produto sem regras (ou inexistente) volta lista vazia, não 404.

GET/api/v1/admin/brazil/state-pricing/{productID}Admin

Lista regras de um produto

Parâmetros de caminho

productIDuuidobrigatório

Id do produto.

Exemplo de requisição

bash

curl "$BASE_URL/api/v1/admin/brazil/state-pricing/d8a6c5e7-8e44-4055-a0e2-49014f5d17f6" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Regras

json

{
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "rules": [
    {
      "id": 12,
      "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
      "state_code": "SP",
      "price_centavos": 15990,
      "min_qty": 1,
      "status": "A",
      "created_at": "2026-10-11T12:00:00Z",
      "updated_at": "2026-10-11T12:00:00Z"
    }
  ],
  "total": 1
}

Campos da resposta

product_iduuid

Eco do produto pedido.

totalinteger

Quantidade de regras.

rulesarray

Regras, com os campos abaixo.

idinteger

Id numérico da regra.

product_iduuid

Produto.

state_codestring

UF em maiúsculas.

price_centavosinteger

Preço em centavos para quem compra a partir de min_qty.

min_qtyinteger

Quantidade mínima da faixa (mínimo 1).

statusstring

AD

A ativa, D desativada.

created_atstring

Criação (RFC 3339).

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_brazil` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}`

Criar uma regra

POST/api/v1/admin/brazil/state-pricingAdmin

Cria uma regra de preço

Corpo da requisição

product_iduuidobrigatório

Produto (UUID).

state_codestringobrigatório

UF, por exemplo SP.

price_centavosinteger

Preço em centavos, zero ou mais.

min_qtyintegerpadrão: 1

Quantidade mínima; menor que 1 vira 1.

statusstring

active/A ou disabled/D. Vazio = ativa.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/brazil/state-pricing" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
    "state_code": "SP",
    "price_centavos": 15990,
    "min_qty": 1
  }'

Resposta

201Regra criada

json

{
  "id": 12,
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "state_code": "SP",
  "price_centavos": 15990,
  "min_qty": 1,
  "status": "A",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger

Id numérico da regra.

product_iduuid

Produto.

state_codestring

UF em maiúsculas.

price_centavosinteger

Preço em centavos para quem compra a partir de min_qty.

min_qtyinteger

Quantidade mínima da faixa (mínimo 1).

statusstring

AD

A ativa, D desativada.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração.

Erros

Status	Quando	Corpo de exemplo
400	`product_id` ou `state_code` ausente, UF inexistente, preço negativo, ou regra repetida.	`{"error":"a rule for state SP with min_qty 1 already exists for this product"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_brazil` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}`

Alterar uma regra

Atualização parcial: só os campos enviados mudam.

PUT/api/v1/admin/brazil/state-pricing/{id}Admin

Altera uma regra de preço

Parâmetros de caminho

idintegerobrigatório

Id numérico da regra.

Corpo da requisição

state_codestring

Nova UF.

price_centavosinteger

Novo preço em centavos, zero ou mais.

min_qtyinteger

Nova quantidade mínima, pelo menos 1.

statusstring

A/active ou D/disabled.

Exemplo de requisição

bash

curl -X PUT "$BASE_URL/api/v1/admin/brazil/state-pricing/12" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "price_centavos": 14990
  }'

Resposta

200Regra alterada

json

{
  "id": 12,
  "product_id": "d8a6c5e7-8e44-4055-a0e2-49014f5d17f6",
  "state_code": "SP",
  "price_centavos": 14990,
  "min_qty": 1,
  "status": "A",
  "created_at": "2026-10-11T12:00:00Z",
  "updated_at": "2026-10-11T12:00:00Z"
}

Campos da resposta

idinteger

Id numérico da regra.

product_iduuid

Produto.

state_codestring

UF em maiúsculas.

price_centavosinteger

Preço em centavos para quem compra a partir de min_qty.

min_qtyinteger

Quantidade mínima da faixa (mínimo 1).

statusstring

AD

A ativa, D desativada.

created_atstring

Criação (RFC 3339).

updated_atstring

Última alteração.

Erros

Status	Quando	Corpo de exemplo
400	Id inválido, UF inexistente, preço negativo, `min_qty` menor que 1 ou status inválido.	`{"error":"min_qty must be at least 1"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_brazil` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}`
404	Regra inexistente.	`{"error":"state price rule 12 not found"}`

Remover uma regra

Apaga a regra de forma definitiva (não há lixeira). Para só pausar, mude o status para D.

DELETE/api/v1/admin/brazil/state-pricing/{id}Admin

Remove uma regra de preço

Parâmetros de caminho

idintegerobrigatório

Id numérico da regra.

Exemplo de requisição

bash

curl -X DELETE "$BASE_URL/api/v1/admin/brazil/state-pricing/12" \
  -H "Authorization: Bearer $TOKEN"

Resposta

200Removida

json

{
  "status": "deleted"
}

Erros

Status	Quando	Corpo de exemplo
400	Id inválido.	`{"error":"invalid rule ID"}`
401	Sem token ou token inválido.	`{"error":"missing authorization header"}`
403	O usuário não tem `manage_brazil` nem `manage_settings`.	`{"error":"insufficient privileges","privilege_required_any":["manage_brazil","manage_settings"]}`
404	Regra inexistente.	`{"error":"state price rule 12 not found"}`