API atual/Referência completa/Promoções do seller

Criar, alterar e excluir orçamento

Cria, ajusta e remove um teto de gasto em desconto do seller.

Crie um orçamento para proteger o caixa de uma campanha. Ele vale a partir do momento em que é criado e só conta descontos concedidos depois disso. O dono é sempre o seller do token e quem paga é sempre o seller (funding_source seller), mesmo que você envie outro valor. O PUT ajusta o teto, a janela, o alerta e o status; o que o orçamento limita (scope, scope_ref, dimension) não muda: para isso, exclua e crie outro. Para pausar sem perder o histórico de consumo, envie "status": "paused".

Criar um orçamento

POST/api/v1/vendor/promotion-budgetsSeller

Cria um orçamento de promoções do seller

Corpo da requisição

scopestringobrigatório

promotiongroupcategorybrandseller

O que o teto limita. marketplace é recusado com 403.

scope_refuuidobrigatório

Id do alvo, em UUID. Em promotion e group precisa ser do próprio seller; em seller precisa ser o id do seu seller; em category e brand qualquer UUID é aceito.

dimensionstringobrigatório

discount_amountredemptions

O que medir: centavos de desconto ou número de usos.

limit_centsinteger

Teto em centavos, para discount_amount.

limit_countinteger

Teto em usos, para redemptions. Em redemptions enviar só limit_cents é recusado.

windowstringpadrão: lifetime

lifetimedailyweeklymonthly

Janela de contagem.

alert_threshold_pctinteger

Percentual do teto (1 a 100) que liga alert_reached.

enforcementstringpadrão: stop_applying

Comportamento ao esgotar. Deixe o padrão.

on_low_balancestringpadrão: hard_stop

hard_stoppartial

Gravado, mas só hard_stop tem efeito hoje.

funding_splitobject

Partição do custo. Informativa.

statusstringpadrão: active

active ou outro valor para deixar o orçamento fora do cálculo.

Sem limit_cents nem limit_count o orçamento é ilimitado: serve só para medir o consumo.

Exemplo de requisição: criar

bash

curl -X POST "$BASE_URL/api/v1/vendor/promotion-budgets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "promotion",
    "scope_ref": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
    "dimension": "discount_amount",
    "limit_cents": 500000,
    "window": "monthly",
    "alert_threshold_pct": 80
  }'

Resposta: criar

201Orçamento criado

json

{
  "id": "3d0a7c1e-7b52-4a43-8d0f-0f6a21c9d001",
  "scope": "promotion",
  "scope_ref": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "dimension": "discount_amount",
  "limit_cents": 500000,
  "window": "monthly",
  "enforcement": "stop_applying",
  "alert_threshold_pct": 80,
  "on_low_balance": "hard_stop",
  "funding_source": "seller",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "active",
  "spent": 0,
  "usage_limit": 500000,
  "remaining": 500000,
  "unlimited": false,
  "exhausted": false,
  "alert_reached": false,
  "pct_used": 0
}

Os campos da resposta são os descritos em Consultar orçamentos.

Alterar um orçamento

PUT/api/v1/vendor/promotion-budgets/{id}Seller

Ajusta um orçamento do seller

Parâmetros de caminho

iduuidobrigatório

Id do orçamento.

Corpo da requisição

limit_centsinteger

Novo teto em centavos.

limit_countinteger

Novo teto em usos.

windowstring

lifetimedailyweeklymonthly

Nova janela.

enforcementstring

Comportamento ao esgotar. Deixe stop_applying.

alert_threshold_pctinteger

Novo percentual de alerta.

on_low_balancestring

hard_stoppartial

Gravado; só hard_stop tem efeito.

funding_sourcestring

Aceito, mas sempre regravado como seller.

funding_splitobject

Nova partição do custo. Informativa.

statusstring

active para valer; paused (ou outro valor) para deixar o orçamento fora do cálculo.

Exemplo de requisição: alterar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/promotion-budgets/3d0a7c1e-7b52-4a43-8d0f-0f6a21c9d001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "limit_cents": 800000, "status": "active" }'

