API atual/Referência completa/Campo e alçadas dos representantes

Alçadas e régua de desconto

Configura por seller os parâmetros financeiros e a régua de desconto por cluster, e simula em qual camada um desconto cai.

Estas rotas configuram quanto desconto um representante pode dar e quem precisa aprovar o que passa disso. Tudo é configurado por seller (vendor_id). Para entender a cadeia (livre, alçada própria, aprovação), leia a visão geral. Descontos em pontos-base (500 = 5%), preços em centavos.

Ler os parâmetros financeiros

GET/api/v1/admin/trade-reps/finance-settingsAdmin

Lê os parâmetros financeiros de um seller

Parâmetros de consulta

vendor_iduuidobrigatório

Seller.

200Parâmetros

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "order_commission_bp": 300,
  "global_free_discount_bp": 200,
  "approval_limit_1_bp": 500,
  "approval_limit_2_bp": 1000,
  "approval_limit_3_bp": 1500,
  "blocked_order_status": "",
  "extended_approval_levels": false
}

Campos da resposta

vendor_iduuid

Seller.

order_commission_bpinteger

Comissão sobre o pedido, em pontos-base, creditada ao representante na conta-corrente.

global_free_discount_bpinteger

Desconto livre padrão do seller, usado quando nem o produto nem a categoria têm um limite próprio.

approval_limit_1_bpinteger

Excesso sobre o desconto livre até o qual o nível 1 aprova. Acima disso o nível exigido é 2 (ou mais, com níveis estendidos). 0 significa que o nível 1 resolve tudo.

approval_limit_2_bpinteger

Excesso até o qual o nível 2 aprova. Só vale com extended_approval_levels.

approval_limit_3_bpinteger

Excesso até o qual o nível 3 aprova. Só vale com extended_approval_levels. Acima disso o nível exigido é 4, que a plataforma bloqueia (não há quem aprove).

blocked_order_statusstring

Código do status em que o pedido fica retido enquanto espera a aprovação de desconto. Vazio usa o status de espera padrão da loja.

extended_approval_levelsboolean

false: só existem os níveis 1 e 2. true: níveis 1 a 3 e o nível 4 como bloqueio.

Para um seller sem configuração salva, o GET devolve todos os campos em 0, vazio ou false.

Gravar os parâmetros financeiros

Grava (cria ou substitui) a configuração do seller. É um upsert completo: todo campo não enviado é gravado como 0, vazio ou false.

PUT/api/v1/admin/trade-reps/finance-settingsAdmin

Grava os parâmetros financeiros de um seller

Corpo da requisição

vendor_iduuidobrigatório

Seller.

order_commission_bpintegerpadrão: 0

Comissão sobre o pedido, em pontos-base.

global_free_discount_bpintegerpadrão: 0

Desconto livre padrão, em pontos-base.

approval_limit_1_bpintegerpadrão: 0

Limite do nível 1.

approval_limit_2_bpintegerpadrão: 0

Limite do nível 2.

approval_limit_3_bpintegerpadrão: 0

Limite do nível 3.

blocked_order_statusstring

Status em que o pedido fica retido aguardando aprovação.

extended_approval_levelsbooleanpadrão: false

Liga os níveis 3 e 4.

A resposta é o mesmo objeto enviado (200).

Simular um desconto

Não cria nada. Diz em qual camada um preço cai para um representante, quanto custaria (débito) e se precisaria de aprovação.

POST/api/v1/admin/trade-reps/discount-previewAdmin

Simula a alçada de um preço com desconto

Corpo da requisição

vendor_iduuidobrigatório

Seller (usado para o desconto livre e os níveis).

rep_idintegerobrigatório

Representante que daria o desconto.

product_iduuid

Produto. Procura o desconto livre do produto primeiro.

category_iduuid

Categoria. Usada se o produto não tem limite próprio.

original_price_centsintegerobrigatório

Preço de tabela, em centavos.

price_centsintegerobrigatório

Preço negociado, em centavos.

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/discount-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "rep_id": 2, "original_price_cents": 10000, "price_cents": 9000}'

