API atual/Referência completa/Promoções e cupons

Estatísticas e projeção

Mede o uso de uma promoção (ou de todas) e projeta o retorno de um percentual de desconto.

stats responde "quanto essa promoção rendeu e custou?". uplift responde antes de criar: "se eu der 15%, o que acontece com a receita?". As duas só leem dados.

Estatísticas de uso

GET/api/v1/admin/promotions/statsAdmin

Estatísticas de uso de uma promoção ou de todas

Parâmetros de consulta

promotion_iduuid

Promoção a medir. Se omitido, soma todas as promoções (promotion_id volta vazio).

Exemplo de requisição: estatísticas

bash

curl "$BASE_URL/api/v1/admin/promotions/stats?promotion_id=7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30" \
  -H "Authorization: Bearer $TOKEN"

Resposta: estatísticas

200Estatísticas

json

{
  "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "total_uses": 25,
  "unique_customers": 7,
  "total_discount_sum": 51464,
  "revenue_influenced": 253690
}

Campos da resposta

promotion_idstring

A promoção medida; vazio na soma geral.

total_usesinteger

Quantas vezes foi usada.

unique_customersinteger

Clientes distintos que a usaram.

total_discount_suminteger

Desconto total concedido, em centavos.

revenue_influencedinteger

Valor dos pedidos em que ela foi usada, em centavos.

Erros: estatísticas

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	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`promotion_id` não é UUID.	`{"error":"invalid promotion_id","detail":"..."}`

Projeção de retorno

GET/api/v1/admin/promotions/upliftAdmin

Projeta o retorno de um desconto percentual

Parâmetros de consulta

discount_pctnumberobrigatório

Percentual de desconto a avaliar, maior que zero (por exemplo 15 para 15%). Note: aqui é percentual comum, não pontos-base.

Exemplo de requisição: projeção

bash

curl "$BASE_URL/api/v1/admin/promotions/uplift?discount_pct=15" \
  -H "Authorization: Bearer $TOKEN"

Resposta: projeção

200Ainda calculando

json

{
  "status": "calculating",
  "discount_pct": 15
}

Campos da resposta

statusstring

calculating quando ainda não há projeção recente para esse percentual. Quando há, a resposta traz o retorno esperado, a receita incremental e o custo de margem, nunca um número inventado.

discount_pctnumber

O percentual avaliado.

Erros: projeção

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	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`discount_pct` ausente, não numérico ou menor ou igual a zero.	`{"error":"invalid discount_pct","detail":"discount_pct (>0) is required"}`

Veja também

Estatísticas e projeção

Mede o uso de uma promoção (ou de todas) e projeta o retorno de um percentual de desconto.

stats responde "quanto essa promoção rendeu e custou?". uplift responde antes de criar: "se eu der 15%, o que acontece com a receita?". As duas só leem dados.

Estatísticas de uso

GET/api/v1/admin/promotions/statsAdmin

Estatísticas de uso de uma promoção ou de todas

Parâmetros de consulta

promotion_iduuid

Promoção a medir. Se omitido, soma todas as promoções (promotion_id volta vazio).

Exemplo de requisição: estatísticas

bash

curl "$BASE_URL/api/v1/admin/promotions/stats?promotion_id=7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30" \
  -H "Authorization: Bearer $TOKEN"

Resposta: estatísticas

200Estatísticas

json

{
  "promotion_id": "7c1f0a52-3b8e-4d11-9a47-5e2b6d8c1f30",
  "total_uses": 25,
  "unique_customers": 7,
  "total_discount_sum": 51464,
  "revenue_influenced": 253690
}

Campos da resposta

promotion_idstring

A promoção medida; vazio na soma geral.

total_usesinteger

Quantas vezes foi usada.

unique_customersinteger

Clientes distintos que a usaram.

total_discount_suminteger

Desconto total concedido, em centavos.

revenue_influencedinteger

Valor dos pedidos em que ela foi usada, em centavos.

Erros: estatísticas

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	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`promotion_id` não é UUID.	`{"error":"invalid promotion_id","detail":"..."}`

Projeção de retorno

GET/api/v1/admin/promotions/upliftAdmin

Projeta o retorno de um desconto percentual

Parâmetros de consulta

discount_pctnumberobrigatório

Percentual de desconto a avaliar, maior que zero (por exemplo 15 para 15%). Note: aqui é percentual comum, não pontos-base.

Exemplo de requisição: projeção

bash

curl "$BASE_URL/api/v1/admin/promotions/uplift?discount_pct=15" \
  -H "Authorization: Bearer $TOKEN"

Resposta: projeção

200Ainda calculando

json

{
  "status": "calculating",
  "discount_pct": 15
}

Campos da resposta

statusstring

calculating quando ainda não há projeção recente para esse percentual. Quando há, a resposta traz o retorno esperado, a receita incremental e o custo de margem, nunca um número inventado.

discount_pctnumber

O percentual avaliado.

Erros: projeção

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	O usuário não tem o privilégio exigido (`view_promotions` para ler, `manage_promotions` para gravar).	`{"error":"insufficient privileges","required":"manage_promotions"}`
400	`discount_pct` ausente, não numérico ou menor ou igual a zero.	`{"error":"invalid discount_pct","detail":"discount_pct (>0) is required"}`