Resposta: alterar

200Orçamento alterado

json

{
  "id": "3d0a7c1e-7b52-4a43-8d0f-0f6a21c9d001",
  "scope": "promotion",
  "dimension": "discount_amount",
  "limit_cents": 800000,
  "status": "active",
  "spent": 125000,
  "usage_limit": 800000,
  "remaining": 675000,
  "exhausted": false,
  "pct_used": 15
}

A resposta é o orçamento inteiro com o consumo (trimado aqui).

Excluir um orçamento

DELETE/api/v1/vendor/promotion-budgets/{id}Seller

Remove um orçamento do seller

Parâmetros de caminho

iduuidobrigatório

Id do orçamento.

Resposta: excluir

200Orçamento removido

json

{ "deleted": true }

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller.	`{"error":"insufficient permissions"}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	`scope` desconhecido.	`{"error":"invalid scope","detail":"store"}`
400	Escopo `promotion`, `group`, `category` ou `brand` sem `scope_ref`.	`{"error":"scope_ref is required for scope promotion"}`
400	`dimension` inválida, `scope_ref` que não tem forma de UUID, ou `redemptions` com `limit_cents` sem `limit_count`.	`{"error":"failed to create promotion budget","detail":"promotion budget validation: invalid dimension \"x\""}`
403	Escopo `marketplace`.	`{"error":"vendors cannot set marketplace budgets"}`
403	Escopo `seller` com o id de outro seller.	`{"error":"seller scope must reference your own vendor"}`
403	Promoção ou grupo que não é seu.	`{"error":"promotion does not belong to your vendor"}`
404	`scope` `promotion` com promoção inexistente; `group` com grupo inexistente; ou, em `PUT` e `DELETE`, orçamento inexistente ou de outro seller.	`{"error":"promotion budget not found"}`
500	Falha inesperada. Um `scope_ref` de promoção que não é UUID também chega como `500`.	`{"error":"failed to resolve promotion","detail":"..."}`

Veja também

API atual/Referência completa/Promoções do seller

Criar, alterar e excluir orçamento

Cria, ajusta e remove um teto de gasto em desconto do seller.

Criar um orçamento

POST/api/v1/vendor/promotion-budgetsSeller

Cria um orçamento de promoções do seller

Corpo da requisição

scopestringobrigatório

promotiongroupcategorybrandseller

O que o teto limita. marketplace é recusado com 403.

scope_refuuidobrigatório

Id do alvo, em UUID. Em promotion e group precisa ser do próprio seller; em seller precisa ser o id do seu seller; em category e brand qualquer UUID é aceito.

dimensionstringobrigatório

discount_amountredemptions

O que medir: centavos de desconto ou número de usos.

limit_centsinteger

Teto em centavos, para discount_amount.

limit_countinteger

Teto em usos, para redemptions. Em redemptions enviar só limit_cents é recusado.

windowstringpadrão: lifetime

lifetimedailyweeklymonthly

Janela de contagem.

alert_threshold_pctinteger

Percentual do teto (1 a 100) que liga alert_reached.

enforcementstringpadrão: stop_applying

Comportamento ao esgotar. Deixe o padrão.

on_low_balancestringpadrão: hard_stop

hard_stoppartial

Gravado, mas só hard_stop tem efeito hoje.

funding_splitobject

Partição do custo. Informativa.

statusstringpadrão: active

active ou outro valor para deixar o orçamento fora do cálculo.

Sem limit_cents nem limit_count o orçamento é ilimitado: serve só para medir o consumo.

Exemplo de requisição: criar

bash

curl -X POST "$BASE_URL/api/v1/vendor/promotion-budgets" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "scope": "promotion",
    "scope_ref": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
    "dimension": "discount_amount",
    "limit_cents": 500000,
    "window": "monthly",
    "alert_threshold_pct": 80
  }'

Resposta: criar

201Orçamento criado

json

{
  "id": "3d0a7c1e-7b52-4a43-8d0f-0f6a21c9d001",
  "scope": "promotion",
  "scope_ref": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "dimension": "discount_amount",
  "limit_cents": 500000,
  "window": "monthly",
  "enforcement": "stop_applying",
  "alert_threshold_pct": 80,
  "on_low_balance": "hard_stop",
  "funding_source": "seller",
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "status": "active",
  "spent": 0,
  "usage_limit": 500000,
  "remaining": 500000,
  "unlimited": false,
  "exhausted": false,
  "alert_reached": false,
  "pct_used": 0
}

Os campos da resposta são os descritos em Consultar orçamentos.

Alterar um orçamento

PUT/api/v1/vendor/promotion-budgets/{id}Seller

Ajusta um orçamento do seller

Parâmetros de caminho

iduuidobrigatório

Id do orçamento.

Corpo da requisição

limit_centsinteger

Novo teto em centavos.

limit_countinteger

Novo teto em usos.

windowstring

lifetimedailyweeklymonthly

Nova janela.

enforcementstring

Comportamento ao esgotar. Deixe stop_applying.

alert_threshold_pctinteger

Novo percentual de alerta.

on_low_balancestring

hard_stoppartial

Gravado; só hard_stop tem efeito.

funding_sourcestring

Aceito, mas sempre regravado como seller.

funding_splitobject

Nova partição do custo. Informativa.

statusstring

active para valer; paused (ou outro valor) para deixar o orçamento fora do cálculo.

Exemplo de requisição: alterar

bash

curl -X PUT "$BASE_URL/api/v1/vendor/promotion-budgets/3d0a7c1e-7b52-4a43-8d0f-0f6a21c9d001" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "limit_cents": 800000, "status": "active" }'

Resposta: alterar

200Orçamento alterado

json

{
  "id": "3d0a7c1e-7b52-4a43-8d0f-0f6a21c9d001",
  "scope": "promotion",
  "dimension": "discount_amount",
  "limit_cents": 800000,
  "status": "active",
  "spent": 125000,
  "usage_limit": 800000,
  "remaining": 675000,
  "exhausted": false,
  "pct_used": 15
}

A resposta é o orçamento inteiro com o consumo (trimado aqui).

Excluir um orçamento

DELETE/api/v1/vendor/promotion-budgets/{id}Seller

Remove um orçamento do seller

Parâmetros de caminho

iduuidobrigatório

Id do orçamento.

Resposta: excluir

200Orçamento removido

json

{ "deleted": true }

Erros

Status	Quando	Corpo de exemplo
401	Token ausente ou inválido.	`{"error":"missing authorization header"}`
403	O token não é de um usuário seller.	`{"error":"insufficient permissions"}`
400	Corpo que não é JSON.	`{"error":"invalid request body","detail":"..."}`
400	`scope` desconhecido.	`{"error":"invalid scope","detail":"store"}`
400	Escopo `promotion`, `group`, `category` ou `brand` sem `scope_ref`.	`{"error":"scope_ref is required for scope promotion"}`
400	`dimension` inválida, `scope_ref` que não tem forma de UUID, ou `redemptions` com `limit_cents` sem `limit_count`.	`{"error":"failed to create promotion budget","detail":"promotion budget validation: invalid dimension \"x\""}`
403	Escopo `marketplace`.	`{"error":"vendors cannot set marketplace budgets"}`
403	Escopo `seller` com o id de outro seller.	`{"error":"seller scope must reference your own vendor"}`
403	Promoção ou grupo que não é seu.	`{"error":"promotion does not belong to your vendor"}`
404	`scope` `promotion` com promoção inexistente; `group` com grupo inexistente; ou, em `PUT` e `DELETE`, orçamento inexistente ou de outro seller.	`{"error":"promotion budget not found"}`
500	Falha inesperada. Um `scope_ref` de promoção que não é UUID também chega como `500`.	`{"error":"failed to resolve promotion","detail":"..."}`