Page tree

 

 

 

 

 

 

 

Account Management API
Conformance Profile

 

Document Number TMF666B

June 2017

 

 

 

 

 

 

 

Release: Frameworx Release 17.0

Status: Member Evaluation

Version: 1.1.0

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:

4 Century Drive
Suite 100
Parsippany, NJ 07054, 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 DESCRIPTION

RESOURCE MODEL CONFORMANCE

API MANDATORY AND OPTIONAL RESOURCES

Party Account MANDATORY AND OPTIONAL ATTRIBUTES

Billing Account MANDATORY AND OPTIONAL ATTRIBUTES

Settlement Account MANDATORY AND OPTIONAL ATTRIBUTES

Financial Account MANDATORY AND OPTIONAL ATTRIBUTES

Billing Cycle Specification MANDATORY AND OPTIONAL ATTRIBUTES

Bill Format MANDATORY AND OPTIONAL ATTRIBUTES

Bill Presentation Media MANDATORY AND OPTIONAL ATTRIBUTES

NOTIFICATION MODEL CONFORMANCE

API  MANDATORY AND OPTIONAL NOTIFICATIONS

API OPERATIONS CONFORMANCE

API MANDATORY AND OPTIONAL OPERATIONS

API GET OPERATION CONFORMANCE

/partyAccount?fields=...&{filtering}

/partyAccount/{id}?fields=...&{filtering}

/billingAccount?fields=...&{filtering}

/billingAccount/{id}?fields=...&{filtering}

/settlementAccount?fields=...&{filtering}

/settlementAccount/{id}?fields=...&{filtering}

/financialAccount?fields=...&{filtering}

/financialAccount/{id}?fields=...&{filtering}

/billingCycleSpecification?fields=...&{filtering}

/billingCycleSpecification/{id}?fields=...&{filtering}

/billFormat?fields=...&{filtering}

/billFormat/{id}?fields=...&{filtering}

/billPresentationMedia?fields=...&{filtering}

/billPresentationMedia/{id}?fields=...&{filtering}

API POST OPERATION CONFORMANCE

/partyAccount

/billingAccount

/settlementAccount

/financialAccount

/billingCycleSpecification

/billFormat

/billPresentationMedia

API PATCH OPERATION CONFORMANCE

/partyAccount/{id}

/billingAccount/{id}

/settlementAccount/{id}

/financialAccount/{id}

/billingCycleSpecification/{id}

/billFormat/{id}

/billPresentationMedia/{id}

API DELETE OPERATION CONFORMANCE

/partyAccount/{id}

/billingAccount/{id}

/settlementAccount/{id}

/financialAccount/{id}

/billingCycleSpecification/{id}

/billFormat/{id}

/billPresentationMedia/{id}

API CONFORMANCE TEST SCENARIOS

PartyAccount  resource TEST CASES

Release History

Introduction - API DESCRIPTION

The Account API provides standardized mechanism for the management of billing and settlement accounts, as well as for financial accounting (account receivable) either in B2B or B2B2C contexts.

It allows creation, update and retrieval of account information either in a B2B2C relationship context (creation of mass market customer billing account within a “Billing on Behalf of” process for example) or in a B2B context (creation of a billing/settlement account for a partner or B2B customer).

It also allows creation and query of bill items allowing partners or B2B customer to check their invoice.

Accounts typically refer to parties and party roles. However, the management of party and party roles is out of the scope of this API. The TMF APIs Party Management, Customer Management and Party Role Management can be used for this purpose.

 

RESOURCE MODEL CONFORMANCE

API MANDATORY AND OPTIONAL RESOURCES

For the resources defined by the API fill the following table and indicate which ones are mandatory and which ones are optional.

 

Resource Name

Mandatory or Optional

Comments

PartyAccount

M

 

BillingAccount

M

 

SettlementAccount

M

 

FinancialAccount

M

 

BillingCycleSpecification

M

 

BillFormat

M

 

BillPresentationMedia

M

 

 

 

Party Account MANDATORY AND OPTIONAL ATTRIBUTES

