Administration Guide | PUBLIC

Document Version: 2022.1 – 2023-02-22

REST APIs Documentation

© 2023 SAP SE or an SAP affiliate company. All rights reserved.

THE BEST RUN

Content

1 Welcome. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3

2 Before You Start. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4

2.1 About This Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.2 Target Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.3 What's New in This Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.4 Additional Information. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
2.5 Document Abbreviations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

3 Getting Started with APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

3.1 Call the APIs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

4 API Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.1 Charging Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Event-Based Rating. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11
Session-Based Rating. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
4.2 Loading Service. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Usage Event Loading. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5 Error Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

REST APIs Documentation

2 PUBLIC Content
1 Welcome

Giving you the best user experience is our priority. Therefore, we do our best to provide you with the clearest
and the most complete documentation possible.

For this purpose, feel free to leave additional feedbacks by using the dedicated feature on the Help
Portal. Please write some details about your suggestion. Based on SAP user feedbacks, we improve your
documentation and deliver Frequently Asked Questions (FAQs) about all aspects of working with SAP
Convergent Charging efficiently. We complete these solutions with our best time-saving and task-completion
tips and tricks.

You can also visit our page Community Questions and Answers for SAP Convergent Charging .

REST APIs Documentation

Welcome PUBLIC 3
2 Before You Start

About This Document [page 4]

Target Audience [page 4]

What's New in This Document [page 5]

Additional Information [page 5]

Document Abbreviations [page 6]

2.1 About This Document

This guide provides information that supports developers using the SAP Convergent Charging APIs and
business events. It supplements the documentation that is available on the SAP API Business Hub with
additional information, such as prerequisites, constraints and dependencies, concepts, and examples.

You can find the SAP Convergent Charging API package on the SAP API Business Hub at https://
int.api.hana.ondemand.com/package/SAPConvergentCharging.

 Note

Due to separate publication processes, there can be a small delay between changes becoming visible on
the SAP API Business Hub and the publication of a new version of this guide reflecting those changes.

2.2 Target Audience

This guide is intended for the following audience:

• Developers
• Project Team Member (Implementation, Integration)
• Application and System Administrators
• Operation Team Expert
• Support Specialist (SAP SE, Local Support Team)

REST APIs Documentation

4 PUBLIC Before You Start
2.3 What's New in This Document

What’s New in FPS 1?

As of release 2022 FPS 1, SAP Convergent Charging provides you with a new REST API.

The table below provides an overview of changes, with the most recent changes at the top. You can search
through the table and filter content.

Available API Package Version Description of Change

2023-02-22 Loading Service [page 1 The Usage Event Loading [page 13] API is now active. It enables
13] you to load event-based usage consumptions to be rated after­
wards.

2022-11-16 Charging Service [page 1 The Event-Based Rating [page 11] and the Session-Based Rating
11] [page 12] APIs are now active. They enable you to rate usage
consumptions of 2 types: event and session types.

What’s New in FPS 0?

As of 2022 FPS 0 major release, SAP Convergent Charging provides you with this brand new documentation to
help you find additional information about the available REST APIs.

The table below provides an overview of changes, with the most recent changes at the top. You can search
through the table and filter content.

Available API Package Version Description of Change

2022-11-16 Charging Service [page 1 The Event-Based Rating [page 11] and the Session-Based Rating
11] [page 12] APIs are now active. They enable you to rate usage
consumptions of 2 types: event and session types.

2.4 Additional Information

For more information about specific topics, see the quick links as shown in the table below:

REST APIs Documentation

Before You Start PUBLIC 5
Content Quick Link

SAP CC documentation help.sap.com/cc2022

 Note
SAP CC is part of the SAP solution SAP Billing based on SAP Business Suite or SAP
S/4 HANA. Consult the central solution information at the following address: https://
cx.sap.com/fr/products/billing

Related release notes https://support.sap.com/en/my-support/knowledge-base.html

2.5 Document Abbreviations

Abbreviation Meaning

AAA Authentication, Authorization, and Accounting

BART Batch Acquisition and Rating Toolset

CAT Connector Administration Tool

CI Chargeable Item

CIF Charging output Integration Framework

CMA Customer Management Area

DBA DataBase Administrator

GUI Graphical User Interface

HA High Availability

HCI HTTP Communication Interface

HTTP HyperText Transfer Protocol

