PAAccount¶

This type represents an account, either a Customer, Reseller, or Provider in the platform. One administrative user, a User resource, must be created along with an account resource. The user resource depends on the account in accordance with the declared relationship. Additional administrative users may be added or removed, but it is prohibited to remove the only remaining administrative user.

In this document:

Schema
Properties
Relationship
Custom Operations
Structures
Examples

Schema ¶

The considered APS type (download) extends the Account APS type(s) and looks as follows:

{
  "name": "PAAccount",
  "id": "http://parallels.com/aps/types/pa/account/1.2",
  "apsVersion": "2.0",
  "implements": [
    "http://aps-standard.org/types/core/account/1.0"
  ],
  "relations": {
    "subscriptions": {
      "type": "http://parallels.com/aps/types/pa/subscription/1.0",
      "collection": true
    },
    "domains": {
      "type": "http://parallels.com/aps/types/pa/dns/zone/1.0",
      "collection": true
    },
    "templates": {
      "type": "http://parallels.com/aps/types/pa/serviceTemplate/1.0",
      "collection": true
    },
    "brands": {
      "type": "http://parallels.com/aps/types/pa/brand/1.0",
      "collection": true
    },
    "publicActor": {
      "type": "http://parallels.com/aps/types/pa/account/public/actor/1.0",
      "assign": {
        "access": {
          "referrer": false
        }
      }
    },
    "parent": {
      "type": "http://parallels.com/aps/types/pa/account/1.2"
    },
    "accounts": {
      "type": "http://parallels.com/aps/types/pa/account/1.2",
      "collection": true,
      "assign": {
        "access": {
          "referrer": false
        }
      }
    },
    "adminContactUser": {
      "type": "http://aps-standard.org/types/core/user/1.0",
      "backrel": false
    },
    "billingContactUser": {
      "type": "http://aps-standard.org/types/core/user/1.0",
      "backrel": false
    },
    "techContactUser": {
      "type": "http://aps-standard.org/types/core/user/1.0",
      "backrel": false
    },
    "bssAccountInfo": {
      "type": "http://parallels.com/pa/bss-account-info/1.0"
    }
  },
  "properties": {
    "id": {
      "type": "integer",
      "required": true,
      "final": true
    },
    "type": {
      "type": "string",
      "required": true,
      "default": "CLIENT",
      "enum": [
        "ADMIN",
        "RESELLER",
        "CLIENT",
        "SYSTEM"
      ],
      "enumTitles": [
        "Provider",
        "Reseller",
        "Customer",
        "System"
      ]
    },
    "personal": {
      "type": "boolean",
      "required": true,
      "default": "true"
    },
    "locked": {
      "type": "boolean",
      "default": "false"
    },
    "adminContact": {
      "type": "Contact"
    },
    "billingContact": {
      "type": "Contact"
    },
    "techContact": {
      "type": "Contact"
    },
    "updatedBy": {
      "type": "string"
    },
    "externalId": {
      "type": "string",
      "access": {
        "global": false
      }
    }
  },
  "operations": {
    "resources": {
      "path": "/resources",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "SubscriptionResourceList"
        }
      },
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "referrer": false
      }
    },
    "roles": {
      "path": "/roles",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "Role"
        }
      },
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "referrer": false
      }
    },
    "getLoginURL": {
      "path": "/loginUrl",
      "verb": "GET",
      "response": {
        "type": "string"
      },
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "referrer": false
      }
    },
    "getDefaultBrand": {
      "path": "/defaultBrand",
      "verb": "GET",
      "response": {
        "type": "Brand"
      },
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "referrer": false
      }
    },
    "getAccountHierarchy": {
      "path": "/hierarchy",
      "verb": "GET",
      "response": {
        "type": "array",
        "items": {
          "type": "PAAccount"
        }
      },
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "referrer": true,
        "public": true
      }
    },
    "getNewExperience": {
      "path": "/new-experience",
      "verb": "GET",
      "response": {
        "type": "boolean"
      },
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "referrer": false
      }
    },
    "switchNewExperience": {
      "path": "/new-experience",
      "verb": "PUT",
      "errorResponse": {
        "type": "object"
      },
      "access": {
        "referrer": false
      }
    }
  },
  "structures": {
    "Contact": {
      "type": "object",
      "properties": {
        "email": {
          "type": "string",
          "format": "email"
        },
        "givenName": {
          "type": "string"
        },
        "familyName": {
          "type": "string"
        },
        "middleName": {
          "type": "string"
        },
        "organizationName": {
          "type": "string"
        },
        "telVoice": {
          "type": "string"
        },
        "telFax": {
          "type": "string"
        },
        "locale": {
          "type": "string"
        }
      }
    },
    "SubscriptionResourceList": {
      "type": "object",
      "properties": {
        "subscriptionId": {
          "type": "string",
          "required": true
        },
        "resources": {
          "type": "array",
          "items": {
            "type": "http://aps-standard.org/types/core/subscription/1.0#SubscriptionResource"
          }
        }
      }
    },
    "Role": {
      "type": "object",
      "properties": {
        "id": {
          "type": "integer"
        },
        "name": {
          "type": "string"
        },
        "description": {
          "type": "string"
        }
      }
    },
    "Brand": {
      "type": "object",
      "properties": {
        "uid": {
          "type": "string"
        },
        "id": {
          "type": "integer"
        }
      }
    }
  }
}

