API Support - BSS Commerce Wiki

We provide you lists of Restful API and GraphQL API that our Magento 2 Gift Card extension supports.

*Note:

Restful API support is included in the main module package (from Gift Card v1.0.5).
GraphQL API support is included in the GraphQL package, acting as an add-on for anyone who needs to use GraphQL

1. Restful API

Please check the following Restful API supported by our modules:

With detailed tutorial:

- GET /rest/V1/bssGiftCard/template/{:templateId}
  Get the template's information via template id.
- GET /rest/V1/bssGiftCard/pattern/{:patternId}
  Get the pattern's information
- POST /rest/V1/bssGiftCard/checkCode
  Check gift card code

Detailed coming soon:

- DELETE /rest/V1/bssGiftCard/guest/remove/{:cartId}/{:giftCardQuoteId}
  Delele the gift card code that is applied in Quote
- DELETE /rest/V1/bssGiftCard/mine/remove/{:giftCardQuoteId}
  delete the gift card code in the shopping cart of the logged-in customer
- PUT /rest/V1/bssGiftCard/apply/{:cartId}/{:giftCardCode}
  Apply gift card code in the cart quote
- PUT /rest/V1/bssGiftCard/mine/apply/{:giftCardCode}
  Apply the gift card code in the cart quote of logged-in customers

1.1 Get information about a template using template id

PATH: GET /rest/V1/bssGiftCard/template/{:templateId}

Header: Content-Type : application/json

Response detail:

template_id	“template_id”: 1 Gift card template ID
name	"name": "Test gift card" Gift card template name
status	"status": "1" Enable/disable template
code_color	"code_color": "ff00ff" Gift card code color
message_color	"message_color": "faf5fa" Message color in Gift card
created_time	"created_time": "2020-06-05 03:49:44" Create time
updated_time	"updated_time": "2020-06-05 03:49:44" Update time
images	images: [ { "id": "1", "position": "1", "url": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\ /700x560\/7\/2\/72394990_409978003041784_4233065152133464064_o.jpg", "thumbnail": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\ /148x111\/7\/2\/72394990_409978003041784_4233065152133464064_o.jpg", "alt": null } ] List of images in the current template. Here is the image attributes, including: id: Image Id position url: Urls of main images thumbnail: Url of thumbnail images alt: alt tag s of images

Error:

400	Bad request

Validation:

Template id needs to be pushed.

How to get the template's information?

GET /rest/V1//bssGiftCard/template/:templateId

Response:

{
    "template_id": "1",
    "name": "Test gift card",
    "status": "1",
    "code_color": "ff00ff",
    "message_color": "faf5fa",
    "created_time": "2020-06-05 03:49:44",
    "updated_time": "2020-06-05 03:49:44",
    "images": [
      {
        "id": "1",
 "position": "1",
        "url": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/700x560\/7\/2\/72394990_409978003041784_4233065152133464064_o.jpg",
        "thumbnail": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/148x111\/7\/2\/72394990_409978003041784_4233065152133464064_o.jpg",
        "alt": null
      },
      {
        "id": "2",
        "position": "2",
        "url": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/700x560\/7\/2\/72374608_425146505059507_6066963719056441142_n.jpg",
        "thumbnail": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/148x111\/7\/2\/72374608_425146505059507_6066963719056441142_n.jpg",
        "alt": null
      },
      {
        "id": "3",
        "position": "3",
        "url": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/700x560\/7\/0\/70066944_119172596122773_1342264300332384256_o.jpg",
        "thumbnail": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/148x111\/7\/0\/70066944_119172596122773_1342264300332384256_o.jpg",
        "alt": null
      },
      {
        "id": "4",
        "position": "4",
        "url": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/700x560\/6\/9\/69529680_117463876293645_8838466387866288128_o.jpg",
        "thumbnail": "http:\/\/235-mage.bss.com\/pub\/media\/tmp\/bss\/giftcard\/image\/148x111\/6\/9\/69529680_117463876293645_8838466387866288128_o.jpg",
        "alt": null
      }
    ]
  }

1.2. Get pattern information. Submit pattern id information.

Path: GET /rest/V1/bssGiftCard/pattern/{:patternId}

Header: Content-Type : application/json

