TM Forum Ecosystem API Portal

Space shortcuts

Page tree

Versions Compared

Old Version 7

changes.mady.by.user Unknown User ([email protected])

Saved on

compared with

New Version Current

changes.mady.by.user Unknown User ([email protected])

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Hide If
special@authenticated
Note
titleTo access this API specification you wil need to be logged in

To login with your TM Forum account please click on the Login button below

Button Hyperlink
titleLogin
typeprimary
urlhttps://projects.tmforum.org/wiki/login.action?os_destination=%2Fdisplay%2FAPI%2FOpen%2BAPI%2BTable

Don't have an account? You can register by clicking here:

Button Hyperlink
titleRegister
typeprimary
urlhttps://www.tmforum.org/user-registration/
targettrue

Show If
special@authenticated

For every single of operation on the entities use the following templates and provide sample REST requests and responses.
Remember that the following Uniform Contract rules must be used :

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.

GET API/billingManagement/ BillingAccount /{ID}

Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :

  • Operation to retrieve BillingAccount (s) in a BillingAccount repository
  • Filtering is enabled for all attributes
  • Attribute selection is enabled for all attributes
  • The resource is either a managed entity (query by id) or a collection (query with criteria)
  • The resource identifier is a http uri


Behavior :

  • Standard behavior and response codes for GET operations

We mandate L0 (equality) filtering in every specification as per REST Guidelines.
Example: Retrieve BillingAccount 65.

REQUEST

GET /billingManagement/billingAccount/65
Accept: application/json

RESPONSE

{
"id": "65",
"href": "http://serverlocation:port/billingManagement/billingAccount/65",
"ratingType": "postpaid",
"name": "my personal Billing Account",
"state": "Active",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"customerAccount": {
"id": "15",
"href": "http://serverlocation:port/customerManagement/customerAccount/15",
"name": "Customer Account xxx"
},
"customerBillingCycleSpecification": {
"id": "26",
"href": "http://serverlocation:port/billingManagement/customerbillingCycleSpecification/26",
"name": "Monthly billing on the 15"
},
"customerBillFormat": {
"id": "23",
"href": "http://serverlocation:port/billingManagement/customerBillFormat/23",
"name": "Detailed invoice"
},
"customerBillPresentationMedia": {
"id": "25",
"href": "http://serverlocation:port/billingManagement/customerBillPresentationMedia/25",
"name": "Electronic invoice"
},
"currency": {
"currencyCode": "EUR"
},
"billingAccountBalance": [
{
"type": "ReceivableBalance",
"amount": 52.3,
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
},
"status": "Due"
}
],
"relatedParty": [
{
"id": "1",
"href": "http://serverlocation:port/partyManagement/partyRole/1",
"role": "bill receiver"
},
{
"id": "5",
"href": "http://serverlocation:port/partyManagement/partyRole/5",
"role": "bill responsible"
}
],
"paymentMean": {
"id": "45",
"href": "http://serverlocation:port/customerManagement/paymentMean/45",
"name": "my favourite payment mean"
}
}

PUT API/BillingManagement/BillingAccount/{ID}

No put operation for BillingAccount

PATCH API/billingManagement/ BillingAccount /{ID}

This Uniform Contract operation is used to partially update the representation of a managed entity or a task.
Description :

  • Provide an overall description of the Operation
  • Describe the input representation of the <resource> instance.
  • Describe if the resource represents a managed entity or a task.
  • Describe the structure of the identifier.

