All of the data elements and actions related to the usage management module are available through the API that could be used interchangeably with the manual usage reporting through the User interface.
This procedure will require interaction with following APIs:
# | API Method Name |
1 | Get Listings – GET /listings |
2 | Get Listing Details – GET /listings/{id} |
3 | Get Usage Files – GET /usage/files |
4 | Create Usage File – POST /usage/files |
5 | Get usage File – GET /usage/files/{id} |
6 | Upload usage file records – POST /usage/files/{id}/upload |
7 | Change usage file status – POST /usage/files/{id}/{status} |
Note that all of the API calls described in this article follow common Data Format Conventions.
Vendor is free to upload usage files as often as it is required, any way is recommended to:
Resource | /listings/{id} |
Method | GET |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Filter(s) | – |
Default Filter(s) | – |
Ordering | – |
Default Ordering | – |
Limit | – |
Default limit | – |
Response BodyHTML
Content-Type: application/json<span class="fr-marker" data-id="0" data-type="false" style="display: none; line-height: 0;"></span><span class="fr-marker" data-id="0" data-type="true" style="display: none; line-height: 0;"></span>
[ listing_obj1,
listing_obj1,
listing_obj1
]
Resource | /listings |
Method | GET |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Filter(s) | status, contract, product, created_date |
Default Filter(s) | – |
Ordering | – |
Default Ordering | – |
Limit | – |
Default limit | 1000 |
Response Body
Content-Type: application/json
{
"id": "LST-066-644-910",
"status": "listed",
"contract": {
"id": "CRD-99082-45842-69180",
"type": "distribution",
"name": "Contract of IMC Demos Spain Distribution Agreement",
"marketplace": {
"id": "MP-91673",
"name": "IMC demos Marketplace",
"icon": "/media/PA-425-033/marketplaces/MP-91673/icon.jpg"
}
},
"product": {
"id": "CN-276-025-466",
"name": "release14Test"
},
"created": "2018-12-26T09:58:09+00:00",
"vendor": {
"id": "VA-004-290",
"name": "Marc's Staging Vendor"
},
"provider": {
"id": "PA-425-033",
"name": "IMCDemos Testing Account"
}
}
NOTE: Is only possible to report usage for products in status listed
Resource | /usage/files |
Method | GET |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Filter(s) | product_id, distribution_contract_id, status, created_at |
Default Filter(s) | – |
Ordering | Descending |
Default Ordering | created_at |
Limit | 1000 |
Default limit | – |
Response Body
Content-Type: application/json
[
usage_file_object1,
usage_file_object2,
usage_file_object3
]
Resource | /usage/files |
Method | POST |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Filter(s) | – |
Default Filter(s) | – |
Ordering | – |
Default Ordering | – |
Limit | – |
Default limit | – |
Request Body example
{
"name": "January 2019 usage",
"note": "",
"product": {
"id": "PRD-670-247-426"
},
"contract": {
"id": "CRD-00000-00000-00000"
}
}
Response body:
Content-Type: application/json
{
"id": "UF-2019-06-2923-9341",
"name": "January 2019 usage",
"note": "",
"status": "draft",
"created_by": "SU-164-531-341",
"created_at": "2019-06-05T14:09:19Z",
"records": {
"valid": 0,
"invalid": 0,
"closed": 0
},
"vendor": {
"id": "VA-004-290",
"name": "Acme Vendor"
},
"provider": {
"id": "PA-323-693",
"name": "ACME Provider"
},
"environment": "test",
"product": {
"id": "PRD-670-247-426",
"name": "Usage Product"
},
"contract": {
"id": "CRD-00000-00000-00000",
"name": "ACME Distribution Contract"
},
"marketplace": {
"id": "MP-00000",
"name": "ACME Marketplace"
}
}
Resource | /usage/files({id} |
Method | GET |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Filter(s) | – |
Default Filter(s) | – |
Ordering | – |
Default Ordering | – |
Limit | – |
Default limit | – |
Response body:
Content-Type: application/json
{
"id": "UF-2019-06-2923-9341",
"name": "January 2019 usage",
"note": "",
"status": "draft",
"created_by": "SU-164-531-341",
"created_at": "2019-06-05T14:09:19Z",
"records": {
"valid": 0,
"invalid": 0,
"closed": 0
},
"vendor": {
"id": "VA-004-290",
"name": "Acme Vendor"
},
"provider": {
"id": "PA-323-693",
"name": "ACME Provider"
},
"environment": "test",
"product": {
"id": "PRD-670-247-426",
"name": "Usage Product"
},
"contract": {
"id": "CRD-00000-00000-00000",
"name": "ACME Distribution Contract"
},
"marketplace": {
"id": "MP-00000",
"name": "ACME Marketplace"
}
}
Usage file must be prepared according to the template in XLSX format. Please check the usage reporting article to get more information about the file structure.
Resource | /usage/files({id}/upload |
Method | POST |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Request Content Type | multipart/form-data |
Response will return code 201 if success
Resource | /usage/files/{id}/{status} |
Method | POST |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Filter(s) | – |
Default Filter(s) | – |
Ordering | – |
Default Ordering | – |
Limit | – |
Default limit | – |
Resource | /usage/files/{id}/submit |
Method | POST |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Actor | Vendor |
Request Body
Content-Type: application-json
{}
Response Body
Content-type: application/json
{
id: 'UF-2018-11-9878764342',
name: 'Usage for Feb 2019',
description: 'This file contains usage for the product belonging to month Feb 2019',
note: 'My personal note',
status:'pending',
created_by: 'admin@vendor.com',
created_at: '2018-11-21T11:10:29+00:00',
product: {
id: 'CN-783-317-575',
name: 'Google Apps'
},
contract: {
id: 'CRD-00000-00000-00000',
name: 'ACME Distribution Contract'
},
marketplace: {
id: 'MP-198987',
name: 'France',
icon: '/media/PA-123-123/marketplaces/MP-12345/image.png'
},
upload_file_uri: '<File Location for uploaded file>',
processed_file_uri: '<File Location for generated file>',
records: {
valid: 56,
invalid: 0
},
uploaded_by: 'admin@vendor.com',
uploaded_at: '2019-01-21T11:10:29+00:00',
submitted_by: 'admin@vendor.com',
submitted_at: '2018-01-21T11:10:29+00:00'
}
Resource | /usage/files/{id}/accept |
Method | POST |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Actor | Provider |
Request Body
Content-Type: application-json
{
acceptance_note: 'All usage data is correct'
}
Response Body
{
id: 'UF-2018-11-9878764342',
name: 'Usage for Feb 2019',
description: 'This file contains usage for the product belonging to month Feb 2019',
status:'accepted',
product: {
id: 'CN-783-317-575',
name: 'Google Apps'
},
contract: {
id: 'CRD-00000-00000-00000',
name: 'ACME Distribution Contract'
},
marketplace: {
id: 'MP-198987',
name: 'France',
icon: '/media/PA-123-123/marketplaces/MP-12345/image.png'
},
processed_file_uri: '<File Location for generated file>',
acceptance_note: 'All usage data is correct',
records: {
valid: 56,
invalid: 0
},
accepted_by: 'admin@provider.com',
accepted_at: '2018-11-21T11:10:29+00:00'
}
Resource | /usage/files/{id}/reject |
Method | POST |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Actor | Provider |
Request Body
Content-Type: application-json
{
"rejection_note": "Rejected due to wrong usage for item 56"
}
Response Body
{
id: 'UF-2018-11-9878764342',
name: 'Usage for Feb 2019',
description: 'This file contains usage for the product belonging to month Feb 2019',
status:'rejected',
product: {
id: 'CN-783-317-575',
name: 'Google Apps'
},
contract: {
id: 'CRD-00000-00000-00000',
name: 'ACME Distribution Contract'
},
marketplace: {
id: 'MP-198987',
name: 'France',
icon: '/media/PA-123-123/marketplaces/MP-12345/image.png'
},
processed_file_uri: '<File Location for generated file>',
rejection_note: 'Rejected due to wrong usage for item 56',
records: {
valid: 56,
invalid: 0
},
rejected_by: 'admin@provider.com',
rejected_at: '2018-11-21T11:10:29+00:00'
}
Resource | /usage/files/{id}/close |
Method | POST |
Header | Authorization: ApiKey <key_id>:<key_secret> |
Actor | Provider |
Request Body
Content-Type: application-json
{}
Response Body
{
id: 'UF-2018-11-9878764342',
name: 'Usage for Feb 2019',
description: 'This file contains usage for the product belonging to month Feb 2019',
status:'closed',
product: {
id: 'CN-783-317-575',
name: 'Google Apps'
},
contract: {
id: 'CRD-00000-00000-00000',
name: 'ACME Distribution Contract'
},
marketplace: {
id: 'MP-198987',
name: 'France',
icon: '/media/PA-123-123/marketplaces/MP-12345/image.png'
},
processed_file_uri: '<File Location for generated file>',
acceptance_note: 'All usage data is correct',
records: {
valid: 56,
invalid: 0
},
accepted_by: 'admin@provider.com',
accepted_at: '2018-11-21T11:10:29+00:00',
closed_by: 'admin@provider.com',
closed_at: '2018-11-21T11:10:29+00:00'
}
Supported (valid) transitions: