Cloudstore API

CloudStore API endpoints

This document is intended as a reference for working with the Cloudstore API.
The CloudStore API is a collection of endpoints that enable you to place, change, renew or cancel orders in the 2tCloud Platform. You can register new customers, get an overview of all active subscriptions for that customer for subscription management purposes, and order new subscriptions.
More details on each endpoint can be found in this reference guide.

Take a note of the OAuth Base URL in the screenshot above. You will get a different URL, most likely https://portal.cloudnet.services. You need to prepend that URL to all endpoints described below.

Full API description can be found here: https://docs.cloudblue.com/cbc/sdk/20.4/systems/

Sending requests

You send a request to a specific endpoint, with headers to identify yourself, with a specific method, and with optional parameters. You need to know the Base URL in advance.

For example:

Item	Description
URL	https://portal.cloudnet.services/aps/2/collections/service-plans
HTTP headers	OAuth oauth_consumer_key="AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",oauth_signature_method="HMAC-SHA1",oauth_timestamp="1613642599",oauth_nonce="9MkVTAHZ4XV",oauth_version="1.0",oauth_signature="sUFt3q3CYjkzRlTsrSAYc%2BlRz9c%3D"
Method	GET

You can use Postman to specify these details. Note that the method and the URL are on the top left, and you can specify the key and secret in the authorization tab:

The key and secret that you fill in at the Authorization tab are automatically converted to the correct HTTP header. You can verify that header in the Headers tab.

By clicking on the Code link, you will receive various examples of how to use code in various languages to connect.

If you send parameters in a POST command, you can click on the Body tab, and specify the Json content. Make sure to also select the content type to JSON as shown below :

Get available service plans

Item	Description
URL	/aps/2/collections/service-plans
Method	GET

A list of all available service plans will be returned in the following format:

CODE

[
    {
        "name": {
            "en_US": "Hosted Exchange Basic 2013",
            "fr_FR": "Hosted Exchange Basic 2013",
            "nl_NL": "Hosted Exchange Basic 2013"
        },
        "planId": 93530,
        "publication": {
            "published": false
        },
        "billingTerms": {
            "model": "CHARGE_BEFORE_SUBSCRIPTION_PERIOD",
            "period": {
                "unit": "STATEMENT_DAY",
                "duration": 1
            },
            "autorenewal": {
                "days": 1,
                "type": "BEFORE_EXPIRATION_DATE"
            },
            "recurringPricesEvery": "BILLING_PERIOD"
        },
        "resourceRates": [
 
       ...
 
       ]
 
    }
 
]

Note that the name of each plan is available in multiple languages, and you can identify the planId from the response.

Get all available resources

Item	Description
URL	/aps/2/collections/bss-resources
Method	GET

A list of all available resources will be returned in the following format:

CODE

[
    {
        "id": 1003711,
        "MPN": "0a590a70-13fa-4cf4-996e-7c7da8055491",
        "name": {
            "en_US": "Microsoft Stream Storage Add-On (500 GB) for students",
            "fr_FR": "Microsoft Stream Storage Add-On (500 GB) for students",
            "nl_NL": "Microsoft Stream Storage Add-On (500 GB) for students"
        },
        "vendorId": "Microsoft",
        "vendorName": "Microsoft",
        "unitOfMeasure": {
            "en_US": "License",
            "fr_FR": "Licence",
            "nl_NL": "Licentie"
        },
        "aps": {
            "modified": "2021-02-16T11:48:04Z",
            "id": "ebd5884b-9902-4c33-950c-50d35e1427f4",
            "type": "http://www.odin.com/billing/Resource/1.3",
            "status": "aps:ready",
            "revision": 4
        }
    },
     ...
]

Note that you can identify the name of each resource in multiple languages, and the Id of the resource can be determined.

Get service plan details

Item	Description
URL	/aps/2/resources/452a91b7-d565-4f47-904a-8aac8d9c0628
Method	GET

When you know the ID of a specific plan, you can get the plan details. The response looks like:

CODE

{
    "name": {
        "en_US": "NCE Microsoft Azure Reserved Instances",
        "fr_FR": "NCE Microsoft Azure Reserved Instances",
        "nl_NL": "NCE Microsoft Azure Reserved Instances"
    },
    "planId": 1798135,
    "publication": {
        "published": true
    },
...
}

Get service plan resources

Item	Description
URL	/aps/2/resources/452a91b7-d565-4f47-904a-8aac8d9c0628/resources
Method	GET

When you know the ID of a specific plan, you can get the available resources for that particular plan with this query. The response looks like:

CODE

[
    {
        "unitOfMeasure": {
            "en_US": "Unit(s)",
            "fr_FR": "Unité(s)",
            "nl_NL": "Stuk(s)"
        },
        "aps": {
            "modified": "2021-02-22T11:23:15Z",
            "id": "27e90c64-7277-4862-8993-4b3280a1690c",
            "type": "http://www.odin.com/billing/Resource/1.3",
            "status": "aps:ready",
            "revision": 2
        },
        "name": {
            "en_US": "Azure RI",
            "fr_FR": "Azure RI",
            "nl_NL": "Azure RI"
        },
...
}]

