API atual/Referência completa/Orçamentos e grupos de promoções

Consultar orçamentos

Lista os orçamentos de promoções com o consumo atual e devolve o detalhe de um deles.

Cada orçamento já vem com o consumo calculado na hora (spent, remaining, pct_used) e as marcas exhausted e alert_reached, então não é preciso somar nada do seu lado. A lista não é paginada: devolve todos, do mais novo para o mais antigo.

Listar orçamentos

GET/api/v1/admin/promotion-budgetsAdmin

Lista os orçamentos de promoções com o consumo

Parâmetros de consulta

scopestring

promotiongroupcategorybrandsellermarketplace

Filtra por escopo.

scope_refuuid

Filtra pelo id do alvo.

vendor_iduuid

Só orçamentos deste seller. Presente e vazio (?vendor_id=) devolve só os da loja.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/admin/promotion-budgets?scope=group" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Orçamentos

json

{
  "budgets": [
    {
      "id": "c777e051-253e-4da0-a156-a1fe4032e8d1",
      "scope": "group",
      "scope_ref": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
      "dimension": "discount_amount",
      "limit_cents": 999900,
      "window": "lifetime",
      "enforcement": "stop_applying",
      "on_low_balance": "hard_stop",
      "funding_source": "seller",
      "status": "active",
      "created_at": "2026-07-20T00:55:13.241665Z",
      "updated_at": "2026-07-20T01:32:33.732761Z",
      "spent": 120000,
      "usage_limit": 999900,
      "remaining": 879900,
      "unlimited": false,
      "exhausted": false,
      "alert_reached": false,
      "pct_used": 12
    }
  ]
}

Campos da resposta

budgetsarray

Os orçamentos, com os campos abaixo. Lista vazia vem como [].

iduuid

Identificador do orçamento.

scopestring

O que o teto limita: promotion, group, category, brand, seller ou marketplace.

scope_refuuid | omitted

Id do alvo do escopo. Ausente em marketplace.

dimensionstring

O que é medido: discount_amount (centavos de desconto) ou redemptions (número de usos).

limit_centsinteger | omitted

Teto em centavos, para discount_amount.

limit_countinteger | omitted

Teto em número de usos, para redemptions.

windowstring

Janela de contagem: lifetime, daily, weekly ou monthly (fuso de São Paulo).

enforcementstring

Como reage ao esgotar. Hoje o único comportamento é parar de aplicar (stop_applying).

alert_threshold_pctinteger | omitted

Percentual de consumo (1 a 100) a partir do qual alert_reached vira true.

on_low_balancestring

hard_stop ou partial. Hoje só hard_stop tem efeito; partial é gravado mas não lido.

funding_sourcestring

Quem paga o desconto: seller, operator, manufacturer ou shared. Informativo: não muda se o orçamento bloqueia.

funding_splitobject | omitted

Partição do custo quando funding_source é shared.

vendor_iduuid | omitted

Seller dono do orçamento. Ausente = orçamento da loja.

statusstring

active participa do cálculo; qualquer outro valor deixa o orçamento fora.

created_atstring (RFC 3339)

Criação.

updated_atstring (RFC 3339)

Última alteração.

spentinteger

Consumo atual na janela corrente, na unidade da dimensão (centavos ou usos). Soma o que já foi concretizado em pedidos e o que está reservado em carrinhos que ainda não expiraram.

usage_limitinteger | null

O teto na mesma unidade de spent (limit_cents ou limit_count). null = sem teto.

remaininginteger

usage_limit menos spent. 0 quando não há teto.

unlimitedboolean

true quando não há teto (o orçamento só mede).

exhaustedboolean

true quando remaining chegou a zero ou menos: as promoções cobertas param de aplicar.

alert_reachedboolean

true quando o consumo passou de alert_threshold_pct.

pct_usedinteger

Consumo em percentual inteiro do teto. 0 sem teto.