The table below summarizes mandatory and optional attributes for resource "PartyAccount"

 

Attribute Name

 

Mandatory or Optional

 

Comments

creditLimit

O

 

description

O

 

href

M (in response messages)
O (otherwise)

Url for the created resource

id

M (in response messages)
O (otherwise)

Generated by the server

lastModified

O

 

name

M (for resource creation)
O (otherwise)

 

state

O

 

type

O

 

paymentStatus

O

 

billStructure

O

 

paymentPlan

O

 

financialAccount

O

 

defaultPaymentMethod

O

 

relatedParty

O

 

taxExemption

O

 

contact

O

 

accountBalance

O

Attribute non patchable

accountRelationship

O

 

Billing Account MANDATORY AND OPTIONAL ATTRIBUTES

The table below summarizes mandatory and optional attributes for resource "BillingAccount"

 

Attribute Name

 

Mandatory or Optional

 

Comments

paymentStatus

O

 

creditLimit

O

 

description

O

 

href

M (in response messages)
O (otherwise)

Url for the created resource

id

M (in response messages)
O (otherwise)

Generated by the server

lastModified

O

 

name

M (for resource creation)
O (otherwise)

 

state

O

 

type

O

 

billStructure

O

 

paymentPlan

O

 

financialAccount

O

 

defaultPaymentMethod

O

 

relatedParty

O

 

taxExemption

O

 

contact

O

 

accountBalance

O

Attribute non patchable

accountRelationship

O

 

Settlement Account MANDATORY AND OPTIONAL ATTRIBUTES

The table below summarizes mandatory and optional attributes for resource "SettlementAccount"

 

Attribute Name

 

Mandatory or Optional

 

Comments

paymentStatus

O

 

creditLimit

O

 

description

O

 

href

M (in response messages)
O (otherwise)

Url for the created resource

id

M (in response messages)
O (otherwise)

Generated by the server

lastModified

O

 

name

M (for resource creation)
O (otherwise)

 

state

O

 

type

O

 

billStructure

O

 

paymentPlan

O

 

financialAccount

O

 

defaultPaymentMethod

O

 

relatedParty

O

 

taxExemption

O

 

contact

O

 

accountBalance

O

Attribute non patchable

accountRelationship

O

 

Financial Account MANDATORY AND OPTIONAL ATTRIBUTES

The table below summarizes mandatory and optional attributes for resource "FinancialAccount"

 

Attribute Name

 

Mandatory or Optional

 

Comments

creditLimit

O

 

description

O

 

href

M (in response messages)
O (otherwise)

Url for the created resource

id

M (in response messages)
O (otherwise)

Generated by the server

lastModified

O

Attribute non patchable

name

M (for resource creation)
O (otherwise)

 

state

O

 

type

O

 

relatedParty

O

 

taxExemption

O

 

contact

O

 

accountBalance

O

 

accountRelationship

O

 

Billing Cycle Specification MANDATORY AND OPTIONAL ATTRIBUTES

The table below summarizes mandatory and optional attributes for resource "BillingCycleSpecification"

 

Attribute Name

 

Mandatory or Optional

 

Comments

billingDateShift

O

 

billingPeriod

O

 

chargeDateOffset

O

 

creditDateOffset

O

 

description

O

 

frequency

O

 

href

M (in response messages)
O (otherwise)

Url for the created resource

id

M (in response messages)
O (otherwise)

Generated by the server

mailingDateOffset

O

 

name

M (for resource creation)
O (otherwise)

 

paymentDueDateOffset

O

 

validFor

O

 

Bill Format MANDATORY AND OPTIONAL ATTRIBUTES

The table below summarizes mandatory and optional attributes for resource "BillFormat"

 

Attribute Name

 

Mandatory or Optional

 

Comments

description

O

 

href

M (in response messages)
O (otherwise)

Url for the created resource

id

M (in response messages)
O (otherwise)

Generated by the server

name

M (for resource creation)
O (otherwise)

 

Bill Presentation Media MANDATORY AND OPTIONAL ATTRIBUTES

