The common task for distributor or reseller automation is to automate billing. Manual processing requires a lot of time and might be affected by human errors hard to locate. It's why billing automation is one of the most requested integrations for any partner.
Before the C21.11 release of Acronis Cyber Cloud, it was possible but resources consuming to have an automated billing integration. We are continuously evolving our API so we are proud to present an additional option for usages reports creating API which requires us to spend months of development and planning behind to simplify our partner's daily tasks.
Create Usages Reports with SKU Included
The usages reports are designed specifically to provide correct Acronis Cyber Cloud usages information updated on daily basis (UTC midnight). Similar reports are used by the Acronis operations team to generate billing reports for partners.
All operations with the reports in the cloud platform are located under the /reports endpoint. Reports allow you to have detailed statistics of your usage of Acronis Cyber Cloud services.
POST /api/2/reportsThe reports use binary gigabytes (GB), which are 1024^3 bytes, or gibibytes (GiB) as of measurement units for storage space.
Two result action types of reports can be created from API: save and send. The send type report is not usable for automation as it is designed to send human-readable reports formats: CSV and HTML. Thus for automation cases save action results should be used. When a developer called for a save action result report, a stored report is created. Information about created stored reports can be retrieved, and that reports can be downloaded through API.
"result_action": "save"Most useful for billing automation are csv_v2_0 and json_v2_0 reports formats. They are equal, just represent the same information in different formats.
"formats": [
"csv_v2_0"
]Normally, usages reports for billing purposes are called in the first days of the next month of a billing month. Thus, to specify the last month first and last days as a period for that report, a usage_summary kind of reports should be used.
"period": {
"start": "2021-08-01",
"end": "2021-08-31"
}
Finally, the reporting hierarchy should be specified. tenant_id -- a UUID identifier for the root tenant from which the report starts and level of hierarchy. For most cases, you need only direct partners children of your root accounts, so the level is direct_partners.
"kind": "usage_summary",
"level": "direct_partners",
"tenant_id": "{root_report_hierarchy_tenant_uuid}"Finally, to create a report, ready for billing automation, a new parameter should be added show_skus parameter set to true. It may include SKUs in reports. Not all partners can access that functionality.
"show_skus": trueThe final JSON for the POST /reports call should look like below:
{
"parameters": {
"kind": "usage_summary",
"level": "direct_partners",
"tenant_id": "{root_report_hierarchy_tenant_uuid}",
"formats": [
"csv_v2_0"
],
"show_skus": true,
"hide_zero_usage": true,
"period": {
"start": "2021-08-01",
"end": "2021-08-31"
}
},
"schedule": {
"type": "once"
},
"result_action": "save"
}
The successful result of such a call will be near the same JSON, but with id -- report UUID which is needed to find and download created report.
{
"id": "865b114a-bca6-43db-a058-5d0446eb1c0d",
"version": 1,
"recipients": [],
"result_action": "save",
"schedule": {
"enabled": true,
"type": "once"
},
"parameters": {
"formats": [
"csv_v2_0"
],
"level": "direct_partners",
"kind": "usage_summary",
"tenant_id": "531789f2-2be9-42af-8474-18177593c77b",
"show_skus": true,
"period": {
"end": "2021-10-24",
"start": "2021-10-01"
"generation_date": "2021-10-25",
}
}
}Locate and Download Stored Reports
When a usages report is created, a request is sent to the cloud to create that report. It means that in the real world that created usage report won't be available for download immediately. In most cases, 60-90 seconds is enough for any report generation. However, during the first days of a month, as many requests including internal billing is processed, and for code sustainability, we would recommend implementing a pull API code with a check that a generated report is available for download.
To retrieve information regarding sored reports the following API call can be used:
GET /api/2/reports/{report_id}/storedwhere report_id is id in a report creation response.
There are 3 possible responses for that call. If a report is ready:
{
"items": [
{
"id": "cc593092-8820-45f4-a347-35e0979a5bd6",
"report_format": "csv_v2_0",
"created_at": "2020-02-04T10:37:53+00:00",
"size": 2467,
"status": "saved"
}
]
}
and if it's in progress
{
"items": [
{
"report_format": "csv_v2_0",
"created_at": "2020-02-04T10:37:53+00:00",
"status": "in_progress"
}
]
}
and if it's failed
{
"items": [
{
"report_format": "csv_v2_0",
"created_at": "2020-02-04T10:37:53+00:00",
"status": "faild"
}
]
}Please note, that for each format you specify in a report creation JSON you will receive an additional array item as a result of the stored report call
{
"items": [
{
"id": "cc593092-8820-45f4-a347-35e0979a5bd6",
"report_format": "csv_v2_0",
"created_at": "2020-02-04T10:37:53+00:00",
"size": 2467,
"status": "saved"
},
{
"id": "21869a3b-c0fb-4c4f-8af0-3714d75410ed",
"report_format": "json_v2_0",
"created_at": "2020-02-04T10:37:53+00:00",
"size": 2467,
"status": "saved"
}
]
}When you know a report id and a stored report id for that report, it's quite simple to download it.
GET /api/2/reports/{report_id}/stored/{stored_report_id}where report_id is the report id of the created report and stored_report_id is the id of the stored report with the selected format.
The result is a gzipped octet-stream, so you need to use the corresponding tooling to receive the final un-gzipped report file.
csv_v2_0 Usages Report with SKU example imported to Excel (some columns and rows are hidden)
csv_v2_0 Usages Report with SKU example imported to Excel (some columns and rows are hidden)
So now you have ready for billing automation usages report with SKU. You only need to remove non-SKU rows as well as rows with zero usage, add SKU's names and your prices for that SKUs.
As well, you can use hide_zero_usage reports creation parameter set to true, to exclude SKUs with zero usage.
Summary
Now you know how to implement billing automation for the Acronis Cyber Cloud with usages reports.
For further API learning, register at our Platform Program or Developer Network on https://developer.acronis.com site.
Find our public Postman API collection for standard automation and integration tasks https://explore.postman.com/grey-rocket-585331 or use our GitHub examples https://github.com/acronis.
About Acronis
Acronis is a Swiss company, founded in Singapore. Celebrating two decades of innovation, Acronis has more than 1,800 employees in 45 locations. The Acronis Cyber Protect Cloud solution is available in 26 languages in over 150 countries and is used by 20,000 service providers to protect over 750,000 businesses.