HTTPS HyperText Transfer Protocol Secured

IEC Import/Export Connector

JDBC Java Database Connectivity

JRE Java Runtime Environment

JVM Java Virtual Machine

MDC Multiple Data Container

NFS Network File system

PAM SAP Product Availability Matrix

PKCS Public-Key Cryptography Standards

PSE Personal Security Environment

RAC Real Application Cluster

REST APIs Documentation

6 PUBLIC Before You Start
Abbreviation Meaning

RDBMS Relational Database Management System

SAPSID SAP System Identifier

RDBMS Relational Database Management System

SAR SAP Archive

RDBMS Relational Database Management System

REST REpresentational State Transfer

SID SAP System Identifier

SNC Secure Network Communications

TIF Transaction Integration Framework

URL Uniform Resource Locator

VAT Value Added Tax

XML eXtended Markup Language

REST APIs Documentation

Before You Start PUBLIC 7
3 Getting Started with APIs

This section gives you the basic information that you need to start working with the SAP Convergent Charging
APIs.

Use the APIs in Your Own Environment

You can test and use APIs productively in your own instances of SAP Convergent Charging, using the following
tools:

• SAP API Business Hub

• A REST API client of your choice

 Note

Rate limiting is in place for API requests. If you exceed the limit, you'll receive a 429 response status code
(too many requests).

API Versioning

Versioning of APIs in the SAP Convergent Charging API package follows widely-accepted concepts to
differentiate between breaking and non-breaking changes. In case of breaking changes, a new API version
will be provided, whereas the recent API version is still available but marked as deprecated. Deprecated APIs
and API versions will be supported for a minimum period of 12 months from the date of deprecation. However,
we highly recommend that you migrate to the most recent APIs as soon as possible.

The following are examples of breaking (incompatible) and non-breaking (also known as "compatible" or
"smooth") changes in REST APIs. The list of examples is not comprehensive.

Examples of breaking changes

• Deleting a path
• Deleting or renaming parameters
• Changing the type of a parameter
• Adding a constraint on a parameter (for example, making it mandatory)

Examples of non-breaking changes

• Adding a path
• Adding a non-mandatory parameter
• Adding non-mandatory properties to a resource
• Adding a response code

REST APIs Documentation

8 PUBLIC Getting Started with APIs
As APIs do not remain fixed and unchanged within the same API version, API consumers must prepare their
client-side implementation to handle non-breaking changes.

3.1 Call the APIs

You can call the APIs using a REST API client.

Using a REST API Client

Use a REST API client of your choice to make calls using the endpoint URL. The URL consists of the following
parts:

SAP Convergent Charging

https://<INSTANCE_HOST_ADDRESS>:<INSTANCE_WS_PORT_NB>/rest/<API_NAME>/<VERSION>/
<ENDPOINT>

 Example

• https://<DISPATCHER_HOST_ADDRESS>:9180/rest/charging/v1/chargingSessions

SAP Convergent Charging for Kubernetes

https://<INGRESS_CONTROLLER_BASE_URI>/<SID>/<INSTANCE_NAME>rest/<API_NAME>/
<VERSION>/<ENDPOINT>

 Example

• https://<NGINX_BASE_URI>/<SID>/dispatcher/rest/charging/v1/
chargeableItemProcess

Refer to the SAP API Business Hub for SAP CC 2022 for more information.

Authorizations

HTTP Basic Authentication

You can authenticate your REST messages using the HTTP basic authentication protocol.

To use this protocol with the SAP CC REST APIs, you specify the Authorization field in the HTTP header of
the requests, using the Basic type, followed by the credentials of the SAP CC service user (user logon/ID and
password) encoded in Base64. Authorization: Basic <USERID>:<PASSWORD>

REST APIs Documentation

Getting Started with APIs PUBLIC 9
Example Header Keys for POST Call

Key Value

Content-Type application/json

Authorization Basic <USERID>:<PASSWORD>

(replace <USERID>:<PASSWORD> with your own credentials)

REST APIs Documentation

10 PUBLIC Getting Started with APIs
4 API Index

To access to a particular REST API quickly, you can use the alphabetical list of the REST APIs available with SAP
Convergent Charging:

API Name Package Description Related Instance

Event-Based Rating Charging Rates event-based usage consumptions. Dispatcher