200Simulação

json

{
  "discount_bp": 1000,
  "free_limit_bp": 0,
  "rep_limit_bp": 200,
  "debit_cents": 0,
  "requires_approval": true,
  "required_level": 1,
  "allowed": false,
  "message": "discount exceeds free+rep alçada; requires level 1"
}

Campos da resposta

discount_bpinteger

Desconto pedido, em pontos-base, calculado de original_price_cents e price_cents.

free_limit_bpinteger

Desconto livre aplicável (produto, depois categoria, depois o global do seller).

rep_limit_bpinteger

Alçada própria do representante (discount_limit_bp).

debit_centsinteger

Débito na conta-corrente quando o desconto passa do livre mas cabe na alçada. Em centavos.

requires_approvalboolean

true quando passa do livre somado à alçada.

required_levelinteger

Nível de aprovação exigido, de 1 a 4. Só quando requires_approval. O nível 4 não pode ser aprovado.

allowedboolean

true quando o representante pode dar o desconto sozinho.

messagestring

Explicação curta. Vem em inglês misturado a "alçada" (termo da plataforma para o limite de desconto).

Se o preço negociado é maior ou igual ao de tabela, ou o preço de tabela é zero, a resposta é allowed: true com uma message explicando.

Ler a régua de desconto

A régua é uma matriz de desconto máximo por cluster do cliente (P, M, G) e nível hierárquico (0 a 3), por seller.

GET/api/v1/admin/trade-reps/discount-rulerAdmin

Lê a régua de desconto de um seller

Parâmetros de consulta

vendor_iduuidobrigatório

Seller.

200Régua sugerida (ainda não gravada)

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "seeded": true,
  "message": "Matriz padrão P/M/G (não salva — clique em Salvar para persistir)",
  "cells": [
    { "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "cluster_code": "P", "hierarchy_level": 0, "max_discount_bp": 500 },
    { "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "cluster_code": "P", "hierarchy_level": 1, "max_discount_bp": 1000 }
  ]
}

Campos da resposta

cellsarray

Células da matriz, ordenadas por cluster e nível.

cells[].cluster_codestring

PMG*

Cluster do cliente. * vale para qualquer cluster sem célula própria.

cells[].hierarchy_levelinteger

0123

Nível hierárquico.

cells[].max_discount_bpinteger

Desconto máximo, em pontos-base.

seededboolean

Presente e true quando o seller não tem régua salva: as cells são uma sugestão (P 500/1000/1500/2000, M 300/800/1200/1800, G 200/500/1000/1500 por nível 0 a 3) e nada foi gravado.

messagestring

Aviso que acompanha a sugestão (texto em português, como o servidor devolve).

Gravar a régua de desconto

PUT/api/v1/admin/trade-reps/discount-rulerAdmin

Grava a régua de desconto de um seller

Corpo da requisição

vendor_iduuidobrigatório

Seller.

cellsarrayobrigatório

Células da matriz.

cells[].cluster_codestringobrigatório

PMG*

Cluster. Aceita também pequeno, medio, grande (e small, medium, large), convertidos para a letra.

cells[].hierarchy_levelintegerobrigatório

0123

Nível. Valores fora de 0 a 3 são ajustados para o extremo mais próximo.

cells[].max_discount_bpintegerobrigatório

Desconto máximo em pontos-base. Negativo vira 0.

replacebooleanpadrão: true

true apaga a matriz atual antes de gravar; false só atualiza as células enviadas e mantém as outras.

A resposta é a régua gravada, no mesmo formato do GET.

Erros

Status	Quando	Corpo de exemplo
400	Falta `vendor_id` (nos quatro `GET`/`PUT` de configuração).	`{"error":"vendor_id is required"}`
400	Falta `vendor_id` no `PUT` de parâmetros.	`{"error":"save failed","detail":"vendor_id is required"}`
400	Corpo não é JSON.	`{"error":"invalid body","detail":"..."}`
400	Representante da simulação não existe.	`{"error":"preview failed","detail":"rep not found"}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`

Veja também

API atual/Referência completa/Campo e alçadas dos representantes

Alçadas e régua de desconto

Configura por seller os parâmetros financeiros e a régua de desconto por cluster, e simula em qual camada um desconto cai.

Ler os parâmetros financeiros

GET/api/v1/admin/trade-reps/finance-settingsAdmin

Lê os parâmetros financeiros de um seller

Parâmetros de consulta

vendor_iduuidobrigatório

Seller.

200Parâmetros

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "order_commission_bp": 300,
  "global_free_discount_bp": 200,
  "approval_limit_1_bp": 500,
  "approval_limit_2_bp": 1000,
  "approval_limit_3_bp": 1500,
  "blocked_order_status": "",
  "extended_approval_levels": false
}

