Calcula o cashback que um determinado pedido pode acumular. Este endpoint
opera em dois modos: Privado e Público. Escolha o modo conforme o
seu caso de uso abaixo.
Try-it values populated from environment ACME (Demo)
Retorna dados do cliente, informações de resgate disponível e um
token de confirmação que pode ser usado depois no confirmOrder.
Exige um token de usuário válido.
Autenticação
Token
Send your user token in the x-guper-authorization header. Endpoints that
support a Public mode (e.g. acúmulo and resgate previews) accept the same
request without the header — Private mode adds customer data and a
confirmation token to the response.
Cabeçalhos
Name
Type
Description
x-guper-authorization
*
string
User token issued by Guper. Omit only on endpoints that explicitly support a Public mode.
Content-Type
*
string
Always `application/json` for endpoints that accept a JSON body.
Tipo da compra, definido pela sua integração (texto livre, ex.: delivery, retirada, loja-fisica). Até 100 caracteres; espaços nas pontas são removidos e valor vazio é ignorado. Qualquer outro tipo (número, booleano, lista) retorna 400.
Fica guardado com a transação até o confirmOrder e o updateTransaction. É usado pela regra de campanha Tipo da compra (code 20 em Criar regra).
creationDate
string (date-time)
Data e hora do pedido, em ISO 8601. Envie quando a compra aconteceu antes da chamada (loja offline, lote enviado depois, pedido reprocessado); sem o campo, vale o horário da chamada.
Define tudo o que depende da data da compra: quais campanhas estavam ativas naquela data, o início e o fim da validade do card e a data do pedido gravada na transação. Sem fuso (2026-11-02 10:00:00), vale o fuso da organização.
Valor ilegível, data que não existe (ex.: 2026-02-31) ou data mais de um dia no futuro retorna 400.
▸
client
object | int | null
Identificador do cliente. Aceita três formatos:
Object — um ou mais campos de identidade. Resolvido pelo pipeline de Mapping + Translate e encaminhado ao serviço Register, que encontra ou cria o cliente. Qualquer campo de pareamento (id/refId, email, cellphone, document) localiza uma pessoa existente; os demais campos de perfil (name, dateOfBirth, gender, postalCode, language, …) são gravados no cadastro encontrado/criado.
Integer — personId interno do Guper.
null — cliente anônimo.
O objeto aceita os mesmos campos de Criar cliente — veja aquele endpoint para a lista completa. Abaixo aparecem apenas os campos de identificação principais, mais isCollaborator, que é exclusivo deste endpoint e não é um campo de Criar cliente. Qual campo de fato pareia um cliente existente depende do matchPattern da organização; document é a chave de pareamento principal na maioria das organizações, então envie sempre que tiver.
Object fields
Field
Type
Description
id
string
External refId (o identificador no seu sistema). Mapeado para refId internamente.
name
string
Nome completo do cliente.
document
string
Documento (CPF/CNPJ, RFC, CURP, …). Chave de pareamento principal na maioria das organizações. Armazenado sem caracteres não-alfanuméricos e em minúsculas.
email
string
Convertido para minúsculas ao salvar. E-mails inválidos são descartados silenciosamente.
countryCallingCode
integer
DDI do país (ex.: 55 para Brasil). Herdado da organização quando omitido.
cellphone
string
Celular sem formatação. Despojado de não-dígitos; se prefixado com +, é parseado via libphonenumber e o countryCallingCode é preenchido automaticamente.
isCollaborator
boolean
Marca o cliente encontrado/criado como funcionário (colaborador). true marca, false desmarca, omitir não altera o campo. Gravado no cadastro do Register. Exclusivo deste endpoint — não disponível em Criar cliente.
▸
attendants
object
Sales staff that handled this order.
Object fields
Field
Type
Description
▸
cashier
object
Object fields
Field
Type
Description
id
*
string
Cashier ID in the Register service.
▸
salesperson
object
Object fields
Field
Type
Description
id
*
string
Salesperson ID in the Register service.
▸
items
*
array<object>
Itens do pedido. Pelo menos um item é obrigatório.
Campos monetários (price, listPrice, tax) são enviados como inteiros em centavos — veja Valores monetários para a convenção.
Array item
Field
Type
Description
id
*
string
SKU identifier.
SKU id
productId
string
Parent product ID.
name
*
string
Display name of the item.
categoryId
string
Category identifier.
brandId
string
Brand identifier.
sellerId
string
Seller (marketplace) identifier.
tax
integer
Tax amount in cents.
cents
quantity
*
integer
Quantity.
int ≥ 1
price
*
integer
Unit price in cents.
cents
listPrice
integer
Original list price (before discounts).
cents
▸
shipping
array<object>
Informações de frete. Envie uma entrada por embarque.
Campos monetários (price, listPrice) são enviados como inteiros em centavos — veja Valores monetários.
Resgate barrado pela regra da carteira. Quando a carteira tem mínimo
dinâmico (minOrderRate), o saldo do cliente só pode ser usado se o pedido
valer N vezes esse saldo — 3 com saldo de R$ 30,00 exige uma compra de
R$ 90,00. É tudo-ou-nada: abaixo disso não resgata nada, nem parte.
Nesse caso redeemable.total volta 0 e redeemable.blocked diz o porquê:
wallet é o id da política, rate o multiplicador, balance o saldo
considerado, required quanto o pedido precisaria valer e missing o que
falta (required − total do pedido). Valores em centavos.
O saldo continua intacto — userBalance segue mostrando ele, e o mesmo
cliente resgata normalmente num carrinho maior. Mostre o missing: "faltam
R$ 15,00 para usar seu saldo". O mesmo bloco aparece em
Atualizar transação,
que reaplica a regra quando o carrinho muda.
Retorna apenas o cashback que será acumulado neste pedido —
sem dados do cliente e sem token de confirmação. Omita o header
x-guper-authorization para usar este modo.
Cabeçalhos
Name
Type
Description
Content-Type
*
string
Always `application/json` for endpoints that accept a JSON body.