The type is used to implement Charge Import API
In this document:
The considered APS type (download
)
extends the Resource APS type(s) and looks as follows:
{
"name": "UsageAdapterManager",
"id": "http://com.odin.rating/usage-adapter-manager/1.0",
"apsVersion": "2.0",
"implements": [
"http://aps-standard.org/types/core/resource/1.0"
],
"operations": {
"processUsageReports": {
"path": "usageReports",
"verb": "POST",
"errorResponse": {
"type": "object"
}
},
"getUsageReports": {
"path": "usageReportsList",
"verb": "GET",
"response": {
"type": "object"
},
"errorResponse": {
"type": "object"
}
},
"getReportErrors": {
"path": "errorList",
"verb": "GET",
"response": {
"type": "object"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"reportId": {
"kind": "query",
"type": "string"
},
"productId": {
"kind": "query",
"type": "string"
}
}
},
"getReportTemplate": {
"path": "/usageReportTemplate",
"verb": "GET",
"response": {
"type": "object"
},
"errorResponse": {
"type": "object"
}
},
"getReport": {
"path": "usageReports/{report_id}",
"verb": "GET",
"response": {
"type": "object"
},
"errorResponse": {
"type": "object"
},
"parameters": {
"report_id": {
"kind": "path",
"type": "integer"
}
}
}
}
}
OPERATION |
VERB |
PATH |
RETURNS |
Description |
---|---|---|---|---|
POST |
/usageReports |
|||
GET |
/usageReportsList |
|||
GET |
/errorList |
|||
GET |
/usageReportTemplate |
|||
GET |
/usageReports/{report_id} |
HTTP Request
GET /aps/2/resources/{aps-id}/errorList
Description
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
reportId |
String |
|
productId |
String |
Returns
HTTP Request
GET /aps/2/resources/{aps-id}/usageReportTemplate
Description
Returns
HTTP Request
GET /aps/2/resources/{aps-id}/usageReports/{report_id}
Description
Parameters
PARAMETER |
TYPE |
DESCRIPTION |
---|---|---|
report_id |
Integer |
Returns
Only the provider staff is authorized to call the Usage Adapter Manager operations.
This API is initially intended for CloudBlue Connect, a business-to-business (B2B) matching platform that connects various software vendors with various commerce platforms. Other integrated applications can use this API as well.
The platform supports a sales channel hierarchy with several levels
. The following is a typical
hierarchy that consists of four levels:
The provider, also called as level 0 (L0), is the platform owner. The provider can interact with software vendors directly or through L1 resellers that can be operating units of the provider rather than partners.
L1 resellers can be the provider’s partners (who have a commercial relationship with the provider) or the provider’s operating units. For example, in the latter case, they represent the provider in different countries.
L2 resellers are the partners of the upper-level resellers.
Customers are the consumers of products sold by their L2 resellers.
On the software vendor side, the business hierarchy terminology can differ from the terminology described above. For
example, the CloudBlue Connect platform breaks the account
hierarchy vertically into tiers
counting them from customers up to the provider. In this case, keep in mind the
following mapping:
Account |
Levels on the commerce platform |
Tiers on a vendor’s side |
---|---|---|
Provider |
L0 |
T3 |
Reseller as a partner or a provider’s operating unit |
L1 |
T2 |
Reseller as a partner |
L2 |
T1 |
Customer |
Not applicable |
T0 |
A product usage schema defines the way the vendor and the commerce platform charge the provider, resellers, and customers. Currently, the following schemas can be used in vendor-rated reports:
TR (Tier-Rated):
The vendor specifies prices for all tiers.
The platform uses those prices to charge all involved accounts except for the provider. The provider pays to the vendor outside the BSS.
CR (Cost Rated):
The vendor specifies the cost for the used resources, that is, the price that the provider must pay the vendor.
The platform calculates prices for the other levels using a margin. According to this method, the price for every lower-level account equals the upper-level price with an added margin assigned to that upper-level account.
PR (Price Rated):
The vendor specifies the price for the end customer. Typically, this is the MSRP (Manufacture Suggested Retail Price).
The platform calculates prices for the other levels using a margin. According to this method, the price for each upper-level account equals the price of the lower-level account minus the margin assigned to that upper-level account.
External systems, including UI systems, can use the considered API to upload the resource usage reported by a software vendor system as a file in XLSX format. The file must contain at least two tabs:
general
defines general parameters of the report, including identification of the schema, marketplace, and hub.
records
defines charges for resources of a specific product sold through the specified hub.
Attribute ID |
Example |
Description |
Required |
---|---|---|---|
report_name |
Consumption report for April 2020 |
The name that the vendor assigns to this report. |
Yes |
report_note |
Please process before May 15th. |
Anything that the vendor wants to note. |
Yes |
report_id |
RID-12345-12345 |
The report ID on the vendor side. |
Yes |
report_start_time_utc |
01/04/20 00:00 |
The usage period start date and time. |
Yes |
report_end_time_utc |
01/05/20 00:00 |
The usage period end date and time. |
Yes |
usage_schema |
CR |
Defines one of the billing modes (TR, CR, PR, or QT). |
Yes |
marketplace_account_id |
10000012 |
Applicable only to the CR schema. It defines the marketplace owner (typically, the provider or L1 reseller) ID assigned in the platform. |
Yes |
currency |
USD |
Applicable to AR, CR, and PR schemas. |
Yes |
product_id |
PRD-12345-67890 |
The product ID on the vendor side. |
Yes |
product_name |
Cloud Puzzles |
The product name. |
Yes |
marketplace_id |
MKT-1234-1234 |
The marketplace ID on the vendor side. A marketplace is a logical unit containing several hubs. |
No |
marketplace_name |
United States |
The marketplace name on the vendor side. |
No |
hub_id |
HB-1234-1234 |
The hub ID on the vendor side. A hub is a specific installation of the commerce platform belonging to the provider. |
No |
hub_name |
European Production |
The name of the hub on the vendor side. |
No |
vendor_account_id |
VA-1234-1234 |
The vendor ID that is typically assigned by an intermediate B2B matching platform. |
No |
vendor_account_name |
Puzzles and Games for Business |
The vendor name. |
No |
provider_account_id |
PA-1234-1234 |
The provider ID that is typically assigned by an intermediate B2B matching platform. |
No |
provider_account_name |
Fun for Business Provider |
The provider name on the vendor side. |
No |
distribution_contract_id |
CRD-12345-12345 |
The ID of the distribution contract signed by the provider and vendor. This is typically assigned by an intermediate B2B matching platform. |
No |
An imported XLS file must contain the records
tab with a table that consists of charges with the following
attributes (columns):
Attribute ID |
Example |
Description |
Required |
---|---|---|---|
record_id |
f2b0b523-38ae-4653-b870-48b3cddcd38d |
A globally unique record ID that comes from the vendor side. |
Yes |
report_note |
Please process before May 15th. |
An optional note that is associated with the charge record. |
No |
start_time_utc |
01/04/20 00:00 |
The timestamp in UTC 0 that represents the beginning of the time period for the usage file. |
Yes |
end_time_utc |
01/05/20 00:00 |
timestamp in UTC 0 that represents the end of the time period for the usage file. |
Yes |
item_name |
Migration Tool |
A descriptive name of a resource (product item) defined by the vendor. |
Yes |
item_id |
PRD-111-222-333-444 |
A globally unique product item ID assigned on the vendor side. |
Yes |
item_mpn |
Migration-001-001 |
The product item MPN assigned on the vendor side. It is unique within a given product and can be changed by the vendor during the product lifetime. |
Yes |
item_unit |
item |
A unit of measure for the product item. |
Yes |
asset_external_id |
1000044 |
The asset ID that is the respective subscription ID assigned in the commerce platform. |
Yes |
asset_external_uid |
df0d6f14-22a9-11ea-9fdf-2b0b8bc501b3 |
The asset unique ID that is the APS ID assigned to the respective resource in the commerce platform. |
Yes |
asset_recon_id |
ABC123 |
A primary reconciliation ID assigned on the vendor side. |
No |
quantity |
4 |
A quantity of the resource usage. |
Yes |
amount |
15.8 |
Total monetary amount in the currency specified in the |
Yes for TR, CR, and PR |
tier |
0 |
A tier that the charge is generated for. |
Yes for TR |
The tier
and amount
parameters can be ignored depending on the product usage schema:
Schema |
Tier |
Amount |
---|---|---|
TR |
A separate row for every tier; see the example for the TR schema below |
A different value for every tier |
CR |
Ignored |
The provider’s cost |
PR |
Ignored |
The price that the customer pays for the resource (the customer’s cost) |
QT |
Ignored |
Ignored |
To upload resource usage data from the resource-usage.xlsx
file to the platform, run the following command:
curl -F ‘data=@path/to/local/file’ https://{brand-endpoint}/aps/2/{aps-id}/usageReports
If a product supports the TR schema, the resource usage table contains several rows for every resource differentiated by tiers. For simplicity, the following example has only a few columns:
asset_external_id |
asset_external_uid |
quantity |
asset_recon_id |
amount |
tier |
---|---|---|---|---|---|
10000012 |
df0d6f14-22a9-11ea-9fdf-2b0b8bc501b3 |
15,75 |
ABC123 |
70 |
0 |
10000012 |
df0d6f14-22a9-11ea-9fdf-2b0b8bc501b3 |
15,75 |
ABC123 |
60 |
1 |
10000012 |
df0d6f14-22a9-11ea-9fdf-2b0b8bc501b3 |
15,75 |
ABC123 |
50 |
2 |