Page tree

 

    Frameworx Specification

 

Customer Bill Management
API REST Specification

 

 

 

 

 

 

      TMF678

      Release 17.5

      September 2017

 

 

 

Latest Update: Frameworx Release 17.5

Member Evaluation

Version 2.1.0

IPR Mode: RAND

NOTICE

Copyright © TM Forum 2016. All Rights Reserved.

This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published, and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this section are included on all such copies and derivative works. However, this document itself may not be modified in any way, including by removing the copyright notice or references to TM FORUM, except as needed for the purpose of developing any document or deliverable produced by a TM FORUM Collaboration Project Team (in which case the rules applicable to copyrights, as set forth in the TM FORUM IPR Policy , must be followed) or as required to translate it into languages other than English.

The limited permissions granted above are perpetual and will not be revoked by TM FORUM or its successors or assigns.

This document and the information contained herein is provided on an "AS IS" basis and TM FORUM DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY OWNERSHIP RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

 

Direct inquiries to the TM Forum office:

240 Headquarters Plaza,

East Tower – 10 th Floor,

Morristown, NJ   07960 USA

Tel No.   +1 973 944 5100

Fax No.   +1 973 944 5110

TM Forum Web Page: www.tmforum.org

Table of Contents

NOTICE

Table of Contents

List of Tables

Introduction

SAMPLE USE CASES

Use case 1 : retrieve customer bill(s) information

Description

Sample to illustrate the resource JSON representation

Use case 2 : request on demand a customer bill creation

Description

Main Actors

Use Case Steps

Success Outcome

RESOURCE MODEL

Managed Entity and Task Resource Models

Customer Bill resource

Applied Customer Billing Rate resource

Customer Bill on demand resource

Notification Resource Models

Customer Bill State Change Notification

Customer Bill Creation Notification

Customer Bill on demand Creation Notification

Customer Bill on demand State Change Notification

API OPERATIONS

Operations on Customer Bill

List customer bills

Retrieve customer bill

Patch customer bill

Operations on Applied Customer Billing Rate

List applied customer billing rates

Retrieve applied customer billing rate

Operations on Customer Bill on demand

Retrieve customer bill on demand with filter criteria

Retrieve a customer bill on demand with its id

Create a customer bill on demand

API NOTIFICATIONS

Register listener

Unregister listener

Publish Event to listener

Acknowledgements

Release History

Contributors to Document

List of Tables

N/A

 

Introduction

 

The following document is the specification of the REST API for customer bill management. It includes the model definition as well as all available operations.

 

Products subscribed by a customer are rated at different prices depending on product offering prices and prices rules and additional terms and conditions determined by the customer. The rating process takes product usages and applies rates to them. The billing process applies additional charges (recurring charges, one time charges), discounts and taxes to products then aggregate applied rates into bills sent to customers.

The bill, ultimate goal of a billing process, can be created as a result of a cycle run (done by batch in general) or by the result of others events such as a customer request or an account termination (done in real-time).

This API allows to find and retrieve one or several customer bills (also called invoices) produced for a customer. A customer bill is an electronic or paper document produced at the end of the billing process. The customer bill gathers and displays different items (applied customer billing rates generated during the rating and billing processes) to be charged to a customer. It represents a total amount due for all the products during the billing period and all significant information like dates, bill reference... The API model support the needs for the three basic billing types : postpaid periodical bill, postpaid real-time bill and prepaid real-time bill.

This API provides also operations to find and retrieve the details of applied customer billing rates presented on a customer bill.

Finally, this API allows to request in real-time a customer bill creation and to manage this request.

Nota : Customer Billing covers business entities utilized by rating and billing processes. These entities form the Customer Bill ABE, the Applied Customer Billing Rate ABE and the Customer Bill Collection ABE. They are specified in the GB922 Customer document of the Framework SID Suite R16.5.0.

 

SAMPLE USE CASES

Use case 1 : retrieve customer bill(s) information

Description

Front-End applications need to display information about the customer bills produced for postpaid and prepaid customers. These customer bills are managed on local IS Back-Ends. For example, they have to find and retrieve :Main information about a customer bill (amount due, due date, state, remaining amount to be paid, …).

  • A customer bill history with a defined proof (a list of customer bills with their payment history for example).
  • A link to the customer bill document (pdf file for example).
  • A detail of the applied billing charges displayed on a customer bill.

Sample to illustrate the resource JSON representation

We consider that the amount due aggregates the following applied billing rates :

-           Recurring charge : 119.60 € (100 € + 19.60 € of applied tax)

-           One time charge : 239.20 € (200 € + 39.20 € of applied tax)

-           National voice usage : 418.60 € (350 € + 68.60 of applied tax)

-           International voice usage : 239.20 € (200 € + 39.20 € of applied tax)

Use case 2 : request on demand a customer bill creation

Description

The main purpose of this use case is the creation of the customer bill for Bill on Demand operation identified by a commercial identifier such as a msisdn or an in ternal identifier.

Main Actors

  • The Customer
  • The Operator

 

Use Case Steps

  1. The requestor makes use of any of the available channels in order to initiate a Bill on Demand  operation
  2. The Operator receives a Bill on Demand request with indication of the following minimum information
    1. Requestor identifier
    2. subscriber identifier
  3. The operator confirms that the requestor is authorized to perform the bill on demand operation on the specific affected subscriber. This could be based on just the requestor identifier or via a more sophisticated token-based authorization mechanisms
  4. The Bill on Demand operation is processed and the Customer Bill resource for customer is created according to the Bill on Demand. The operation processes in the current bill cycle and the Bill data include monthly rentals, taxes, service fees and so on.
  5. The requestor is informed of the sucessful outcome

 