pattern_id	“pattern_id”: “1” Pattern Id
name	"name": "Testt pattern" Name of pattern
pattern	"pattern": "Vaduuu-{D}-{L}" Maximum number of D (digit) and L (letter) to be added is 6. E.g. BIRTHDAY-{D}-{L} results in BIRTHDAY-8-A
pattern_code_qty	“pattern_code_qty”: “17” The code quantity of the pattern
pattern_code_unused	"pattern_code_unused": "17" The parttern code that is/ unsused
pattern_code_qty_max	"pattern_code_qty_max": "191" The max pattern code quantity that the pattern can generate. Ex: pattern is “lucthanca-{D}-{L}”. Có 1 D -> maxCodeQty = 10^1, has 1 L -> maxCodeQty = maxCodeQty * (26^1) = 260. Multiply by 0.8 = 208. This value will decrease by eliminating the number that is generated by admin. Case in point: admin generates 100 code the value of code qty max is 208-100=108. If the admin deletes the generated code then the value will not be returned or increased back.
created_time	"created_time": "2020-06-05 03:52:21" Create time
updated_time	"updated_time": "2020-06-16 07:13:43" Update time

Error:

400	Bad request

Validation:

Pattern id must be pushed forward.

Response:

GET /rest/V1/bssGiftCard/pattern/{:patternId}
Response:
[{
    "pattern_id": "2",
    "name": "vadu",
    "pattern": "vadu_{L}_{D}",
    "pattern_code_qty": "100",
    "pattern_code_unused": "100",
    "pattern_code_qty_max": "108",
    "created_time": "2021-03-10 03:38:58",
    "updated_time": "2021-03-10 03:39:32"
}]

1.3. Check giftcard code

PATH: POST/rest/V1/bssGiftCard/checkCode

Header: Content-Type : application/json
Body:

code	"code": "lucthanca-C-1" Code is generated by pattern

Response:

Status:

"status": true

The status of request. Aim to check whether or not the code exist and/or where or not you can check the code.

Data:

"data": [
           {
               "label": "Code",
               "value": "lucthanca-C-1"
           },
           {
               "label": "Origin Value",
               "value": "99,00 US$"
           },
           {
               "label": "Current Value",
               "value": "99,00 US$"
           },
           {
               "label": "Status",
               "value": "Inactive"
           },
           {
               "label": "Expire At",
               "value": "11 thg 5, 2021"
           }
       ]

The detail information of the code. Definition of fields:

+ label: The lable of code.

+ value: The value of code.

Error:

400	Bad request
404	Not Found

Validation:

Pattern id must be pushed forward.

Response:

{
"code": "lucthanca-C-1"
}
Response
[
   {
       "status": true,
       "data": [
           {
               "label": "Code",
               "value": "lucthanca-C-1"
           },
           {
               "label": "Origin Value",
               "value": "99,00 US$"
           },
           {
               "label": "Current Value",
               "value": "99,00 US$"
           },
           {
               "label": "Status",
               "value": "Inactive"
           },
           {
               "label": "Expire At",
               "value": "11 thg 5, 2021"
           }
       ]
   }
]

2. GraphQl API

Please check the following GraphQL API supported by our modules:

Query:

With detailed tutorial:

+ bssGiftCardStoreConfig
Get Store Config của module.
Get giftcard information with query products of Magento default.
Get giftcard information in query cart.

Detail Coming Soon:

+ bssGiftCardTemplates
Get ALL gift card information within template.
+ bssGetListTimezone
Get the timezone list.
+ bssCustomerGiftCards
Get ordered gift card information of the customer.
+ bssPreviewGiftCard
Preview giftcard.

Mutation:

+ addGiftCardProductsToCart

Add gift card to cart.

2.1 Get store configuration of the module

Path: bssGiftCardStoreConfig

+ Arguments

Argument	Description
store_view (Int\|Null) Required	Store view Id. If null is given then it will get the value according to default.

+ Example

query {
  bssGiftCardStoreConfig(store_view: 1) {
    active
    active_to_sender
    day_before_notify_expire
    expire_day
    max_time_limit
    notify_to_recipient
    number_character
    replace_character
    sender_identity
    to_recipient
    to_sender
  }
}
 Response {
 "data": {
   "bssGiftCardStoreConfig": {
     "active": 1,
     "active_to_sender": 1,
     "day_before_notify_expire": null,
     "expire_day": null,
     "max_time_limit": null,
     "notify_to_recipient": "bss_giftcard_notify_to_recipient",
     "number_character": null,
     "replace_character": null,
     "sender_identity": "sales",
     "to_recipient": "bss_giftcard_to_recipient",
     "to_sender": "bss_giftcard_to_sender"
   }
 }
}

+ Return Fields

- active: on/off Module

- active_to_sender: Send email to the sender

- day_before_notify_expire: Send Notification Mail of Expiration before number of days

- expire_day: Expiry Day. 0 for unlimited usage day

- max_time_limit: Allowed Maximum Time (s) to Enter Gift Code Incorrectly

- notify_to_recipient: Notification Email Template of Expiration to Recipient

- number_character: Number of Characters Shown in Gift Code

- replace_character: Replace Hidden Character by