Campos da resposta

vendor_iduuid

Seller.

order_commission_bpinteger

Comissão sobre o pedido, em pontos-base, creditada ao representante na conta-corrente.

global_free_discount_bpinteger

Desconto livre padrão do seller, usado quando nem o produto nem a categoria têm um limite próprio.

approval_limit_1_bpinteger

Excesso sobre o desconto livre até o qual o nível 1 aprova. Acima disso o nível exigido é 2 (ou mais, com níveis estendidos). 0 significa que o nível 1 resolve tudo.

approval_limit_2_bpinteger

Excesso até o qual o nível 2 aprova. Só vale com extended_approval_levels.

approval_limit_3_bpinteger

Excesso até o qual o nível 3 aprova. Só vale com extended_approval_levels. Acima disso o nível exigido é 4, que a plataforma bloqueia (não há quem aprove).

blocked_order_statusstring

Código do status em que o pedido fica retido enquanto espera a aprovação de desconto. Vazio usa o status de espera padrão da loja.

extended_approval_levelsboolean

false: só existem os níveis 1 e 2. true: níveis 1 a 3 e o nível 4 como bloqueio.

Para um seller sem configuração salva, o GET devolve todos os campos em 0, vazio ou false.

Gravar os parâmetros financeiros

Grava (cria ou substitui) a configuração do seller. É um upsert completo: todo campo não enviado é gravado como 0, vazio ou false.

PUT/api/v1/admin/trade-reps/finance-settingsAdmin

Grava os parâmetros financeiros de um seller

Corpo da requisição

vendor_iduuidobrigatório

Seller.

order_commission_bpintegerpadrão: 0

Comissão sobre o pedido, em pontos-base.

global_free_discount_bpintegerpadrão: 0

Desconto livre padrão, em pontos-base.

approval_limit_1_bpintegerpadrão: 0

Limite do nível 1.

approval_limit_2_bpintegerpadrão: 0

Limite do nível 2.

approval_limit_3_bpintegerpadrão: 0

Limite do nível 3.

blocked_order_statusstring

Status em que o pedido fica retido aguardando aprovação.

extended_approval_levelsbooleanpadrão: false

Liga os níveis 3 e 4.

A resposta é o mesmo objeto enviado (200).

Simular um desconto

Não cria nada. Diz em qual camada um preço cai para um representante, quanto custaria (débito) e se precisaria de aprovação.

POST/api/v1/admin/trade-reps/discount-previewAdmin

Simula a alçada de um preço com desconto

Corpo da requisição

vendor_iduuidobrigatório

Seller (usado para o desconto livre e os níveis).

rep_idintegerobrigatório

Representante que daria o desconto.

product_iduuid

Produto. Procura o desconto livre do produto primeiro.

category_iduuid

Categoria. Usada se o produto não tem limite próprio.

original_price_centsintegerobrigatório

Preço de tabela, em centavos.

price_centsintegerobrigatório

Preço negociado, em centavos.

bash

curl -X POST "$BASE_URL/api/v1/admin/trade-reps/discount-preview" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "rep_id": 2, "original_price_cents": 10000, "price_cents": 9000}'

200Simulação

json

{
  "discount_bp": 1000,
  "free_limit_bp": 0,
  "rep_limit_bp": 200,
  "debit_cents": 0,
  "requires_approval": true,
  "required_level": 1,
  "allowed": false,
  "message": "discount exceeds free+rep alçada; requires level 1"
}

