1. Overview

Usage Consumption TMF Webservices Documentation

1.1. URI scheme

Host : hostname
BasePath : /usageconsumptiontmfwebservices/v2

1.2. Tags

  • Query Usage Consumption : Uc Query Usage Consumption Controller

  • Usage Consumption Report : Uc Usage Consumption Report Controller

1.3. Produces

  • application/json

2. Security

2.1. oauth2_password

Type : oauth2
Flow : password
Token URL : https://localhost:9002/authorizationserver/oauth/token

Name

basic

2.2. oauth2_client_credentials

Type : oauth2
Flow : application
Token URL : https://localhost:9002/authorizationserver/oauth/token

Name

extended

3. Resources

3.1. Query Usage Consumption

Uc Query Usage Consumption Controller

3.1.1. Creates a QueryUsageConsumption

POST /queryUsageConsumption
Description

This operation creates a query usage consumption entity.

Parameters
Type Name Description Schema

Body

queryUsageConsumption
required

The query usage consumption to be created

TuaQueryUsageConsumption
Responses
HTTP Code Description Schema

200

Success

TuaQueryUsageConsumption

201

Created

No Content

400

Bad Request

Error

401

Unauthorized

Error

403

Forbidden

Error

404

Not Found

No Content

405

Method Not allowed

Error

409

Conflict

Error

500

Internal Server Error

Error
Consumes

  • application/json;charset=utf-8

Produces

  • application/json;charset=utf-8

Security
Type Name

oauth2

oauth2_client_credentials

oauth2

oauth2_password

3.2. Usage Consumption Report

Uc Usage Consumption Report Controller

3.2.1. List or find UsageConsumptionReport objects

GET /usageConsumptionReport
Description

This operation list or find UsageConsumptionReport entities

Parameters
Type Name Description Schema

Query

fields
optional

Comma-separated properties to be provided in response

string

Query

limit
optional

Requested number of resources to be provided in response

integer(int32)

Query

offset
optional

Requested index for start of resources to be provided in response

integer(int32)

Query

product.id
optional

Network product id value

string

Query

publicIdentifier
optional

Public identifier value

string

Query

relatedParty.id
optional

Related party id value

string
Responses
HTTP Code Description Schema

200

Success

< UsageConsumptionReport > array

206

Partial Content

< UsageConsumptionReport > array

400

Bad Request

Error

401

Unauthorized

Error

403

Forbidden

Error

404

Not Found

Error

405

Method Not allowed

Error

409

Conflict

Error

500

Internal Server Error

Error
Produces

  • application/json;charset=utf-8

Security
Type Name

oauth2

oauth2_client_credentials

oauth2

oauth2_password

4. Definitions

4.1. BucketRefOrValue

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

bucketCounter
optional

< ConsumptionSummary > array

bucketRelationship
optional

< BucketRelationship > array

description
optional

Bucket name

string

href
optional

Hyperlink reference of the bucket

string

id
optional

Unique identifier of the bucket

string

isShared
optional

True if the bucket is shared between several devices or users

boolean

logicalResource
optional

< UsageConsumptionLogicalResourceRef > array

name
optional

Bucket name

string

partyAccount
optional

< PartyAccountRef > array

product
optional

< UsageConsumptionProductRef > array

relatedParty
optional

< RelatedParty > array

remainingValue
optional

Numeric remaining value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example

Quantity

remainingValueName
optional

Remaining value in a formatted string for the bucket given in the balance unit (for example 1.9 Gb). This formatted string could be used for display needs for example

string

reserveBalance
optional

The ReserveBalance resource allows adjustments to be made to the original BalanceTopup eg increment the amount, alter the recharge periodicity.

ReserveBalanceRef

reservedValue
optional

Indicate the amount on the bucket.

Quantity

service
optional

Service reference, for when Service is used by other entities.

< UsageConsumptionServiceRef > array

status
optional

status for the bucket. active, expired, suspended.

string

usageType
optional

defines the type of the underlying Balance eg data,voice, any currency eg EUR, USD etc.

string

validPeriod
optional

Remaining value in a formatted string for the bucket given in the balance unit (for example 1.9 Gb). This formatted string could be used for display needs for example

TimePeriod

4.2. BucketRelationship

Linked bucket to the one instantiate, such as [isAggregated] if the bucket is a part of other or [aggregator] is the bucket holds others .

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@referredType
optional

The actual type of the target instance when needed for disambiguation.

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

bucketRefOrValue
optional

< BucketRefOrValue > array

relationshipType
optional

Type of the bucket relationship, such as [isAggregated] if the bucket is a part of other or [aggregator] is the bucket holds others.

string

4.3. ConsumptionSummary

