Business Apps France
Boost your SaaS revenue by joining Orange Business Services' partner program.

Getting started



Prerequisites

Contracting with Orange Business Services

Before implementing the API, a partnership agreement must be established between your company and the Orange team responsible for Business Apps partnerships.

Your Orange contact: businessapps.contact@orange.com.

Once the partnership agreement is established, you will receive a contract number which will be required when subscribing to the Business Apps offer.

The agreement itself will include useful information such as:

  • A list of Orange contacts for the integration and production phases.

  • Additional information about API use (Appendix 2 of the contract, "Technical specifications of APIs").

The Appendix 2 will allow each partner to:

  • specify the features of userService they want or can implement
Specifying your operating mode

The minimum features required to be displayed by an Orange Mobile Apps partner are identified inside the following array.

FeatureAPIoptional/mandatory
Service availabilitypingmandatory
Creation of a customerproductOrderingmandatory
Ordering user licensesproductOrderingmandatory
Deletion of a customerproductOrderingmandatory
Consultation of licensesuserServicemandatory
Management of end user using licenses (add, modify, delete)userServiceoptional
Change of state of licensesuserServiceoptional
Deletion of licensesuserServicemandatory
Change of product offering for licensesuserServiceoptional
Management of technical resource supported by the licenseuserServiceoptional
Renewal of the login and/or the password of licenseuserServiceoptional

  • define the technical information required to deliver the service and specify if this technical information is only technical a prerequisite or if it should be provided in addition to the subscribed offer to properly configure the licenses (example: storage size, CPU value, OS type and version ...). A technical resource has a generic name (name) and one or more properties (value).

  • define the type of medium (Type of RealizingResource) on which the licenses are running to deliver the service to the end user. Typical examples of Realizing resource are an URL (access to the service via a URL), an email, a phone number, IMEI, etc. In the APIs, the value of this item is called RealizingResource).

    • The partner must define, for each product offering, the technical resource that will be exchanged with Orange through the APIs:
      • type (name): maximum 50 characters (eg "Mobile")
      • for each property (value):
        • its name (name): maximum 50 characters (eg "sn")
        • its description and format (example: 10-digit local calling format starting with 0)
    • To complete this information,the partner must specify if:
      • licenses can be created without Orange providing the value of realizingResource for each license or with Orange providing a default value applying to all.
      • the value ​​will be provided by the partner to Orange once licenses are created as it does not depend on end user knowledge (provided to Orange thanks the consultation of licenses using GET userService API. Partner specifies the value as "realizingResource" data )
      • the value can or must be provided during the assignment of an end user to a license (in this case, Orange will make the corresponding end user information mandatory for the assignment and will transfer the value using UserService API)
      • If the value is provided during end user assignement, the partner will indicate if they prefer that Orange provides it explicitely as Realizing Resource OR if the partner will extract value from the end user information and provide it back to Orange using realizingResource data.
  • specify whether the results will be provided in synchronous or asynchronous mode.

For any question about Business apps features to provide inside Appendix 2 of the agreement , contact us at the following e-mail address : shine-project.team@orange.com

Go up

Project phases

Development phase

Software Development Kits in Java and PHP are provided in addition to JSON files , to assist you in the development phase. These SDKs are documented and include both provider and consumer code.

JSON files of the APIs and the Software Development Kits (SDK JAVA and SDK PHP) are available here.

A dedicated API must be reserved for web application server status. This API must be named "ping", available as a GET request, and the response must be HTTP 200.

Publish and subscribe to the APIs

At least two weeks before the integration phase, you have to publish the APIs (ProductOrdering and UserService) and subscribe to the APIs event if you use the asynchronous mode.

To achieve this, the different steps are as follows:

  1. Create an account on the current Orange Partner site
  2. Log on and create your application: you get credentials you may use to obtain an access token (OAuth 2.0) and be able to invoke Business Apps API events. See here
  3. Subscribe to Business Apps APIs (select Business Apps in the list of APIs to include in your application): during subscription you must complete a form with the contract number and technical informations used by Orange to call your API.

Those steps are detailed through the following screenshots: screenshots

API authentication :

API authentication

Integration phase

Once your APIs are developed and published (after the validation of step 3 described in the previous chapter), you will start a new phase: the integration tests.

Because API calls are initiated by Orange, you must send an email at shine-project.team@orange.com to begin testing.

On Orange's side, tests are performed on the production environment using a simulated customer.

