.wpb_animate_when_almost_visible { opacity: 1; }

Billing M2M 1.0

  • Payments

The Billing API lets international My Services Space users with the Billing module retrieve, manage, and integrate bills into their financial systems.

Use this API Contact us

Billing for Business API Documentation

This API is restricted to International Orange Business Services Customers.

Pre-requisites Before Starting

  • For this "Getting Started" guide, we will use the command-line tool Curl.
  • The API requires the generation of an API Key (API-Key).
  • Your Orange Business Services representative will provide you with this API key.
  • The API key must be included in the HTTP headers of each API call using the header X-Api-Key.
  • The API key expires after 2 years and must be renewed by contacting Orange Support.

Authentication Prerequisites

Access to this API is secured by the OAuth 2.0 framework with the Client Credentials grant type. This means you must provide an OAuth 2.0 access_token for each API request.

To obtain this access_token, send a request to the token negotiation endpoint with a Basic authentication header containing your client_id and client_secret. The token negotiation endpoint is:

https://api.orange.com/oauth/v3/token

A technical guide is available to learn how to negotiate and manage these access_token.

API Reference

The API reference documentation is available here.

Authentication Modes

The Billing for Business API uses OAuth 2.0 to authorize third-party applications. It supports two modes:

  • 2 legs + API Key: Ideal for Machine-to-Machine (M2M) architectures.
  • 3 legs: Suitable for User-to-Machine-to-Machine interactions, with Orange authenticating the end-user. This mode is not yet available and should be available this summer.

These authentication methods and their implementations are described here.

The API-Key is provided by Orange Business Services (contact your representative) and must be included in all HTTP request headers.

Collections

The reference documentation, detailing models and endpoints, is available in the Reference Guide. The API exposes the following resources:

  • bills (invoices)
  • billingAccounts (billing accounts)
  • search (search)
  • reports (reports)
  • snapshots (snapshots)
  • status (status)

Note: All examples use the 2 legs + API Key method. For the 3 legs method, simply remove the X-Api-Key header.

Retrieve a Collection

To list all bills, for example, send a GET request to the /bills resource:

curl -X GET \
  -H "Authorization: {access_token}" \
  -H "X-Api-Key: {api_key}" \
  https://api.orange.com/billing/b2b/v1/bills

A successful response (HTTP status code 200) will be:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
X-Total-Count: 25
X-Result-Count: 10
[
  {
    "id": "1013390",
    "customer": {
      "id": "9999",
      "name": "ACME Corp",
      "segment": "int"
    },
    "type": "invoice",
    "sendingFormat": "paper"
  },
  ...
]

In the response headers, X-Result-Count indicates the number of bills returned, and X-Total-Count indicates the total number of bills matching the request.

By replacing bills with billingAccounts, you can retrieve all billing accounts within your scope.

Pagination of a Collection

The API provides a pagination mechanism using the following query parameters:

  • offset: The index of the first item to retrieve (0 for the first item).
  • limit: The maximum number of items to retrieve.
  • sort: A comma-separated list of field names to sort the results. Prefix a field with - for descending order.

Example: To retrieve the next 20 bills starting from the 10th bill, sorted by updatedAt in descending order:

curl -X GET \
  -H "Authorization: {access_token}" \
  -H "X-Api-Key: {api_key}" \
  https://api.orange.com/billing/b2b/v1/bills?offset=10&limit=20&sort=-updatedAt

Filter a Collection

You can filter a collection by adding attributes and their values to the URL.

Example: To retrieve bills of type invoice:

curl -X GET \
  -H "Authorization: {access_token}" \
  -H "X-Api-Key: {api_key}" \
  https://api.orange.com/billing/b2b/v1/bills?type=invoice

You can also filter on attributes of nested objects.

Example: To retrieve bills for the customer "ACME Corp":

curl -X GET \
  -H "Authorization: {access_token}" \
  -H "X-Api-Key: {api_key}" \
  https://api.orange.com/billing/b2b/v1/bills?customer.name=ACME Corp

You can combine multiple filters, e.g., customer.name=ACME Corp&type=creditNote.

Get Details

With the Billing for Business API, you can retrieve detailed information about a specific resource (bill, billing account, etc.) using its ID.

Example:

curl -X GET \
  -H "Authorization: {access_token}" \
  -H "X-Api-Key: {api_key}" \
  https://api.orange.com/billing/b2b/v1/bills/17006

