Page tree

Macintosh HD:Users:itsupport:Desktop:2012Files:2013Branding:TMForumUSLetterhead2013Header.jpg  

 

 

 

 

 

 

 

 

Customer Bill Management API

Conformance Profile

 

 

Document Number: TMF678B

September 2017

 

 

 

 

 

 

Release: Release 17.5

Status: Member Evaluation

Version: 1.0.1

IPR Mode: RAND

 

 

 

NOTICE

Copyright © TM Forum 2017. 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

Introduction – api descripton

RESOURCE MODEL CONFORMANCE

API MANDATORY AND OPTIONAL RESOURCES

CUSTOMER BILL MANDATORY AND OPTIONAL ATTRIBUTES

AppliedCustomerBillingRate resource MANDATORY AND OPTIONAL ATTRIBUTES

CustomerBillOnDemand resource MANDATORY AND OPTIONAL ATTRIBUTES

NOTIFICATION MODEL CONFORMANCE

API  MANDATORY AND OPTIONAL NOTIFICATIONS

API OPERATIONS CONFORMANCE

Customer Bill MANDATORY AND OPTIONAL OPERATIONS

API GET FILTERING OPERATION CONFORMANCE

Filtering in Customer Bill resource

GET /customerBillManagement/customerBill

GET /customerBillManagement/customerBill /{ID}

API POST OPERATION CONFORMANCE

API PATCH OPERATION CONFORMANCE

API DELETE OPERATION CONFORMANCE

API CONFORMANCE TEST SCENARIOS

Customer resource TEST CASES

 

 

 

Introduction – api descripton

The following document is the Conformance Profile 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.

 

RESOURCE MODEL CONFORMANCE

API MANDATORY AND OPTIONAL RESOURCES

Resource Name

Mandatory or Optional

Comments

CustomerBill

M

 

AppliedCustomerBillingRate

O

 

CustomerBillOnDemand

O

 

CUSTOMER BILL MANDATORY AND OPTIONAL ATTRIBUTES

The table below summarizes mandatory and optional attributes for resource "CustomerBill".

Attribute Name

Mandatory or Optional

Comments

id

M (in response messages)

O (otherwise)

Generated by the server and provided in the response

href

M (in response messages)

O (otherwise)

 

billNo

O

 

category

O

 

runType

O

 

state

M/O

Required in response messages from the server (responses to read-GET the entity)

lastUpdate

O

Generated by the server

billDate

M (in response messages)

O (otherwise)

 

nextBilldate

O

 

billingPeriod

O

 

 

startDateTime

O

 

 

endDateTime

O

 

amountDue

M (in response messages)

O (otherwise)

 

 

value

M (in response messages)

O (otherwise)

 

 

unit

M (in response messages)

O (otherwise)

 

paymentDueDate

M (in response messages)

O (otherwise)

 

remainingAmount

O

 

 

value

O

 

 

unit

O

 

taxExcludedAmount

O

 

 

value

O

 

 

unit

O

 

taxIncludedAmount

O

 

 

value

O

 

 

unit

O

 

@baseType

O

 

@type

O

 

@schemaLocation

O

 

billDocument

O

Array of bill documents

 

id

O

 

 

href

O

 

 

name

O

 

 

description

O

 

 

mimeType

O

 

 

sizeUnit

O

 

 

size

O

 

 

url

O

 

 

@type

O

 

 

@schemaLocation

O

 

appliedPayment

O

Array of applied payments

 

appliedAmount

M (if appliedPayment included)

O (otherwise)

 

 

 

value

M (if appliedPayment included)

O (otherwise)

 

 

 

unit

M (if appliedPayment included)

O (otherwise)

 

 

payment

M (if appliedPayment included)

O (otherwise)

 

 

 

id

M (if appliedPayment included)

O (otherwise)

 

 

 

paymentDate

O

 

 

 

@type

O

 

billingAccount

O

 

 

id

M (if billingAccount included)

O (otherwise)

 

 

href

M (in response messages and if billingAccount included)

O (otherwise)

Only required in response messages from the server

 

name

O

 

 

@type

O

 

TaxItem

O

Array of tax items

 

taxCategory

O

 

 

taxRate

O

 

 

taxAmount

M (if taxItem included)

O (otherwise)

 

 

 

value

M (if taxItem included)

O (otherwise)

 

 

 

unit

M (if taxItem included)

O (otherwise)

 

paymentMethod

O

 

 

id

M (if paymentMethod included)

O (otherwise)

 

 

href

M (if paymentMethod included)

O (otherwise)

Only required in response messages from the server

 

name

O

 

 

@type

O

 

relatedParty

O

Array of related parties

 

id

M (if relatedParty included)

O (otherwise)

 

 

href

M (if relatedParty included)

O (otherwise)

Only required in response messages from the server

 

role

M (if relatedParty included)

O (otherwise)

 

 

name

O

 

 

@type

O

 

financialAccount

O

 

 

id

M (if financialAccount included)

O (otherwise)

 

 

href

M (if financialAccount included)

O (otherwise)

Only required in response messages from the server

 

name

O

 

 

@type

O

 

AppliedCustomerBillingRate resource MANDATORY AND OPTIONAL ATTRIBUTES

