Get Data Reports

To assist resellers in analyzing their commercial activities, there is a Reporting and Data Export (RDE) service that, once installed on the platform, allows resellers to generate and download rated data reports about the accounts and related commercial resources (customers, subscriptions, invoices, and other) that changed during a specified period.

The platform RDE service exposes its resources on the /reports endpoint.

Report Configuration

Using the UX1 panel, a reseller can create any number of RDE generators:

Each generator exports reports periodically (once per day or month) or on the invoice creation event. A reseller can also export a report at any time manually. A report structure is defined by one of the data sets, either Provisioned Orders or Payments.

On the final step of the report generator configuration, the Report View field enables the reseller to select the schema customized for Marketplace API. The latter is a simplified version of the full report view with the report parameter names matching the properties used in Marketplace API requests and responses. The report representation format can be JSON, XML, CSV, or XSLX.

Note

We highly recommend that you select the schema customized for the Marketplace API in the Report View field. The Report Details section represents all parameters in customized reports.

The generated reports are uploaded to an Azure cloud repository owned by the provider. An exported report is stored there for 90 days.

Requesting Report Collection

The API client can send a request for a set of rated data reports generated during a specified period. For this, a request contains the following query parameters:

from: the first day of the requested period in ISO 8601 format.
to: the last day of the requested period in ISO 8601 format.
format (optional): requests the reports of the specified format only. The formats supported by RDE are: json, xml, csv, and xslx.

Note

The pagination query parameters

offset and limit are not parsed on this endpoint as mentioned above from, to, and format query parameters define the limitation for the response.

In a response, offset is always zero and limit equals total.

Get All Reports

Use a request without the format query parameter to receive the URLs of all reports for a specified period:

GET /reports?from=2019-11-05&to=2019-12-03 HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16

JSON

If successful, the response looks like this (the URLs are cut for brevity):

HTTP/1.1 200 OK