On the partner's side, we recommend performing the tests, in a development environment (type of environment - cf. Publish and subscribe to the APIs).

After the validation tests have been completed, the operational phase may start as defined in the joint agreement (between your company and Orange). The prerequisite is to publish your APIs to your production environment (cf. Publish and subscribe to the APIs as it can require to create an application again if you first create an application for your development environment)

Development and integration overheads

Here are some questions to help you estimate the cost of the integration project:

  • Did I already expose APIs to partners or customers ?
  • Am I familiar with web service REST style ?
  • Do I use Java or PHP to develop the APIs so that I can use the provided software development kit ?
  • Are the concepts used in API already implemented into my information system ?
  • Is the data model exchanged via APIs distant or close to my model ?
  • How many features need to be implement ?
  • Will results of operations sent by APIs be provided synchronously or asynchronously (asynchronously you must invoke the event resource to send the result so there are additional development on your side) ?

To give you an idea, our first two partners devoted about 15 man-day to integrating the APIs.

Go up

API Description

Overview

To interact with partners and provide a seamless customer experience, Orange provides partners with a set of API enabling orders and change management.

The set of APIs is called Business Apps API

These APIs are developed both by Orange and our partners.

Thanks to the APIs:

  • partners receive customer requests to apply in their system (orders or changes on existing application)
  • partners can answer in a synchronous way or can update Orange later on the deployment of orders and changes.

Synchronously, the partner immediately processes the request and returns the corresponding result. Asynchronously, the partner registers the request which is subsequently processed and returns an acknowledgment. Once the request is processed, the partner sends Orange the result, calling the event resource (see explanation in next chapters).

GS API context

Two APIs are used:

• ProductOrdering for customer creation/deletion, product creation or adding of licenses in one existing product.

• UserService for license management (consult, change status, change offer, manage end user, delete license, renew login and / or pwd, change technical support of license)

Inside each API, there are 2 main resources:

  • the main business resource exposed by partner and consumed by Orange:

    • productOrder inside ProductOrdering,
    • userService inside UserService API, these allow Orange to transfer customer requests to the partner
  • event resource exposed by Orange and consumed by partner. This resource is provided both inside productOrdering and userService APIs. It allows the partner to answer Orange's requests in an asynchronous way to.

Call back API

The following illustration shows what is under the partner's responsibility in term of development:

What you have to encode

The UserService API allows to manage several type of changes. It can be implemented partially by the partner. The list of operations chosen by the partner has to be provided during the initial partnership discussion phase (see chapter "before starting" for information to provide in the agreement).

Go up


Standard sequence of activities relying on the API bundle

(*1) Partner may implement a synchronous or an asynchronous response to orange POST requests

Number - InitiatorActivityAPI calls
1 - Customerorders a business application product to Orange
2 - Orangefollowing 1, sends customer information and contacts to partnerOrange POST /productordering/v2/productOrder
only if partner has implemented asynchronous response (*1)partner POST /mba/productordering/v2/event
3 - Customeroptionally begin test/integration phase with the same activities (5,6,7,8,9,10) as in deployment phase but on a limited number of user services.Use of APIs with same end points
4 - Customerfollowing 2 or 3 , begins deployment
5 - Orangefollowing 4, instructs partner to create the product with activation of licensesOrange POST /productordering/v2/productOrder
only if partner has implemented asynchronous response (*1)Partner POST /mba/productordering/v2/event
6 - Orangefollowing 5, can consult licenses of customer’s productOrange GET /userservice/v2/userService
7 - Customerfollowing 5, can consult licenses of their mobile business appOrange GET /userservice/v2/userService
8 - Customer or Orangefollowing 5, can modify licenses: suspend/activate licenses,change product offering on licenses, renew login/password, attach/release a link between end-user and license, modify end user information, change technical support of licenseOrange POST /userservice/v2/userService/update
only if partner has implemented asynchronous response (*1)Partner POST /mba/userservice/v2/event
9 - Customerfollowing 5, can suppress servicesOrange POST /userservice/v2/userService/update
only if partner has implemented asynchronous response (*1)Partner POST /mba/userservice/v2/event
10 - Customerfollowing 5, can add user services to their mobile business appOrange POST /productordering/v2/productOrder
only if partner has implemented asynchronous response (*1)Partner POST /mba/productordering/v2/event
11 - Customercan terminate their mobile business appOrange POST /productordering/v2/productOrder
only if partner has implemented asynchronous response (*1)Partner POST /mba/productordering/v2/event