This resource is optional and not included in the basic CONNECT certification.

CustomerBillOnDemand resource MANDATORY AND OPTIONAL ATTRIBUTES

This resource is optional and not included in the basic CONNECT certification.

NOTIFICATION MODEL CONFORMANCE

The Pub/Sub models are common and described in the TMF REST Design Guidelines. Use the following templates to describe the Hub Mandatory and Optional attributes and filtering support.

API  MANDATORY AND OPTIONAL NOTIFICATIONS

For the Notifications defined by the API the following table indicates which ones are mandatory and which ones are optional.

Notification Name

Mandatory or Optional

Comments

CustomerBillCreationNotification

M

 

CustomerBillStateChangeNotification

M

 

 

All attributes of the resource associated with the notification are mandatory

 

API OPERATIONS CONFORMANCE

For every single resource use the following templates and define what operations are optional and what operations are mandatory.

Customer Bill MANDATORY AND OPTIONAL OPERATIONS

Uniform API Operation

Mandatory/Optional

Comments

GET

M

GET must be used to retrieve a representation of a resource

 

PATCH

O

PATCH must be used to partially update a resource

 

API GET FILTERING OPERATION CONFORMANCE

Definitions

 

Filtered Search: A filtered search can be applied using query parameters in order to obtain only the resource entities that meet the criteria defined by the filtering parameters included in the query request. Several elements can be applied to the filtered search. In that case logic, a logical AND is applied to combine the criteria (e.g.:?customerRank=<value> &status=<value>)

 

Attribute selection (Filtered Response Data): In order to apply a filter and limit the number of attributes included in the response, the GET request can include the  “ ?fields=” query parameter. Several elements can be applied to the filter. In that case, a logical AND is applied to combine the values (e.g.:?fields=severity,status) will provide in the response only the values assigned to attributes category and channel. Attribute selection capabilities are the same for collections retrieval and individual resource queries

 

All the GET operations in this API share the same status code pattern.

GET

M

 

Response Status Code 200

M

 

Other Status Codes

NA

 

 

Filtering in Customer Bill resource

Attribute name

Filtered search

First Level

Filtered search

N Level

Attribute Selection First Level

Attribute Selection N Level

id

NA

NA

M

NA

href

NA

NA

M

NA

runType

O

NA

M

NA

category

O

NA

M

NA

state

M

NA

M

NA

lastUpdate

O

NA

M

NA

billDate

O

NA

M

NA

nextBillDate

O

NA

M

NA

billingPeriod

NA

O

M

O

amountDue

NA

O

M

O

paymentDueDate

O

NA

M

NA

remainingAmount

NA

O

M

O

taxtExcludedAmount

NA

O

M

O

taxIncludedAmount

NA

O

M

O

billDocument

NA

O

M

O

paymentItem

NA

O

M

O

billingAccount

NA

M

M

O

taxItem

NA

O

M

O

paymentMethod

NA

O

M

O

relatedParty

NA

M

M

O

financialAccount

NA

O

M

O

 

GET /customerBillManagement/customerBill

 

Filtered Search: A filtered search can be applied using the following filtering criteria

 

  • state: to obtain the list of customer bills that are in a given status

 

  • billingAccount.id : to obtain the customer bills of a given billing account id

 

  • relatedParty.id and relatedPartyRole : to obtain  the customer bills of a given related party playing a given role

 

  • other optional attributes as defined in the table above

 

Filtered Data: A filtered response can be requested for the following attributes using the “?fields=” query parameter

-           Any of the attributes in the first level of Customer resource definition

GET /customerBillManagement/customerBill /{ID}

Filtered Data : A filtered response can be requested for the following attributes using the “?fields=” query parameter

-           Any of the attributes in the first level of Customer bill resource definition

 

API POST OPERATION CONFORMANCE

No POST operation available in Customer Bill API.

 

 

API PATCH OPERATION CONFORMANCE

This section defines which attributes are patchable.

Since PATCH operation is optional and not included in the basic CONNECT certification this is not applicable in this conformance document.

API DELETE OPERATION CONFORMANCE

No DELETE operation available in Customer Bill API.

API CONFORMANCE TEST SCENARIOS

This section describes the test scenarios required for the basic CONNECT certification of Customer Bill Management API.

Test Cases must be executed in the order defined for each resource because the result from one of the scenarios will be input for the next one.

Requests must be addressed to the endpoint provided for certification, specifically they must be addressed to the URI defined by the concatenation of the {apiRoot} and the specific resource, where the {apiRoot} is defined as {serverRoot}/customerBillManagement/v1 , being {serverRoot} defines the certification endpoint.

Customer resource TEST CASES

Nominal Scenarios

TC_CustBill_N1 – Search for customer bills with specific characteristics

 

TC_CustBill_N2 – Filtered retrieval of Customer bill data

 

TC_CustBill_N3 – Filtered Search and Filtered data response

 

Error Scenarios

TC_CustBill_E1 – Unknown Customer bill identifier

 

TC_CustBill_E2 – Invalid Request – Missing mandatory parameter

 

TC_CustBill_E3 – Invalid Request – Missing parameter mandatory in context