The table below summarizes mandatory and optional attributes for resource "BillPresentationMedia"

 

Attribute Name

 

Mandatory or Optional

 

Comments

description

O

 

href

M (in response messages)
O (otherwise)

Url for the created resource

id

M (in response messages)
O (otherwise)

Generated by the server

name

M (for resource creation)
O (otherwise)

 

NOTIFICATION MODEL CONFORMANCE

The Pub/Sub models are common and described in the TMF REST Design Guidelines.

 

API MANDATORY AND OPTIONAL NOTIFICATIONS

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

 

Notification Name

Mandatory or Optional

Comments

PartyAccountAttributeValueChangeNotification

M

 

PartyAccountStateChangeNotification

M

 

BillingAccountAttributeValueChangeNotification

M

 

BillingAccountStateChangeNotification

M

 

SettlementAccountAttributeValueChangeNotification

M

 

SettlementAccountStateChangeNotification

M

 

FinancialAccountCreationNotification

M

 

FinancialAccountAttributeValueChangeNotification

M

 

FinancialAccountStateChangeNotification

M

 

FinancialAccountRemoveNotification

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.

API MANDATORY AND OPTIONAL OPERATIONS

Fill the following table and indicate which ones are mandatory and which ones are optional for each one of the resources in the API (default is for all resources).

 

Uniform API Operation

Mandatory/Optional

Comments

GET

M for all resources

GET must be used to retrieve a representation of a resource

 

POST

M for resources:
PartyAccount
BillingAccount
SettlementAccount
FinancialAccount
BillingCycleSpecification
BillFormat
BillPresentationMedia

POST must be used to create a new resource

PATCH

M for resources:
PartyAccount
BillingAccount
SettlementAccount
FinancialAccount
BillingCycleSpecification
BillFormat
BillPresentationMedia

PATCH must be used to partially update a resource

DELETE

M for resources:
PartyAccount
BillingAccount
SettlementAccount
FinancialAccount
BillingCycleSpecification
BillFormat
BillPresentationMedia

DELETE must be used to remove a resource

 

API GET OPERATION CONFORMANCE

For every single resource use the following template to specify the mandatory and optional features supported by the GET operation.

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.:?severity=<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

 

/partyAccount?fields=...&{filtering}

This operation list party account entities.
Attribute selection is mandatory for all first level attributes.
Filtering is mandatory for first compliance level (L1) and optional otherwise.

/partyAccount/{id}?fields=...&{filtering}

This operation retrieves a party account entity.
Attribute selection is mandatory for all first level attributes.
Filtering on sub-resources is optional for all compliance levels.

/billingAccount?fields=...&{filtering}

This operation list billing account entities.
Attribute selection is mandatory for all first level attributes.
Filtering is mandatory for first compliance level (L1) and optional otherwise.

/billingAccount/{id}?fields=...&{filtering}

This operation retrieves a billing account entity.
Attribute selection is mandatory for all first level attributes.
Filtering on sub-resources is optional for all compliance levels.

/settlementAccount?fields=...&{filtering}

This operation list settlement account entities.
Attribute selection is mandatory for all first level attributes.
Filtering is mandatory for first compliance level (L1) and optional otherwise.

/settlementAccount/{id}?fields=...&{filtering}

This operation retrieves a settlement account entity.
Attribute selection is mandatory for all first level attributes.
Filtering on sub-resources is optional for all compliance levels.

/financialAccount?fields=...&{filtering}

This operation list financial account entities.
Attribute selection is mandatory for all first level attributes.
Filtering is mandatory for first compliance level (L1) and optional otherwise.

/financialAccount/{id}?fields=...&{filtering}

This operation retrieves a financial account entity.
Attribute selection is mandatory for all first level attributes.
Filtering on sub-resources is optional for all compliance levels.

/billingCycleSpecification?fields=...&{filtering}

This operation list billing cycle specification entities.
Attribute selection is mandatory for all first level attributes.
Filtering is mandatory for first compliance level (L1) and optional otherwise.

/billingCycleSpecification/{id}?fields=...&{filtering}

