User guide
Incoming orders API

Incoming Orders API

This section provides a formal technical specification of the Incoming Orders API, including supported endpoints, request and response structure, and expected HTTP behavior.

The Incoming Orders is a service responsible for handling incoming product order requests. It provides endpoints to create, retrieve and cancel product orders.

API Security

The API is secured and requires an authorization token. Each request to the API must include the token in the header to be processed correctly. For more information on how to obtain a token from Keycloak here.

Endpoints

1. Create Product Order

URL: /productOrder Method: POST Description: Creates a new product order with the provided payload and headers.

Request Headers:

  • Accepts a Map of headers for metadata processing.

Request Body:

  • Type: String
  • Description: JSON payload that matches the model defined in CUSTOMIZATION: Order Service

Response:

  • Status: 201 Created
  • Body: String
  • Contains the order with enriched ID and href.

Example Request:

POST /productOrder
Headers: {...}
Body: {
   productOrder
}

Example Response:

Status: 201 Created
Body: {
   {productOrder},
   "id": "o-a18ba806-1cf9-4e54-9960-6c9d716b4a9b",
   "href": "/productOrder/o-a18ba806-1cf9-4e54-9960-6c9d716b4a9"
}

2. Retrieve Product Order

URL: /productOrder/{id} Method: GET Description: Retrieves details of an existing product order by its ID.

Path Parameters:

  • id (String): The ID of the product order to retrieve.

Response:

  • Status: 200 OK
  • Body: JSON containing the details of the product order, enriched with an href property.

Example Request:

GET /productOrder/o-a18ba806-1cf9-4e54-9960-6c9d716b4a9b

Example Response:

Status: 200 OK
Body: {
  "orderId": "o-a18ba806-1cf9-4e54-9960-6c9d716b4a9b",
  "href": "/productOrder/o-a18ba806-1cf9-4e54-9960-6c9d716b4a9b",
  {productOrder}
}

3. Patch Product Order

URL: /productOrder/{id}
Method: PATCH
Description: Applies partial updates to an existing product order, such as cancelling individual items or adding new ones.

Request Headers:

  • Content-Type: application/json
  • Authorization: Bearer <ACCESS_TOKEN>

Request Body:

  • Type: Partial ProductOrder
  • Description: JSON payload containing only the fields that need to be updated.

Response:

  • Status: 204 No Content
  • No response body is returned when the update is accepted.

Example Request:

PATCH /productOrder/o-a18ba806-1cf9-4e54-9960-6c9d716b4a9b
Headers: {
  "Content-Type": "application/json",
  "Authorization": "Bearer <ACCESS_TOKEN>"
}
Body: {
  "productOrderItem": [
    {
      "id": "POI_0002",
      "state": "cancelled"
    },
    {
      "id": "POI_0006",
      "action": "add",
      "product": {
        "productCharacteristic": [
          {
            "name": "IMSI",
            "valueType": "string",
            "value": ""
          },
          {
            "name": "ICCID",
            "valueType": "string",
            "value": ""
          }
        ]
      },
      "state": "acknowledged"
    }
  ]
}

Example Response

Status: 204 No Content

4. Cancel Product Order

URL: /cancelProductOrder Method: POST Description: Cancels an existing product order based on the cancellation reason provided.

Request Body:

  • Type: CancelProductOrder (based on TMF622 API specification).
  • Description: JSON payload with details of the order to be canceled, including the cancellation reason.

Response:

  • Status: 201 Created
  • Body: CancelProductOrder object containing:
  • id (String): The ID of the canceled order.
  • state (TaskStateType): The state of the cancellation.

Example Request:

POST /cancelProductOrder
Body: {
  "productOrder": {
    "id": "o-a18ba806-1cf9-4e54-9960-6c9d716b4a9b"
  },
  "cancellationReason": "Customer request"
}

Example Response:

Status: 201 Created
Body: {
  "productOrder": {
    "id": "o-a18ba806-1cf9-4e54-9960-6c9d716b4a9b"
  },
  "cancellationReason": "Customer request",
  "id": "o-a18ba806-1cf9-4e54-9960-6c9d716b4a9b",
  "state": "done"
}

Related

ApplicationRun sample order processing