1. Overview

Bill Management TMF Webservices Documentation

1.1. Version information

Version : 1.0.0

1.2. URI scheme

Host : hostname
BasePath : /billmanagementtmfwebservices/v1

1.3. Tags

  • Customer Bill Management : Bm Customer Bill Controller

1.4. 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. Customer Bill Management

Bm Customer Bill Controller

3.1.1. List or find CustomerBill objects

GET /customerBill
Description

This operation list or find CustomerBill 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

relatedParty.id
optional

Related party id value

string
Responses
HTTP Code Description Schema

200

Success

< CustomerBill > 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

3.1.2. Retrieves a CustomerBill by ID

GET /customerBill/{id}
Description

This operation retrieves a CustomerBill entity. Attribute selection is enabled for all first level attributes.

Parameters
Type Name Description Schema

Path

id
required

Identifier of the CustomerBill

string

Query

fields
optional

Comma-separated properties to provide in response

string
Responses
HTTP Code Description Schema

200

Success

CustomerBill

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. AccountBalance

Balances linked to the account

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

amount
required

Balance amount

Money

balanceType
required

Type of the balance : deposit balance, disputed balance, loyalty balance, receivable balance…

string

validFor
required

Balance validity period

TimePeriod

4.2. AppliedPayment

The applied payment is the result of lettering process. It enables to assign automatically or manually part of incoming payment amount to a bill.

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

appliedAmount
optional

Money

payment
optional

PaymentRef

4.3. AttachmentRefOrValue

An attachment by value or by reference. For AttachmentRefOrValue, the attribute type,schemaLocation and referredType are related to the contained entity and not to AttchmentRefOrValue itself

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

attachmentType
optional

Attachment type such as video, picture

string

content
optional

The actual contents of the attachment object, if embedded, encoded as base64

string

description
optional

A narrative text describing the content of the attachment

string

href
optional

URI for this Attachment

string

id
optional

Unique identifier for this particular attachment

string

mimeType
optional

Attachment mime type such as extension file for video, picture and document

string

name
optional

The name of the attachment

string

size
optional

The size of the attachment.

Quantity

url
optional

Uniform Resource Locator, is a web page address (a subset of URI)

string

validFor
optional

The period of time for which the attachment is valid

TimePeriod

4.4. BillingAccountRef

Reference to the billing account in case of not billed item.

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

URL serving as reference for the <xyz> resource

string

id
required

Unique-Identifier for this <123>

string

name
optional

Name of the Billingaccount

string

4.5. CustomerBill

The billing account receives all charges (recurring, one time and usage) of the offers and products assigned to it during order process. Periodically according to billing cycle specifications attached to the billing account or as a result of an event, a customer bill (aka invoice) is produced. This customer bill concerns different related parties which play a role on it : for example, a customer bill is produced by an operator, is sent to a bill receiver and has to be paid by a payer. A payment method could be assigned to the customer bill to build the call of payment. Lettering process enables to assign automatically or manually incoming amount from payments to customer bills (payment items). A tax item is created for each tax rate used in the customer bill. The financial account represents a financial entity which records all customer’s accounting events : payment amount are recorded as credit and invoices amount are recorded as debit. It gives the customer overall balance (account balance). The customer bill is linked to one or more documents that can be downloaded via a provided url.

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

amountDue
optional

Money

appliedPayment
optional

< AppliedPayment > array

billDate
optional

Bill date

string(date-time)

billDocument
optional

< AttachmentRefOrValue > array

billNo
optional

Bill reference known by the customer or the party and displayed on the bill. Could be different from the id

string

billingAccount
optional

BillingAccountRef

billingPeriod
optional

TimePeriod

category
optional

Category of the bill produced : normal, duplicate, interim, last, trial customer or credit note for example

string

financialAccount
optional

FinancialAccountRef

href
optional

Bill unique reference

string

id
optional

Unique identifier of he bill

string

lastUpdate
optional

Date of bill last update

string(date-time)

nextBillDate
optional

). Approximate date of the next bill production given for information (only used for onCycle bill)

string(date-time)

paymentDueDate
optional

Date at which the amount due should have been paid

string(date-time)

paymentMethod
optional

PaymentMethodRef

relatedParty
optional

< RelatedPartyRef > array

remainingAmount
optional

Money

runType
optional

onCycle (a bill can be created as a result of a cycle run) or offCycle (a bill can be created as a result of other events such as customer request or account close)

string

state
optional

enum (new, onHold, validated, sent, partiallyPaid, settled)

taxExcludedAmount
optional

Money

taxIncludedAmount
optional

Money

taxItem
optional

< TaxItem > array

4.6. Error

Used when an API throws an Error, typically with a HTTP error response-code (3xx, 4xx, 5xx)

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

code
required

Application relevant detail, defined in the API or a common list.

string

message
optional

More details and corrective actions related to the error which can be shown to a client user.

string

reason
optional

Explanation of the reason for the error which can be shown to a client user.

string

referenceError
optional

URI of documentation describing the error.

string

status
optional

HTTP Error code extension

string

4.7. FinancialAccountRef

AccountReceivable reference. An account of money owed by a party to another entity in exchange for goods or services that have been delivered or used. An account receivable aggregates the amounts of one or more party accounts (billing or settlement) owned by a given 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

accountBalance
optional

< AccountBalance > array

href
optional

Unique reference of the account

string

id
required

Unique identifier of the account

string

name
optional

Name of the account

string

4.8. Money

A base / value business entity used to represent money

Name Description Schema

unit
optional

Currency (ISO4217 norm uses 3 letters to define the currency)

string

value
optional

A positive floating point number

number(float)

4.9. PaymentMethodRef

PaymentMethod reference. A payment method defines a specific mean of payment (e.g direct debit).

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 payment mean

string

id
required

Unique identifier of the payment mean

string

name
optional

Name of the payment mean

string

4.10. PaymentRef

If an immediate payment has been done at the product order submission, the payment information are captured and stored (as a reference) in the order.

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

A name for the payment

string

4.11. 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.12. RelatedPartyRef

RelatedParty 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 party, could be a party reference or a party role reference

string

id
required

Unique identifier of a related party

string

name
optional

Name of the related party

string

role
optional

Role of the related party.

string

4.13. TaxItem

A tax item is created for each tax rate and tax type used in the bill.

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

taxAmount
optional

Amount of tax expressed in the given currency

Money

taxCategory
optional

Tax category

string

taxRate
optional

Applied rate of the tax

number(float)

4.14. 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)