This operation retrieves a billing cycle specification entity.
Attribute selection is mandatory for all first level attributes.
Filtering on sub-resources is optional for all compliance levels.

/billFormat?fields=...&{filtering}

This operation list bill format entities.
Attribute selection is mandatory for all first level attributes.
Filtering is mandatory for first compliance level (L1) and optional otherwise.

/billFormat/{id}?fields=...&{filtering}

This operation retrieves a bill format entity.
Attribute selection is mandatory for all first level attributes.
Filtering on sub-resources is optional for all compliance levels.

/billPresentationMedia?fields=...&{filtering}

This operation list bill presentation media entities.
Attribute selection is mandatory for all first level attributes.
Filtering is mandatory for first compliance level (L1) and optional otherwise.

/billPresentationMedia/{id}?fields=...&{filtering}

This operation retrieves a bill presentation media entity.
Attribute selection is mandatory for all first level attributes.
Filtering on sub-resources is optional for all compliance levels.

API POST OPERATION CONFORMANCE

 

For every single resource use the following template to specify the mandatory and optional features supported by the POST operation.

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

POST

M

 

Status Code 201

M

 

Other Status Codes

NA

 

/partyAccount

This operation creates a party account entity.

Mandatory and Non- Mandatory Attributes

The following tables provides the list of mandatory and non-mandatory attributes when creating a PartyAccount, including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add additional mandatory attributes.

Mandatory Attributes

Rule

name

 

 

Non- Mandatory Attributes

Default Value

Rule

creditLimit

 

 

description

 

 

lastModified

 

 

state

 

 

type

 

 

paymentStatus

 

 

billStructure

 

 

paymentPlan

 

 

financialAccount

 

 

defaultPaymentMethod

 

 

relatedParty

 

 

taxExemption

 

 

contact

 

 

accountBalance

 

 

accountRelationship

 

 

 

Default Values Summary

When creating the resource, the following table summarizes the default values applicable to optional attributes of the resource (or sub-resources).

Attributes

Default Value

validFor.startDateTime

Current date

billStructure.cycleSpecification.name

"Bill issuer choice"

billStructure.format.name

"Standard invoice"

billStructure.presentationMedia.name

"Electronic invoice"

/billingAccount

This operation creates a billing account entity.

Mandatory and Non- Mandatory Attributes

The following tables provides the list of mandatory and non-mandatory attributes when creating a BillingAccount, including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add additional mandatory attributes.

Mandatory Attributes

Rule

name

 

 

Non- Mandatory Attributes

Default Value

Rule

paymentStatus

 

 

creditLimit

 

 

description

 

 

lastModified

 

 

state

 

 

type

 

 

billStructure

 

 

paymentPlan

 

 

financialAccount

 

 

defaultPaymentMethod

 

 

relatedParty

 

 

taxExemption

 

 

contact

 

 

accountBalance

 

 

accountRelationship

 

 

 

Default Values Summary

When creating the resource, the following table summarizes the default values applicable to optional attributes of the resource (or sub-resources).

Attributes

Default Value

validFor.startDateTime

Current date

billStructure.cycleSpecification.name

"Bill issuer choice"

billStructure.format.name

"Standard invoice"

billStructure.presentationMedia.name

"Electronic invoice"

/settlementAccount

This operation creates a settlement account entity.

Mandatory and Non- Mandatory Attributes

The following tables provides the list of mandatory and non-mandatory attributes when creating a SettlementAccount, including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add additional mandatory attributes.

Mandatory Attributes

Rule

name

 

 

Non Mandatory Attributes

Default Value

Rule

paymentStatus

 

 

creditLimit

 

 

description

 

 

lastModified

 

 

state

 

 

type

 

 

billStructure

 

 

paymentPlan

 

 

financialAccount

 

 

defaultPaymentMethod

 

 

relatedParty

 

 

taxExemption

 

 

contact

 

 

accountBalance

 

 

accountRelationship

 

 

 

Default Values Summary

When creating the resource, the following table summarizes the default values applicable to optional attributes of the resource (or sub-resources).