Behavior :

  • What status and exception codes are returned.
  • Returns HTTP/1.1 status code 201 if the request was successful.

  • Any other special return and/or exception codes.

    Attribute name

    Patchable

    error

    RatingType

    No

     

    Name

    Y

     

    Valid for. startDateTime

    Y

     

    Valid for:endDateTime

    Y

    After the start date

    CustomerAccount.id

    Y

    Should exist

    CustomerBillingCycleSpecification.id

    Y

     

    CustomerBillFormat.id

    Y

     

    CustomerBillPresentationMedia.id

    Y

     

    Currency code

    Y

     

    PaymentMean.id

    Y

     

    RelatedParty.id

    Y

    Bill receiver is mandatory

    State

    Y

    Transition state should be valid (need further work in financial entities)

    BillingAccountBalance

    N

     


    No additional complex rules for patching attributes.
    Example : Update BillingAccount 65 : change of customer bill presentation media.

    REQUEST

    PATCH billingManagement/billingAccount/65
    Content-type: application/json
    {
    "customerBillPresentationMedia": {
    "id": "78",
    "href": http://serverlocation:port/billingManagement/customerBillPresentationMedia/78"}
    }

    RESPONSE

    201
    Content-Type: application/json
    {
    "customerBillPresentationMedia": {
    "id": "78",
    "href": http://serverlocation:port/billingManagement/customerBillPresentationMedia/78",
    "name": "Paper invoice"
    }
    }

    POST API/bILLING Management/BillingAccount

    This operation is used to create a BillingAccount.
    Pre-conditions:
    We assume that the customer and the customer account have been already defined. The bill receiver contact also exists.
    All reference data have been already defined.
    Description :
  • Provides an overall description of the Operation
  • Describes the input representation of the <resource> instance.
  • Describes if the resource represents a managed entity or a task.
  • Describes the structure of the identifier.

Mandatory attributes are :

Attribute name

Mandatory

Default

error

RatingType

N

Postpaid

 

Name

N

Customer name

 

Valid for. startDateTime

N

Today

Valid date not earlier than one bill cycle in the past

Valid for:endDateTime

N

 

After the start date

CustomerAccount.id

Y

 

Should exist (see precondition)

CustomerBillingCycleSpecification.id

N

Bill issuer choice

 

CustomerBillFormat.id

N

Standard invoice

 

CustomerBillPresentationMedia.id

N

Electronic invoice

 

Currency code

N

National currency

 

PaymentMean

N

Customer choice

 

RelatedParty.id

Y

 

Bill receiver is mandatory (see precondition)

BillingAccountBalance.id

N

 

 


Additional rules

Rule name

Rule

POST Preconditions

Customer account must have been created previously
Party role must exist

Behavior :

  • Standard POST behavior

Example : creation of a BillingAccount

REQUEST

POST billingManagement/billingAccount
Content-type: application/json
{
"ratingType": "postpaid",
"name": "my personal Billing Account",
"state": "active",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"customerAccount": {
"id": "45",
"href": "http://serverlocation:port/customerManagement/customerAccount/15",
"name": "Customer Account xxx"
},
"customerBillingCycleSpecification": {
"id": "26",
"href": "http://serverlocation:port/billingManagement/customerbillingCycleSpecification/26",
"name": "Monthly billing on the 15"
},
"customerBillFormat": {
"id": "23",
"href": "http://serverlocation:port/billingManagement/customerBillFormat/23",
"name": "Detailed invoice"
},
"customerBillPresentationMedia": {
"id": "25",
"href": "http://serverlocation:port/billingManagement/customerBillPresentationMedia/25",
"name": "Electronic invoice"
},
"currency": {
"currencyCode": "EUR"
},
"billingAccountBalance": [
{
"type": "ReceivableBalance",
"amount": 52.3,
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
},
"status": "Due"
}
],
"relatedParty": [
{
"id": "1",
"href": "http://serverlocation:port/partyManagement/partyRole/1",
"role": "bill receiver"
},
{
"id": "5",
"href": "http://serverlocation:port/partyManagement/partyRole/5",
"role": "bill responsible"
}
],
"paymentMean": {
"id": "45",
"href": "http://serverlocation:port/customerManagement/paymentMean/45",
"name": "my favourite payment mean"
}
}

RESPONSE