[page 11] Service
Session-Based Rating Charging Rates session-based usage consumptions with Dispatcher
[page 12] Service reservations.

Usage Event Loading Loading Service Loads event-based usage consumptions. Dispatcher
[page 13]

4.1 Charging Service

The Charging Service REST API package enables you to rate event- and session-based consumptions.

For an event-based consumption, one chargeable item specifying the whole consumption is rated.

For a session-based consumption, multiple chargeable items of a session consumption are rated, with
reservation first.

You can find the Charging Service API on the SAP API Business Hub for SAP CC 2022 .

4.1.1 Event-Based Rating

Rates event-based usage consumptions.

Operation

/chargeableItemProcess [POST]

The operation takes a single chargeable item as input data in the request. The chargeable item is processed
and if the rating is successful, the response can return a charged item with notifications if defined in the rate
plan. The returned charged item provides details to the client application about the execution of the rating
process. If the rating process fails, the reason of the failure is returned in the response.

Related instance: Dispatcher

REST APIs Documentation

API Index PUBLIC 11
Package

The Event-Based Rating REST API is part of the Charging Service REST API package.

You can find the Event-Based Rating REST API on SAP API Business Hub for SAP CC 2022

4.1.2 Session-Based Rating

Rates session-based usage consumptions with reservations.

Operation

The Session-Based Rating REST API includes two operations:

/chargingSessions/{sessionId} [POST]

The operation takes a session identifier as a parameter in the path of the request. In addition, it takes
chargeable item used to confirm or cancel already reserved items (for stop and update operations) and
chargeable items to be reserved (for update operation only). All the chargeable items share the same default
properties but have different custom properties. There is no need to provide custom properties in case of a
cancelation.

Chargeable items used to confirm (or cancel) reserved items, are processed in the same order as the one in
the request. The correlation between the items in the request and reserved ones is based on the reservation
identifier. The rating process is executed for each chargeable item in confirmation (or cancelation) mode.
The confirmation mode cancels the reserved item (and its related effects) and rates the confirmed item
instead. When the rating of a chargeable item is successful, the response returns the related charged item and
notifications if defined in the rate plan. The returned charged item provides details to the client application
about the execution of the rating process. If the rating process fails, the reason of the failure is returned in the
response. The cancelation mode of the rating process just cancels the reserved item.

For chargeable items to be reserved, the rating process is the same as the one described when creating a
charging session using the /chargingSessions operation.

/chargingSessions [POST]

The operation takes a session identifier that must be unique as input data in the request. It takes one or
multiple chargeable items to be reserved as well. All the chargeable items share the same default properties
but have different custom properties. In addition to custom properties, each chargeable item has reservation
related data like the identifier of the reservation, the TTL in seconds…

Chargeable items are processed in the same order as the one in the request. The rating process is executed
for each chargeable item in reservation mode. This mode allows to check if the rating process can be executed
without any confirmation. It is used for authorization purposes. When the rating of a chargeable item is
successful, the response returns the related charged item and notifications if defined in the rate plan. The
returned charged item provides details to the client application about the execution of the rating process. If
the rating process fails, the reason of the failure is returned in the response. Each reserved chargeable item

REST APIs Documentation

12 PUBLIC API Index
must be confirmed (or canceled) in a subsequent operation using the reservation identifier. The rating process
records all the reservations as part of the charging session.

For chargeable items to be reserved, the rating process is the same as the one described when creating a
charging session using the /chargingSessions operation.

Related instance: Dispatcher

Package

The Session-Based Rating REST API is part of the Charging Service REST API package.

You can find the Session-Based Rating REST API on SAP API Business Hub for SAP CC 2022

4.2 Loading Service

The Loading Service REST API package enables you to load event-based usage consumptions to be rated
afterwards.

The Loading Service REST API is used to execute the loading process of SAP Convergent Charging. More
precisely, it allows to upload a batch of chargeable items in the system. Once stored, chargeable items can be
rated in a second step.

You can find the Charging Service API on the SAP API Business Hub for SAP CC 2022 .

4.2.1 Usage Event Loading

Loads event-based usage consumptions.

Operation

/chargeableItemsLoad [POST]

The operation takes a list of chargeable items as input data. The response returns a list of operation status with
the same order as the chargeable item list.

• If the loading of a chargeable item is successful, a success status is added to the list.
• If the loading fails, a failure status is returned in the list with an error code providing the reason of the
failure.

