Open APIs

 View Only
Back to discussions
Expand all | Collapse all

Clarifications on Implementation integration layer by applying TMF OpenApi Specifications

  • 1.  Clarifications on Implementation integration layer by applying TMF OpenApi Specifications

    TM Forum Member
    Posted Jun 23, 2025 15:54

    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?

    TMF677– Usage Consumption Management API

    Api is used to fetch the usage information of products and services.

    Request: 

    {
        "searchCriteria": {
            "logicalResource": [
                {
                    "id": "63989999",
                    "characteristic": [
                        {
                            "name": "DataUsageSummaryRequired",
                            "value": "DATA"
                        },
                        {
                            "name": "IsLanguageInfoRequired",
                            "value": "Y"
                        },
                        {
                            "name": "paidMode",
                            "value": "PREP"
                        }
                    ]
                }
            ]
        }
    Response
    {
        "usageConsumption": [
            {
                "logicalResource": [
                    {
                        "id": "968987654321"
                    }
                ],
                "validPeriod": {
                    "endDateTime": "2025-06-22T23:59:59Z"
                },
                "relatedParty": [
                    {
                        "id": "3243242432"
                    }
                ],
                "characteristic": [
                    {
                        "name": "STATUS",
                        "value": "ACTIVE",
                        "valueType": "string"
                    },
                    {
                        "name": "COMMUNICATION_LANGUAGE",
                        "value": "1",
                        "valueType": "string"
                    }
                ],
                "bucketRefOrValue": [
                    {
                        "id": "PREPAID_BALANCE",
                        "usageType": "OMR",
                        "status": "active",
                        "name": "Prepaid Balance",
                        "remainingValue": {
                            "amount": 1.5,
                            "units": "OMR"
                        }
                    },
                    {
                        "id": "POSTPAID_BALANCE",
                        "usageType": "OMR",
                        "status": "active",
                        "name": "Postpaid Balance",
                        "remainingValue": {
                            "amount": 1.5,
                            "units": "OMR"
                        }
                    },
                    {
                        "id": "POSTPAID_CREDIT_LIMIT",
                        "usageType": "OMR",
                        "status": "active",
                        "name": "Postpaid Credit Limit",
                        "remainingValue": {
                            "amount": 1.5,
                            "units": "OMR"
                        }
                    },
                    {
                        "id": "OUTSTANDING_LOAN",
                        "usageType": "OMR",
                        "status": "active",
                        "name": "Outstanding Loan",
                        "remainingValue": {
                            "amount": 1.5,
                            "units": "OMR"
                        }
                    },
                    {
                        "id": "OUTSTANDING_PAYMENTS",
                        "usageType": "OMR",
                        "status": "active",
                        "name": "Outstanding Payments",
                        "remainingValue": {
                            "amount": 1.5,
                            "units": "OMR"
                        }
                    },
                    {
                        "id": "OUTSTANDING_SERVICE_FEES",
                        "usageType": "OMR",
                        "status": "active",
                        "name": "Outstanding Service Fees",
                        "remainingValue": {
                            "amount": 1.5,
                            "units": "OMR"
                        }
                    },
                    {
                        "id": "ADJUSTED_LOAN_AMOUNT",
                        "usageType": "OMR",
                        "status": "active",
                        "name": "Adjusted Loand Amount",
                        "remainingValue": {
                            "amount": 1.5,
                            "units": "OMR"
                        }
                    },
                    {
                        "id": "UBCL_STATUS",
                        "status": "suspended",
                        "name": "UBCL Status"
                    },
                    {
                        "id": "CREDIT_LIMIT_REACHED",
                        "status": "active",
                        "name": "Credit Limit Status"
                    },
                    {
                        "id": "ROAMING_BARRED",
                        "status": "active",
                        "name": "Roaming Barriing Status"
                    }, {
                        "id": "1201390",
                        "status": "active",
                        "remainingValue": {
                            "amount": 0,
                            "units": ""
                        },
                        "validFor": {
                            "startDateTime": "2025-06-01T00:00:00Z",
                            "endDateTime": "2025-06-30T23:59:59Z"
                        },
                        "characteristic": [
                            {
                                "name": "ARABIC_NAME",
                                "value": "",
                                "valueType": "string"
                            },
                            {
                                "name": "BUNDLE_STATUS",
                                "value": "",
                                "valueType": "string"
                            },
                            {
                                "name": "TOTAL_BALANCE",
                                "value": "",
                                "valueType": "number"
                            },
                            {
                                "name": "IS_UNLIMITED",
                                "value": "",
                                "valueType": "string"
                            },
                            {
                                "name": "IS_ROAMING",
                                "value": "",
                                "valueType": "string"
                            },
                            {
                                "name": "IS_MULTIPLE_SUBSCRIPTION_ALLOWED",
                                "value": "",
                                "valueType": "string"
                            }
                        ]
                    },
                    {
                        "id": "1271252",
                        "name": "5GB Global Data",
                        "usageType": "data",
                        "status": "active",
                        "remainingValue": {
                            "amount": 1024,
                            "units": "MB"
                        },
                        "validFor": {
                            "startDateTime": "2025-06-01T00:00:00Z",
                            "endDateTime": "2025-06-30T23:59:59Z"
                        },
                        "characteristic": [
                            {
                                "name": "ARABIC_NAME",
                                "value": "5جيجابايت حول العالم ",
                                "valueType": "string"
                            },
                            {
                                "name": "BUNDLE_STATUS",
                                "value": "0",
                                "valueType": "string"
                            },
                            {
                                "name": "TOTAL_BALANCE",
                                "value": "5120",
                                "valueType": "number"
                            },
                            {
                                "name": "IS_UNLIMITED",
                                "value": "N",
                                "valueType": "string"
                            },
                            {
                                "name": "IS_ROAMING",
                                "value": "1",
                                "valueType": "string"
                            },
                            {
                                "name": "IS_MULTIPLE_SUBSCRIPTION_ALLOWED",
                                "value": "0",
                                "valueType": "string"
                            }
                        ]
                    },
                    {
                        "id": "1270621",
                        "name": "Unlimited national calls",
                        "usageType": "voice",
                        "status": "active",
                        "remainingValue": {
                            "amount": 100,
                            "units": "Minutes"
                        },
                        "validFor": {
                            "startDateTime": "2025-06-01T00:00:00Z",
                            "endDateTime": "2025-06-30T23:59:59Z"
                        },
                        "characteristic": [
                            {
                                "name": "ARABIC_NAME",
                                "value": "مكالمات محليه غير محدوده ",
                                "valueType": "string"
                            },
                            {
                                "name": "BUNDLE_STATUS",
                                "value": "0",
                                "valueType": "string"
                            },
                            {
                                "name": "TOTAL_BALANCE",
                                "value": "10000",
                                "valueType": "number"
                            },
                            {
                                "name": "IS_UNLIMITED",
                                "value": "N",
                                "valueType": "string"
                            },
                            {
                                "name": "IS_ROAMING",
                                "value": "1",
                                "valueType": "string"
                            },
                            {
                                "name": "IS_MULTIPLE_SUBSCRIPTION_ALLOWED",
                                "value": "0",
                                "valueType": "string"
                            }
                        ]
                    }
                ]
            }
        ]
    }

     

    Queries

    • is the above request valid? i do not characteristic field available in request payload as per the SID?
    • does the response mapping look good and reasonable?
    • does the response has characteristic as such field is not available in SID? how to handle such cases? 
    • Samples would be really helpful


    ------------------------------
    Manudeep Bhandaru
    OMANTEL
    ------------------------------