Attributes

Default Value

validFor.startDateTime

Current date

billStructure.cycleSpecification.name

"Bill issuer choice"

billStructure.format.name

"Standard invoice"

billStructure.presentationMedia.name

"Electronic invoice"

/financialAccount

This operation creates a financial account entity.

Mandatory and Non- Mandatory Attributes

The following tables provides the list of mandatory and non-mandatory attributes when creating a FinancialAccount, including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add additional mandatory attributes.

Mandatory Attributes

Rule

name

 

 

Non Mandatory Attributes

Default Value

Rule

creditLimit

 

 

description

 

 

lastModified

Automatically generated

 

state

 

 

type

 

 

relatedParty

 

 

taxExemption

 

 

contact

 

 

accountBalance

 

 

accountRelationship

 

 

 

Additional Rules

The following table provides additional rules indicating mandatory fields in sub-resources or relationships when creating a FinancialAccount resource.

Context

Mandatory Sub-Attributes

taxExemption

issuingJurisdiction, validFor

accountRelationship

relationshipType, validFor

contact

contactType, validFor

accountBalance

type, amount, validFor, status

paymentPlan

status, amount, paymentFrequency, validFor, paymentMethod

 

Default Values Summary

When creating the resource, the following table summarizes the default values applicable to optional attributes of the resource (or sub-resources).

Attributes

Default Value

id

Automatically generated

href

Automatically generated

lastModified

Automatically generated

/billingCycleSpecification

This operation creates a billing cycle specification entity.

Mandatory and Non- Mandatory Attributes

The following tables provides the list of mandatory and non-mandatory attributes when creating a BillingCycleSpecification, including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add additional mandatory attributes.

Mandatory Attributes

Rule

name

 

 

Non- Mandatory Attributes

Default Value

Rule

billingDateShift

 

 

billingPeriod

 

 

chargeDateOffset

 

 

creditDateOffset

 

 

description

 

 

frequency

 

 

mailingDateOffset

 

 

paymentDueDateOffset

 

 

validFor

 

 

/billFormat

This operation creates a bill format entity.

Mandatory and Non- Mandatory Attributes

The following tables provides the list of mandatory and non-mandatory attributes when creating a BillFormat, including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add additional mandatory attributes.

Mandatory Attributes

Rule

name

 

 

Non- Mandatory Attributes

Default Value

Rule

description

 

 

/billPresentationMedia

This operation creates a bill presentation media entity.

Mandatory and Non- Mandatory Attributes

The following tables provides the list of mandatory and non-mandatory attributes when creating a BillPresentationMedia, including any possible rule conditions and applicable default values. Notice that it is up to an implementer to add additional mandatory attributes.

Mandatory Attributes

Rule

name

 

 

Non- Mandatory Attributes

Default Value

Rule

description

 

 

 

 

 

API PATCH OPERATION CONFORMANCE

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

PATCH

O

 

Status Code 201

M

 

Other Status Codes

NA

 

/partyAccount/{id}

This operation allows partial updates of a party account 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

creditLimit

 

description

 

lastModified

 

name

 

state

 

type

 

paymentStatus

 

billStructure

 

paymentPlan

 

financialAccount

 

defaultPaymentMethod

 

relatedParty

 

taxExemption

 

contact

 

accountRelationship

 

 

Non- Patchable Attributes

Rule

id

 

href

 

accountBalance

 

creditLimit

 

description

 

lastModified

 

name

 

state

 

type

 

paymentStatus

 

billStructure

 

paymentPlan

 

financialAccount

 

defaultPaymentMethod

 

relatedParty

 

taxExemption

 

contact

 

accountRelationship

 

/billingAccount/{id}

This operation allows partial updates of a billing account 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.
Notice that patching is possible only for 'admin' API users.

Patchable Attributes

Rule

billStructure.cycleSpecification

 

billStructure.format

 

billStructure.presentationMedia

 

paymentStatus

 

creditLimit

 

description

 

lastModified

 

name

 

state

 

type

 

