The generic BSS APS API allows managing accounts and other related objects in the platform.
In this document:
In the platform, a full-featured account is represented by an APS resource
based on the PAAccount
APS type and linked through the one-to-one bssAccountInfo
link to an APS resource based on
the BssAccountInformation APS type.
Besides this, to be managed by a user, the account is linked with a user who
can perform particular administrative operations on behalf of the account in the platform control panel.
In the diagram, the blue boxes (PAAccount and PAAdminUser) represent the APS types of the OSS platform, while the other boxes represent APS types exposed by BSS (BssAccountInformation and CustomerClass):
An APS resource based on the PAAccount APS type represents a company or a personal account (not to be confused with a user) with all necessary contacts and the links with various other resources. The latter (not shown here) are the links with the subscriptions owned by the account, the parent account, child accounts, and other resources.
An APS resource based on the BssAccountInformation APS type represents commercial data of the account, for example, the currency to pay the purchased services. The resource is linked with other BSS APS resources, for example with an APS resource based on the CustomerClass APS type.
An APS resource based on the CustomerClass APS type represents a minimal set of properties that the respective customer class actually has. You can find the full set of properties in the provider (or reseller) control panel. For example, a class defines credit terms, a statement cycle, and billing type as various parts of the account’s contract with the parent account, also known as vendor in BSS (not to be confused with ISV, an independent software vendor). The BssAccountInformation APS type has the following relationship with the CustomerClass APS type:
A link named customerClass
defines a customer class containing business parameters for the account.
An optional collection of links, ownCustomerClasses
, relevant for the provider and resellers
(in BSS, they are generally called vendors)
defines the vendor’s own collection of customer classes to be assigned to the vendor’s customers or sub-resellers.
An APS resource based on the PAAdminUser APS type represents an administrator who can manage the account properties.
An external system must do some BSS operations itself as explained in this scenario.
In the step-by-step scenario considered in the next section, an external system operates on behalf of a vendor to manage its customers. That can be either the provider (always exists in the platform) or a reseller:
If the vendor in your scenario is a reseller, ensure your test platform contains at least one reseller.
The vendor must have at least two customer classes configured in BSS. By default, every vendor has a customer class called “Default” in its collection.
An external system will do the following operations in a sequence:
Lookup accounts in the platform. The aim is to define a list of vendors and to check if among the existing accounts none has the same properties that you want to be unique in an account you are going to create.
Create a customer with BSS properties.
Change a customer status by means of two operations. One puts a customer on credit hold and stops providing the services the customer is subscribed to. The other releases the customer from the credit hold.
Reassign a customer class for a customer. In that step, it is also necessary to define the customer class currently assigned to the customer and the vendor’s collection of available customer classes.
Note
To create an administrator for the account, refer to the Manage Users scenario.
To manage an account (whether reseller or customer), an external management system must first find the account APS resource based on the PAAccount APS type and the linked APS resource based on the BssAccountInformation APS type using a Resource Query Language (RQL) filter. As soon as the external system has the APS IDs of both linked APS resources, it can run the operations available for those resources.
When looking up for an account, the search parameter can be any property of the APS resource.
This can be the account ID assigned internally in the platform and synced with the external system.
For example, if you need the APS resource representing the provider, filter out the list of accounts with an account ID
of 1
.
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 omitted 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"
}
}]
If the platform is integrated with an external account management system, they can synchronize a list of accounts using custom attributes. To create a new custom attribute (for example, “crmId”) for the whole platform or for a certain sales vendor, the provider must follow the Creating Custom Attributes section in the Provider Guide. After that, this custom attribute can be configured per account using UI or API. The latter case is demonstrated in the next section.
Here is an example of request for accounts whose custom attribute crmId
is “ABC123”:
GET /aps/2/collections/bss-accounts?contains(attributes,and(eq(attributeID,crmId),eq(value,ABC123)))
The above request uses the contains RQL function.
As explained in the APS Types section, for every account APS resource, there is a linked APS resource representing the BSS data of that account. This means, when creating a customer through the APS API, it is necessary to create both APS resources linked to each other in a batch request:
Use the PAAccount APS type to create the customer APS resource.
Use the BssAccountInformation APS type to add an APS resource representing the BSS data of the customer.
The customer account APS resource will be linked with the other APS resource through the bssAccountInfo
link.
The backward link on the other side is called paAccount
.
Note
Optionally, you can add the creation of an administrator to the batch request. To do this, add the user JSON representation from the Manage Users scenario.
You cannot create a reseller directly using the procedure described in this section. The platform enables you to promote a customer to a reseller using the Create Resellers procedure.
From all available properties, the following table contains only the properties required to create an APS resource representing a customer.
Property |
Type |
Sample value |
Notes |
---|---|---|---|
|
URI |
"http://parallels.com/aps/types/ pa/account/1.2" |
Exact match with the ID specified in the PAAccount APS type. |
|
String enum [“ADMIN”, “RESELLER”, “CLIENT”, “SYSTEM”] |
“CLIENT” |
Specifies the type of the new account, respectively, provider, reseller, or customer. The last value, “SYSTEM”, is used only in GET requests. |
|
Boolean |
false |
Create a company, not a person. |
|
String |
“1st APS inc.” |
Assign a name to the customer company. |
|
Structure |
{“streetAddress”:”11, APS”, “locality”:”APS”, “region”:”VA”, “countryName”:”us”, “postalCode”:”12345”} |
Enter full postal address as specified by the Address structure inherited by the Account type. |
|
Structure |
{“email”:”isv1@aps.test”, “givenName”:”Mike”, “familyName”:”Wilson”, “telVoice”:”1#888#1234567”} |
Enter the administrative contacts. |
|
Structure |
{“email”:”isv1@aps.test”, “givenName”:”Mike”, “familyName”:”Wilson”, “telVoice”:”1#888#1234567”} |
Enter the billing contacts. |
|
Structure |
{“email”:”isv1@aps.test”, “givenName”:”Mike”, “familyName”:”Wilson”, “telVoice”:”1#888#1234567”} |
Enter the technical contacts. |
From all available properties, the following table contains only the properties required to create an APS resource representing BSS data of the customer.
Property |
Type |
Sample value |
Notes |
---|---|---|---|
|
URI |
|
Exact match with the ID specified in the BssAccountInformation APS type. |
|
String enum [“PROVIDER”, “PERSONAL”, “COMPANY”] |
|
Specifies the tax status of the account, respectively, “Provider”, “Personal”, or “Company”. |
|
String enum |
“en_US” |
Specifies a locale ID in accordance with the Locale Name rule. |
|
Array of { |
[{
“attributeID”: “external_id”,
“value”: “1111-2222-3333”
}]
|
Creates a set of custom attributes of the account in BSS. |
Keynotes:
The accountCurrencyCode
property is readonly
and therefore cannot be assigned in the request, although
visible in the Account Lookup section.
The attributes
array must include all account applicable BSS custom attributes that are marked as Required
.
You can identify them in the BSS provider control panel:
Both of the above-mentioned APS resources must be created at once, that is why the external system must use the Batch Provisioning request.
Since the resources must be bound to each other, a request must comply with the following rules:
The BssAccountInformation resource must go first in the batch. It is typical for the OSS/BSS platform, when a required operation first starts in BSS and then continues in OSS.
The BssAccountInformation
JSON representation must specify a unique APS ID to assign to the new resource
for the Account (second resource in the batch) to link to it. There are multiple online
Internet resources where you can generate
a UUID, for example Online UUID Generator.
The Account JSON representation must specify the bssAccountInfo
link with connection to the APS ID of
the first resource.
If the new account must be placed under a certain reseller, the Account JSON representation must
specify the APS ID of the reseller in the parent
link. By default, the account will be created under the provider.
The above rules are illustrated in the following example:
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"
}
}
]
In response, the APS controller must return the “200 OK” code along with the JSON representation of the created APS resources. The provider control panel must show the new customer in both OSS and BSS:
Unlike customers, resellers are not created directly by a single API call, but by promoting a customer to the reseller status as described in Provider Guide . For this purpose, a customer must subscribe to a reseller service plan. When using API, the whole procedure looks as follows:
Identify a reseller service plan to be used for promoting a customer to the reseller status as described in Service Plans.
Identify an account of the customer type as described in Account Lookup or create one as described in Create Customers.
For the selected account, order the selected service plan as described in Sales Orders.
Verify that a reseller subscription is created for the account as described in List Subscriptions and the account gets the reseller status as described in Account Lookup.
Initialize the new reseller by calling the initializeReseller
operation exposed by the
BssAccountInformation APS type. This operation is required to set the currency
code for the new reseller as in this example:
POST /aps/2/resources/3719e346-fe3d-4a69-b146-7b7362ae5e6e/initializeReseller
{ "currency": "USD" }
If successful, the response code is “204 No Content”.
Resellers can log in to the platform user panel as well as use their own external systems to manage their resources and customers in the platform through the platform API as described in the document set Partner Integration Scenarios.
To update an account property, send a PUT request. The request’s URL must specify the APS ID of the account. The JSON payload must contain a set of the properties you need to update and the APS section with the APS type ID and the account resource APS ID. For example, to update the company name, 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.
This section covers the operations that must be performed in accordance with credit terms, which are a part of the agreement between the provider and the customer. To change an account status, the external system must send the proper REST request addressed to the APS ID identified in the previous Create Customers step. The external system can also find it by following the Account Lookup section.
The BssAccountInformation APS type provides two custom operations to manage the account status in BSS:
putOnCreditHold
puts an account on credit hold similarly to the Put On Credit Hold operation in the
Provider Control Panel (PCP). The operation sets some restrictions on the commercial operations
for the account as well as it stops some services in accordance with the required policy
passed
as an input parameter with the following possible values:
ALL_SUBSCRIPTIONS
: the services in all subscriptions will be stopped. This is similar to the Suspend all
subscriptions option in the PCP.
UNPAID_SUBSCRIPTIONS
- only the services in the unpaid subscriptions will be stopped. This is similar
to the Suspend only unpaid subscriptions option in the PCP.
The operation also requires a sender to specify a reason
for the required action and a comment
.
releaseFromCreditHold
releases the account from the credit hold similarly to the Release From Credit Hold operation
in the PCP. As in the previous operation, it requires
the sender to specify a policy
and a comment
. The policy can be either, DEFAULT
or TEMPORARY
.
In the latter case, the account
is released from the credit hold until the date and time specified by the activeUntil
input parameter.
The sequence of operations will look as follows.
Put the account on credit hold using the ALL_SUBSCRIPTIONS
policy:
POST /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097/putOnCreditHold
{
"policy": "ALL_SUBSCRIPTIONS",
"reason": "ACCOUNT_OVERDUE",
"comment": "Account put on hold due to unpaid invoices, ID #1000123 and #1000125."
}
Check the current status of the account:
GET /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097
The response must show the CREDIT_HOLD
status:
HTTP/1.1 200 OK
{
"aps": {
"type": "http://parallels.com/pa/bss-account-info/1.0",
"id": "ceeeffac-d2f2-4e36-ae4a-3fe27ed58097",
"status": "aps:ready",
/* ... */
},
"accountCurrencyCode": "USD",
"accountId": 1000001,
"status": "CREDIT_HOLD"
}
The operation must change the account status and the status of the account’s subscription in both OSS and BSS:
OSS |
BSS |
Release the account from credit hold temporarily:
POST /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097/releaseFromCreditHold
{
"policy": "TEMPORARY",
"activeUntil": "2017-09-07T13:44:01Z",
"comment": "Account temporarily released from hold per approval ID #23231."
}
If successful, the response in either of the above POST operations will be:
HTTP/1.1 204 No Content
Every account, except for the provider, is created by its parent (also known as the sales vendor).
When creating a child account, the vendor must assign it to a customer class. In the APS API,
the parent can choose an APS resource linked to the parent’s ownCustomerClasses
collection
and assign it to the child through the child’s customerClass
link.
When needed, the vendor can reassign a child account to another customer class by relinking the respective BssAccountInformation resource to another customer class from the vendor’s collection.
External management systems can do the same operations. For that, they must know the APS ID of the PAAccount and BssAccountInformation resources as explained in the Account Lookup section.
Using the APS ID of the vendor’s BssAccountInformation resource , get the list of available customer classes, as in the following example:
GET /aps/2/resources/b7aba5b5-0516-4ad1-aec9-b31c77d74296/ownCustomerClasses
The response must look like this:
HTTP/1.1 200 OK
[
{
"aps": {
"type": "http://www.odin.com/billing/CustomerClass/1.0",
"id": "208e4172-1fdc-6ce9-aebd-1f4152889255",
"status": "aps:ready",
"revision": 2,
"modified": "2017-10-13T12:03:32Z"
},
"classId": 0,
"name": "Default"
},
{
"aps": {
"type": "http://www.odin.com/billing/CustomerClass/1.0",
"id": "6e465116-637c-4977-9524-f1c52a00633e",
"status": "aps:ready",
"revision": 2,
"modified": "2017-10-16T08:37:49Z"
},
"classId": 1,
"name": "Test Class"
}
]
The above operation shows the vendor has two customer classes, so it is possible to switch customers to either customer class.
To determine the customer class currently assigned to an account, request that account for
the customer class linked with the BssAccountInformation resource through the customerClass
link.
In the following example, the GET request refers to the customerClass
link of the BssAccountInformation
resource belonging to the required account:
GET /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097/customerClass
The response contains the representation of the customer class.
HTTP/1.1 200 OK
[
{
"aps": {
"type": "http://www.odin.com/billing/CustomerClass/1.0",
"id": "208e4172-1fdc-6ce9-aebd-1f4152889255",
"status": "aps:ready",
"revision": 2,
"modified": "2017-10-13T12:03:32Z"
},
"classId": 0,
"name": "Default"
}
]
In accordance with the aps.id
, classId
, and name
fields, the customer is currently linked with the “Default”
customer class from the vendor’s list identified in the previous step.
Now, switch the customer from the “Default” class to the “Test Class” customer class from the vendor’s list.
For this purpose, use the standard Relink resources
operation. The following request relinks the BssAccountInformation resource
through the customerClass
link to “Test Class”. The APS ID of the latter is specified in the message body, as follows:
POST /aps/2/resources/ceeeffac-d2f2-4e36-ae4a-3fe27ed58097/customerClass
{
"aps": {
"type": "http://www.odin.com/billing/CustomerClass/1.0",
"id": "6e465116-637c-4977-9524-f1c52a00633e"
}}
If successful, the response is similar to this:
HTTP/1.1 200 OK
{
"aps": {
"type": "http://www.odin.com/billing/CustomerClass/1.0",
"id": "6e465116-637c-4977-9524-f1c52a00633e",
"status": "aps:ready",
"revision": 2,
"modified": "2017-10-16T08:37:49Z",
"package":
{
"id": "f8521d26-a3a9-4f1a-a48c-a3bcc96b7921",
"href": "/aps/2/packages/f8521d26-a3a9-4f1a-a48c-a3bcc96b7921"
}
},
"classId": 1,
"name": "Test Class"
}
Now, the customer is assigned to another customer class.
The explanations and step-by-step instructions in this document help you gain experience in managing accounts in the platform through the APS REST interface.