Billing API

Introduction

This page describes the billing API and shows examples on how to use it. The billing API reports the total number of active certificates for a certain period of time as well as their serial numbers.

Active certificates are certificates that have been issued in the past, have not expired, and they have the status active (e.g., they are not revoked).

This API also provides the feature of getting the number of certificates that were issued within a specific year and month (or just year) and are still active. Given the same conditions (year and month or just year), it can also report the serial numbers of those certificates.

Requirements

To enable the billing endpoints add:

billing.endpoints.enabled=true in the application.properties file.

Get number of active certificates

To query the number of all active certificates in the application, an HTTP POST request should be sent to the /api/v1/public/billings/certificates endpoint of the application.

The example below shows how to query the number of all active certificates on a server, listening at host mtg.example.com and on port 8501 with [curl]:

Request the number of all active certificates
curl -H "Content-Type: application/json" -X POST https://mtg.example.com/api/v1/public/billings/certificates

An example of the response to the above is shown below:

Server response to a client request to get the number of active certificates
{"total":300}

You can do the same by giving a year and month value in the request. An example is shown below.

Request the number of all active certificates issued in April 2022
curl -H "Content-Type: application/json" -X POST https://mtg.example.com/api/v1/public/billings/certificates --data '{"year"=2022,"month"=4}'

The response to the above will be similar to Server response to a client request to get the number of active certificates.

However, you can make a request by giving only the year parameter. All certificates that are still active and were issued in that year will be returned. An example is shown below:

Request the number of all active certificates issued in year 2022
curl -H "Content-Type: application/json" -X POST https://mtg.example.com/api/v1/public/billings/certificates --data '{"year"=2022}'

Get serial number of active certificates

With the use of the billing API, it is possible to return the serial number of the certificates issued in a certain time period.

The same parameters are applied, i.e. no-content, year only, year and month. To request the serial numbers of certificates, a https POST request should be sent to: /api/v1/public/billings/certificates/serial-numbers. An example of the responses is shown below:

Server response to a client query to get the serial numbers of active certificates
{
  "serialNumbers": [
    6,
    5,
    7
  ]
}

Following are examples of POST requests with different parameters:

Request the serial numbers of all active certificates
curl -H "Content-Type: application/json" -X POST https://mtg.example.com/api/v1/public/billings/certificates/serial-numbers
Request the serial numbers of all active certificates issued in year 2022
curl -H "Content-Type: application/json" -X POST https://mtg.example.com/api/v1/public/billings/certificates/serial-numbers --data '{"year"=2022}'
Request the serial numbers of all active certificates issued in November 2021
curl -H "Content-Type: application/json" -X POST https://mtg.example.com/api/v1/public/billings/certificates/serial-numbers --data '{"year"=2021,"month"=11}'

Get number of active end entities

To query the number of all active end entities in the application, an HTTP GET request should be sent to the /api/v1/public/billings/active-end-entities-count endpoint of the application.

The request below shows how to query the number of all active end-entities on a server, listening at host mtg.example.com and on port 8501 with curl [curl]:

Request the number of all active end entities
curl -H "Content-Type: application/json" -X GET https://mtg.example.com/api/v1/public/billings/active-end-entities-count

An example of the response to the request of the above is shown below:

Server response to a client request to get the number of active end-entities
{"total":25}

To query the number of all active end entities with related active certificates in the application, an HTTP GET request should be sent to the /api/v1/public/billings/active-end-entities-with-certificates-count endpoint of the application.

The example below shows how to query the number of all active end-entities with active certificates on a server, listening at host mtg.example.com and on port 8501 with [curl]:

Request the number of active end entities with active certificates
curl -H "Content-Type: application/json" -X GET https://mtg.example.com/api/v1/public/billings/active-end-entities-with-certificates-count

An example of the response to the request above is shown below:

Server response to a client request to get the number of active end-entities with active certificates
{"total":25}

Get id and common name of active end entities

With the billing API it is possible to return the id and common name of all active end entities.

To query a list with id and common name of all active end entities in the application an HTTP GET request should be sent to the /api/v1/public/billings/active-end-entities endpoint of the application.

Request id and common name of all active end entities shows how to query a list with id and common name of all active end-entities using pagination parameters on a server listening at host mtg.example.com and on port 8501 with curl [curl].

Request id and common name of all active end entities
curl -H "Content-Type: application/json" -X GET https://mtg.example.com/api/v1/public/billings/active-end-entities?page=8&size=5

An example of the response to the request of Request id and common name of all active end entities is shown in Server response to a client request to get id and common name of all active end entities

Server response to a client request to get id and common name of all active end entities
{
    "content": [
        {
            "id": "dfa68592-e197-4993-9b46-5e66d4592cf7",
            "commonName": "common name272593"
        },
        {
            "id": "e0e2a075-aa5a-4c51-8657-26d47e43ad5e",
            "commonName": "common name496803"
        },
        {
            "id": "e42582bd-cb8f-48ea-b2c6-d20f6fc72056",
            "commonName": "common name204932"
        },
        {
            "id": "e709de50-8bfa-4713-86e7-7119ef13fa1f",
            "commonName": "common name993236"
        }
    ],
    "pageDetailsDto": {
        "totalElements": 44,
        "pageNumber": 8,
        "pageSize": 5,
        "numberOfElementsInPage": 4
    }
}

References