Billing M2M (1.0) API – Getting started

This API is restricted to International ORange Business Services Customers

The reference of the API is available here

Prerequisite before starting

Billing for Business API uses OAuth 2.0 to grant third-party applications. The API supports 2 modes:

2 legs + API key well adapted for Machine 2 Machine architecture
3 legs well adapted for User to Machine to Machine. Orange will authenticate the end-user. This method is not available yet, and should be available this summer

These authentication methods and their implementations are described here.

The 'API-Key' is delivered by Orange Business Services (Please contact your representative) and must be added in all HTTP headers calls.

Collection

The reference documentation providing all details on models & endpoints is avaialble in the Reference Guide.

The API expose the following resources:

bills
billingAccounts
search
reports
snapshots
status.

Note: All samples are for 2 legs + API key method, for the 3 legs method, you have just to remove the X-API-Key header.

retrieve a collection

To list all bills (for example) you have just to initiate a GET on 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 answer (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 HTTP header of the response, you will receive in ``X-Result-Countthe number of bills returned and inX-Total-Count`, the number of all Bills matching the request.

By replacing bills by billingAccounts you will retrieve all billing accounts of your perimeter.

pagination of a collection

The API provides a pagination mechanism based on the following query parameters

offset: The index of the first element to retrieve. Zero is the first item of the collection.
limit: The maximum number of items to retrieve.
sort: The comma-separated list of field names to sort the result. Prefixing a field name with "-" sign will indicate a descending order.

Example, to get the next 20 Bills from the 10th Bills and sorted by the updatedAt attribute in desc 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 have the possibility to filter a collection by adding on the URI some attributes and their values.

Example to retrieve bills with a type equals to 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 attribute of object embedded in a collection. Example to retrieve bills of 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

Obviously, you can combine several filters such as customer.name=ACME Corp&type=creditNote

Get details

With the Billing for Business API, you can retrieve all information about a specific resource (bill, billing account...) thanks to the id of the resource.

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"
}

Advanced search

For complex query, Billing for Business API proposes an advanced search method.

The query is defined via a JSON structure for define criteria based on logical & comparison operators.

Example of a query for Bills

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

logical operators

with the possibility to use logical operators.

$and: an AND operator
$or; an OR operator
$not: a NOT operator

$and and $or use the following syntax:

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

and the $not use the following syntax:

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

Considering the following example:

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

Search returns all bills with a type equals to invoice and sending format equals to paper.

comparison operators

You can also use the following comparison operators having the same syntax

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

Available operators are:

$eq: selects items where the value of the field is equal to the specified value
$neq: selects items where the value of the field is not equal to the specified value
$gt: selects items where the value of the field is greater than the specified value
$gte: selects the items where the value of the field is less than the specified value
$lt: selects the items where the value of the field is less than the specified value
$lte: selects the items where the value of the field is less than or equal to the specified value

Consider this example:

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

the response will be composed only of bills with a type equals to invoice.

comparison operators for Array

You can also use array for defining you search request. The syntax format is

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

Available operators:

$in: selects items where the value of a field equals any value in the specified array
$nin: selects items where the value of a field is not equal any value in the specified array

In this example

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

will return all bills with a type different than creditNote.

Download a bill/report

With the Billing for Business API, you can also download files such as bill in pdf format, csv file, usage reports etc.

The method is the same than other resource except that you have to indicate in the header the Accept format (text/csv, application/pdf etc...)

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 version of the API didn't allow to retrieve file with a size other 5 m Bytes

Statistics/Counters

Billing for Business API allows to retrieve counters on resources (bills). Counters are computed following one attribute specified via the query parameter groupBy.

For 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

A response will be:

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

The response is a key/value format, for each value of the attribute, you have the number of bills.
You can also combine your request with pagination & filtering query parameters.

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

Obviously, you can sort the response with the sort query parameters with 2 available values: key or value. To sort the response by the number of bills in desc order.

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

A response will be:

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