API reference

Welcome to the API Reference section. This guide provides all the general information you need to get started with our API.

info

External access to CoreAPI is disabled by default. To enable it for your installation, please contact the support department.

Protocols

The API supports both REST and JSON-RPC 2.0 protocols. For each method, the following details are provided:

• REST API: Information about the HTTP method and endpoint to use.
• JSON-RPC: Method names to include in the request payload.

Base URL

CoreAPI is exposed via the same hostname as the JeraSoft Billing web interface, under the /api/ path prefix:

• https://<billing-hostname>/api/

Where <billing-hostname> is the domain name your JeraSoft Billing installation is reachable at.

REST API

• The API follows standard REST conventions over HTTP.
• Use the HTTP method and endpoint documented for the method to call it:
  • Example: GET https://<billing-hostname>/api/accounting/currencies/exchange-rate

JSON-RPC 2.0

• The API follows the JSON-RPC 2.0 specification.
• Use JSON-RPC method name to call the method:
  • Example: accounting.currencies.get_rate
• JSON-RPC requests should be sent as HTTP POST to the base URL:
  • POST https://<billing-hostname>/api/
• The POST payload should include the JSON-RPC request message.

Authorization

There are two authentication mechanisms available for the API:

• API Keys (Preferred)
• JWTs (JSON Web Tokens) (Deprecated)

info

It is recommended to create a dedicated user for each of the integrations you make.

API key

API keys are the recommended authentication mechanism. To authenticate:

• Add an X-Api-Key HTTP header to each request with the value of the user's API key.
  • X-Api-Key: <API_KEY>
• API keys can be retrieved in the System / Users section by selecting a user and checking the API Key field.
• If an invalid token is provided, the HTTP 401 status code will be returned.

JSON Web Tokens (JWTs)

warning

JWT authentication is deprecated and may be removed in the future. It is retained only for backward compatibility.

The JWT authentication process involves:

1. Authentication Request: Exchange login and password for a JWT token by calling the iam.auth.jwt.authenticate method. The response includes the token and its expiry timestamp.
2. Regular Requests: Include the token in the HTTP Authorization header:
   • Authorization: Bearer <TOKEN>
3. Token Refresh: Before the token expires, call iam.auth.jwt.refresh to obtain a new token.

If an invalid token is provided, the API will return a JSON-RPC Error Response with code -32005.

Role and Reseller settings

The Role defined for the user does not affect API requests. All methods are available to be called. However, the Reseller setting is enforced:

• For Reseller-limited entities, only entities associated with that Reseller will be accessible.
• For entities that are not limited by Reseller (e.g. Currencies), no filtering will be done.

Protocol extensions

Timezone conversion

The API supports timezone conversion for incoming and outgoing datetime values on a per-request basis. To enable this:

• Pass the __tz parameter in the request with a value in the Olson database format (e.g., America/New_York).
• If omitted, the server uses the timezone of the authenticated user (and if not set – the global system settings).
• If incoming datetime values include a timezone, the __tz parameter is ignored.

Examples

REST API

cURL

# Get details for the client #42.
curl -X GET "https://<billing-hostname>/api/clients/42" \
    -H "X-Api-Key: <API_KEY>"

# Set credit limit for client #42 to `1000`.
curl -X PATCH "https://<billing-hostname>/api/clients/42" \
    -H "X-Api-Key: <API_KEY>" \
    -d '{"credit": 1000}'

Python

import requests

# Define the base URL and API key.
BASE_URL = "https://<billing-hostname>/api"
API_KEY = "<API_KEY>"

# Get details for the client #42.
response = requests.get(
    f"{BASE_URL}/clients/42",
    headers={"X-Api-Key": API_KEY}
)

if response.status_code == 200:
    print("Client details:", response.json())
else:
    print(f"Failed to get client details: {response.status_code} - {response.text}")

# Set credit limit for client #42 to `1000`.
response = requests.patch(
    f"{BASE_URL}/clients/42",
    headers={"X-Api-Key": API_KEY},
    json={"credit": 1000},
)

if response.status_code == 200:
    print("Credit limit updated successfully:", response.json())
else:
    print(f"Failed to update credit limit: {response.status_code} - {response.text}")

JSON-RPC

cURL

# Get details for the client #42.
curl -X POST "https://<billing-hostname>/api/" \
    -H "X-Api-Key: <API_KEY>" \
    -d '{"jsonrpc": "2.0", "id": 1, "method": "clients.get", "params": {"id": 42}}'

# Set credit limit for client #42 to `1000`.
curl -X POST "https://<billing-hostname>/api/" \
    -H "X-Api-Key: <API_KEY>" \
    -d '{"jsonrpc": "2.0", "id": 1, "method": "clients.update", "params": {"id": 42, "credit": 1000}}'

Python

import requests

# Define the base URL and API key.
API_URL = "https://<billing-hostname>/api/"
API_KEY = "<API_KEY>"

# Get details for the client #42.
response = requests.post(
    API_URL,
    headers={"X-Api-Key": API_KEY},
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "clients.get",
        "params": {
            "id": 42,
        },
    },
)

if response.status_code == 200:
    result = response.json()
    if "result" in result:
        print("Client details:", result["result"])
    else:
        print("Error in response:", result.get("error", "Unknown error"))
else:
    print(f"Failed to get client details: {response.status_code} - {response.text}")


# Set credit limit for client #42 to `1000`.
response = requests.post(
    API_URL,
    headers={"X-Api-Key": API_KEY},
    json={
        "jsonrpc": "2.0",
        "id": 1,
        "method": "clients.update",
        "params": {
            "id": 42,
            "credit": 1000,
        },
    },
)

if response.status_code == 200:
    result = response.json()
    if "result" in result:
        print("Credit limit updated successfully:", result["result"])
    else:
        print("Error in response:", result.get("error", "Unknown error"))
else:
    print(f"Failed to update credit limit: {response.status_code} - {response.text}")