{
  "data": [
    {
      "name": "withres2",
      "format": "XLSX",
      "creationDate": "2019-11-12T09:51:14Z",
      "downloadUrl": "https://drrde3.blob.core.windows.net/rdecontainer/withres2.0fb84e60...-0f2cd36236ce.2019-11-12.10-51-15.216+0100.xlsx?sig=rb8TTt...iUY%3D&api-version=2016-05-31&st=2019-11-12T09%3A...%3A15Z&sv=2016-05-31&sp=rwd&sr=b"
    },
    {
      "name": "daily-dr1",
      "format": "JSON",
      "creationDate": "2019-11-14T20:57:29Z",
      "downloadUrl": "https://drrde3.blob.core.windows.net/rdecontainer/daily-dr1.1124976b...-ce8560b8626b.2019-11-14.21-57-30.014+0100.json.gz?sig=Ub2%2FU...%3D&api-version=2016-05-31&st=2019-11-14T20%3A47%3A...%3A30Z&sv=2016-05-31&sp=rwd&sr=b"
    },
    {
      "name": "report",
      "format": "XLSX",
      "creationDate": "2019-11-05T12:15:18Z",
      "downloadUrl": "https://drrde3.blob.core.windows.net/rdecontainer/report.12e9a7a4...-5d6515120ae1.2019-11-05.13-15-19.254+0100.xlsx?sig=bLUSOw%2BaSP...%3D&api-version=2016-05-31&st=2019-11-05T12%3A05%3A...%3A19Z&sv=2016-05-31&sp=rwd&sr=b"
    },
    {
      "name": "dr-rep2",
      "format": "XLSX",
      "creationDate": "2019-11-05T12:59:32Z",
      "downloadUrl": "https://drrde3.blob.core.windows.net/rdecontainer/dr-rep2.1c65e292...-a3d0a48c39b4.2019-11-05.13-59-32.900+0100.xlsx?sig=pJJRiB6Afp...%3D&api-version=2016-05-31&st=2019-11-05T12%3A49%3A...%3A33Z&sv=2016-05-31&sp=rwd&sr=b"
    },
    {
      "name": "dr-rep1",
      "format": "XLSX",
      "creationDate": "2019-11-05T12:59:13Z",
      "downloadUrl": "https://drrde3.blob.core.windows.net/rdecontainer/dr-rep1.39512e47...-be6c0b6d6bc9.2019-11-05.13-59-13.398+0100.xlsx?sig=CLah1V6%2B...%3D&api-version=2016-05-31&st=2019-11-05T12%3A49%3A...%3A13Z&sv=2016-05-31&sp=rwd&sr=b"
    },
    {
      "name": "sample1",
      "format": "JSON",
      "creationDate": "2019-11-19T15:46:46Z",
      "downloadUrl": "https://drrde3.blob.core.windows.net/rdecontainer/sample1.f162d420...-b261564255a4.2019-11-19.16-46-46.616+0100.json.gz?sig=UhvFMT...%3D&api-version=2016-05-31&st=2019-11-19T15%3A36%3A...%3A46Z&sv=2016-05-31&sp=rwd&sr=b"
    },
    {
      "name": "daily-dr1",
      "format": "JSON",
      "creationDate": "2019-11-22T20:57:43Z",
      "downloadUrl": "https://drrde3.blob.core.windows.net/rdecontainer/daily-dr1.fb548...-0bda2d322d76.2019-11-22.21-57-43.445+0100.json.gz?sig=FsjOYz...3D&api-version=2016-05-31&st=2019-11-22T20%3A47%3A...%3A43Z&sv=2016-05-31&sp=rwd&sr=b"
    },
    {
      /* Other reports */
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 28,
    "total": 28
  }
}

JSON

Get Reports in a Certain Format

Use a request with the format query property to select all reports of the specified format, for example, JSON:

GET /reports?from=2019-11-05&to=2019-12-03&format=json HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16

JSON

If successful, the response looks like this (the URLs are cut for brevity):

HTTP/1.1 200 OK

{
  "data": [
    {
      "name": "daily-dr1",
      "format": "JSON",
      "creationDate": "2019-11-14T20:57:29Z",
      "downloadUrl": "https://drrde3.blob.core.windows.net/rdecontainer/daily-dr1.1124976b...-ce8560b8626b.2019-11-14.21-57-30.014+0100.json.gz?sig=Ub2%2FU...%3D&api-version=2016-05-31&st=2019-11-14T20%3A47%3A...%3A30Z&sv=2016-05-31&sp=rwd&sr=b"
    },
    {
      "name": "sample1",
      "format": "JSON",
      "creationDate": "2019-11-19T15:46:46Z",
      "downloadUrl": "https://drrde3.blob.core.windows.net/rdecontainer/sample1.f162d420...-b261564255a4.2019-11-19.16-46-46.616+0100.json.gz?sig=UhvFMT...%3D&api-version=2016-05-31&st=2019-11-19T15%3A36%3A...%3A46Z&sv=2016-05-31&sp=rwd&sr=b"
    },
    {
      "name": "daily-dr1",
      "format": "JSON",
      "creationDate": "2019-11-22T20:57:43Z",
      "downloadUrl": "https://drrde3.blob.core.windows.net/rdecontainer/daily-dr1.fb548...-0bda2d322d76.2019-11-22.21-57-43.445+0100.json.gz?sig=FsjOYz...3D&api-version=2016-05-31&st=2019-11-22T20%3A47%3A...%3A43Z&sv=2016-05-31&sp=rwd&sr=b"
    },
    {
      /* Other reports */
    }
  ],
  "pagination": {
    "offset": 0,
    "limit": 17,
    "total": 17
  }
}

JSON

Schedule Generation of a One-Time Report

You can also schedule the generation of a report for the specified dates using a request similar to this:

GET /reports?from=2019-11-05&to=2019-12-03&format=json HTTP/1.1
Authorization: Bearer eyJwcm...0fQtrLk4RToj51HAmsRXO78
X-Subscription-Key: 066a6b...33b16

          {
            "name": "Daily report",
            "customizationName": "string",
            "format": "json",
            "startDate": "2019-11-07T17:02:59.000Z",
            "endDate": "2019-12-07T17:02:59.000Z",
            "downloadUrl": "https://report-storage1.blob.core.windows.net/rdecontainer/Customer1.e1...12d.2019-11-21.14-02-20.551+0100.json?sig=4JbyvWJAUwwN7R...3D&api-version=2016-05-31&st=2019-11-21T12%3A52%&se=202...0-02-19T12=2016-05-31&sp=rwd&sr=b"
          }

JSON

If successful, the response looks like this (the URLs are cut for brevity):

HTTP/1.1 200 OK

          {
            "id": "f40c942d-ebec-41b9-b604-5ed9ffb6d4f2",
            "name": "Daily report",
            "customizationName": "string",
            "status": "completed",
            "type": "onetime",
            "format": "json",
            "creationDate": "2020-11-07T17:02:59.000Z",
            "startDate": "2019-11-07T17:02:59.000Z",
            "endDate": "2019-12-07T17:02:59.000Z",
            "downloadUrl": "https://report-storage1.blob.core.windows.net/rdecontainer/Customer1.e1...12d.2019-11-21.14-02-20.551+0100.json?sig=4JbyvWJAUwwN7R...3D&api-version=2016-05-31&st=2019-11-21T12%3A52%&se=202...0-02-19T12=2016-05-31&sp=rwd&sr=b"
          }

JSON

Report Details

As introduced in Report Configuration, a report is based on the Provisioned Orders or Payments data set that can be customized for Marketplace API. The following sections display the full set of parameters in customized reports.

Provisioned Orders

A report based on the customized Provisioned Orders data set contains the following parameters:

Group	Field	Description	Example
Customer	`customerId`	The customer ID	1000008012
	`customerName`	The customer’s name (company’s name or personal name).	Business Toy Sample, inc. John Smith
	`customerCurrency`	The customer’s currency, in which all monetary values are denominated.	USD
	`billingContactPersonName`	The name of the billing contact person.	John Smith
	`billingContactPersonMail`	The email address of the billing contact.	`John.Smith@example.com`
	`billingContactPersonPhone`	The phone number of the billing contact.	+1 (417) 7122740
	`adminContactPersonName`	The name of the administrative contact person.	John Smith
	`adminContactPersonMail`	The email address of the administrative contact.	`John.Smith@example.com`
	`adminContactPersonPhone`	The phone number of the administrative contact.	+1 (417) 7122740
	`techContactPersonName`	The name of the technical contact person.	John Smith
	`techContactPersonMail`	The email address of the technical contact.	`John.Smith@example.com`
	`techContactPersonPhone`	The phone number of the technical contact.	+1 (417) 7122740
Subscribed Product	`productOfferID`	The offer ID.	79
	`productID`	The product ID.	100034
	`productName`	The product name in the multilingual format.	Skype for Business PSTN Conferencing
Order	`orderID`	The ID assigned to the order by the platform.	1000012
	`orderNumber`	The number assigned to the order by the platform according the reseller specific order numbering rule.	SO000521
	`orderDate`	The order creation date.	2018-11-28
	`orderTotal`	The order’s total denominated in the customer’s currency.	22.50000000
	`orderAttributes`	A list of the order’s custom attributes, including PONumber.	[[“PONumber”,”qwe1233”]]
Subscription	`subscriptionID`	The subscription ID.	1036066
	`subscriptionStatus`	The subscription status, which can be `active`, `hold`, `terminated`, or `removed`.	Active
	`subscriptionStartDate`	The subscription provisioning date.	2018-11-28
	`subscriptionEndDate`	The date when the subscription expires and becomes `graced`, `hold`, or `terminated` according the service terms configuration. If the subscription is canceled before the expiration date, this field contains the cancellation date.	2018-11-28
	`subscriptionBillingPeriodUnit`	The unit of length of the subscription billing period.	MONTHS
	`subscriptionBillingPeriod`	The duration of the subscription’s billing period as a number of the billing period units.	1

Payments

A report based on the customized Payments data set contains the following parameters:

Group	Field	Description	Example
Payment	`paymentDocumentNumber`	The number assigned to the payment document in the platform.	0000001
	`paymentCreationDate`	The payment creation date (midnight in the UTC timezone) in the Unix timestamp format.	1567112400
	`paymentDocumentType`	The document type, for example: Payment, Check, or Void.	Payment
	`paymentStatus`	The payment status, for example: Hold, Open, or Closed.	Closed
	`paymentTotal`	The payment total.	5.48000000
	`paymentCurrency`	The payment’s currency code.	AUD
	`paymentReferenceNumber`	The reference number of the last online transaction performed to process an online payment.	2084580
	`paymentAuthCode`	The authentication code of the respective transaction for this payment.	1567112400
Customer	`customerId`	The customer ID	1000008012
	`customerName`	The customer’s name (company’s name or personal full name).	Business Toy Sample, inc. John Smith
	`customerCurrency`	The customer’s currency, in which all monetary values are denominated.	USD
	`billingContactPersonName`	The name of the billing contact person.	John Smith
	`billingContactPersonMail`	The email address of the billing contact.	`John.Smith@example.com`
	`billingContactPersonPhone`	The phone number of the billing contact.	+1 (417) 7122740
	`adminContactPersonName`	The name of the administrative contact person.	John Smith
	`adminContactPersonMail`	The email address of the administrative contact.	`John.Smith@example.com`
	`adminContactPersonPhone`	The phone number of the administrative contact.	+1 (417) 7122740
	`techContactPersonName`	The name of the technical contact person.	John Smith
	`techContactPersonMail`	The email address of the technical contact.	`John.Smith@example.com`
	`techContactPersonPhone`	The phone number of the technical contact.	+1 (417) 7122740

Conclusion

This step completes the typical sales workflow. In the past steps, you learned how to use the Marketplace API to manage your customers, observe and select the required offers and products provided by them, order those products for your customers, manage the created subscriptions, and collect the rated data reports.

To understand how to sell common services in more detail, follow the Sales Scenarios.