Go up

Summary of resources

The main resources of the two APIs and the relationships between the 2 models'ID are represented in the following diagram.

MBA MDD

Cross- references The ExternalReference resource represents Orange references of different resources whose ID attribute is generated by the partner's IS. The diagram does not present all resources which have an ExternalReference.

ProductOrdering API

Resource nameDescription
ProductOrderMain resource. a ProductOrder represents a customer order of licences for a business application. It is composed of productItem and EndUserConfiguration resources. It also defines a unique customer as an Organization resource, and contacts as Individual resources
EventMain resource. If the partner choses asynchronous response to Orange POSTs, then the partner POSTs an event to Orange to answer. The Event carries the final result . An Event is typed and composed of a unique ProductOrder Resource
EndUserConfigurationInputs from Orange are mandatory for some applications or partner to create a license of an application. EndUserConfiguration is composed of RealizingResource the technical support of the license and/or of Individual for end user data . The number of EndUserConfiguration resources in a productOrder will be equal or less than the requested userServiceQuantity
ExternalReferenceReference given by Orange in opposition to ID attributes given by partner. Resources Organization, Individual, ProductOfferingRef have an ExternalReference.
Individualrepresents a customer contact or an Orange contact or an end user
ProductRefthe product selected by the customer and created by the partner. It has characteristics given when product offering is defined between partner and Orange. This is the fleet identification so it also has a number of licenses that can be modified by adding licenses.
ProductOfferingRefthe Mobile Business Application offering in the Orange Catalog
Organizationthe customer information
OrderIteman OrderItem in the ProductOrder defines the content of the order
RealizingResourceA technical resource the service depends on, such as a mobile number, IMEI, email, URL... The technical information needed to deliver the service to the end user. to indicate the value of the realizing resource, use the characteristics

userService API

Resource nameDescription
UserServiceMain resource. This an access to a business application delivered to a customer. It has a relatedProductRefId attribute that is the identifier of the customer application and identifier of the license fleet
EventMain resource. If the partner chose asynchronous response, the partner POST an event to Orange to send the results of operations performed on user services
ExternalReferenceReference given by Orange in opposite to ID attributes given by the partner. Individual has an ExternalReference . The externalReference attribute of the ProductOfferingOperation refer to the ExternalReference of the product offering.
EndUserConfigurationOperation(optional) The technical resource the service depends on and/or the end user data . They are represented respectively by RealizingResource and Individual .
EndUserOperationOperation used to add, modify, swap or delete the end user of the UserService
RealizingResourceOperationOperation used to add, modify, swap, delete the RealizingResource of a service. A RealizingResource is an technical resource the service depends on, such as a mobile number. It has a set of characteristics.
RightOperationOperation used to add, modify or reset a login (1 max per service) or reset the password
ServiceCharacteristicOperationAn operation used to add, modify or delete a service charateristic
ProductOfferingOperationUsed for swapping the product offering of the UserService

Go up

Summary of methods and URL

  • ProductOrdering API
Use CaseCallerEnd pointMethod URL
UC1 - Creation of customer and contactsOrangePartnerPOST https://[partnerServer]/productordering/v2/productOrder
UC2.1 - A customer integration project is needed. Creation of customer product and activation of test licensesOrangePartnerthe same
UC2.2 - After the end of the integration phase, activation of all licensesOrangePartnerthe same
UC2.3 - No Integration phase. Creation of customer product and activation of all licensesOrangePartnerthe same
UC3 - Adding new licenses to an existing fleetOrangePartnerthe same
UC4 - Deletion of the customer's productOrangePartnerthe same
UC5 - if partner has implemented asynchronous response , partner sends result to Orange for UC1, UC2.x, UC3, UC4 and UC5PartnerOrangePOST https://api.orange.com/mba/productordering/v2/event

  • UserService API
Use CaseCallerEnd pointMethod URL
UC1 - Orange consults licensesOrangePartnerGET https://[partnerServer]/userservice/v2/userService
UC2 - Suspension or reactivation of licensesOrangePartnerPOST https://[partnerServer]/userservice/v2/userService/update
UC3.x - Change of licenses through operations, ProductOfferingOperation, RightOperation , EndUserOperation , RealizingResourceOperationOrangePartnerPOST https://[partnerServer]/userservice/v2/userService/update
UC4 - Deletion of licenses within one customer's fleetOrangePartnerPOST https://[partnerServer]/userservice/v2/userService/update
UC5 - if partner has implemented asynchronous response , partner sends result to Orange for UC1, UC2, UC3 and UC4PartnerOrangehttps://api.orange.com/mba/userservice/v2/event