Success Outcome

After completion of these API interactions, the corresponding Customer Bill resource for the indicated customer will be created according to the request.

 

RESOURCE MODEL

Managed Entity and Task Resource Models

Customer Bill resource

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 (applied payments).

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.


Resource model

 

Lifecycle

The customer bill lifecycle is tracked by the 'state" attribute. Typical lifecycle values are : New, On Hold, Validated, Sent, Partially paid and Settled. The state machine specifying the typical state change transitions is provided below.

Note that an implementation of the specification may enrich the list of states depicted in the diagram or otherwise change the lifecycle, according to the CSP business practice.



 

 

Field descriptions

CustomerBill fields

amountDue

A money (Money). Amount due for this bill expressed in the given currency.

billDate

A date time (DateTime). Bill date.

billingPeriod

A time period. Billing period of the bill (used for onCycle bill only).

billNo

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

category

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

href

A string. Bill unique reference.

id

A string. Bill unique identifier.

lastUpdate

A date time (DateTime). Date of bill last update.

nextBillDate

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

paymentDueDate

A date time (DateTime). Date at which the amount due should have been paid.

remainingAmount

A money (Money). Remaining amount to be paid for this bill expressed in the given currency.

runType

A string. 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).

state

A string. State that a bill could take during its lifecycle : New, Validated, On Hold, Sent, Partially paid or Settled.

taxExcludedAmount

A money (Money). Total tax excluded amount expressed in the given currency.

taxIncludedAmount

A money (Money). Total tax included amount expressed in the given.

billDocument

A list of attachments (Attachment[*]). Attachment(s) accompanying an entity.

appliedPayment

A list of payment applied (AppliedPayment [*]). Part of payments already assigned to this bill.

billingAccount

A billing account reference (BillingAccountRef). Reference of the BillingAccount that produced this bill.

taxItem

A list of tax items (TaxItem [*]). A tax item is created for each tax rate and tax type used in the bill. The tax item summarize the total of the various tax types.

paymentMethod

A payment method reference (PaymentMethodRef). A payment method defines a specific mean of payment (e.g direct debit) used to build the call of payment.

relatedParty

A list of related party references (RelatedPartyRef [*]). A related party defines party or party role linked to the bill.

financialAccount