Erros: listar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	Falta o privilégio: `view_promotions` para ler, `manage_promotions` para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
500	Falha ao consultar o banco.	`{"error":"failed to list promotion budgets","detail":"..."}`

Detalhar um orçamento

GET/api/v1/admin/promotion-budgets/{id}Admin

Detalha um orçamento

Parâmetros de caminho

iduuidobrigatório

Id do orçamento.

Exemplo de requisição: detalhar

bash

curl "$BASE_URL/api/v1/admin/promotion-budgets/c777e051-253e-4da0-a156-a1fe4032e8d1" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Orçamento

json

{
  "id": "c777e051-253e-4da0-a156-a1fe4032e8d1",
  "scope": "group",
  "scope_ref": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
  "dimension": "discount_amount",
  "limit_cents": 999900,
  "window": "lifetime",
  "enforcement": "stop_applying",
  "on_low_balance": "hard_stop",
  "funding_source": "seller",
  "status": "active",
  "created_at": "2026-07-20T00:55:13.241665Z",
  "updated_at": "2026-07-20T01:32:33.732761Z",
  "spent": 120000,
  "usage_limit": 999900,
  "remaining": 879900,
  "unlimited": false,
  "exhausted": false,
  "alert_reached": false,
  "pct_used": 12
}

Campos da resposta

(campos do orçamento)object

Os mesmos campos de cada item da lista.

Erros: detalhar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	Falta o privilégio: `view_promotions` para ler, `manage_promotions` para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
500	O id não é um UUID válido. Hoje esta rota responde `500` (e não `400`) nesse caso; a mensagem em `detail` explica o problema.	`{"error":"failed to get promotion budget","detail":"o valor \"xyz\" não é um uuid válido. ..."}`
404	Não existe orçamento com esse id.	`{"error":"failed to get promotion budget","detail":"promotion budget not found"}`

Veja também

Consultar orçamentos

Lista os orçamentos de promoções com o consumo atual e devolve o detalhe de um deles.

Listar orçamentos

GET/api/v1/admin/promotion-budgetsAdmin

Lista os orçamentos de promoções com o consumo

Parâmetros de consulta

scopestring

promotiongroupcategorybrandsellermarketplace

Filtra por escopo.

scope_refuuid

Filtra pelo id do alvo.

vendor_iduuid

Só orçamentos deste seller. Presente e vazio (?vendor_id=) devolve só os da loja.

Exemplo de requisição: listar

bash

curl "$BASE_URL/api/v1/admin/promotion-budgets?scope=group" \
  -H "Authorization: Bearer $TOKEN"

Resposta: listar

200Orçamentos

json

{
  "budgets": [
    {
      "id": "c777e051-253e-4da0-a156-a1fe4032e8d1",
      "scope": "group",
      "scope_ref": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
      "dimension": "discount_amount",
      "limit_cents": 999900,
      "window": "lifetime",
      "enforcement": "stop_applying",
      "on_low_balance": "hard_stop",
      "funding_source": "seller",
      "status": "active",
      "created_at": "2026-07-20T00:55:13.241665Z",
      "updated_at": "2026-07-20T01:32:33.732761Z",
      "spent": 120000,
      "usage_limit": 999900,
      "remaining": 879900,
      "unlimited": false,
      "exhausted": false,
      "alert_reached": false,
      "pct_used": 12
    }
  ]
}

Campos da resposta

budgetsarray

Os orçamentos, com os campos abaixo. Lista vazia vem como [].

iduuid

Identificador do orçamento.

scopestring

O que o teto limita: promotion, group, category, brand, seller ou marketplace.

scope_refuuid | omitted

Id do alvo do escopo. Ausente em marketplace.

dimensionstring

O que é medido: discount_amount (centavos de desconto) ou redemptions (número de usos).

limit_centsinteger | omitted

Teto em centavos, para discount_amount.

limit_countinteger | omitted

Teto em número de usos, para redemptions.