Go up

POST productOrder

POST /productordering/v2/productOrder

  • Request Body Resource : productOrder
  • Response Body Resource : productOrder

productOrder.state provided in the HTTP POST response allows to distinguish how the partner will answer:

  • "acknowledged" if asynchronous answer will be provided
  • " partial ", " completed " or " failed " if synchronous

Note : in this release, the order request contains only one order item. So, the partial state is not used.

UC1 - Partner creates the customer and contacts

Orange sends the partner a productOrder partner with the customer, customer contacts and Orange contacts, but with no orderItem nor endUserConfiguration.

No product or service is created. Only customer and contacts are created.

UC2.x - Partner creates the customer product and activates user services

UC2.3 If no integration phase is required, Orange sends a productOrder to the partner with 'add' action on orderItems . The category attribute of the productOrder is 'production'. For each orderItem the externalReference of a product offering and a userServiceQuantity are provided to create the product. EndUserConfiguration may also be provided in the orderItem depending on what was precized inside Annex 2 of the contract.

In a synchronous or asynchronous mode (see also UC6) , the fleet with its licenses is created by the partner and the fleet ID (product ID) is generated . The ID returned to Orange in the final result will be used to get licenses using the userService API .

UC 2.1 and UC 2.2 If an Integration phase is required, two productOrder calls are sent to the partner : the first one has a category ='trial' which means there is an integration phase. Order Items are provided but the userServiceQuantity is limited to test purposes.

The partner creates the products and associated userservices in the same way.

After the integration phase has ended, a second productOrder call is sent to the partner (UC2.2). A complementary userServiceQuantity is given for previously created products (identified by productRefId generated at first call by the partner).

The partner may choose to create a new productRefId or not for the added services. The rule is:

The productRefId (ID of the customers’s fleet) known by Orange is used in the request:

  • If possible, the new created licenses are attached to this fleet ID.
  • Otherwise, the new licenses are attached to another fleet ID (either new or existing) and in this case, the partner provides this fleet ID in the answer.

In synchronous mode, the productOrder state returned can be:

  • completed if all end user services are produced (not used),
  • failed if nothing has been produced

In asynchronous mode , the productOrder state returned synchronously is acknowledged if no error occurred. Then, asynchronously, the POST /event sends the final state, partial , completed or failed .

Note : in this release, the order request contains only one order item. So, the partial state is not used.

UC3 - Customer adds new licenses

Same behaviour as in UC 2.2.

Orange sends a productOrder to the partner with order items each refering to a previously created product by its productRefId. A complementary userServiceQuantity is given.

UC4 - Customer cancels their subscription to an application, i.e. all licenses of the product

Orange sends a productOrder with an OrderItem whose action is delete . The orderItem supplies the producRefId of the product to terminate.

Go up

POST productordering event

POST /mba/productordering/v2/event

  • Request Body Resource : event
  • Response Body Resource : event

UC5 - if the partner has implemented asynchronous response , the partner sends Orange response for UC1, UC2, UC3 and UC4

If partner has implemented asynchronous response for Orange requests, the productOrder.state in HTTP POST response is "acknowledged" . Then, the partner sends an event with the final productOrder state and content.

The event has a state according to the final state of the order : 'completedStateNotification', 'partialStateNotification', 'failedStateNotification'.

Note : in this release, the order request contains only one order item. So, the partial state is not used.

The event provides the details of the ProductOrder with created or modified resources especially productRefId or id of userService and the state of the productOrder and product order items.

Go up

GET userService

GET /userservice/v2/userService

  • Request query parameter:

    • id (is a list of userService IDs, comma separated)
    • or path parameter : mba/UserService/V2/userService/{id} ( to consult one service)
    • or productRefId (id of the product = id of the fleet of user services )
  • Response Body Resource: array of userService

UC1 - Orange consults licenses

The query parameters allow three kinds of consultations:

  • get all user services for one given customer fleet. Note that if the partner creates a new product (new producRefId) each time user services are added, then many calls may be necessary to get all expected user services.
  • get a list of user services using their IDs
  • Get one dedicated user service