201
Content-Type: application/json
{
"id": "65",
"href": "http://serverlocation:port/billingManagement/billingAccount/65",
"ratingType": "postpaid",
"name": "my personal Billing Account",
"state": "Active",
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z"
},
"customerAccount": {
"id": "15",
"href": "http://serverlocation:port/customerManagement/customerAccount/15",
"name": "Customer Account xxx"
},
"customerBillingCycleSpecification": {
"id": "26",
"href": "http://serverlocation:port/billingManagement/customerbillingCycleSpecification/26",
"name": "Monthly billing on the 15"
},
"customerBillFormat": {
"id": "23",
"href": "http://serverlocation:port/billingManagement/customerBillFormat/23",
"name": "Detailed invoice"
},
"customerBillPresentationMedia": {
"id": "25",
"href": "http://serverlocation:port/billingManagement/customerBillPresentationMedia/25",
"name": "Electronic invoice"
},
"currency": {
"currencyCode": "EUR"
},
"billingAccountBalance": [
{
"type": "ReceivableBalance",
"amount": 52.3,
"validFor": {
"startDateTime": "2013-04-19T16:42:23.0Z",
"endDateTime": "2013-06-19T00:00:00.0Z"
},
"status": "Due"
}
],
"relatedParty": [
{
"id": "1",
"href": "http://serverlocation:port/partyManagement/partyRole/1",
"role": "bill receiver"
},
{
"id": "5",
"href": "http://serverlocation:port/partyManagement/partyRole/5",
"role": "bill responsible"
}
],
"paymentMean": {
"id": "45",
"href": "http://serverlocation:port/customerManagement/paymentMean/45",
"name": "my favourite payment mean"
}
}

DELETE API/billingManagement/BillingAccount/{ID}

No delete operation for the BillingAccount.

REQUEST

 

RESPONSE

 

POST API/bILLING Management/AppliedCustomerbillingcharge

This operation is used to create applied customer billing charges..
Note: Adjustment needs another API to cover invoice adjustment and charge adjustment.
Pre-conditions:
Description :

  • Provides an overall description of the Operation
  • Describes the input representation of the <resource> instance.
  • Describes if the resource represents a managed entity or a task.
  • Describes the structure of the identifier.

Mandatory attributes are :

Attribute name

Mandatory

Default

error

date

N

Today

 

description

N

 

 

type

Y

 

Recurring, non recurring, usage, …

currencyCode

Y

 

 

taxIncludedAmount

N

 

 

taxExcludedAmount

Y

 

 

taxRate.amount

N

 

 

service.id

Y

 

400 if service.id is invalid

service.idType

N

 

 

productSpecification.name

Y

 

 

productSpecification.productNumber

N

 

 

period.startPeriod

N

 

Only mandatory for recurring charge

period.endPeriod

N

 

Only mandatory for recurring charge


Additional rules

Rule name

Rule

POST Preconditions

Service must have been created previously
productSpecification must have been created previously


Behavior :

  • Standard POST behavior


Example : creation of applied customer billing charge

REQUEST

POST billingManagement/appliedCustomerBillingCharge
Content-type: application/json
{
"date": "2013-04-19T16:42:23.0Z",
"description": "Partner Premium monthly fee",
"type": "recurring",
"currencyCode": "USD",
"taxIncludedAmount": 2.4,
"taxExcludedAmount": 2,
"appliedCustomerBillingTaxRate": [
{
"amount": 0.4,
"taxCategory": "VAT"
}
],
"serviceId": [
{
"id": "0601020304",
"type": "Mobile number"
}
],
"productSpecification": [
{
"name": "Partner Premium",
"productNumber": "P001"
}
],
"period": [
{
"startPeriod": "2013-10-01T00:00:00.0Z",
"endPeriod": "2013-10-31T00:00:00.0Z"
}
]
}

RESPONSE

201
Content-Type: application/json
{
"id": "25",
"href": "http://serverlocation:port/BillingManagement/appliedCustomerBillingCharge/25",
"date": "2013-04-19T16:42:23.0Z",
"description": "Partner Premium monthly fee",
"type": "recurring",
"currencyCode": "USD",
"taxIncludedAmount": 2.4,
"taxExcludedAmount": 2,
"appliedCustomerBillingTaxRate": [
{
"amount": 0.4,
"taxCategory": "VAT"
}
],
"serviceId": [
{
"id": "0601020304",
"type": "Mobile number"
}
],
"productSpecification": [
{
"name": "Partner Premium",
"productNumber": "P001"
}
],
"period": [
{
"startPeriod": "2013-10-01T00:00:00.0Z",
"endPeriod": "2013-10-31T00:00:00.0Z"
}
]
}

GET API/bILLING Management/AppliedCustomerbillingcharge

Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :

  • Operation to retrieve AppliedCustomerBillingCharge (s) in a repository
  • Filtering is enabled for all attributes
  • Attribute selection is enabled for all attributes
  • The resource is either a managed entity (query by id) or a collection (query with criteria)
  • The resource identifier is a http uri


Behavior :

  • Standard behavior and response codes for GET operations