A financial account reference (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 billing accounts owned by a given party.

Attachment sub-resource

Attachment refers to extensions or additional parts that is or may be attached to something (agreements, contracts, appointments) to perform a particular function. They can be communication attachments, documents and other.

url

A string. URL of the attachment

mimeType

A string. Mime type of the attachment.

name

A string. Name of the attachment.

size

A decimal. The size  in Bytes of the document or attachment.

sizeUnit

An string. Size unit (in bytes by default).

Money sub-resource

A base / value business entity used to represent money.

unit

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

value

A float. A positive floating point number.

AppliedPayment sub-resource

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

appliedAmount

A money (Money). Part of a payment amount lettered to the bill.

payment

A payment reference (PaymentRef).

TaxItem sub-resource

A tax item is created for each tax rate and tax type used in the bill. The tax item specifies the applied tax rate and the total resulting amount.

taxAmount

A money. Amount of tax expressed in the given currency.

taxCategory

A string. A tax category.

taxRate

A float.  Applied rate of the tax.

AccountBalance relationship

AccountBalance  linked to the account.

amount

A money. Balance amount.

type

A string. Type of the balance : deposit balance, disputed balance, loyalty balance, receivable balance....

validFor

A time period. Balance validity period.

BillingAccountRef relationship

BillingAccount reference. A BillingAccount is a detailed description of a bill structure.

href

A string. Reference of the billing account.

id

A string. Unique identifier of the billing account.

name

A string. Name of the billing account.

FinancialAccountRef relationship

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.

href

A string. Unique reference of the account.

id

A string. Unique identifier of the account.

name

A string. Name of the account.

accountBalance

A list of account balances (AccountBalance [*]). Balances linked to the financial account.

PaymentMethodRef relationship

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

href

A string. Reference of the payment mean.

id

A string. Unique identifier of the payment mean.

name

A string. Name of the payment mean.

PaymentRef relationship

A payment reference.

amount

A money (Money). Payment amount done.

href

A string. Reference of the payment.

id

A string. Unique identifier of the payment.

paymentDate

A date time (DateTime). Payment date.

 

RelatedPartyRef relationship

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

href

A string. Reference of the related party, could be a party reference or a party role reference.

id

A string. Unique identifier of a related party.

name

A string. Name of the related party.

role

A string. Role of the related party.

Json representation sample

We provide below the json representation of an example of a 'CustomerBill' resource object

 

{
    "id": "8297",

    "href": "https://host:port/customerBillManagement/customerBill/8297",
    "billNo": "1516171800",
    "runType": "onCycle",
    "category": "normal",
    "state": "sent",
    "lastUpdate": "2016-02-08T:10:04:55",
    "billDate": "2016-01-31T:15:44:28",
    "nextBillDate": "2016-02-29T:00:00:00",
    "billingPeriod": {
        "endDateTime": "2016-01-31T:15:00:00",
        "startDateTime": "2016-01-01T:15:00:00"
    },
    "amountDue": {
        "value": 1016.6,
        "unit": "EUR"
    },
    "paymentDueDate": "2016-02-15T:15:44:28",
    "remainingAmount": {
        "value": 466.6,
        "unit": "EUR"
    },
    "taxExcludedAmount": {
        "value": 850.0,
        "unit": "EUR"
    },
    "taxIncludedAmount": {
        "value": 1016.6,
        "unit": "EUR"
    },

    "billDocument": [
        {
            "name": "CustomeBill1516171800.pdf",

            "mimeType": "application/pdf",
            "sizeUnit": "bytes",

            "size": 130,

            "url": " http://DocumentManager/6576342/CustomeBill1516171800.pdf "

        }
    ],
    "appliedPayment": [
        [
            {
                "appliedAmount": {
                    "value": 100.0,
                    "unit": "EUR"
                },
                "payment": {
                    "id": "601",
                    "paymentDate": "2016-02-03T:10:04:55"
                }
            },
            {
                "appliedAmount": {
                    "value": 450.0,
                    "unit": "EUR"
                },
                "payment": {
                    "id": "602",
                    "paymentDate": "2016-02-08T:10:04:55"
                }
            }
        ]
    ],
    "billingAccount": {
        "id": "65",
        "href": "https://host:port/accountManagement/billingAccount/65",
        "name": "Adam Smith billing account"
    },
    "taxItem": [
        [
            {
                "taxCategory": "VAT",
                "taxRate": 19.6,
                "taxAmount": {
                    "value": 166.6,
                    "unit": "EUR"
                }
            }
        ]
    ],
    "paymentMethod": {
        "href": " https://host:port/accountManagement/paymentMethod/41",
        "id": "41",
        "name": "Credit Card"
    },
    "relatedParty": [
        [
            {
                "href": " https://host:port/partyManagement/organization/500",
                "role": "issuer",
                "id": "500",
                "name": "Orange"
            },
            {
                "href": " https://host:port/partyManagement/organization/710",
                "role": "billReceiver",
                "id": "710",
                "name": "Adam Smith"
            },
            {
                "href": " https://host:port/partyManagement/organization/710",
                "role": "payer",
                "id": "710",
                "name": "Adam Smith"
            }
        ]
    ],
    "financialAccount": {
        "id": "15",
        "href": " https://host:port/accountManagement/financialAccount/15",
        "name": "Adam Smith financial account",
        "accountBalance": [ {

            "type": "receivableBalance",
            "status": "due",
            "amount": {
                "value": 466.6,
                "unit": "EUR"
            }
        } ]
    }
}

 

Applied Customer Billing Rate resource

A customer bill displays applied billing rates created before or during the billing process.

Resource model

Lifecycle

No state machine for this resource.

Field descriptions

AppliedCustomerBillingRate fields

date

A date time (DateTime). Creation date of the applied billing charge.

description

A string. Additional data to be displayed on the bill for this customer applied billing rate.

href

A string. Reference of the customer applied billing rate.

id

A string. Unique identifier of the customer applied billing rate.

name

A string. Name of the customer applied billing rate.

taxExcludedAmount

A money (Money). Tax excluded amount to be charged on the bill (expresses in the given currency) for this applied billing rate.

taxIncludedAmount

A money (Money). All taxes included amount to be charged on the bill (expressed in the given currency) for this applied billing rate.

type

A string. Type of the applied billing rate : appliedBillingCharge (any kind of charge except taxation charges : recurringCharge, oneTimeCharge, usageCharge),  appliedBillingCredit (any kind of credit : rebate or productAlteration) or appliedPenaltyCharge (penalty charges such as late fees, payment rejection fees,...).

appliedTax

A list of applied billing tax rates (AppliedBillingTaxRate [*]). The applied billing tax rate represents taxes applied to billing rate it refers to. It is calculated during the billing process.

bill

A bill reference (BillRef). Reference of the bill on which the applied billing rate  is presented.

characteristic

A list of applied billing rate characteristics (AppliedBillingRateCharacteristic [*]). An applied billing rate has dynamic characteristics according to the its type (characteristics are based on the service type, line of business or on others parameters for example).

AppliedBillingRateCharacteristic sub-resource

An applied billing rate has dynamic characteristics according to the its type (characteristics are based on the service type, line of business or on others parameters).

name

A string. Characteristic name.

value

A string. Value affected to the characteristic.

AppliedBillingTaxRate sub-resource

The applied billing tax rate represents taxes applied billing rate it refers to. It is calculated during the billing process.

taxAmount

A money (Money). Tax amount expressed in the given currency.

taxCategory

A string. A categorization of the tax rate.

taxRate

A float. Applied rate.

Money sub-resource

A base / value business entity used to represent money.

unit

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

value

A float. A positive floating point number.

BillRef relationship

Bill reference.

href

A string. Unique reference of the bill.

id

A string. Unique identifier of the bill.

 

 

Json representation sample

We provide below the json representation of an example of a 'AppliedCustomerBillingRate' resource object :

{
    "id": "2082",
    "href": "https://host:port/customerBillManagement/appliedCustomerBillingRate/2082",
    "name": "National Voice Usage",
    "description": "National Voice Usage amount",
    "date": "2016-01-31T15:44:28",
    "type": "usageCharge",

    "taxExcludedAmount": {
        "value": 350.0,
        "unit": "EUR"
    },
    "taxIncludedAmount": {
        "value": 418.60,
        "unit": "EUR"
    },

    "appliedTax": [
        {
            "taxCategory": "VAT",
            "taxRate": 19.6,

            "taxAmount": {
                    "value": 68.60,
                    "unit": "EUR"
            }
        }
    ],
    "bill": {
        "id": "8297",
        "href": " https://host:port/customerBillManagement/customerBill/8297 "

    },
    "characteristic": [
        [
            {
                "name": "unitCode",
                "value": "mn"
            },
            {
                "name": "UnitNumber",
                "value": "3600"
            }
        ]
    ]
}

 

Customer Bill on demand resource

This resource is used to manage the creation request of a customer bill in real-time (on demand).

Resource model

Lifecycle

The CustomerBillOnDemand lifecycle is tracked by the “state” attribute. Typical lifecycle values are : inProgress, rejected, done or terminatedWithError. The state machine specifying the typical state change transitions is provided below.

Note that an implementation of the specification may enrich the list of states depicted in the diagram or otherwise change the lifecycle, according to the CSP business practice.

 

Field descriptions

CustomerBillOnDemand fields

id

A string. Unique identifier of the customer bill on demand request given by the server

href

A string. Reference of the customer bill on demand request.

name

A string. Friendly name to identify the customer bill on demand request.

description

A string. Additional data describing the customer bill on demand request.

state

A string. State of the customer bill on demand request : rejected, inProgress, done or terminatedWithError.

lastUpdate

A date time (DateTime). The last date time when the customer bill on demand has been updated.

billingAccount

A billing account reference (BillingAccountRef). Reference of the billing account that produces the customer bill on demand.

relatedParty

A related party reference (RelatedPartyRef). A related party for which the customer bill on demand is requested.

customerBill

A bill reference (BillRef). Reference of the bill generated by the customer bill on demand request.

BillingAccountRef relationship

BillingAccount reference. A BillingAccount is a detailed description of a bill structure.

href

A string. Reference of the billing account.

id

A string. Unique identifier of the billing account.

name

A string. Name of the billing account.

BillRef relationship

Bill reference.

href

A string. Unique reference of the bill.

id

A string. Unique identifier of the bill.

RelatedPartyRef relationship

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

href

A string. Reference of the related party, could be a party reference or a party role reference.

id

A string. Unique identifier of a related party.

name

A string. Name of the related party.

role

A string. Role of the related party.

Json representation sample

We provide below the json representation of an example of a 'CustomerBillOnDemand' resource object :

 

{
    "id": "115643244",
    "href": "https://host:port/customerBillManagement/customerBillOnDemand/115643244",
    "name": "Last bill",
    "description": "Bill on demand requested for de-registration",
    "state": "done",

    "lastUpdate": "2016-01-31T15:44:28",
    "billingAccount": {
        "id": "65",
        "href": "https://host:port/accountManagement/billingAccount/65",
        "name": "Adam Smith billing account"
    },

    "relatedParty":   {
         "id": "710", 

         "href": " https://host:port/partyManagement/individual/710",
         "role": "billReceiver",
         "name": "Adam Smith"

      },

     "customerBill": {
        "id": "8297",
        "href": " https://host:port/customerBillManagement/customerBill/8297"
    }

}

 

 

Notification Resource Models

4 notifications are defined for this API.

Notifications related to CustomerBill :
    - CustomerBillStateChangeNotification

    - CustomerBillCreationNotification

 

Notifications related to CustomerBillOnDemand :

    - CustomerBillOnDemandCreationNotification

    - CustomerBillOnDemandStateChangeNotification

 

The notification structure for all notifications in this API follow the pattern depicted by the figure below.
A notification resource (depicted by "SpecificNotification" placeholder) is a sub class of a generic Notification structure containing an id of the event occurence (eventId), an event timestamp (eventTime), and the name of the notification resource (eventType).

This notification structure owns an event structure ("SpecificEvent" placeholder) linked to the resource concerned by the notification using the resource name as access field ("resourceName" placeholder).

 

 

Customer Bill State Change Notification

Notification sent when changing the state of a CustomerBill resource.

Json representation sample

We provide below the json representation of an example of a 'CustomerBillStateChangeNotification' notification object

 

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"CustomerBillStateChangeNotification",
     "event": {
        "customerBill" :
            {-- SEE CustomerBill RESOURCE SAMPLE --}
    }
}
 