The consumption counters (called ConsumptionSummary in the SID model) detail for example the different kind of consumption done on the bucket.

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

consumptionPeriod
optional

Consumption counter period between a start date time and an end date time. For prepaid bucket, the period of counters is between the start date of the bucket and the effective date of the usage consumption report generation. For postpaid bucket, the period of counters is between the last bill date and the effective date of the usage consumption report generation.

TimePeriod

counterType
optional

Type of the consumption counter. We can give for example a counter of the used value for a bucket (counterType=used for example) or the value of the consumption done out of the bucket(s) (counterType=outOfBucket for example)

string

level
optional

Counter level. The counter can be given globally for the bucket or detailed by user or by network product for example in case of shared bucket

string

product
optional

Public identifier associated to the product for which the consumption counter is detailed. If the level of the counter is global (i.e. concerning all the network products), the list of them is not specified. It can be found through the network products listed in the bucket sub-resource

NetworkProductRef

user
optional

Reference of the user for which the consumption counter is detailed. If the level of the counter is global (i.e. concerning all the users), the list of them is not specified. It can be found through the users listed in the network products of the bucket sub-resource

RelatedParty

value
optional

Numeric value of the bucket counter in a given unit

Quantity

valueName
optional

Value of the counter in a formatted string used for display needs for example

string

4.4. Error

Name Schema

cause
optional

Throwable

localizedMessage
optional

string

message
optional

string

stackTrace
optional

< StackTraceElement > array

suppressed
optional

< Throwable > array

4.5. NetworkProduct

An instantiated network product (specialization of a product) subscribed by a customer.

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

href
optional

Reference to the network product

string

id
optional

Unique identifier of the network product

string

name
optional

Network product name

string

outOfBucketCounter
optional

Counters detailing usage consumption out of the buckets

< ConsumptionSummary > array

publicIdentifier
optional

Public number associated to the network product (msisdn number for mobile line for example)

string

user
optional

References of the users of the network product

< RelatedParty > array

4.6. NetworkProductRef

Reference of a product

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@referredType
optional

Generic attribute indicating the name of the class type of the referred resource entity

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

href
required

Reference to the network product

string

id
required

Unique identifier of the network product

string

name
optional

Network product name

string

publicIdentifier
optional

Public number associated to the product (msisdn number for mobile line for example)

string

4.7. PartyAccountRef

PartyAccount reference. A party account is an arrangement that a party has with an enterprise that provides products to the party.

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@referredType
optional

The actual type of the target instance when needed for disambiguation.

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

description
optional

Detailed description of the party account.

string

href
optional

Reference of the party account.

string

id
optional

Unique identifier of a party account

string

name
optional

Name of the party account

string

status
optional

The condition of the account, such as due, paid, in arrears.

string

4.8. Quantity

An amount in a given unit

Name Description Schema

amount
optional

Numeric value in a given unit

number(float)

units
optional

Unit

string

4.9. RelatedParty

Related Entity reference. A related party defines party or party role linked to a specific entity.

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@referredType
optional

The actual type of the target instance when needed for disambiguation.

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

href
optional

Reference of the related entity.

string

id
required

Unique identifier of a related entity.

string

name
optional

Name of the related entity.

string

role
optional

Role played by the related party

string

4.10. ReserveBalanceRef

The ReserveBalance resource allows adjustments to be made to the original BalanceTopup eg increment the amount, alter the recharge periodicity.

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@referredType
optional

The actual type of the target instance when needed for disambiguation.

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

href
optional

Hyperlink reference of the related entity.

string

id
optional

Unique identifier of the related entity.

string

name
optional

Name of the related entity.

string

4.11. StackTraceElement

Name Schema

classLoaderName
optional

string

className
optional

string

fileName
optional

string

lineNumber
optional

integer(int32)

methodName
optional

string

moduleName
optional

string

moduleVersion
optional

string

nativeMethod
optional

boolean

4.12. Throwable

Name Schema

cause
optional

Throwable

localizedMessage
optional

string

message
optional

string

stackTrace
optional

< StackTraceElement > array

suppressed
optional

< Throwable > array

4.13. TimePeriod

A period of time, either as a deadline (endDateTime only) a startDateTime only, or both

Name Description Schema

endDateTime
optional

End of the time period, using IETC-RFC-3339 format

string(date-time)

startDateTime
optional

Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end

string(date-time)

4.14. TuaQueryUsageConsumption

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

href
optional

Hyperlink reference of the bucket.

string

id
optional

Unique identifier of the bucket.

string

partyAccount
optional

< PartyAccountRef > array

queryUsageConsumptionDate
optional

Date and time of the last update.

string(date-time)

relatedParty
optional

< RelatedParty > array

searchCriteria
optional

UsageConsumption

usageConsumption
optional