Behavior :

  • Standard GET behavior

We mandate L0 (equality) filtering in every specification as per REST Guidelines
Example: retrieval of applied customer billing charges

REQUEST

GET billingManagement/appliedCustomerBillingCharge?service.id=0601020304
Content-type: application/json

RESPONSE

{
"id": "25",
"href": "http://serverlocation:port/BillingManagement/appliedCustomerBillingCharge/25",
"date": "2013-04-19T16:42:23.0Z",
"description": "Partner Premium monthly fee",
"type": "recurring",
"currencyCode": "USD",
"taxIncludedAmount": 2.4,
"taxExcludedAmount": 2,
"appliedCustomerBillingTaxRate": [
{
"amount": 0.4,
"taxCategory": "VAT"
}
],
"serviceId": [
{
"id": "0601020304",
"type": "Mobile number"
}
],
"productSpecification": [
{
"name": "Partner Premium",
"productNumber": "P001"
}
],
"period": [
{
"startPeriod": "2013-10-01T00:00:00.0Z",
"endPeriod": "2013-10-31T00:00:00.0Z"
}
]
}

DELETE API/billingManagement/ appliedCustomerBillingCharge /{ID}

No delete operation for the AppliedCustomerBillingCharge

REQUEST

 

RESPONSE

 

PATCH API/billingManagement/ appliedCustomerBillingCharge /{ID}

No patch operation for the AppliedCustomerBillingCharge

REQUEST

 

RESPONSE

 

PUT API/billingManagement/ appliedCustomerBillingCharge /{ID}

No put operation for the AppliedCustomerBillingCharge

REQUEST

 

RESPONSE

 

GET API/bILLINGManagement/SettlementnoteADVICE /{ID}

Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :

  • Operation to retrieve SettlementNoteAdvice (s) in a repository
  • Filtering is enabled for all attributes
  • Attribute selection is enabled for all attributes
  • The resource is either a managed entity (query by id) or a collection (query with criteria)
  • The resource identifier is a http uri


Behavior :

  • Standard behavior and response codes for GET operations

Behavior :

  • Standard GET behavior

We mandate L0 (equality) filtering in every specification as per REST Guidelines
Example: get a settlement note advice

REQUEST

GET billingManagement/settlementNoteAdvice?id=26
Content-type: application/json

RESPONSE

Status:200
Content-Type: application/json
Last-Modified:11/28/13 13:30:30
{
"id": "26",
"href": "http://serverlocation:port/BillingManagement/settlementNoteAdvice/26",
"date": "2013-04-19T16:42:23.0Z",
"description": "Settlement note â€" From 2013/10/01 to 2013/10/31",
"paymentDueDate": "2013-04-19T16:42:23.0Z",
"taxDate": "2013-04-19T16:42:23.0Z",
"currencyCode": "EUR",
"taxExcludedAmount": 89933.25,
"taxIncludedAmount": 107560.16,
"taxItem": [
{
"taxCategory": "VAT",
"taxRate": 19.6,
"taxAmount": 17626.91
}
],
"settlementMethod": {
"code": "NET",
"label": "Netting"
},
"receiver": {
"id": "63796",
"href": "http://serverlocation:port/PartyManagement/partyRole/63796",
"taxRegistration": {
"number": "FR12345678912"
}
},
"issuer": {
"id": "0800",
"href": "http://serverlocation:port/PartyManagement/partyRole/0800",
"taxRegistration": {
"number": "FR98765432178"
}
},
"settlementNoteImage": {
"imageFormat": "pdf",
"imageSize": 130,
"imageFileName": "BungiornoFrance-2013October-1234",
"imageFileURL": "http://serverlocation:port/SettlementNoteImage/RQAAAABAAAAAAAAALryCQAbAAAAMAAxAF8ASQBuAHMAdABhAGwAb"
},
"settlementNoteItem": [
{
"itemNumber": "1",
"itemId": "0815",
"itemLabel": "Achats Gamifive",
"quantity": 34873,
"taxExcludedUnitPrice": 1.463,
"taxExcludedAmount": 51019.2,
"taxIncludedAmount": 61018.96,
"taxItem": [
{
"taxCategory": "VAT",
"taxRate": 19.6,
"taxAmount": 9999.76
}
],
"period": {
"startPeriod": "2013-10-01T00:00:00.0Z",
"endPeriod": "2013-10-31T00:00:00.0Z"
},
"productSpecification": {
"name": "Gamifive",
"productNumber": "17060"
}
},
{
"itemNumber": "2",
"itemId": "0816",
"itemLabel": "Achats iGirls TV",
"quantity": 19001,
"taxExcludedUnitPrice": 2.048,
"taxExcludedAmount": 38914.05,
"taxIncludedAmount": 46541.2,
"period": {
"startPeriod": "2013-10-01T00:00:00.0Z",
"endPeriod": "2013-10-31T00:00:00.0Z"
},
"productSpecification": {
"name": "iGirls TV",
"productNumber": "17063"
}
}
]
}