Customer Bill Creation Notification

Notification sent when a CustomerBill resource is created.

Json representation sample

We provide below the json representation of an example of a 'CustomerBillCreationNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"CustomerBillCreationNotification",
     "event": {
        "customerBill" :
            {-- SEE CustomerBill RESOURCE SAMPLE --}
    }
}
 

 

Customer Bill on demand Creation Notification

Notification sent when a CustomerBillOnDemand resource is created.

Json representation sample

We provide below the json representation of an example of a 'CustomerBillOnDemandCreationNotification' notification object

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"CustomerBillSOnDemandCreationNotification",
     "event": {
        "customerBillOnDemand" :
            {-- SEE CustomerBillOnDemand RESOURCE SAMPLE --}
    }
}
 

 

Customer Bill on demand State Change Notification

Notification sent when changing the state of a CustomerBillOnDemand resource.

 

Json representation sample

We provide below the json representation of an example of a 'CustomerBillOnDemandStateChangeNotification' notification object

 

{
    "eventId":"00001",
    "eventTime":"2015-11-16T16:42:25-04:00",
    "eventType":"CustomerBillOnDemandStateChangeNotification",
     "event": {
        "customerBillOnDemand" :
            {-- SEE CustomerBillOnDemand RESOURCE SAMPLE --}
    }
}
 

 

  API OPERATIONS

Remember the following Uniform Contract:

Operation on Entities

Uniform API Operation

Description

Query Entities

GET Resource

GET must be used to retrieve a representation of a resource.

 

Create Entity

POST Resource

POST must be used to create a new resource

Partial Update of an Entity

PATCH Resource

PATCH must be used to partially update a resource

Complete Update of an Entity

PUT Resource

PUT must be used to completely update a resource identified by its resource URI

Remove an Entity

DELETE Resource

DELETE must be used to remove a resource

Execute an Action on an Entity

POST on TASK Resource

POST must be used to execute Task Resources

Other Request Methods

POST on TASK Resource

GET and POST must not be used to tunnel other request methods.

 

Filtering and attribute selection rules are described in the TMF REST Design Guidelines.

Notifications are also described in a subsequent section.