Related instance: Dispatcher

REST APIs Documentation

API Index PUBLIC 13
Package

The Usage Event Loading REST API is part of the Loading Service REST API package.

You can find the Usage Event Loading REST API on SAP API Business Hub for SAP CC 2022

REST APIs Documentation

14 PUBLIC API Index
5 Error Types

The table below includes a list of possible errors and their description. Generally, response codes are divided
into 4xx for client-side errors, and 5xx for server-side errors.

HTTP Code Error Description

400 Your input data is not valid

or not in a consistent format.
Please check it and try again.
You can also check the re­
sponse payload for more in­
formation.

401 Your user is not authorized.

403 You do not have the neces­

sary authorization as defined
by the permissions assigned
to your user.

500 The server is not able to rate

the chargeable item.

500 The server is not able to up­

date or stop the session.

500 The server is not able to cre­

ate the session.

REST APIs Documentation

Error Types PUBLIC 15
Important Disclaimers and Legal Information

Hyperlinks
Some links are classified by an icon and/or a mouseover text. These links provide additional information.
About the icons:

• Links with the icon : You are entering a Web site that is not hosted by SAP. By using such links, you agree (unless expressly stated otherwise in your
agreements with SAP) to this:

• The content of the linked-to site is not SAP documentation. You may not infer any product claims against SAP based on this information.

• SAP does not agree or disagree with the content on the linked-to site, nor does SAP warrant the availability and correctness. SAP shall not be liable for any
damages caused by the use of such content unless damages have been caused by SAP's gross negligence or willful misconduct.

• Links with the icon : You are leaving the documentation for that particular SAP product or service and are entering an SAP-hosted Web site. By using
such links, you agree that (unless expressly stated otherwise in your agreements with SAP) you may not infer any product claims against SAP based on this
information.

Videos Hosted on External Platforms

Some videos may point to third-party video hosting platforms. SAP cannot guarantee the future availability of videos stored on these platforms. Furthermore, any
advertisements or other content hosted on these platforms (for example, suggested videos or by navigating to other videos hosted on the same site), are not within
the control or responsibility of SAP.

Beta and Other Experimental Features

Experimental features are not part of the officially delivered scope that SAP guarantees for future releases. This means that experimental features may be changed by
SAP at any time for any reason without notice. Experimental features are not for productive use. You may not demonstrate, test, examine, evaluate or otherwise use
the experimental features in a live operating environment or with data that has not been sufficiently backed up.
The purpose of experimental features is to get feedback early on, allowing customers and partners to influence the future product accordingly. By providing your
feedback (e.g. in the SAP Community), you accept that intellectual property rights of the contributions or derivative works shall remain the exclusive property of SAP.

Example Code
Any software coding and/or code snippets are examples. They are not for productive use. The example code is only intended to better explain and visualize the syntax
and phrasing rules. SAP does not warrant the correctness and completeness of the example code. SAP shall not be liable for errors or damages caused by the use of
example code unless damages have been caused by SAP's gross negligence or willful misconduct.

Bias-Free Language
SAP supports a culture of diversity and inclusion. Whenever possible, we use unbiased language in our documentation to refer to people of all cultures, ethnicities,
genders, and abilities.

REST APIs Documentation

16 PUBLIC Important Disclaimers and Legal Information
REST APIs Documentation
Important Disclaimers and Legal Information PUBLIC 17
www.sap.com/contactsap

© 2023 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form

or for any purpose without the express permission of SAP SE or an SAP
affiliate company. The information contained herein may be changed
without prior notice.

Some software products marketed by SAP SE and its distributors

contain proprietary software components of other software vendors.
National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for

informational purposes only, without representation or warranty of any
kind, and SAP or its affiliated companies shall not be liable for errors or
omissions with respect to the materials. The only warranties for SAP or
SAP affiliate company products and services are those that are set forth
in the express warranty statements accompanying such products and
services, if any. Nothing herein should be construed as constituting an
additional warranty.

SAP and other SAP products and services mentioned herein as well as
their respective logos are trademarks or registered trademarks of SAP
SE (or an SAP affiliate company) in Germany and other countries. All
other product and service names mentioned are the trademarks of their
respective companies.

Please see https://www.sap.com/about/legal/trademark.html for

additional trademark information and notices.

THE BEST RUN