This is a central enpoint for contracting or modifing products. Depending on `change` object passed to this method you can initialize basket, mark product to be contracted, mark product to be terminated, set some parameter for contracting process and so on. Below you will find example scenarios of using basket.

Modify contract

1. Find contract to modify using: GET /contract/all
2. Check if contract modification is possible for selected contract using: GET /order/operations. Check flags for modify in response (visible and enabled are set to true).
3. Initialize basket using selected contract: POST /contracting/basket

   {
       "contractId": [id of contract to be modified]
   }
   

4. Get basket content (including products tree): GET /contracting/basket
5. Now you can select and deselect products (you can send more than one - every change will be proceeded one after another) using: POST /contracting/basket

   {
     "productActions": [{
       "productId": [id field from tree],
       "amount": [optional number of products to be put - important only for PUT action, min 1, max 100, default 1],
       "type": ["PUT" | "REMOVE"]
     }]
   }
   

   Sending multiply changes should be used mainly if you are sure all changes can be applied (i.e. one action won't exclude following ones). Step 4 and 5 can be repeated multiply times.
6. You can create order with introduced changes via POST /contracting/basket/order

   {
     "referenceNumber": [reference number],
     "wishDate": [date when the order is going to be started]
   }
   

Create new contract

1. Find subscriber for whom you want to create new contract, e.g. GET /hierarchy/subscribers
2. Initialize basket using selected account (subscriber): POST /contracting/basket

   {
     "accountGroupId": [subscriber id found in previous step]
   }
   

3. Get basket content (including products tree): GET /contracting/basket
4. Select and deselect products - in the same way as during contract modification
5. Right now you can fill in some characteristic values. Characteristics are all values which are needed to fully configured the future contract. The set of characteristics depends on previously selected products (for example you will receive different values for mobile subscription and for fixed one). What is more, it is possible that setting some characteristics can enable another ones. So after every such action you should check basket content. Let's assume you've selected in the previous step IP Centrex. In such situation you will get in your basket something like this:

   (...)
     "characteristics": {
       "firstName": {
         "name": "firstName",
         "value": "Jan",
         "possibleValues": [{"value": "Jan"}]
       },
       "lastName": {
         "name": "lastName",
         "value": "Kowalski",
         "possibleValues": [{"value": "Kowalski"}]
       },
       "loginExtension": {
         "name": "loginExtension"
       },
       "loginExtensionPrefix": {
         "name": "loginExtensionPrefix",
         "value": "",
         "possibleValues": [{"value": ""}]
       },
       "deviceOption": {
         "name": "deviceOption",
         "possibleValues": [
           {
             "value": "Off-The-Shelf",
             "caption": {"en": "Off-The-Shelf", "nl": "Off-The-Shelf"}
           },
           {
             "value": "Deviceless",
             "caption": {"en": "Deviceless", "nl": "Deviceless"}
           },
           {
             "value": "Existing Shared",
             "caption": {"en": "Existing Shared", "nl": "Existing Shared"}
           }
         ]
       },
       "fixedNumber": {
         "name": "fixedNumber"
       },
       "email": {
         "name": "email",
         "value": "jan.kowalski@comarch.com",
         "possibleValues": [{"value": "jan.kowalski@comarch.com"}]
       },
       "group": {
         "name": "group",
         "possibleValues": [
           {
             "value": "166715563",
             "caption": {"en": "Codemaster Group 1", "nl": "Codemaster Group 1"}
           },
           {
             "value": "166715564",
             "caption": {"en": "Codemaster Group 2", "nl": "Codemaster Group 2"}
           }
         ]
       }
     }
   (...)
   

   Some of these characteristics are read-only as they have only one possible value which is prefilled and can't be changed to anything else (for example firstName, lastName). They are included in the response for informational purpose and can be presented on a front-end. The rest of characteristics should be entered:
   • loginExtension,
   • deviceOption,
   • fixedNumber,
   • group. Setting characteristic value is done through the same POST /contracting/basket endpoint, but now we are going to use characteristicActions key, for example:

   {
     "characteristicActions": [{
       "name": "deviceOption",
       "value": "Off-The-Shelf"
     }]
   }
   

   After deviceOption is set to Off-The-Shelf you will receive additionally deviceType characteristic to set. Theoretically, you can merge many characteristic requests into one request by passing a list of actions instead of single one. But please be aware, that in such case they are proceeded sequentially one-by-one, so their order may be important (for example you need set deviceOption characteristic before deviceType). Or you can just make separated request for each individual value. It's up to you. The process of consulting basket content and setting characteristics value should be repeated until all required values are set.6. Next, if you decide to give a new sim card (possible only when you haven't ordered a new one), you should POST /basket the following object:

   {"simCardNumber": <short uiccid>}
   

6. You can create order with introduced changes via POST /contracting/basket/order

   {
     "referenceNumber": [reference number],
     "wishDate": [date when the order is going to be started]
   }
   

   Please note that if you selected some order you have to extend this object with address section.

Create new contract (by template)

1. Find subscriber for whom you want to create new contract, e.g. GET /hierarchy/subscribers
2. Initialize basket using selected account (subscriber): POST /contracting/basket

   {
     "accountGroupId": [subscriber id found in previous step]
   }
   