Create a customer account

Item	Description
URL	/aps/2/resources
Method	POST

First you must make an a customer account. Post the following data to create an account. Substitute with the correct data for the account you want to create:

CODE

[
    {
        "aps": {
            "type": "http://parallels.com/pa/bss-account-info/1.0",
            "id": "ceeeffac-d2f2-4e36-ae4a-3fe27ed58097"
        },
        "taxStatus": "COMPANY",
        "localeId": "en_US"
    },
    {
        "aps": {
            "type": "http://parallels.com/aps/types/pa/account/1.2"
        },
        "type": "CLIENT",
        "personal": false,
        "companyName": "1st APS inc",
        "bssAccountInfo": {
            "aps": {
                "id": "ceeeffac-d2f2-4e36-ae4a-3fe27ed58097"
            }
        },
        "addressPostal": {
            "countryName": "us",
            "locality": "APS",
            "postalCode": "12345",
            "region": "VA",
            "streetAddress": "11, APS"
        },
        "adminContact": {
            "email": "isv1@aps.test",
            "givenName": "Mike",
            "familyName": "Wilson",
            "telVoice": "1#888#1234567"
        },
        "billingContact": {
            "email": "isv1@aps.test",
            "givenName": "Mike",
            "familyName": "Wilson",
            "telVoice": "1#888#1234567"
        },
        "techContact": {
            "email": "isv1@aps.test",
            "givenName": "Mike",
            "familyName": "Wilson",
            "telVoice": "1#888#1234567"
        }
    }
]

Note that you must also create a user for the account. See following steps.

Get list of accounts

Item	Description
URL	/aps/2/collections/accounts
Method	GET

This will return a list of all accounts. Note that you can get the APS id of the account in this section:

...,

"aps": {
            "modified": "2021-02-22T11:04:47Z",
            "id": "b5369636-94c8-4768-a180-d88d485a93ba",
            "type": "http://parallels.com/aps/types/pa/account/1.2",
            "status": "aps:ready",
            "revision": 4
        },

...

Do not use the nummeric ID field that contains only numbers, like 123456, but always use the Guid type ID's.

Create a user for the created account

Item	Description
URL	/aps/2/resources/b5369636-94c8-4768-a180-d88d485a93ba/users/
Method	POST

Post the following data to create a user. In the URL you must place the ID of the created account. You can get that ID by using the list of accounts. Substitute below with the correct data for the user:

CODE

{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/admin-user/1.2"
   },
   "isAccountAdmin": true,
   "login": "mw@aps.test",
   "password": "p@$$w0rd",
   "email": "mw@aps.test",
   "givenName": "Mike",
   "familyName": "Wilson",
   "telVoice": "1(888)1234567",
   "addressPostal": {
      "streetAddress":"11, ISVone",
      "locality":"Herndon",
      "region":"VA",
      "countryName":"us",
      "postalCode":"12345"
   }
}

Place an order

Item	Description
URL	/aps/2/services/order-manager/orders
Method	POST
Parameters	The ID of the Customer Account The ID of the Plan The Subscription period (optionally) Additional Resources (optionally) Parameters required for the underlying APS or plan, such as Office 365 AcceptedTerms, some Plans require that you accept terms of use(s) PaymentMethodId, default 0 for 'pay via invoice'

Important ! Substitute the accountId, planId and resourceId with valid values.

Example:

CODE

{
    "type": "SALES",
    "accountId": "3fef9702-b2ad-419a-9924-a56882e5f06c",
    "promoCode": "123",
    "paymentMethodId": "3",
    "products": [
        {
            "planId": "ae0e6e84-0d37-4b17-8f6c-5709633529ab",
            "period": {
                "unit": "MONTHS",
                "duration": 1
            },
            "resources": [
                {
                    "resourceId": "1c3ab0be-3160-45a1-a9b4-7824f74673ff",
                    "amount": 40
                }
            ],
            "parameters": [
                {
                    "aps": {
                        "type": "http://aps-standard.org/samples/vpsdemo/management/1.0"
                    },
                    "client": "1st APS, inc.",
                    "mail": "jsmith@aps.test"
                }
            ],
            "childProducts": [
                { // Another service plan - upsell
                }
            ]
        },
        { // Another service plan
        }
    ],
    "attributes": [
        {
            "attributeID": "comments",
            "value": "Requested by the ERP system."
        }
    ],
    "acceptedTerms": [
        "1"
    ],
    "specialPricing": { // See the "Set Special Prices" section for details
    }
}

Example for ordering Office 365:

CODE

{
    "type": "SALES",
    "accountId": "ceeeffac-d2f2-4e36-ae4a-3fe27ed58098",
    "paymentMethodId": "0",
    "products": [
        {
            "planId": "cdc7dbd7-977a-4f48-8d17-4f9847c090f5",
            "period": {
                "unit": "MONTHS",
                "duration": 1
            },
            "parameters": [
                {
                    "Type": "http://www.parallels.com/Office365/Tenant/2.8",
                    "Param": {
                        "Subdomain": "CopacoOfficeTest12",
                        "Email": "admin@CopacoOfficeTest6.onmicrosoft.com",
                        "FirstName": "first",
                        "LastName": "last",
                        "Phone": "123"
                    }
                }
            ]
        }
    ],
    "acceptedTerms": [
        "1"
    ]
}