windowstring

Janela de contagem: lifetime, daily, weekly ou monthly (fuso de São Paulo).

enforcementstring

Como reage ao esgotar. Hoje o único comportamento é parar de aplicar (stop_applying).

alert_threshold_pctinteger | omitted

Percentual de consumo (1 a 100) a partir do qual alert_reached vira true.

on_low_balancestring

hard_stop ou partial. Hoje só hard_stop tem efeito; partial é gravado mas não lido.

funding_sourcestring

Quem paga o desconto: seller, operator, manufacturer ou shared. Informativo: não muda se o orçamento bloqueia.

funding_splitobject | omitted

Partição do custo quando funding_source é shared.

vendor_iduuid | omitted

Seller dono do orçamento. Ausente = orçamento da loja.

statusstring

active participa do cálculo; qualquer outro valor deixa o orçamento fora.

created_atstring (RFC 3339)

Criação.

updated_atstring (RFC 3339)

Última alteração.

spentinteger

Consumo atual na janela corrente, na unidade da dimensão (centavos ou usos). Soma o que já foi concretizado em pedidos e o que está reservado em carrinhos que ainda não expiraram.

usage_limitinteger | null

O teto na mesma unidade de spent (limit_cents ou limit_count). null = sem teto.

remaininginteger

usage_limit menos spent. 0 quando não há teto.

unlimitedboolean

true quando não há teto (o orçamento só mede).

exhaustedboolean

true quando remaining chegou a zero ou menos: as promoções cobertas param de aplicar.

alert_reachedboolean

true quando o consumo passou de alert_threshold_pct.

pct_usedinteger

Consumo em percentual inteiro do teto. 0 sem teto.

Erros: listar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	Falta o privilégio: `view_promotions` para ler, `manage_promotions` para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
500	Falha ao consultar o banco.	`{"error":"failed to list promotion budgets","detail":"..."}`

Detalhar um orçamento

GET/api/v1/admin/promotion-budgets/{id}Admin

Detalha um orçamento

Parâmetros de caminho

iduuidobrigatório

Id do orçamento.

Exemplo de requisição: detalhar

bash

curl "$BASE_URL/api/v1/admin/promotion-budgets/c777e051-253e-4da0-a156-a1fe4032e8d1" \
  -H "Authorization: Bearer $TOKEN"

Resposta: detalhar

200Orçamento

json

{
  "id": "c777e051-253e-4da0-a156-a1fe4032e8d1",
  "scope": "group",
  "scope_ref": "7af8cfda-fbbc-4a75-b266-fb90ad2d11fb",
  "dimension": "discount_amount",
  "limit_cents": 999900,
  "window": "lifetime",
  "enforcement": "stop_applying",
  "on_low_balance": "hard_stop",
  "funding_source": "seller",
  "status": "active",
  "created_at": "2026-07-20T00:55:13.241665Z",
  "updated_at": "2026-07-20T01:32:33.732761Z",
  "spent": 120000,
  "usage_limit": 999900,
  "remaining": 879900,
  "unlimited": false,
  "exhausted": false,
  "alert_reached": false,
  "pct_used": 12
}

Campos da resposta

(campos do orçamento)object

Os mesmos campos de cada item da lista.

Erros: detalhar

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"authentication required"}`
403	O módulo `promotions` está desligado na loja.	`{"error":"module_disabled","module":"promotions"}`
403	Falta o privilégio: `view_promotions` para ler, `manage_promotions` para gravar.	`{"error":"insufficient privileges","required":"manage_promotions"}`
500	O id não é um UUID válido. Hoje esta rota responde `500` (e não `400`) nesse caso; a mensagem em `detail` explica o problema.	`{"error":"failed to get promotion budget","detail":"o valor \"xyz\" não é um uuid válido. ..."}`
404	Não existe orçamento com esse id.	`{"error":"failed to get promotion budget","detail":"promotion budget not found"}`