This method can be used to redeem a reward in behalf of a customer.

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pvt/POS/rewards/{id}/redeem \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "CustomerId": "<string>",
  "Value": 123,
  "Points": 123,
  "OriginalKey": "<string>",
  "Metadatas": [
    {
      "Name": "<string>",
      "Value": "<string>"
    }
  ],
  "RedeemOrigin": 0,
  "Branch": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "SalesPerson": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "ForceGenerateCoupon": true
}
'

{
  "ErrorMessage": "<string>",
  "ErrorCode": 123,
  "Result": {
    "RewardId": 123,
    "Point": {
      "PointId": 123,
      "Quantity": 123,
      "Metadatas": [
        {
          "Name": "<string>",
          "Value": "<string>"
        }
      ]
    },
    "ExternalCode": "<string>",
    "OriginalKey": "<string>",
    "Coupon": {
      "CouponCode": "<string>",
      "CouponType": 0,
      "CouponValue": 123,
      "ValidDateStart": "2023-11-07T05:31:56Z",
      "ValidDateEnd": "2023-11-07T05:31:56Z"
    }
  },
  "HasError": true
}

POS

This method can be used to redeem a reward in behalf of a customer.

There are 2 types of rewards:

Discount Rewards: Percent (10%) or Value (R$10,00). This rewards are simples as they use pre-configured values
Cashback: As a value (R$5,00). The used value must be informed in the Value field of the request body

They both can be used with this method. Just be aware that:

The field Value must have the selected cashback value for the purchase. Use only if the reward is Cashback type
For other rewards this field can be null

The rewardId field can be obtained by calling the rewards/available endpoint

The customerId field in the body is the same used in the rewards/avaible endpoint.

The `OriginalKey` field

This field allows you to create idempotency: even if you make the exactly same request twice it will redeem only once. As distributed systems should be fault-tolerant it may result in requests being done more than one time. Not using the OriginalKey may duplicate a redeem request

How to use this field

Inform some string that is unique for this change.

For instance: if you are redeeming the reward Id=OPQ for customerID=ABC regarding the OrderId=123 with Value=10,our key could be OPQ-ABC-123-10

If you dont need this kind of verification you can just use some time-related string, such as 2023-01-01 23:59:00:000

Coupon Generation

It’s important to note that unlike the customers/{id}/redeem endpoint this call will not generate a coupon in BonifiQ. That is true even if the reward if configured so.

This is by design as in Point of Sale endpoints it is expected that the caller (PoS) will give the customer the necessary discounts.

The `ExternalCode` return

One of the most important fields returned by this method is the ExternalCode. This field represents an External identification for this redeem. This exact value must be passed on the Coupon field for the Order Add Method from this API. This will make a link between the redeem and the order.

Important: Remember to pass the ExternalCode value to the Coupon field when adding an order

POST

pvt

POS

rewards

{id}

redeem

This method can be used to redeem a reward in behalf of a customer.

curl --request POST \
  --url https://api.bonifiq.com.br/v1/pvt/POS/rewards/{id}/redeem \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "CustomerId": "<string>",
  "Value": 123,
  "Points": 123,
  "OriginalKey": "<string>",
  "Metadatas": [
    {
      "Name": "<string>",
      "Value": "<string>"
    }
  ],
  "RedeemOrigin": 0,
  "Branch": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "SalesPerson": {
    "OriginalId": "<string>",
    "Name": "<string>"
  },
  "ForceGenerateCoupon": true
}
'

{
  "ErrorMessage": "<string>",
  "ErrorCode": 123,
  "Result": {
    "RewardId": 123,
    "Point": {
      "PointId": 123,
      "Quantity": 123,
      "Metadatas": [
        {
          "Name": "<string>",
          "Value": "<string>"
        }
      ]
    },
    "ExternalCode": "<string>",
    "OriginalKey": "<string>",
    "Coupon": {
      "CouponCode": "<string>",
      "CouponType": 0,
      "CouponValue": 123,
      "ValidDateStart": "2023-11-07T05:31:56Z",
      "ValidDateEnd": "2023-11-07T05:31:56Z"
    }
  },
  "HasError": true
}

