Hi Manudeep,
To your two points:
- Yes - it is completely fine to use filter criteria in a GET to narrow the range of responses. The TMForum API Design Guidelines mention this. However I think you would achieve your example "
customerBill?filter=billingAccount.id=in=('ACC-001','ACC-002')" as "customerBill?billingAccount.id=ACC-001&billingAccount.id=ACC-002".
The design guidelines use a similar example of "GET /resourceInventoryManagement/logicalResource?id=42&id=44" - so retrieving a collection using multiple ids is fine.
- For your date range example, I would probably try JSON-Path expression syntax which gives you operators (
>, >=, != etc) and functions (min(), avg(), sum() etc). JSON-Path is mentioned as the defacto expression syntax in various places in the design guidelines.
Regarding your point about:
is it ok to use characteristic in response? there is no such field in the specifications? what is best way to implement such fields which are not available in SID schema?
It is very much recognised that the TMF schemas present a generic framework that might have wide applicability to many use-cases, but if you want to add properties specific to your internal interactions (like your DISPUTEAMOUNT), you can always extend the TMF schemas. This is typically done by adding a new schema to the definitions section of the TMF swagger, called (say) CustomerBillExtended, looking a bit like this:
"definitions": {
"CustomerBillExtended": {
"allOf": [
{
"$ref": "#/definitions/CustomerBill"
},
{
"type": "object",
"properties": {
"disputedAmount": {
"type": "string",
"description": "The amount being disputed on the customer bill",
"pattern": "^[0-9]+\\.[0-9]{2}"
}
}
}
]
}
}
Then you can fiddle with the existing operations to accept and return a CustomerBillExtended rather than a CustomerBill. The resultant API will be compatible with the TMF original, and would still pass a TMF Conformance Test Kit (CTK), which would only test for mandatory properties from the original. It will ignore any additional properties.
------------------------------
Stephen Harrop
Principal Integration Architect
Vodafone Group
------------------------------
Original Message:
Sent: Jun 24, 2025 00:33
From: Manudeep Bhandaru
Subject: TMF678 – Customer Bill Managament Api
Need support and guidance and reviewing the below and suggesting the best practices
TMF678 – Customer Bill Managament Api
1. Get all bills for a customer with CRM Customer No & date range
GET {{baseUrl}}/customerBillManagement/v4/customerBill?filter=relatedParty.id=='32523424';billDate=ge=2024-01-01;billDate=le=2024-06-30
2. Get all bills for multiple billing accounts with date range & state
GET {{baseUrl}}/customerBill?filter=billingAccount.id=in=('ACC-001','ACC-002');billDate>='2025-01-01';billDate<='2025-06-01';state=='new'
Response :
[
{
"billNo": "INV-2025-001",
"state": "new",
"billDate": "2025-06-01",
"paymentDueDate": "2025-06-15",
"amountDue": {
"value": 125.5,
"unit": "OMR"
},
"taxIncludedAmount": {
"value": 125.5,
"unit": "OMR"
},
"appliedPayment": [
{
"amount": {
"value": 75.5,
"unit": "OMR"
}
}
],
"billingAccount": {
"id": "ACC-001"
},
"relatedParty": [
{
"id": "CUST-001",
"role": "customer",
"name": "John Doe"
}
],
"category": "MULTIPLE",
"characteristic": [
{
"name": "ADJUSTMENT",
"value": 0,
"valueType": "number"
},
{
"name": "DISPUTEAMOUNT",
"value": 0,
"valueType": "number"
}
]
}
]
Queries
- Is it allowed to use filter in the url?
- is the above syntax correct? can we use FIQL?
- is it allowed to fetch by multiple billing accounts?
- is it ok to use characteristic in response? there is no such field in the specifications? what is best way to implement such fields which are not available in SID schema?
------------------------------
Manudeep Bhandaru
OMANTEL
------------------------------