Campos da resposta

discount_bpinteger

Desconto pedido, em pontos-base, calculado de original_price_cents e price_cents.

free_limit_bpinteger

Desconto livre aplicável (produto, depois categoria, depois o global do seller).

rep_limit_bpinteger

Alçada própria do representante (discount_limit_bp).

debit_centsinteger

Débito na conta-corrente quando o desconto passa do livre mas cabe na alçada. Em centavos.

requires_approvalboolean

true quando passa do livre somado à alçada.

required_levelinteger

Nível de aprovação exigido, de 1 a 4. Só quando requires_approval. O nível 4 não pode ser aprovado.

allowedboolean

true quando o representante pode dar o desconto sozinho.

messagestring

Explicação curta. Vem em inglês misturado a "alçada" (termo da plataforma para o limite de desconto).

Se o preço negociado é maior ou igual ao de tabela, ou o preço de tabela é zero, a resposta é allowed: true com uma message explicando.

Ler a régua de desconto

A régua é uma matriz de desconto máximo por cluster do cliente (P, M, G) e nível hierárquico (0 a 3), por seller.

GET/api/v1/admin/trade-reps/discount-rulerAdmin

Lê a régua de desconto de um seller

Parâmetros de consulta

vendor_iduuidobrigatório

Seller.

200Régua sugerida (ainda não gravada)

json

{
  "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36",
  "seeded": true,
  "message": "Matriz padrão P/M/G (não salva — clique em Salvar para persistir)",
  "cells": [
    { "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "cluster_code": "P", "hierarchy_level": 0, "max_discount_bp": 500 },
    { "vendor_id": "94bd7e9a-fdad-4d01-8fc2-ba9d677d8b36", "cluster_code": "P", "hierarchy_level": 1, "max_discount_bp": 1000 }
  ]
}

Campos da resposta

cellsarray

Células da matriz, ordenadas por cluster e nível.

cells[].cluster_codestring

PMG*

Cluster do cliente. * vale para qualquer cluster sem célula própria.

cells[].hierarchy_levelinteger

0123

Nível hierárquico.

cells[].max_discount_bpinteger

Desconto máximo, em pontos-base.

seededboolean

Presente e true quando o seller não tem régua salva: as cells são uma sugestão (P 500/1000/1500/2000, M 300/800/1200/1800, G 200/500/1000/1500 por nível 0 a 3) e nada foi gravado.

messagestring

Aviso que acompanha a sugestão (texto em português, como o servidor devolve).

Gravar a régua de desconto

PUT/api/v1/admin/trade-reps/discount-rulerAdmin

Grava a régua de desconto de um seller

Corpo da requisição

vendor_iduuidobrigatório

Seller.

cellsarrayobrigatório

Células da matriz.

cells[].cluster_codestringobrigatório

PMG*

Cluster. Aceita também pequeno, medio, grande (e small, medium, large), convertidos para a letra.

cells[].hierarchy_levelintegerobrigatório

0123

Nível. Valores fora de 0 a 3 são ajustados para o extremo mais próximo.

cells[].max_discount_bpintegerobrigatório

Desconto máximo em pontos-base. Negativo vira 0.

replacebooleanpadrão: true

true apaga a matriz atual antes de gravar; false só atualiza as células enviadas e mantém as outras.

A resposta é a régua gravada, no mesmo formato do GET.

Erros

Status	Quando	Corpo de exemplo
400	Falta `vendor_id` (nos quatro `GET`/`PUT` de configuração).	`{"error":"vendor_id is required"}`
400	Falta `vendor_id` no `PUT` de parâmetros.	`{"error":"save failed","detail":"vendor_id is required"}`
400	Corpo não é JSON.	`{"error":"invalid body","detail":"..."}`
400	Representante da simulação não existe.	`{"error":"preview failed","detail":"rep not found"}`
401 / 403	Sem token, módulo desligado ou sem privilégio.	`{"error":"module_disabled","module":"trade-reps"}`