Operations on Customer Bill

List customer bills

  GET /customerBill?fields=...&{filtering}

Description

This operation list customer bill entities.
Attribute selection is enabled for all first level attributes.
Filtering may be available depending on the compliance level supported by an implementation.

Usage Samples

Here's an example of a request for retrieving CustomerBill resources using the filter criteria billingAccount.id = 65 and selecting only the following attributes : billDate, amountDue, paymentDueDate and state.


Request
 

 

GET /customerBillManagement/customerBill?fields=billDate,amountDue,remainingAmount,state&billingAccount.id=65

Accept: application/json
 


Response
 

 

200
Content-Type : application/json
[

  {

      "id": "6541",

      "state": "settled",
      "billDate": "2016-01-31T:15:44:28",
      "amountDue": {
           "value": 250.0,
           "unit": "EUR"
      },

     "paymentDueDate": "2016-02-15T:15:44:28"

  },

  {

      "id": "7140",

      "state": "settled",
      "billDate": "2016-02-29T:15:44:28",
      "amountDue": {
           "value": 150.0,
           "unit": "EUR"
      },

     "paymentDueDate": "2016-03-15T:15:44:28"

  },

  {

      "id": "7852",

      "state": "partiallyPaid",
      "billDate": "2016-03-31T:15:44:28",
      "amountDue": {
           "value": 250.0,
           "unit": "EUR"
      },

     "paymentDueDate": "2016-04-15T:15:44:28"

  },

  {

      "id": "8123",

      "state": "sent",
      "billDate": "2016-04-30T:15:44:28",
      "amountDue": {
           "value": 60.0,
           "unit": "EUR"
      },

     "paymentDueDate": "2016-05-15T:15:44:28"

  }

]
 

Retrieve customer bill

  GET /customerBill/{id}?fields=...&{filtering}

Description

This operation retrieves a customer bill entity.
Attribute selection is enabled for all first level attributes.
Filtering on sub-resources may be available depending on the compliance level supported by an implementation.

Usage Samples

Here's an example of a request for retrieving a CustomerBill resource.


Request
 

 

GET /customerBillManagement/customerBill/8297
Accept: application/json
 


Response
 

 

200

Content-Type : application/json

{
    "id": "8297",

    "href": "https://host:port/customerBillManagement/customerBill/8297",
    "billNo": "1516171800",
    "runType": "onCycle",
    "category": "normal",
    "state": "sent",
    "lastUpdate": "2016-02-08T:10:04:55",
    "billDate": "2016-01-31T:15:44:28",
    "nextBillDate": "2016-02-29T:00:00:00",
    "billingPeriod": {
        "endDateTime": "2016-01-31T:15:00:00",
        "startDateTime": "2016-01-01T:15:00:00"
    },
    "amountDue": {
        "value": 1016.6,
        "unit": "EUR"
    },
    "paymentDueDate": "2016-02-15T:15:44:28",
    "remainingAmount": {
        "value": 466.6,
        "unit": "EUR"
    },
    "taxExcludedAmount": {
        "value": 850.0,
        "unit": "EUR"
    },
    "taxIncludedAmount": {
        "value": 1016.6,
        "unit": "EUR"
    },

    "billDocument": [
        {
            "name": "CustomeBill1516171800.pdf",

            "mimeType": "application/pdf",
            "sizeUnit": "bytes",

            "size": 130,

            "url": " http://DocumentManager/6576342/CustomeBill1516171800.pdf "

        }
    ],
    "appliedPayment": [
        [
            {
                "appliedAmount": {
                    "value": 100.0,
                    "unit": "EUR"
                },
                "payment": {
                    "id": "601",
                    "paymentDate": "2016-02-03T:10:04:55"
                }
            },
            {
                "appliedAmount": {
                    "value": 450.0,
                    "unit": "EUR"
                },
                "payment": {
                    "id": "602",
                    "paymentDate": "2016-02-08T:10:04:55"
                }
            }
        ]
    ],
    "billingAccount": {
        "id": "65",
        "href": "https://host:port/accountManagement/billingAccount/65",
        "name": "Adam Smith billing account"
    },
    "taxItem": [
        [
            {
                "taxCategory": "VAT",
                "taxRate": 19.6,
                "taxAmount": {
                    "value": 166.6,
                    "unit": "EUR"
                }
            }
        ]
    ],
    "paymentMethod": {
        "href": " https://host:port/accountManagement/paymentMethod/41",
        "id": "41",
        "name": "Credit Card"
    },
    "relatedParty":
        [
            {
                "href": " https://host:port/partyManagement/organization/500",
                "role": "issuer",
                "id": "500",
                "name": "Orange"
            },
            {
                "href": " https://host:port/partyManagement/organization/710",
                "role": "billReceiver",
                "id": "710",
                "name": "Adam Smith"
            },
            {
                "href": " https://host:port/partyManagement/organization/710",
                "role": "payer",
                "id": "710",
                "name": "Adam Smith"
            }
    ],
    "financialAccount": {
        "id": "15",
        "href": " https://host:port/accountManagement/financialAccount/15",
        "name": "Adam Smith financial account",
        "accountBalance": [ {

            "type": "receivableBalance",
            "amount": {
                "value": 466.6,
                "unit": "EUR"
            }
        } ]
    }
}

 

Patch customer bill

  PATCH /customerBill/{id}

Note: this operation is available only to ADMIN API users.

The PATCH Bill operation is optional. An implementation is not required to support PATCH to be compliant with the standard.

Description