The APS type is used to manage a collection of APS resources. To get a list of resources from that collection, use the following API call:

GET  /aps/2/collections/pa-accounts?<RQL-filter>

Properties ¶

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
id	Integer	Required Final		Account ID in the platform.
type	Enum	Required	CLIENT	Identifies an account type AccountType. Account Type: `ADMIN` - Provider `RESELLER` - Reseller `CLIENT` - Customer `SYSTEM` - System (for the platform internal operations)
personal	Boolean	Required	true	The account represents a person (true) or an organization (false).
locked	Boolean	Not Required	false	The account is locked (true) or unlocked (false).
adminContact	Contact	Not Required		Administrative Contact data.
billingContact	Contact	Not Required		Billing Contact data.
techContact	Contact	Not Required		Technical Contact data.

Relationship ¶

NAME	TYPE	REQUIRED	DESCRIPTION
subscriptions	Collection of PASubscription	No	Subscriptions owned by the account.
domains	Collection of PAHostedDomain	No	Domains owned by the account.
templates	Collection of PAServiceTemplate	No	Service templates owned by the account (the provider or a reseller).
brands	Collection of http://parallels.com/aps/types/pa/brand	No	Brands created for the account.
publicActor	PublicActor	No	Public Actor related to the account is a system built-in object. Normally, APS applications do not use it.
parent	PAAccount	No	Parent account (the provider or a reseller, also known as the vendor for the considered account).
accounts	Collection of PAAccount	No	Child accounts (resellers and customers) if the current account is the provider or a reseller.
adminContactUser	User	No	Administrative user of the account.
billingContactUser	User	No	Billing user of the account.
techContactUser	User	No	Technical user of the account.
bssAccountInfo	BssAccountInformation	No	BSS account data; presents only if billing is enabled for the account.

Custom Operations ¶

OPERATION	VERB	PATH	RETURNS	Description
resources	GET	/resources		“/resources” custom operation (GET) returns resources SubscriptionResourceList for all subscriptions owned by the account.
roles	GET	/roles		“/roles” custom operation (GET) returns roles Role that can be assigned to account member.
getLoginURL	GET	/loginUrl		“/loginUrl” custom operation (GET) returns account login url
getDefaultBrand	GET	/defaultBrand		Returns account default brand
getAccountHierarchy	GET	/hierarchy	Account hierarchy in the order: ADMIN -> RESELLER -> … -> ACCOUNT
getNewExperience	GET	/new-experience	Boolean.	Retrieves if the new UX1 experience is enabled
switchNewExperience	PUT	/new-experience		Changes the value of new experience value in the database

resources¶

HTTP Request

GET /aps/2/resources/{aps-id}/resources

Description

“/resources” custom operation (GET) returns resources SubscriptionResourceList for all subscriptions owned by the account.

Returns

roles¶

HTTP Request

GET /aps/2/resources/{aps-id}/roles

Description

“/roles” custom operation (GET) returns roles Role that can be assigned to account member.

Returns

getLoginURL¶

HTTP Request

GET /aps/2/resources/{aps-id}/loginUrl

Description

“/loginUrl” custom operation (GET) returns account login url

Returns

getDefaultBrand¶

HTTP Request

GET /aps/2/resources/{aps-id}/defaultBrand

Description

Returns account default brand

Returns

getAccountHierarchy¶

HTTP Request

GET /aps/2/resources/{aps-id}/hierarchy

Description

Returns

Account hierarchy in the order: ADMIN -> RESELLER -> … -> ACCOUNT

getNewExperience¶

HTTP Request

GET /aps/2/resources/{aps-id}/new-experience

Description

Retrieves if the new UX1 experience is enabled

Returns

Boolean.

switchNewExperience¶

HTTP Request

PUT /aps/2/resources/{aps-id}/new-experience

Description

Changes the value of new experience value in the database

Returns

Structures ¶

Contact¶

Contains contact data of a user, such as full name, email, and locale.