Authorizations

Authorization

string

header

required

Use API Basic Auth Keys

Path Parameters

integer<int32>

required

Body

application/json

Parameters used in redeeming

CustomerId

string

The id of the customer. It can be email or document (CPF/CNPJ).

Value

number<decimal> | null

Used only for Cashback Rewards. It the Cashback value selected by the customer. You can use either Points or Value for representing the selected amount of cashback to use.

Points

integer<int32> | null

Used only for Cashback Rewards. It the Cashback represented by points selected by the customer. You can use either Points or Value for representing the selected amount of cashback to use.

OriginalKey

string

This field allows you to create idempotency: even if you make the exactly same request twice it will consume the redeem only once. As distributed systems should be fault-tolerant it may result in requests being done more than one time. Not using the OriginalKey may duplicate a redeem request Inform some string that is unique for this change. For instance: if you are redeeming the reward Id=OPQ for customerID=ABC regarding the OrderId=123 with Value=10,our key could be OPQ-ABC-123-10 If you dont need this kind of verification you can just use some time-related string, such as 2023-01-01 23:59:00:000

Metadatas

object[] | null

Use this field as a key-value store for fields unique to your Business Use Case

Show child attributes

Metadatas.Name

string

Metadatas.Value

string

RedeemOrigin

enum<integer>

Use this field to send redeem origin. Have 4 types: LandingPage, Widget, Copilot, Checkout, API, PDV.

Available options:

0,

1,

2,

3,

4,

5

Branch

object

A Branch is physical location or outlet of a store (loja, filial, etc). This is used to receive information of which store the purchase was made. It can be later used to create rules for points or filtering reports.

Show child attributes

Branch.OriginalId

string

This is the Id of the branch (filial, loja, etc) in the client store. Can be any string.

Branch.Name

string

This is the name of the branch. Can be any string possible

SalesPerson

object

A sales person is the person responsible for the sale. It can be used for filtering reports.

Show child attributes

SalesPerson.OriginalId

string

This is the Id of the Sales Person. Can be any string or number.

SalesPerson.Name

string

This is the name of the sales person. Can be any string.

ForceGenerateCoupon

boolean | null

Normally this endpoint generates a redeem without a coupon. Setting this property to true forces to generate a coupon in the ecommerce plataform

Response

200 - application/json

ErrorMessage

string | null

Error message or description

ErrorCode

integer<int32> | null

Optional error code, if available

Result

object

Show child attributes

Result.RewardId

integer<int32>

This is the unique-id for this reward

Result.Point

object

It`s the underlining point record generating from using this reward

Show child attributes

Result.Point.PointId

integer<int32>

Result.Point.Quantity

integer<int32>

Result.Point.Metadatas

object[] | null

Show child attributes

Result.Point.Metadatas.Name

string

Result.Point.Metadatas.Value

string

Result.ExternalCode

string

When sending orders to BonifiQ use this field value in the Coupon field for the Order This is necessary so we know that this order used this reward

Result.OriginalKey

string

This is the key that was send in the redeem request

Result.Coupon

object

If the request forces the coupon generation It is returned here

Show child attributes

Result.Coupon.CouponCode

string

Result.Coupon.CouponType

enum<integer>

0 = FixedValue 1 = Percent 2 = FreeShipping 3 = DiscountShipping 4 = Others

Available options:

0,

1,

2,

3,

4

Result.Coupon.CouponValue

number<decimal>

Result.Coupon.ValidDateStart

string<date-time> | null

Result.Coupon.ValidDateEnd

string<date-time> | null

HasError

boolean

If true the request had an error.

Returns a list of available rewards for a given customer and purchase.Cancel an existing reward using the OriginalKey

⌘I

API Privada

API Pública

Endpoint Examples

This method can be used to redeem a reward in behalf of a customer.

The `OriginalKey` field

How to use this field

Coupon Generation

The `ExternalCode` return

Authorizations

Path Parameters

Body

Response