DELETE API/billingManagement/ Settlement note ADVICE /{ID}

No delete operation for the SettlementNoteAdvice

REQUEST

 

RESPONSE

 

PATCH API/billingManagement/ Settlement note ADVICE /{ID}

No patch operation for the SettlementNoteAdvice

REQUEST

 

RESPONSE

 

PUT API/billingManagement/ Settlement note ADVICE /{ID}

No put operation for the SettlementNoteAdvice

REQUEST

 

RESPONSE

 

POST API/billingManagement/ Settlement note ADVICE /{ID}

No post operation for the SettlementNoteAdvice

REQUEST

 

RESPONSE

 

GET API/bILLING Management/ CUSTOMER BILLING CYCLE Specification

Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :

  • Operation to retrieve CustomerBillingCycleSpecification (s) in a repository
  • Filtering is enabled for all attributes
  • Attribute selection is enabled for all attributes
  • The resource is either a managed entity (query by id) or a collection (query with criteria)
  • The resource identifier is a http uri


Behavior :

  • Standard behavior and response codes for GET operations

Behavior :

  • Standard GET behavior

We mandate L0 (equality) filtering in every specification as per REST Guidelines
Example: CustomerBillingCycleSpecification retrieval

REQUEST

GET billingManagement/customerBillingCycleSpecification/26
Content-type: application/json

RESPONSE

Status:200
Content-Type: application/json
Last-Modified:11/28/13 13:30:30
{
"id": "26",
"href": "http://serverlocation:port/billingManagement/customerbillingCycleSpecification/26",
"name": "Monthly billing on the 15",
"billingDateShift": 15,
"frequency": "monthly"
}

GET API/bILLING Management/ CUSTOMER BILL Format

Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :

  • Operation to retrieve CustomerBillFormat (s) in a repository
  • Filtering is enabled for all attributes
  • Attribute selection is enabled for all attributes
  • The resource is either a managed entity (query by id) or a collection (query with criteria)
  • The resource identifier is a http uri


Behavior :

  • Standard behavior and response codes for GET operations

Behavior :

  • Standard GET behavior

We mandate L0 (equality) filtering in every specification as per REST Guidelines
Example: CustomerBillFormat retrieval

REQUEST

GET billingManagement/customerBillFormat/26
Content-type: application/json

RESPONSE

Status:200
Content-Type: application/json
Last-Modified:11/28/13 13:30:30
{
"id": "26",
"href": "http://serverlocation:port/billingManagement/customerBillFormat/26",
"name": "Detailed invoice"
}

GET API/bILLING Management/ CUSTOMER BILL Presentation Media

Note that collections can be retrieved via GET /api/<RESOURCE> with no {ID}
Description :

  • Operation to retrieve CustomerBillPresentationMedia (s) in a repository
  • Filtering is enabled for all attributes
  • Attribute selection is enabled for all attributes
  • The resource is either a managed entity (query by id) or a collection (query with criteria)
  • The resource identifier is a http uri


Behavior :

  • Standard behavior and response codes for GET operations

Behavior :

  • Standard GET behavior

We mandate L0 (equality) filtering in every specification as per REST Guidelines
Example: CustomerBillPresentationMedia retrieval

REQUEST

GET billingManagement/customerBillPresentationMedia/26
Content-type: application/json

RESPONSE

Status:200
Content-Type: application/json
Last-Modified:11/28/13 13:30:30
{
"id": "26",
"href": "http://serverlocation:port/billingManagement/customerBillPresentationMedia/26",
"name": "Electronic invoice"
}

 


© TM Forum 2015. All Rights Reserved.