Go up

POST userService update

POST /userservice/v2/userService/update

  • Request body resource userServiceUpdate
  • Response Body Resource : userServiceUpdate ( contents state attribute and an array of userServices )

The state attribute of userServiceUpdate is "acknowledged" if the answer is asynchronous, "completed" or "partial" or "failed" if synchronous and no error.

Note : the partial state is not used. The global response must be completed or failed. All requests for changes (array of user services) are managed as a transaction.

UC2 - Suspension or reactivation of licenses

If Orange sends a list of licenses with userService.externalState equals 'suspended' or 'inactive' then the partner inactivates the userService and set the userService.state to inactive.

The inactivation does not suppress the user service nor modify their login or password.

If userService.externalState is active then the partner reactivates the userService and userService.state is changed to active.

UC3.x - Change of licenses through operations, productOfferingOperation, rightOperation , endUserOperation , realizingResourceOperation

Orange sends the partner a list of user services with a list of operations for each. The operations can be combined but are presented separately beneath.

UC 3.1 - operations on the end user

An endUserOperation consists of an action and enduser data

  • action = "add" to link the service to a user if no user was already linked to the license.
    • user data is provided (name, email,... )
    • user ID is generated by the partner except if Orange provides one that was previously generated by the partner and that still exists.
  • action = "modify” when an existing end user linked to a license is updated (change of name, email for ex)
  • action = "delete” when an end user is deleted from an existing userService (then no more end user is specified)

UC 3.2 - manage the technical resource

The customer can modify the realizingResourceOperation technical resource.

  • action = "modify" to initialize or update the realizingResource.
    • the type of support on which the licenses are implemented to deliver the end user service is provided (mobile, URL, email, etc).
    • the values of realizing resource properties defined by partner are provided.

UC 3.3 - Product offering migration

A productOfferingOperation consists of the swap action of the productOffering . The externalReference of the new productOffering is supplied by Orange.

US 3.4 - operation on the login and password

A rightOperation consists of:

  • an action

    • " resetLogin " if the login is to be reset to a default value generated by the partner. In this case the password is also regenerated
    • " resetPwd " if the login is not modified but the password has to be regenerated.
  • a login type ( LoginKeyValue.key ) : either "login" if specific or "organizationCode" if common to all user services

  • a login value ( LoginKeyValue.value)
  • an e-mail to send the login and/or password

UC4 - Deletion of licenses within one customer's fleet

If Orange sends a list of user services with userService.externalState 'deleted' then the partner terminates the userService.

Go up

POST userservice event

POST /mba/userservice/v2/event

  • Request body resource : event
  • Response body Resource : event

UC5 - if partner has implemented asynchronous response , partner sends response to Orange for UC1, UC2, UC3 and UC4

The event has a state "updateNotification" and contents an array of userServices.

The supplied userServiceUpdate.state in the HTTP POST response allows to distinguish how the partner will anwer: " acknowledged " if asynchronous answer, " completed " or " partial " or " failed " if synchronous.

Note : the partial state is not used. The global response must be complete or failed. All requests for changes (array of user services) are managed as a transaction.

Go up

Advanced description

You will find in the "getting advanced (PDF)" document the different use cases with sequence diagrams and examples.

Business Apps - Getting advanced 2.3.pdf

Go up

Glossary

Term : Definition
Business application : An application produced by a partner and distributed by Orange to customer. This application is used by customer employees.
Customer : The customer is a company or organization who has ordered Orange licenses for business applications
End user : An individual person, who uses the business application subscribed by his company.
Contact : An individual person, either a customer contact or an Orange contact who plays a role in the customer's order
Fleet of services : Set of services owned by a customer. see also service
Fleet Manager : Customer’s contact who manages the business application and fleet of users for the company
Partner : The application developer that has contracted with Orange to distribute their products to customers
Product : A product represents the subscription of a business application by a customer. It is quantified by a number of licenses. A license enables a user service. So the product is a fleet of services owned by the customer corresponding to one dedicated business application
Product Offering : Mobile Business Application offering in Orange Catalog
Service : This is an individual access to a business application delivered to a company. This access may or may not be associated with a unique end user. It is called user Service in the document.

Go up

History of document

Version of the documentmodification datedescription of modificationsAPIversion of the corresponding API
1.020/04/2016initialMBA Order and Service Management2.0
1.131/08/2016wordingMBA Order and Service Management2.0

Go up