ONDC Buyer App Util API'sVersion 1.0.0

Endpoint Details

This endpoint allows you to check the status of a company order and retrieve associated voucher details using order identifiers.

endpoint:
  path: /company_order/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: companyOrderId
      in: query
      description: Unique identifier for the company order.
      required: true
      schema:
        type: string
    - name: ondcOrderId
      in: query
      description: Unique identifier for the ONDC order.
      required: true
      schema:
        type: string
  response:
    description: JSON object containing the status of the company order with encrypted voucher details.

Endpoint Url:

/company_order/status

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

Endpoint Description and Usage:

This endpoint is used to retrieve the status of a company order in the ONDC network. The request requires both company order ID and ONDC order ID as query parameters. The response contains encrypted voucher details along with order status information (Success, Failed, or Processing).

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 company order status using this endpoint:

curl -X GET \
  {{base_url}}/company_order/status?companyOrderId=12345&ondcOrderId=67890 \
  -H "X-API-KEY: YOUR_API_KEY"

Query Parameters

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

parameters:
  - name: companyOrderId
    in: query
    description: Unique identifier for the company order.
    required: true
    schema:
      type: string

  - name: ondcOrderId
    in: query
    description: Unique identifier for the ONDC order.
    required: true
    schema:
      type: string

Encrypted Response

When the request is successful, the API returns an encrypted JSON response with order status and voucher data:

{
  "status": {
    "code": "200",
    "error": false
  },
  "message": "Success",
  "result": {
    "status": "Success",
    "vouchers": {
      "data": "f3swA6Ui857QTEEYuYQGEMZDn7/kSTnQqFXU1XegW2pJEYZPduDY74B5AT3vlras+++64jJyoSMk9rHXoTvpqyCSEMUFyFpugigFBTMHpm6QN/NlldGRxp2y1gNXFL4xeRqUpTCRnq4nN6MZaukifyWD2pKBt4WovY0bNDcWZ34pU0/5xCysvIbJjUfTRRLpfuTwcNuGCNagqilznpeMrw1fTjlDzkCDFjnPKdv65xQbRhXq0xUwZDhs+/7vTcnisVNqu5GrDYm8TZ3u+Tg7NC3DSEQZ9Di0oYMiSXMch2DKHFMYc31c6Nfcc8qZduq+PyI7HdTdqqAUKygf+eFDc0YVAIaKBdvTFTf00V+0JyoEu2me3Kp1ZAL/bpcmMVUjHbabPzRZ8//AXVP/UTjzL43WyHr6tAyIKyRi5Kbe++2RRE41CqLsRmvLLv0b0i9ReNCIi9iCS46Ar5y7i0bOvqiH12mQA7cHlZMP1AbL1iKwo9/DZuobE6WjNXwUrXVV84r/VZEiHGJ5aPto1z9czg==",
      "iv": "871508348dd14963"
    }
  }
}

Decrypted Response

After decrypting the voucher data, you will get detailed voucher information including codes and transaction details:

[
  {
    "updatedAt": "2024-09-17T02:28:53.484Z",
    "createdAt": "2024-09-17T02:26:59.497Z",
    "id": "60eeacf6-7c2c-4210-8f2a-6a281f8fc8f5",
    "fulfillmentId": "7f03a547-b45d-4234-b57c-87dd52759286",
    "voucherCode": "VGME3DSN2J33L",
    "voucherPin": "",
    "validity": null,
    "orderId": "c40ef4e1-1d2d-4a9e-b067-286d08f3d929",
    "ondcOrderId": "2b124b66-f962-4554-86a1-2c23ac67be21",
    "transactionId": "9449d55b-597e-44c3-ac93-0760378c4fcb"
  }
]

Error Response

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

{
  "status": {
    "code": "404",
    "error": true
  },
  "message": "Not found",
  "result": null
}

Response Schema (YAML)

The response schema for both encrypted and decrypted 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:	
          updatedAt:
            type: string
            format: date-time
            description: Timestamp when the voucher was last updated
          createdAt:
            type: string
            format: date-time
            description: Timestamp when the voucher was created
          id:
            type: string
            description: Unique identifier for the voucher entry
          fulfillmentId:
            type: string
            description: Unique identifier for the fulfillment
          voucherCode:
            type: string
            description: Voucher code for redemption
          voucherPin:
            type: string
            description: Voucher PIN, if applicable
          validity:
            type: string
            nullable: true
            description: Voucher validity period
          orderId:
            type: string
            description: Unique identifier for the order
          ondcOrderId:
            type: string
            description: ONDC order identifier
          transactionId:
            type: string
            description: Unique identifier for the transaction