Buyer App Util API'sVersion 1.0.0

Endpoint Details

This endpoint allows you to check the status of your orders and get voucher codes for confirmed orders.

endpoint:
  path: /company/status
  method: GET
  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.
  parameters:
    - name: orderId
      in: query
      description: Order Id returned from the place order API
      required: true
      schema:
        type: string
    - name: externalOrderId
      in: query
      description: Same value passed in place order API
      required: true
      schema:
        type: string
    - name: companyId
      in: query
      description: Helps with the authentication of the API request
      required: true
      schema:
        type: string
  responses:
    description: JSON object containing the status of the company order along with voucher details.

Endpoint Url:

/company/status

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

Endpoint Description and Usage:

This endpoint retrieves the current status of an order placed through the Non-ONDC network. It requires the order ID from the place order API response, the external order ID used when placing the order, and your company ID for authentication. The response includes detailed status information for each line item and associated 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 check order status using this endpoint:

curl -X GET \
  "{{base_url}}/company/status?orderId=12345&companyId=1234&externalOrderId=67890" \
-H "x-api-key: YOUR_API_KEY"

Query Parameters

The GET request requires the following query parameters to identify and authenticate the order:

parameters:
  - name: orderId
    in: query
    description: Order Id returned from the place order API
    required: true
    schema:
      type: string

  - name: externalOrderId
    in: query
    description: Same value passed in place order API
    required: true
    schema:
      type: string

  - name: companyId
    in: query
    description: Helps with the authentication of the API request
    required: true
    schema:
      type: string

Success Response

When the request is successful, the API returns a JSON response with order status and voucher details:

{
  "status": {
    "code": "200",
    "error": false
  },
  "message": "Success",
  "result": {
    "status": "Success",
    "lineStatus": [
      {
        "id": "line-item-1",
        "itemId": "item-12345",
        "quantity": 1,
        "denomination": "100",
        "status": "C",
        "vouchers": [
          {
            "itemId": "item-12345",
            "code": "VGME3DSN2J33L",
            "pin": "",
            "validTill": "2024-12-31",
            "denomination": 100
          }
        ]
      }
    ]
  }
}

Error Response

If there is an error with the request (e.g., order not found, authentication failure), the API will return a JSON object with error details:

{
  "status": {
    "code": "404",
    "error": true
  },
  "message": "Order not found",
  "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:	
        status:
          type: string
          description: Overall status of the order (Success, Processing, Failed)
        lineStatus:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: Unique identifier for the line item status
              itemId:
                type: string
                description: Item ID associated with this status line
              quantity:
                type: number
                description: Quantity of the item in this line
              denomination:
                type: string
                description: Denomination of the item in this line
              status:
                type: string
                description: Status of the item (P=Processing, C=Confirmed, F=Failed)
              vouchers:
                type: array
                items:
                  type: object
                  properties:
                    itemId:
                      type: string
                      description: Item ID for the voucher
                    code:
                      type: string
                      description: Voucher code
                    pin:
                      type: string
                      description: PIN for the voucher, if applicable
                    validTill:
                      type: string
                      description: Validity date of the voucher
                    denomination:
                      type: number
                      description: Denomination value of the voucher