3. From now you can get template list using GET /contracing/basket/templates
4. You can use one of those templates (select it) using POST /contracting/basket:

   {
     "templateId": [template id]
   }
   

5. Get basket content (including products tree): GET /contracting/basket

The rest of steps is analogous to standard way of creating contract.

Reactivate contract

1. Find subscriber for whom you want to create new contract, e.g. GET /hierarchy/subscribers
2. Find service request in which contract was terminated, e.g. GET /track-and-trace/service-requests
3. Initialize basket using selected account (subscriber) and contract: POST /contracting/basket

   {
     "accountGroupId": [subscriber id found in previous step],
     "orderId": [termination order id found in previous step]
   }
   

4. A read-only characteristic previousPhoneNumber is initialized. You can use it to get the previous phone number and present it to an end user.

The rest of steps is analogous to standard way of creating contract.

Port in number

Initials steps are the same as for creating a new contract. After configuring products tree (by hand or by template) you should be able to set porting characteristics. Please note that this characteristic will be only available if you select mobile product. You can check possible list of characteristics to be set using: GET /basket or GET /basket/characteristics. Example response after selecting mobile product (fragment of GET /basket response):

(...)

  "characteristics": {
    "porting": {
      "name": "porting",
      "value": "false",
      "possibleValues": [
        {
          "value": "false",
          "caption": {
            "en": "false",
            "nl": "false"
          }
        },
        {
          "value": "true",
          "caption": {
            "en": "true",
            "nl": "true"
          }
        }
      ]
    }
  }

(...)

The response says that:

• you can set porting characteristic (field name),
• current value is false (field value),
• it can take one of two values: true or false (field possibleValues).

To switch porting value to true, you have to make the following request:

{
  "characteristicActions": [{
    "name": "porting",
    "value": "true"
  }]
}

After setting porting to true there will be possibility to set few more porting-specific parameters (you can get new list of characteristics again using GET /basket):

• phoneNumber - required, regex: 316\d{8} | 3197\d{9}
• customerNumber - required, length <= 70
• customerName, lenght <= 20
• keepExistingSimCard - default false
• note - length <= 60

Theoretically, you can merge characteristic requests into one request by passing a list of actions instead of single action. But please be aware, that in such case they are proceeded sequentially one-by-one, so their order may be important (for example you need set porting characteristic before phoneNumber). Or you can just make separated request for each individual value. It's up to you.

Turning on porting flag additionally disable possibility to get more main products and contract additional main products such as handsets, sim cards etc. During porting contracting such products is not possible.

If sent characteristic value does not met validation criteria an error is raised (400 Bad Request) with possible code values:

• INVALID_CUSTOMER_NAME,
• INVALID_CUSTOMER_NUMBER,
• INVALID_NOTE,
• BASKET_INVALID,
• INVALID_MSISDN_ALREADY_EXISTS_FOR_A_CUSTOMER,
• INVALID_MSISDN_IS_BLOCKED,
• INVALID_MSISDN_FORMAT_NOT_VALID,
• INVALID_MSISDN_LENGTH_FOR_THIS_PRODUCT,
• INVALID_MSISDN_FOR_CUSTOMER_OFFER,

Next, if you decide to give a new sim card (possible only when keepExistingSimCard = false), you should POST /basket the following object:

{
  "simCardNumber": <short uiccid>
}

to pass short UICCD of ported number.

Keeping existing sim card is only possible for phone number registered currently in KPN (internal porting).

Start a new order is possible via 'POST /basket/order'. You can pass:

• wishDate - preferred date of porting (null is treated as ASAP),
• referenceNumber.

We do not pass address to backend.

Possible error codes (for 400 Bad Request response):

• BASKET_INVALID - not all parameters have been set, or product tree is in error state,
• INVALID_WISH_DATE - as wish date should be <= current date + 90, and can not be set on holiday.

Combine fixed and mobile contract

1. Find first contract to combine using: GET /contract/all
2. Check if contract combination is possible for selected contract using: GET /order/operations. Check flags for combineFixedMobile in response (visible and enabled are set to true).
3. Depending on previous contract type find second contract using GET /contracting/id/{id}/vamo/fixed-numbers or GET /contracting/id/{id}/vamo/mobile-numbers
4. Initialize basket using selected contracts: POST /contracting/basket

   {
       "fixedContractId": [id of fixed contract],
       "mobileContractId": [id of mobile contract],
   }
   

5. Get list of possible characterists to bet set (for example pbx groups, service types, combine types). The response contains also current value of every characteristics: `GET /contracting/basket/characteristics
6. Set selected characteristics using modify basket (you can send more than one - every change will be proceeded one after another)

   {
     "characteristicActions": [{
       "name": [characteristic name],
       "value": [characteristic value]
     }]
   }
   Step 5 and 6 can be repeated multiply times.
   

7. Get products tree: GET /contracting/basket/products

The rest of steps are still not implemented.

Modify existing template

1. Find valid template to modify using: GET /contracting/templates
2. Initialize basket using selected template: POST /contracting/basket

   {
       "templatedIdToModify": [id of template to be modified]
   }
   

3. You can preview and modify basket state the same way as during create new subscrition or dduring contract modification
4. When the basket is in valid state you can save all change using POST /contracting/basket/modify-template

{"referenceNumber"=>"Activate eSim Card"}

{"orderId":12345678911}