billStructure

 

paymentPlan

 

financialAccount

 

defaultPaymentMethod

 

relatedParty

 

taxExemption

 

contact

 

accountRelationship

 

 

Non- Patchable Attributes

Rule

id

 

href

 

accountBalance

 

paymentStatus

 

creditLimit

 

description

 

lastModified

 

name

 

state

 

type

 

billStructure

 

paymentPlan

 

financialAccount

 

defaultPaymentMethod

 

relatedParty

 

taxExemption

 

contact

 

accountRelationship

 

/settlementAccount/{id}

This operation allows partial updates of a settlement account 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.
Notice that patching is possible only for 'admin' API users.

Patchable Attributes

Rule

billStructure.cycleSpecification

 

billStructure.format

 

billStructure.presentationMedia

 

paymentStatus

 

creditLimit

 

description

 

lastModified

 

name

 

state

 

type

 

billStructure

 

paymentPlan

 

financialAccount

 

defaultPaymentMethod

 

relatedParty

 

taxExemption

 

contact

 

accountRelationship

 

 

Non- Patchable Attributes

Rule

id

 

href

 

accountBalance

 

paymentStatus

 

creditLimit

 

description

 

lastModified

 

name

 

state

 

type

 

billStructure

 

paymentPlan

 

financialAccount

 

defaultPaymentMethod

 

relatedParty

 

taxExemption

 

contact

 

accountRelationship

 

/financialAccount/{id}

This operation allows partial updates of a financial account 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

creditLimit

 

description

 

name

 

state

 

type

 

relatedParty

 

taxExemption

 

contact

 

accountBalance

 

accountRelationship

 

 

Non- Patchable Attributes

Rule

id

 

href

 

lastModified

 

creditLimit

 

description

 

name

 

state

 

type

 

relatedParty

 

taxExemption

 

contact

 

accountBalance

 

accountRelationship

 

/billingCycleSpecification/{id}

This operation allows partial updates of a billing cycle specification 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

billingDateShift

 

billingPeriod

 

chargeDateOffset

 

creditDateOffset

 

description

 

frequency

 

mailingDateOffset

 

name

 

paymentDueDateOffset

 

validFor

 

 

Non- Patchable Attributes

Rule

id

 

href

 

billingDateShift

 

billingPeriod

 

chargeDateOffset

 

creditDateOffset

 

description

 

frequency

 

mailingDateOffset

 

name

 

paymentDueDateOffset

 

validFor

 

/billFormat/{id}

This operation allows partial updates of a bill format 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.
Notice that patching is possible only for 'admin' API users.

Patchable Attributes

Rule

description

 

name

 

 

Non Patchable Attributes

Rule

id

 

href

 

description

 

name

 

/billPresentationMedia/{id}

This operation allows partial updates of a bill presentation media 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.
Notice that patching is possible only for 'admin' API users.

Patchable Attributes

Rule

description

 

name

 

 

Non- Patchable Attributes

Rule

id

 

href

 

description

 

name

 

API DELETE OPERATION CONFORMANCE

 

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

DELETE

O

 

Status Code 200

M

 

Other Status Codes

NA

 

/partyAccount/{id}

This operation deletes a party account entity.

/billingAccount/{id}

This operation deletes a billing account entity.

/settlementAccount/{id}

This operation deletes a settlement account entity.

/financialAccount/{id}

This operation deletes a financial account entity.

/billingCycleSpecification/{id}

This operation deletes a billing cycle specification entity.

/billFormat/{id}

This operation deletes a bill format entity.

/billPresentationMedia/{id}

This operation deletes a bill presentation media entity.

API CONFORMANCE TEST SCENARIOS

This section describes the test scenarios required for the basic CONNECT certification of the 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}/partyAccount/v1 , where {serverRoot} defines the certification endpoint

For convenience we provide the test cases for only the PartyAccount resource. For the other kinds of accounts, the test cases are similar. Simply replace the PartyAccount by the actual resource being considered.

PartyAccount resource TEST CASES

 

Nominal Scenarios