Get orders

Item	Description
URL	/aps/2/services/order-manager/orders
Method	GET

This will return a list of all orders.

You can optionally add additional filters to the URL. In this case, a request will look as follows:

CODE

GET /aps/2/services/order-manager/orders?in({property},{value}),select({linkToResources}),ge(creationDate,{fromDate}),le(creationDate,{toDate}),like(number,*000001),limit({from},{to})

The following functions can be used:

· in verifies whether a property is in a specified list, for example, request only sales orders and billing orders:

CODE

·       in(type,(SO,BO))

The following properties are allowed in the function:

o resellerId is the APS ID of the reseller that provides the ordered services.

o customerId is the APS ID of the customer that placed the order.

o endCustomerName is a customer name.

o endCustomerType is an account type (“PROVIDER”, “RESELLER”, or “CUSTOMER”).

o ID of an order or account attribute.

o internalId is and integer showing an order unique ID in the platform.

o orderId is a string showing an order unique APS ID.

o orderNumber is a string ID assigned by the platform to an order, for example, “SO000004”.

o status is an order status.

o type is an order type. The most common types for API are in the following list:

§ BO is a billing order generated at the end of a billing period usually to bill an account for resources consumed during the passed billing period.

§ CL is a cancellation order generated when a subscription is cancelled and the sales vendor owns money to the customer.

§ CF is a cancellation order generated when a subscription is cancelled and the customer owns money to the sales vendor.

§ RN is a renewal order created when a subscription must be renewed for the next period.

§ SO is a sales order that contains a request for certain service plans.

§ CH is a change order that a subscriber uses to change a subscription.

o provisioningStatus is an order provisioning status.

o paymentStatus is the payment status of an order.

o subscriptionId is the APS ID of the subscription whose orders are requested.

NOTE

A list of order attribute IDs and account attribute IDs is created by the provider using the control panel. Those IDs are unique within the platform.

· like verifies if a property matches a wildcard mask that uses the wildcard symbols * and ?. Currently, this function is applicable to orderNumber, endCustomerName, and attribute IDs (either account or order attributes).

Example of filtering by order number:

CODE

like(orderNumber,*00001)

Example of filtering by attribute ID:

CODE

like(ORDER_ID1,test1234)

· ge and le (respectively “Greater or Equal” and “Lower or Equal”) functions are applicable to the internal ID and the date-time properties to select the orders in a certain date and time interval:

o internalId

o creationTime

o orderDate

o expirationDate

For example, seek for orders created in the specified time period:

CODE

ge(creationTime,2018-04-26T16:00:00Z),le(creationTime,2018-04-26T18:00:00Z)

· limit fetches orders in a range of numbers, for example get orders in the range of 0 to 9:

CODE

limit(0,9)

Get subscriptions

Item	Description
URL	/aps/2/collections/bss-subscriptions
Method	GET

This will return a list of all subscriptions.

You can optionally specify parameters in the query:

· Get all subscriptions of a customer using a filter:

CODE

·       GET /aps/2/collections/bss-subscriptions?account.aps.id=7fd20173-b11e-4459-8e95-ff4810eb1ebd

The above request contains the APS ID of a customer.

· Search for a subscription using a property with a unique value, for example, search it by name:

CODE

GET /aps/2/collections/subscriptions?like(name,*Demo*)

Change subscription

Item	Description
URL	/aps/2/services/order-manager/orders
Method	POST

Example to change the duration for a subscription:

CODE

{
   "type": "CHANGE",
   "subscriptionId": "456808a0-b5a6-4092-ab67-b77e33743a07",
   "planId": "ae0e6e84-0d37-4b17-8f6c-5709633529ab",
   "paymentMethodId": "11",
   "period": {
      "unit": "MONTHS",
      "duration": 3
   }
}

Example to add additional amount of resources:

CODE

{
   "type": "CHANGE",
   "subscriptionId": "4c867c87-fbf7-49e8-9f7e-0d06e8f7a003", 
   "paymentMethodId": "11", 
   "resources": [{
       "resourceId": "bf8ea705-3f2b-4f3c-b445-a11ec100da82", 
       "amount": 10 
   }]
}

Cancel subscription

Item	Description
URL	/aps/2/services/order-manager/orders
Method	POST

You need to provide the Id of an existing subscription, for example:

CODE

{
   "type": "CANCELLATION",
   "subscriptionId": "456808a0-b5a6-4092-ab67-b77e33743a07",
   "refundType": "CREDIT_MEMO"
}

Renew subscription

Item	Description
URL	/aps/2/services/order-manager/orders
Method	POST

Example to renew a subscription:

CODE

{
   "type": "RENEWAL",
   "subscriptionId": "456808a0-b5a6-4092-ab67-b77e33743a07",
   "paymentMethodId": "11",
   "period": {
      "unit": "MONTHS",
      "duration": 1
   }
}