- sender_identity: Email Sender

- to_recipient: Email Template to Recipient- to_sender: Email Template to Sender

2.2 Giftcard details in products query

+ Arguments

Please refer to Magento's product query document here.

+ Example

query {
  products(
    filter: {
      sku: {eq: "anh-hung-thiep"}
    }
  ) {
    items {
      name
      __typename,
      ... on BssGiftCardProduct {
        giftcard_options {
          amount {
            id
            price
            value
            website
          }
          dynamic_price {
            enable
            max_value
            min_value
            percentage_price_type
            percentage_price_value
          }
          expires_at
          message
          type
          template {
            images {
              url
            }
          }
        }
      }
    }
  }
}
Response {
 "data": {
   "products": {
     "items": [
       {
         "name": "Anh Hùng Thiếp",
         "__typename": "BssGiftCardProduct",
         "giftcard_options": {
           "amount": [
             {
               "id": 2,
               "price": 200,
               "value": 200,
               "website": 0
             }
           ],
           "dynamic_price": {
             "enable": 1,
             "max_value": "200",
             "min_value": "150",
             "percentage_price_type": 1,
             "percentage_price_value": "100"
           },
           "expires_at": "0",
           "message": 1,
           "type": 1,
           "template": [
             {
               "images": [
                 {
                   "url": "http:\/\/242.vadu\/media\/tmp\/bss\/giftcard\/image\/700x560\/8\/0\/80900905_158038935546402_6445742220388597760_n.jpg"
                 },
                 {
                   "url": "http:\/\/242.vadu\/media\/tmp\/bss\/giftcard\/image\/700x560\/8\/0\/80900691_2673092382918470_8015297684673921024_o.jpg"
                 }
               ]
             }
           ]
         }
       }
     ]
   }
 }
}

3. Object Describe.

ProductInterface
- Implementations
  - BssGiftCardProduct
BssGiftCardProduct
- Fields
  - giftcard_options: GiftCardOptions
GiftCardOptions
- Fields
  - amount: [AmountByWebsite]
    An array of linked card amount by website
  - dynamic_price: DynamicPrice
  - expires_at: String
    A number of days which specify the valid time to use the gift card. Gift codes which are automatically created after customers purchase Gift Cards have valid time auto following settings of this Expires After (days) section.
  - message: Int
    Allow the customer to attach a message for the receiver of the giftcard.
  - pattern: GiftCardPattern
    Linked pattern to allow code(s) to apply with the gift card
  - template: [GiftCardTemplate]
    An array of linked Card Template
  - type: Int
    Card type id.
    1 is Virtual
    2 is Physical
    3 is Combined
AmountByWebsite
- Fields
  - id: Int
    Amount value id
  - price: Float
    Card Price
  - value: Float
    Card value
  - website: Int
    Apply in website id
DynamicPrice
- Fields
  - enable: Int
    Is dynamic price
  - max_value: String
    Max card value
  - min_value: String
    Min card value
  - percentage_price_type: Int
    Percentage Price Type.
    0: Same as value
    1: Percentage of value
  - percentage_price_value: String
    Percentage Price Value
GiftCardPattern
- Fields
  - codes: [Code]
    An array of linked codes
  - id: Int
    Pattern Id
  - name: String
    Pattern name
  - pattern: String
    Pattern string
  - qty: Int
    Code qty
  - qty_max: Int
    Max qty code
  - unused: Int
    Unused code
GiftCardTemplate
- Fields
  - code_color: String
    Gift Code Color
  - images: [TemplateImage]
    An array of linked images
  - message_color: String
    Gift Card Message Text Color
  - name: String
    Template Name
  - status: Int
    Template status
  - template_id: Int
    Template Id
Code
- Fields
  - code: String
  - code_id: Int
  - expiry_day: String
  - image_id: Int
  - message: String
  - order_id: Int
  - origin_value: Float
  - product_id: Int
  - recipient_email: String
  - recipient_name: String
  - send_at: String
  - sender_email: String
  - sender_name: String
  - sent: Int
  - sent_expire_notify: Int
    Was sent Notification Email about Expire code
  - status: Int
  - store_id: Int
  - value: Float
  - website_id: Int
TemplateImage
- Fields
  - alt: String
    Image label
  - id: Int
    Image Id
  - position: Int
    Image position
  - thumbnail: String
    Image thumbnail
  - url: String
    Image full width

Magento 2 Product Improvement Extensions

1. Restful API

1.1 Get information about a template using template id

1.2. Get pattern information. Submit pattern id information.

1.3. Check giftcard code

2. GraphQl API

2.1 Get store configuration of the module

2.2 Giftcard details in products query

3. Object Describe.

How can we help?