The response will be:

HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
  "id": "1013390",
  "type": "creditNote",
  "customer": {
    "id": "9999",
    "name": "ACME Corp",
    "segment": "int"
  },
  ...,
  "createdAt": "2018-06-20T06:43:32.092Z",
  "updatedAt": "2018-06-20T06:43:32.092Z"
}

For complex queries, the Billing for Business API offers an advanced search method. Queries are defined using a JSON structure with logical and comparison operators.

Example query for bills:

{
  "$or": [
    {
      "currency.id": "GBP"
    },
    {
      "currency.id": "JPY"
    }
  ]
}

Logical Operators

Available logical operators are:

  • $and: AND operator.
  • $or: OR operator.
  • $not: NOT operator.

Syntax for $and and $or:

{ <operator>: [ { <expression1> }, { <expression2> }, ... , { <expressionN> } ] }

Syntax for $not:

{ <field>: { $not: <value> } }

Example: To retrieve bills of type invoice with a paper sending format:

curl -X POST \
  -H "Authorization: {access_token}" \
  -H "X-Api-Key: {api_key}" \
  -d '{"$and": [ { "type": "invoice" }, { "sendingFormat": "paper" } ] }' \
  https://api.orange.com/billing/b2b/v1/search

Comparison Operators

Available comparison operators are:

  • $eq: Equals.
  • $neq: Not equals.
  • $gt: Greater than.
  • $gte: Greater than or equal to.
  • $lt: Less than.
  • $lte: Less than or equal to.

Syntax:

{ <field>: { <operator>: <value> } }

Example: To retrieve bills with type invoice:

{ "type": { "$eq": "invoice" } }

Comparison Operators for Arrays

You can use arrays in search requests with the following syntax:

{ <field>: { <operator>: [<value1>, <value2>, ... , <valueN>] } }

Available operators:

  • $in: Selects items where the field value matches any value in the array.
  • $nin: Selects items where the field value does not match any value in the array.

Example: To retrieve bills with a type other than creditNote:

{ "type": { "$nin": ["creditNote"] } }

Download a Bill/Report

The Billing for Business API allows downloading files such as bills in PDF format, CSV files, usage reports, etc. The method is similar to other resources, but you must specify the Accept header (e.g., text/csv, application/pdf).

Example:

curl -X GET \
  -H "Authorization: {access_token}" \
  -H "X-Api-Key: {api_key}" \
  -H "Accept: text/csv" \
  https://api.orange.com/billing/b2b/v1/reports/R189-Charges+9300856-......csv

The response will be:

HTTP/1.1 200 OK
Content-Type: text/csv
Customer Number;Customer name;Account number;Invoice number;Invoice Date;Document type;Period from;Period to;Charge Month;Division code;Division name;Service description;Service start date;Site ID;Site name;Site address;Site City;Site State;Postal Code;Country;Country Name;Speed;Bandwidth;Charge Description;Tax Description;Frequency;Number of days;Monthly price;Charge Currency;Exchange rate;Pre-discount amount;Discount percentage;Discount amount;Taxable amount;Tax rate;Tax amount;Invoicing Amount;Invoicing Currency;Total including Tax;TC Cross Reference;Serial Number;Order reference;Credit Comments;Invoice Contact;Phone Number;Payment Term;Payment Due Date;Installed Offer ID;PO Reference;External Reference
...

Note: The current API version does not support retrieving files larger than 5 MB.

Statistics/Counters

The Billing for Business API allows retrieving counters for resources (e.g., bills). Counters are computed based on an attribute specified via the groupBy query parameter.

Example: To retrieve counters by the type attribute:

curl -X GET \
  -H "Authorization: {access_token}" \
  -H "X-Api-Key: {api_key}" \
  https://api.orange.com/billing/b2b/v1/snapshots?groupBy=type

The response will be:

{
  "invoice": 135,
  "creditNote": 4
}

The response is in key/value format, showing the number of bills for each attribute value.

You can combine counters with pagination and filtering parameters. Example:

https://api.orange.com/billing/b2b/v1/snapshots?groupBy=priority&offset=10&limit=30&customer.id=17896

You can also sort the response using the sort parameter with two values: key or value. Example: To sort by the number of bills in descending order:

https://api.orange.com/billing/b2b/v1/snapshots?groupBy=sendingFormat&sort=-value

The response will be:

{
  "paper": 134,
  "eInvoicing": 41
}