Buyer App Util API'sVersion 1.0.0

Endpoint Details

This endpoint allows you to place orders for gift cards and receive an order ID for tracking.

endpoint:
  path: /order/place-order
  method: POST
  headers:
    - name: X-API-KEY
      required: true
      description: API key for authentication. This header will be used to identify the consuming channel of the API.
    - name: Content-Type
      required: true
      description: application/json
  requestBody:
    required: true
    content:
      application/json:
        schema:
          type: object
          properties:
            companyId:
              type: string
              description: Unique identifier of the company initiating the request
              required: true
            externalOrderId:
              type: string
              description: Reference order ID from the external system or client
              required: true
            data:
              type: object
              description: Object containing order details including items and buyer information
              required: true
              properties:
                items:
                  type: array
                  description: Array of items to be ordered with ID, quantity, and denomination
                  required: true
                  items:
                    type: object
                    properties:
                      itemId:
                        type: string
                        description: Item ID from the catalogue
                      quantity:
                        type: number
                        description: Quantity of the item to order
                      denomination:
                        type: string
                        description: Denomination of the gift card
                buyerEmail:
                  type: string
                  description: Email address of the buyer
                  required: true
                buyerPhNumber:
                  type: string
                  description: Phone number of the buyer
                  required: true

Endpoint Url:

/order/place-order

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

Endpoint Description and Usage:

This endpoint processes gift card orders from the Non-ONDC catalogue. It requires a company ID for authentication, an external order ID for tracking, and order data including item details and buyer information. The response provides an order ID that can be used to check order status and retrieve voucher codes.

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 place an order using this endpoint:

curl -X POST \
  {{base_url}}/order/place-order" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "companyId": "YOUR_COMPANY_ID",
    "externalOrderId": "YOUR_EXTERNAL_ORDER_ID",
    "data": {
      "items": [
        {
          "itemId": "ITEM_ID_1",
          "quantity": 1,
          "denomination": "100"
        },
        {
          "itemId": "ITEM_ID_2",
          "quantity": 2,
          "denomination": "200"
        }
      ],
      "buyerPhNumber": "9876543210",
      "buyerEmail": "buyer@example.com"
    }
  }'

Request Body

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

requestBody:
  required: true
  content:
    application/json:
      schema:
        type: object
        properties:
          companyId:
            type: string
            description: Unique identifier of the company initiating the request
            required: true
            example: "YOUR_COMPANY_ID"
          externalOrderId:
            type: string
            description: Reference order ID from the external system or client
            required: true
            example: "YOUR_EXTERNAL_ORDER_ID"
          data:
            type: object
            description: Object containing order details including items and buyer information
            required: true
            properties:
              items:
                type: array
                description: Array of items to be ordered with ID, quantity, and denomination
                required: true
                items:
                  type: object
                  properties:
                    itemId:
                      type: string
                      description: Item ID from the catalogue
                      example: "ITEM_ID_1"
                    quantity:
                      type: number
                      description: Quantity of the item to order
                      example: 1
                    denomination:
                      type: string
                      description: Denomination of the gift card
                      example: "100"
              buyerEmail:
                type: string
                description: Email address of the buyer
                required: true
                example: "buyer@example.com"
              buyerPhNumber:
                type: string
                description: Phone number of the buyer
                required: true
                example: "9876543210"

Success Response

When the request is successful, the API returns a JSON response with the order ID:

{
  "status": {
    "code": "200",
    "error": false
  },
  "message": "Success",
  "result": {
    "id": "POR4545GFGJ"
  }
}

Error Response

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

{
  "status": {
    "code": "404",
    "error": true
  },
  "message": "Error in placing order",
  "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:	
        id:
          type: string
          description: Unique order ID generated for the placed order
          example: "POR4545GFGJ"