Buyer App Util API'sVersion 1.0.0

Endpoint Details

This endpoint allows you to check stock availability for specific items before placing an order.

endpoint:
  path: /catalogue/check-stock
  method: POST
  headers:
    - name: X-API-KEY
      required: true
      description: Unique API key provided to authenticate requests
    - name: Content-Type
      required: true
      description: application/json
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            itemId:
              type: string
              description: Id from an item from the catalogue API
              required: true
            quantity:
              type: string
              description: Specifies the number of gift cards to order
              required: true
            denomination:
              type: string
              description: Denomination of the gift card to order
              required: true
            buyerEmail:
              type: string
              description: Email Id of the buyer
              required: false
            buyerNumber:
              type: string
              description: Phone Number of the buyer
              required: false
  responses:
    description: JSON object indicating stock availability and maximum quantity allowed.

Endpoint Url:

/catalogue/check-stock

Note: Append this path to the base URL as mentioned in the Prerequisites section.

Endpoint Description and Usage:

This endpoint checks the availability of gift cards in stock. It requires the item ID from the catalogue API, the desired quantity, denomination, and optionally buyer contact information. The response indicates whether the item is in stock and the maximum quantity available for purchase.

Security

All requests to this endpoint must be authenticated using the required headers as specified in the Prerequisites section. Ensure that your API key is kept secure and not exposed in client-side code. Failure to provide valid authentication headers will result in a 401 Unauthorized error.

Sample Request:

Here is an example of a cURL command to check stock availability using this endpoint:

curl -X POST \
{{base_url}}/catalogue/check-stock \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
  "itemId": "YOUR_ITEM_ID",
  "quantity": "1",
  "denomination": "100",
  "buyerEmail": "buyer@example.com",
  "buyerNumber": "9876543210"
}'

Request Body

The POST request requires the following parameters in the JSON request body:

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        properties:
          itemId:
            type: string
            description: Id from an item from the catalogue API
            required: true
            example: "YOUR_ITEM_ID"
          quantity:
            type: string
            description: Specifies the number of gift cards to order
            required: true
            example: "1"
          denomination:
            type: string
            description: Denomination of the gift card to order
            required: true
            example: "100"
          buyerEmail:
            type: string
            description: Email Id of the buyer
            required: false
            example: "buyer@example.com"
          buyerNumber:
            type: string
            description: Phone Number of the buyer
            required: false
            example: "9876543210"

Success Response

When the request is successful, the API returns a JSON response with stock availability information:

{
  "status": {
    "code": "200",
    "error": false
  },
  "message": "Success",
  "result": {
    "inStock": true,
    "max": 10
  }
}

Error Response

If there is an error with the request (e.g., invalid parameters, server error), the API will return a JSON object with error details:

{
  "status": {
    "code": "500",
    "error": true
  },
  "message": "Internal Server Error",
  "result": null
}

Response Schema (YAML)

The response schema for both success and error responses is as follows:

parameters:
  - name: status
    in: body
    description: Contains response metadata.
    required: true
    schema:
      type: object
      properties:
        code:
          type: string
          description: HTTP-style status code.
        error:
          type: boolean
          description: Indicates if the API encountered an error.

  - name: message
    in: body
    description: Human-readable message describing the result or error.
    required: true
    schema:
      type: string

  - name: result
    in: body
    description: Contains details of the result in case of success; will be null in case of an error.
    required: true
    schema:
      type: object
      nullable: true
      properties:	
        inStock:
          type: boolean
          description: Indicates if the item is in stock
          example: true
        max:
          type: number
          description: Maximum quantity allowed for the item
          example: 10