TC_Trou_N1 – Create new PartyAccount with minimum required information

  • Send a POST message to {apiRoot}/partyAccount/ with the following contents in the BODY

{

    "name": "MyAccount",

}

  • Wait for a response from the server with the following characteristics

 

-           Response Code 201-Created

 

-           Include a location header in the body set to /{apiRoot}/partyAccount/{IDtt1} where {IDtt1} indicates the identifier assigned by the server to the new PartyAccount resource

 

-           The response message includes all mandatory parameters (including description, severity and type that were not sent in the original request)

 

-           The body of the response matches the values set in the original request

 

  • Send a GET message to /{apiRoot}/partyAccount/

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one PartyAccount resource with ID set to {IDtt1}, the same identifier as assigned by the server to the new resource created

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDtt1} matches the values set in the original request

 

  • Send a GET message to /{apiRoot}/partyAccount/{IDtt1}

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The response message includes all mandatory parameters

 

-           The body of the response includes a PartyAccount resource structure that matches the values in the original request

 

 

TC_Trou_N2 – Search for PartyAccounts with specific characteristics

  • Send a GET message to /{apiRoot}/partyAccount

 

  • Wait for a response from the server with the following characteristics

-           Response Code 200-OK

 

-           The body of the response includes at least two PartyAccount resources referring to {IDtt1} and {IDtt2}

 

-           The body of the response for the resource with each identifier matches the values in the corresponding original request

 

  • Send a GET message to /{apiRoot}/ partyAccount?type=joint

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one PartyAccount resource referring to {IDtt1} and there is no reference to PartyAccount resource {IDtt2}

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDtt1} matches the values in the original request

 

  • Send a GET message to /{apiRoot}/partyAccount?state=Active

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one PartyAccount resource referring to {IDtt2} and there is no reference to PartyAccount resource {IDtt1}

 

-           The response message includes all mandatory parameters

 

-           The body of the response for the resource with identifier {IDtt2} matches the values in the original request

 

 

TC_Trou_N3 – Filtered retrieval of PartyAccounts

  • Send a GET message to /{apiRoot}/partyAccount/{IDtt1}?fields=state

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one PartyAccount resource referring to {IDtt1} and including only attributes name and status, matching the values in the original request

 

  • Send a GET message to /{apiRoot}/ partyAccount /{IDtt2}?fields=state,type

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one PartyAccount resource referring to {IDtt2} and including only attributes severity and status, matching the values in the original request

Notice that this test case is using some specific parameters to filter the data included in the response but any other parameter could be used

 

TC_Trou_N4 – Filtered Search and Filtered data response

  • Send a GET message to /{apiRoot}/partyAccount?state=Active&fields=state,type

 

  • Wait for a response from the server with the following characteristics

 

-           Response Code 200-OK

 

-           The body of the response includes one PartyAccountresource referring to {IDtt1} and there is no reference to PartyAccount resource {IDtt2}

 

-           The body of the response for the resource with each identifier includes only attribute description, matching the values in the corresponding original request

Notice that this test case is using the parameter ”description” to filter the data included in the response  but any other parameter could be used

 

Error Scenarios

TC_Trou_E1 – Unknown PartyAccount identifier

  • Send a GET message to /{apiRoot}/partyAccount/{IDtt3}, where {IDtt3} does not match any of the identifiers previously creted in the server

 

  • Wait for a response from the server with the following characteristics

 

  • Response Code 404-Not Found

 

TC_Trou_E2 – Invalid Request – Missing mandatory parameter

  • Send a POST message to {apiRoot}/partyAccount/ with the following contents in the BODY.

{

}

 

Notice that this request is missing mandatory parameter ”name” but any other mandatory parameter could be used

 

  • Wait for an error response from the server indicating the mandatory parameter is missing in the request

Release History

 

Release Number

Date

Release led by:

Description

Release 1.0

07/15/2015

Pierre Gauthier

TM Forum

pgauthier@tmforum.orf

 

First Release of Draft Version of the Document.

Release 1.1

03/15/2017

 

Updated version including Test scenarios