NAME	TYPE	ATTRIBUTES	DESCRIPTION
email	String	Not Required	Email address.
givenName	String	Not Required	Given Name.
familyName	String	Not Required	Family Name.
middleName	String	Not Required	Middle Name.
organizationName	String	Not Required	Organization Name.
telVoice	String	Not Required	Phone number.
telFax	String	Not Required	Fax number.
locale	String	Not Required	Locale..

SubscriptionResourceList¶

Contains list of resources for a subscription.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
subscriptionId	String	Required		Subscription UUID.
resources	Array of Subscription	Not Required		List of resources.

Role¶

Contains role data, such as id, name and description

NAME	TYPE	ATTRIBUTES	DESCRIPTION
id	Integer	Not Required	Id.
name	String	Not Required	Name.
description	String	Not Required	Description.

Brand¶

Brand.

NAME	TYPE	ATTRIBUTES	DEFAULT	DESCRIPTION
uid	String	Not Required
id	Integer	Not Required

Examples ¶

Get Account by ID¶

If the account ID of a customer in the platform is 1000002, a request to get both APS resources, PAAccount and BssAccountInformation, will be:

GET /aps/2/collections/accounts?eq(id,1000002),select(bssAccountInfo)

If the external system needs the BssAccountInformation resources only, use the bss-accounts alias instead of accounts in the URL, and the other functions (select and eq) must be changed accordingly.

The response will look similar to the following (some data is missed out for brevity):

HTTP/1.1 200 OK

[{
   "aps": {
      "type": "http://parallels.com/aps/types/pa/account/1.2",
      "id": "f654862a-4903-4151-b2b4-ed65c055d120",
      ...
   },
   "companyName": "John Smith",
   "id": 1000002,
   "locked": false,
   "personal": true,
   "type": "CLIENT",
   "addressPostal": { /* ... */ },
   "adminContact": { /* ... */ },
   "billingContact": { /* ... */ },
   "techContact": { /* ... */ },
   "bssAccountInfo": {
      "aps": {
         "type": "http://parallels.com/pa/bss-account-info/1.0",
         "id": "7cad381f-0daf-4557-a53f-b5ea64566622",
         "status": "aps:ready",
         /* ... */
      },
      "branchId": "",
      "accountCurrencyCode": "USD",
      "taxStatus": "PERSONAL",
      "accountId": 1000002,
      "taxZoneId": "Provider-Country",
      "salesId": "",
      "taxRegIdStatus": "NOT_VERIFIED",
      "creditTerm": {
         "duePeriod": 10,
         "holdPeriod": 30
      },
      "externalARManagement": false,
      "taxRegId": "*****",
      "fullyRegistered": true,
      "localeId": "en",
      "status": "ACTIVE"
   }
}]

Create Account with BSS Data¶

POST /aps/2/resources

[
   { "aps":{
         "type":"http://parallels.com/pa/bss-account-info/1.0",
         "id":"ceeeffac-d2f2-4e36-ae4a-3fe27ed58097"
      },
      "taxStatus": "COMPANY",
      "localeId": "en_US",
      "attributes": [
         {
            "attributeID": "external_id",
            "value": "1111-2222-3333"
         }
      ]
   },
   { "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"
         }
      },
      "parent":{
         "aps":{
            "id":"4935d68d-4d26-4930-acf7-3871557305a9"
         }
      },
      "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"
      }
   }
]

Update Account¶

For example, to update the company name of an account, send:

PUT /aps/2/resources/6344049b-8763-417d-837b-490ba0896f41

{
  "aps": {
    "type": "http://parallels.com/aps/types/pa/account/1.2",
    "id": "6344049b-8763-417d-837b-490ba0896f41"
  },
  "companyName": "John Smith and brothers"
}

In response, the APS controller will send the full JSON representation of the updated account.

← ContactManagement

PAAdminUser →

CloudBlue Commerce API

Previous topic

Next topic

PAAccount¶

Schema ¶

Properties ¶

Relationship ¶

Custom Operations ¶

resources¶

roles¶

getLoginURL¶

getDefaultBrand¶

getAccountHierarchy¶

getNewExperience¶

switchNewExperience¶

Structures ¶

Contact¶

SubscriptionResourceList¶

Role¶

Brand¶

Examples ¶

Get Account by ID¶

Create Account with BSS Data¶

Update Account¶

CloudBlue Commerce API

Previous topic

Next topic

PAAccount¶

Schema¶

Properties¶

Relationship¶

Custom Operations¶

resources¶

roles¶

getLoginURL¶

getDefaultBrand¶

getAccountHierarchy¶

getNewExperience¶

switchNewExperience¶

Structures¶

Contact¶

SubscriptionResourceList¶

Role¶

Brand¶

Examples¶

Get Account by ID¶

Create Account with BSS Data¶

Update Account¶

Schema ¶

Properties ¶

Relationship ¶

Custom Operations ¶

Structures ¶

Examples ¶