This operation allows partial updates of a customer bill entity. Support of json/merge (https://tools.ietf.org/html/rfc7386) is mandatory, support of json/patch (http://tools.ietf.org/html/rfc5789) is optional.

Note: If the update operation yields to the creation of sub-resources or relationships, the same rules concerning mandatory sub-resource attributes and default value settings in the POST operation applies to the PATCH operation.  Hence these tables are not repeated here.

Patchable and Non Patchable Attributes

The tables below provide the list of patchable and non patchable attributes, including constraint rules on their usage.

Patchable Attributes

Rule

state

 

 

Non Patchable Attributes

Rule

amountDue

 

billDate

 

billingPeriod

 

billNo

 

category

 

href

 

id

 

lastUpdate

 

nextBillDate

 

paymentDueDate

 

remainingAmount

 

runType

 

taxExcludedAmount

 

taxIncludedAmount

 

billDocument

 

paymentItem

 

billingAccount

 

taxItem

 

paymentMethod

 

relatedParty

 

financialAccount

 

 

Usage Samples

Here's an example of a request for patching state attribute of a CustomerBill resource.


Request
 

PATCH /customerBillManagement/customerBill/8297
Content-Type: application/merge-patch+json

{
    "state": "partiallyPaid"
}
 


Response
 

201

{
    "id": "8297",

    "href": "https://host:port/customerBillManagement/customerBill/8297",
    "billNo": "1516171800",
    "runType": "onCycle",
    "category": "normal",
    "state": "partiallyPaid",
    "lastUpdate": "2016-02-08T:10:04:55",
    "billDate": "2016-01-31T:15:44:28",
    "nextBillDate": "2016-02-29T:00:00:00",
    "billingPeriod": {
        "endDateTime": "2016-01-31T:15:00:00",
        "startDateTime": "2016-01-01T:15:00:00"
    },
    "amountDue": {
        "value": 1016.6,
        "unit": "EUR"
    },
    "paymentDueDate": "2016-02-15T:15:44:28",
    "remainingAmount": {
        "value": 466.6,
        "unit": "EUR"
    },
    "taxExcludedAmount": {
        "value": 850.0,
        "unit": "EUR"
    },
    "taxIncludedAmount": {
        "value": 1016.6,
        "unit": "EUR"
    },

    "billDocument": [
        {
            "name": "CustomeBill1516171800.pdf",

            "mimeType": "application/pdf",
            "sizeUnit": "bytes",

            "size": 130,

            "url": " http://DocumentManager/6576342/CustomeBill1516171800.pdf "

        }
    ],
    "appliedPayment": [
        [
            {
                "appliedAmount": {
                    "value": 100.0,
                    "unit": "EUR"
                },
                "payment": {
                    "id": "601",
                    "paymentDate": "2016-02-03T:10:04:55"
                }
            },
            {
                "appliedAmount": {
                    "value": 450.0,
                    "unit": "EUR"
                },
                "payment": {
                    "id": "602",
                    "paymentDate": "2016-02-08T:10:04:55"
                }
            }
        ]
    ],
    "billingAccount": {
        "id": "65",
        "href": "https://host:port/accountManagement/billingAccount/65",
        "name": "Adam Smith billing account"
    },
    "taxItem": [
        [
            {
                "taxCategory": "VAT",
                "taxRate": 19.6,
                "taxAmount": {
                    "value": 166.6,
                    "unit": "EUR"
                }
            }
        ]
    ],
    "paymentMethod": {
        "href": " https://host:port/accountManagement/paymentMethod/41",
        "id": "41",
        "name": "Credit Card"
    },
    "relatedParty":  [
            {
                "href": " https://host:port/partyManagement/organization/500",
                "role": "issuer",
                "id": "500",
                "name": "Orange"
            },
            {
                "href": " https://host:port/partyManagement/organization/710",
                "role": "billReceiver",
                "id": "710",
                "name": "Adam Smith"
            },
            {
                "href": " https://host:port/partyManagement/organization/710",
                "role": "payer",
                "id": "710",
                "name": "Adam Smith"
            }
    ],
    "financialAccount": {
        "id": "15",
        "href": " https://host:port/accountManagement/financialAccount/15",
        "name": "Adam Smith financial account",
        "accountBalance": {

            "type": "receivableBalance",
            "amount": {
                "value": 466.6,
                "unit": "EUR"
            }
        }
    }
}

 


Operations on Applied Customer Billing Rate

List applied customer billing rates

  GET /appliedCustomerBillingRate?fields=...&{filtering}

Description

This operation list applied customer billing rate entities.
Attribute selection is enabled for all first level attributes.
Filtering may be available depending on the compliance level supported by an implementation.

Usage Samples

Here's an example of a request for retrieving AppliedCustomerBillingRate resources with filtering criteria bill.id = 8297.


Request
 

 

GET /customerBillManagement/appliedCustomerBillingRate?bill.id=8297
Accept: application/json
 


Response
 

200
[

  {
     "id": "2082",
     "href": "https://host:port/customerBillManagement/appliedCustomerBillingRate/2082",
     "name": "National Voice Usage",
     "description": "National Voice Usage amount",
     "date": "2016-01-31T15:44:28",
     "type": "usageCharge",

     "taxExcludedAmount": {
         "value": 350.0,
         "unit": "EUR"
     },
     "taxIncludedAmount": {
         "value": 418.60,
         "unit": "EUR"
     },

     "appliedTax": [
         {
             "taxCategory": "VAT",
             "taxRate": 19.6,

             "taxAmount": {
                 "value": 68.60,
                 "unit": "EUR"
          }
        }
     ],
     "bill": {
         "id": "8297",
         "href": " https://host:port/customerBillManagement/customerBill/8297 "

     },
     "characteristic": [
          {
             "name": "unitCode",
             "value": "mn"
          },
          {
             "name": "UnitNumber",
             "value": "3600"
          }
     ]
},

{
     "id": "2083",
     "href": "https://host:port/customerBillManagement/appliedCustomerBillingRate/2083",
     "name": "International Voice Usage",
     "description": "International Voice Usage amount",
     "date": "2016-01-31T15:44:28",
     "type": "usageCharge",

     "taxExcludedAmount": {
         "value": 200.0,
         "unit": "EUR"
     },
     "taxIncludedAmount": {
         "value": 239.20,
         "unit": "EUR"
     },

     "appliedTax": [
         {
             "taxCategory": "VAT",
             "taxRate": 19.6,

             "taxAmount": {
                 "value": 39.20,
                 "unit": "EUR"
            }
        }
     ],
     "bill": {
         "id": "8297",
         "href": " https://host:port/customerBillManagement/customerBill/8297 "

     },
     "characteristic": [
         {
             "name": "unitCode",
             "value": "mn"
         },
         {
             "name": "UnitNumber",
              "value": "1200"
       }
     ]
},

{
     "id": "2084",
     "href": "https://host:port/customerBillManagement/appliedCustomerBillingRate/2084",
     "name": "Recurring fees",
     "description": "Recurring fees amount",
     "date": "2016-01-31T15:44:28",
     "type": "recurringCharge",

     "taxExcludedAmount": {
        "value": 100.0,
        "unit": "EUR"
     },
     "taxIncludedAmount": {
         "value": 119.60,
         "unit": "EUR"
     },

     "appliedTax": [
        {
            "taxCategory": "VAT",
            "taxRate": 19.6,

            "taxAmount": {
                 "value": 19.60,
                 "unit": "EUR"
           }
       }
     ],
     "bill": {
         "id": "8297",
          "href": " https://host:port/customerBillManagement/customerBill/8297 "

     },
     "characteristic": [
         {
             "name": "startPeriod",
             "value": "2016-01-01"
         },
        {
             "name": "endPeriod",
             "value": "2016-01-31"
        }
   ]
},

{
     "id": "2085",
     "href": "https://host:port/customerBillManagement/appliedCustomerBillingRate/2085",
     "name": "One time fees",
     "description": "One time fees amount",
     "date": "2016-01-31T15:44:28",
     "type": "oneTimeCharge",

     "taxExcludedAmount": {
         "value": 200.0,
         "unit": "EUR"
     },
     "taxIncludedAmount": {
          "value": 239.20,
          "unit": "EUR"
     },

     "appliedTax": [
         {
             "taxCategory": "VAT",
             "taxRate": 19.6,

             "taxAmount": {
                    "value": 39.20,
                    "unit": "EUR"
            }
         }
     ],
     "bill": {
         "id": "8297",
         "href": " https://host:port/customerBillManagement/customerBill/8297 "

     }

  }

]
 

Retrieve applied customer billing rate

  GET /appliedCustomerBillingRate/{id}?fields=...&{filtering}

Description

This operation retrieves an applied customer billing rate entity.
Attribute selection is enabled for all first level attributes.
Filtering on sub-resources may be available depending on the compliance level supported by an implementation.

Usage Samples

Here's an example of a request for retrieving a AppliedCustomerBillingRate resource.


Request
 

 

GET /customerBillManagement/appliedCustomerBillingRate/2082
Accept: application/json
 

 

Response
 

 

{
    "id": "2082",
    "href": "https://host:port/customerBillManagement/appliedCustomerBillingRate/2082",
    "name": "National Voice Usage",
    "description": "National Voice Usage amount",
    "date": "2016-01-31T15:44:28",
    "type": "usageCharge",

    "taxExcludedAmount": {
        "value": 350.0,
        "unit": "EUR"
    },
    "taxIncludedAmount": {
        "value": 418.60,
        "unit": "EUR"
    },

    "appliedTax": [
        {
            "taxCategory": "VAT",
            "taxRate": 19.6,

            "taxAmount": {
                    "value": 68.60,
                    "unit": "EUR"
            }
        }
    ],
    "bill": {
        "id": "8297",
        "href": " https://host:port/customerBillManagement/customerBill/8297 "

    },
    "characteristic": [
        [
            {
                "name": "unitCode",
                "value": "mn"
            },
            {
                "name": "UnitNumber",
                "value": "3600"
            }
        ]
    ]
}

 

 


Operations on Customer Bill on demand

Retrieve customer bill on demand with filter criteria

  GET /customerBillOnDemand?fields=...&{filtering}

Description

This operation list customer bill on demand entities.
Attribute selection is enabled for all first level attributes.
Filtering may be available depending on the compliance level supported by an implementation.

Usage Samples

Here's an example of a request for retrieving CustomerBillOnDemand resources using the filter criteria billingAccount.id = 65 and selecting only the following attributes : state and customerBill reference created by the bill on demand reques state.


Request
 

 

GET /customerBillManagement/customerBillOndemand?fields= state,customerBill&billingAccount.id=65

Accept: application/json
 


Response
 

 

200
Content-Type : application/json
[

{
    "id": "115643244",
    "href": "https://host:port/customerBillManagement/customerBillOnDemand/115643244",
    "name": "Last bill",
    "description": "Bill on demand requested for de-registration",
    "state": "done",

    "lastUpdate": "2016-01-31T15:44:28",
    "billingAccount": {
        "id": "65",
        "href": "https://host:port/accountManagement/billingAccount/65",
        "name": "Adam Smith billing account"
    },

    "relatedParty":   {
         "id": "710", 

         "href": " https://host:port/partyManagement/individual/710",
         "role": "billReceiver",
         "name": "Adam Smith"

      },

     "customerBill": {
        "id": "8297",
        "href": " https://host:port/customerBillManagement/customerBill/8297"
    }

}

]
 

 

Retrieve a customer bill on demand with its id

  GET /customerBillOnDemand/{id}?fields=...&{filtering}

Description

This operation retrieves a customer bill on demand entity.
Attribute selection is enabled for all first level attributes.
Filtering on sub-resources may be available depending on the compliance level supported by an implementation.

 

Usage Samples

Here's an example of a request for retrieving a CustomerBillOnDemand resource.


Request
 

 

GET /customerBillManagement/customerBillOnDemand/115643244
Accept: application/json
 

 

Response
 

200
Content-Type : application/json

{
    "id": "115643244",
    "href": "https://host:port/customerBillManagement/customerBillOnDemand/115643244",
    "name": "Last bill",
    "description": "Bill on demand requested for de-registration",
    "state": "done",

    "lastUpdate": "2016-01-31T15:44:28",
    "billingAccount": {
        "id": "65",
        "href": "https://host:port/accountManagement/billingAccount/65",
        "name": "Adam Smith billing account"
    },

    "relatedParty":   {
         "id": "710", 

         "href": " https://host:port/partyManagement/individual/710",
         "role": "billReceiver",
         "name": "Adam Smith"

      },

     "customerBill": {
        "id": "8297",
        "href": " https://host:port/customerBillManagement/customerBill/8297"
    }

}

 

Create a customer bill on demand

  POST /customerBillOnDemand

Description

This operation creates a customer bill on demand entity.
 

Usage Samples

Here's an example of a request for creating a CustomerBillOnDemand resource.


Request
 

 

POST /customerBillManagement/customerBillOnDemand
Content-Type: application/json

{
    "billingAccount": {
        "id": "65",
        "href": "https://host:port/accountManagement/billingAccount/65",
        "name": "Adam Smith billing account"
    }

}
 

 

Response
 

201
Content-Type : application/json

{
    "id": "115643244",
    "href": "https://host:port/customerBillManagement/customerBillOnDemand/115643244",
    "name": "Last bill",
    "description": "Bill on demand requested for de-registration",
    "state": "inProgress",

    "lastUpdate": "2016-01-31T15:44:28",
    "billingAccount": {
        "id": "65",
        "href": "https://host:port/accountManagement/billingAccount/65",
        "name": "Adam Smith billing account"
    },

    "relatedParty":   {
         "id": "710", 

         "href": " https://host:port/partyManagement/individual/710",
         "role": "billReceiver",
         "name": "Adam Smith"

      }

}

 

API NOTIFICATIONS

For every single of operation on the entities use the following templates and provide sample REST notification POST calls.

It is assumed that the Pub/Sub uses the Register and UnRegister mechanisms described in the REST Guidelines reproduced below.

Register listener

  POST /hub

Description

Sets the communication endpoint address the service instance must use to deliver information about its health state, execution state, failures and metrics. Subsequent POST calls will be rejected by the service if it does not support multiple listeners. In this case DELETE /api/hub/{id} must be called before an endpoint can be created again.

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 409 if request is not successful.

Usage Samples

Here's an example of a request for registering a listener.


Request
 

POST /api/hub

Accept: application/json

 

{"callback": "http://in.listener.com"}
 


Response
 

201

Content-Type: application/json

Location: /api/hub/42

 

{"id":"42","callback":"http://in.listener.com","query":null}

 

 


Unregister listener

  DELETE /hub/{id}

Description

Clears the communication endpoint address that was set by creating the Hub..

Behavior

Returns HTTP/1.1 status code 204 if the request was successful.

Returns HTTP/1.1 status code 404 if the resource is not found.

Usage Samples

Here's an example of a request for un-registering a listener.


Request
 

DELETE /api/hub/42

Accept: application/json
 


Response
 

204

 

Publish Event to listener

  POST /client/listener

Description

Clears the communication endpoint address that was set by creating the Hub.

Provides to a registered listener the description of the event that was raised. The /client/listener url is the callback url passed when registering the listener.

Behavior

Returns HTTP/1.1 status code 201 if the service is able to set the configuration.

Usage Samples

Here's an example of a notification received by the listener. In this example “EVENT TYPE” should be replaced by one of the notification types supported by this API (see Notification resources Models section) and EVENT BODY refers to the data structure of the given notification type.


Request
 

POST /client/listener

Accept: application/json

 

{

    "event": {

                EVENT BODY

            },

    "eventType": "EVENT_TYPE"

}
 


Response
 

201

 

For detailed examples on the general TM Forum notification mechanism, see the TMF REST Design Guidelines.

 


Acknowledgements

Release History

Release Number

Date

Release led by:

Description

Release 2.1

18/09/2017

Pierre Gauthier
TM Forum
pgauthier@tmforum.org

Sophie Bouleau
Orange
sophie.bouleau@orange.com

Jia Jiangtao
Huawei
jiajiangtao@huawei.com

New release introducing the CustomerBillOnDemand resource and operations

In CustomerBill resource, PaymentItem is renamed in AppliedPayment and Document in Attachment (to be conform with Document Management API)

Release 2.0

03/03/2017

Pierre Gauthier
TM Forum
pgauthier@tmforum.org

Sophie Bouleau
Orange
sophie.bouleau@orange.com

New release taking into account various remarks from tmforum members.

Generated from API Data Model and completed with use cases and samples.

Release 1.0

15/04/2016

Pierre Gauthier
TM Forum
pgauthier@tmforum.org

Sophie Bouleau
Orange
sophie.bouleau@orange.com

Initial Document.

Generated from API Data Model.

Contributors to Document

Sophie Bouleau

Orange

Jia Jiangtao

Huawei

Mariano Belaunde

Orange

Pierre Gauthier

TM Forum