getBonusHistory
Obtenha o histórico de transações de bônus do usuário atual. 🔐 Este método requer autorização.
Descrição
Busca as transações de bônus do usuário autenticado, opcionalmente filtradas por tipo, intervalo de datas, desconto, módulo e flag de administrador. Resolve para um IBonusHistoryResponse, um contêiner { items, total }, e não um array.
A API retorna no máximo as 30 transações mais recentes, das mais novas para as mais antigas. total é a contagem completa de transações correspondentes, então pode ser maior que items.length. O método ainda não aceita offset nem limit, então as transações além das 30 primeiras não podem ser obtidas; em vez disso, restrinja o intervalo com dateFrom/dateTo ou type.
Antes da versão 1.0.168, o método era declarado como retornando IBonusTransactionEntity[], mas o endpoint sempre retornou um contêiner: uma conta sem transações recebe {"items":[],"total":0}. O código escrito com base no tipo antigo lia .length de um objeto e obtinha undefined. Leia as transações em result.items e a contagem em result.total.
.getBonusHistory(
,
,
,
,
,
,
,
);
Esquema de parâmetros
Esquema
type: IBonusTransactionType
Tipo de transação para filtrar: ACCRUAL, USAGE, REDUCE, REVERSAL_ACCRUAL, REVERSAL_USAGE ou EXPIRATION.
dateFrom: string
Início do intervalo de datas. Data-hora ISO completa (2026-01-01T00:00:00.000Z); uma data simples responde 400 dateFrom must be a ISOString.
dateTo: string
Fim do intervalo de datas. Data-hora ISO completa (2026-12-31T00:00:00.000Z); uma data simples responde 400 dateTo must be a ISOString.
discountId: number
Retornar apenas transações deste ID de desconto.
moduleId: number
Retornar apenas transações deste módulo, por exemplo 2 para formulários ou 12 para pedidos.
isAdmin: boolean
Quando true, retorna apenas os ajustes manuais feitos por um administrador.
offset: number
Número de transações a pular, 0 ou mais. Padrão: 0.
exemplo: 0
limit: number
Número máximo de transações a retornar, 1 ou mais. Padrão: 30.
exemplo: 30
Exemplos
Exemplo mínimo
const response = await Discounts.getBonusHistory();
Exemplo com parâmetros opcionais
const response = await Discounts.getBonusHistory(
'ACCRUAL',
'2026-01-01T00:00:00.000Z',
'2026-12-31T23:59:59.000Z'
);
Exemplo de resposta
{
"items": [],
"total": 0
}
Esquema de resposta
Esquema: IBonusHistoryResponse
items: IBonusTransactionEntity[]
Até 30 transações correspondentes mais recentes, das mais novas para as mais antigas.
items.balanceId: number
ID do saldo de bônus.
items.amount: string
Valor da transação. A API o retorna como uma STRING decimal, por exemplo "100.00" (apesar de o swagger declará-lo como número) — faça o parse antes de operações aritméticas.
items.type: IBonusTransactionType
Tipo de transação.
items.discountId: number
ID do desconto.
items.moduleId: number
ID do módulo que gerou a transação, por exemplo 2 para formulários ou 12 para pedidos.
items.entityIdentifier: string
Identificador da entidade de origem no seu módulo, como um ID de pedido ou um marcador de formulário.
items.comment: string
Comentário.
items.isAdmin: boolean
Se um administrador fez a transação manualmente.
items.remainingAmount: string | null
Valor restante (para uso/expiração FIFO). STRING decimal como "100.00" em acúmulos, null em reduções.
items.triggerType: 'EVENT' | 'SCHEDULED'
O que acionou a transação: "EVENT" ou "SCHEDULED".
items.expiresAt: string
Quando o bônus acumulado expira; null se ele não expira.
items.createdAt: string
Data de criação.
total: number
Quantas transações o filtro corresponde no total.