Pular para o conteúdo principal

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.

O tipo de retorno foi corrigido na versão 1.0.168

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.