< UsageConsumption > array

4.15. UsageConsumption

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

bucketRefOrValue
optional

< BucketRefOrValue > array

creationDate
optional

Date and time of the request creation.

string(date-time)

description
optional

Description

string

href
optional

Hyperlink reference of the bucket.

string

id
optional

Unique identifier of the bucket.

string

lastUpdate
optional

Date and time of the last update.

string(date-time)

logicalResource
optional

< UsageConsumptionLogicalResourceRef > array

name
optional

Usage consumption name.

string

product
optional

< UsageConsumptionProductRef > array

relatedParty
optional

Reference and role of the related parties for which the usage consumption is requested.

< RelatedParty > array

service
optional

< UsageConsumptionServiceRef > array

state
optional

State of the report report defined in the state engine.

string

validPeriod
optional

Validity period.

TimePeriod

4.16. UsageConsumptionLogicalResourceRef

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

consumptionSummary
optional

< ConsumptionSummary > array

href
optional

Hyperlink reference of a Logical resource

string

id
optional

Unique identifier of a Logical resource

string

name
optional

Name of a Logical resource

string

4.17. UsageConsumptionProductRef

Reference to the product, e.g., 5GB Shared Data Package.

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@referredType
optional

The actual type of the target instance when needed for disambiguation.

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

consumptionSummary
optional

< ConsumptionSummary > array

href
optional

Hyperlink reference of the related entity.

string

id
optional

Unique identifier of the related entity.

string

name
optional

Name of the related entity.

string

4.18. UsageConsumptionReport

An usage consumption report enables to know at a given point the balances and the consumption counters related to various buckets (SMS, Voice, Data for example). It could be calculated for a device identified by a public key (msisdn number for a mobile device for example or PSTN or VOIP number for a fix device), for a subscribed offer or option or for an user.

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

bucket
optional

Bucket(s) included in the offer or option subscribed.

< UsageVolumeProduct > array

description
optional

Free short text describing the usage consumption report content

string

effectiveDate
optional

Date and time when the usage consumption report was calculated and generated

string(date-time)

href
optional

Hyperlink to access the usage consumption report. The report is calculated at the time of the request by the server. Generally, this report is not recorded by the server. If it is, an unique identifier of the usage consumption report is given by the server

string

id
optional

The report is calculated at the time of the request by the server. Generally, this report is not recorded by the server. If it is, an unique identifier of the usage consumption report is given by the server

string

name
optional

Usage consumption report name

string

relatedParty
optional

RelatedParty

4.19. UsageConsumptionServiceRef

Service reference, for when Service is used by other entities.

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@referredType
optional

The actual type of the target instance when needed for disambiguation.

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

consumptionSummary
optional

< ConsumptionSummary > array

href
optional

Hyperlink reference of the related entity.

string

id
optional

Unique identifier of the related entity.

string

name
optional

Name of the related entity.

string

4.20. UsageVolumeBalance

The balance (called UsageVolumeBalance in the SID model) defines the remaining allowed product usage quantity in terms of volume, time, currency or events. It corresponds to the initial allowed usage quantity minus the usage consumed on the bucket.

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

remainingValue
optional

Numeric remaining value for the bucket given in the unit (for example 1.9). This numeric value could be used for calculation for example

Quantity

remainingValueName
optional

Remaining value in a formatted string for the bucket given in the balance unit (for example 1.9 Gb). This formatted string could be used for display needs for example

string

validFor
optional

Balance period between a start date time and an end date time. For prepaid bucket, the period of the balance is between the effective date of the usage consumption report generation and the end date of the bucket. For postpaid bucket, the period of the balance is between the effective date of the usage consumption report generation and the next bill date.

TimePeriod

4.21. UsageVolumeProduct

A bucket (called UsageVolumeProduct in the SID model) represents a quantity of usage, as 2 hours national calls or 50 sms for example. It could be either a quantity or an amount in a currency (i.e. It could represent a fixed number of SMS, MMS, minutes of calls, quantity of data, number of events as well as a specific amount in a given currency). It requires one or more network products from which usages will debit the bucket.

Name Description Schema

@baseType
optional

When sub-classing, this defines the super-class

string

@schemaLocation
optional

A URI to a JSON-Schema file that defines additional attributes and relationships

string

@type
optional

When sub-classing, this defines the sub-class entity name

string

bucketBalance
optional

< UsageVolumeBalance > array

bucketCounter
optional

< ConsumptionSummary > array

id
optional

Unique identifier of the bucket

string

isShared
optional

True if the bucket is shared between several devices or users

boolean

name
optional

Bucket name

string

product
optional

< NetworkProduct > array

usageType
optional

Type of usage concerned by the bucket, such as voice, sms, data

string