.wpb_animate_when_almost_visible { opacity: 1; }
Orange Business Applications France
Boost your SaaS revenue by joining Orange Business Services' partner program (France)
2.2

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 Orange Business Applications 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 (mentioned in the 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 Business Applications partner are identified inside the following array.

FeatureAPIoptional/mandatorythe call comes from
Service availabilitypingmandatoryOrange
Creation of a customerproductOrderingmandatoryOrange
Ordering user licensesproductOrderingmandatoryOrange
Consultation of licensesuserServicemandatoryOrange
Management of the end user using a license (add, modify, delete)userServiceoptionalPartner
Change of state of licensesuserServicemandatoryOrange
Deletion of one or many licensesuserServicemandatoryOrange
Change the product offering of one or many licensesuserServiceoptionalOrange
Management of technical resource supported by a licenseuserServiceoptionalPartner
Renewal of login of a licenseuserServiceoptionalPartner

Specify whether the results will be provided in synchronous or asynchronous mode.

In the Appendix 2, you must in particularly :

  • 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).
  • Optional: 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).

For any question about Business apps features to provide inside Appendix 2 of the agreement , contact us at the following e-mail address : Orange business Applications technical team

Go Up

Project phases

Publish and subscribe to the APIs

At least two weeks before the integration phase, you have to publish the APIs (ProductOrdering and UserService).

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 Orange Business Applications API events.
  3. Subscribe to Orange Business Applications APIs (select Orange Business Applications in the list of APIs to include in your application). Orange team will validate your subscription to activate authentication key for your API subscription
  4. As soon as API is included in your application (don't wait for API validation, click right now), click on "configure" button to fill 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.

Nota: This section describes how to subscribe to APIs in the Orange production environment. To test the APIs during integration phase in a non-production environment, you have to subscribe to a specific offer "Orange Business Applications – Beta". You must contact the Orange technical team at the following e-mail address Orange business Applications technical team to manage this subscription. They will help you to to receive an invitation to subscribe.

Consume the APIs

The standard protocol of authentication OAuth 2.0 with https is used with grant_type = client_credentials to manage the authentication of an application to access resources through Orange Partner Gateway (See here for more information about 2-Legged OAuth2.0 proxy V3 identity and authentication protocol):

API authentication

The following document explains how to request a token via the server token provided by the Orange Gateway OPE and how to use this token to consume the API toward the Orange gateway OPE: Consumption of an API via Orange Gateway OPE

Development phase

JSON files are provided to assist you in the development phase in the following zip files: productOrder zip file and userService zip file

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.

During the development phase, in addition to the tests performed in the partner IT, developers could use a tool provided by Orange: Partner Onboarding Helper. This application allows to perform in complete autonomy a first level of tests on the development done to integrate part of functionalities of the Orange Business Applications France API. it allows to simulate the API calls made in synchronous mode by the Orange IT without asking Orange to make these calls. The aim is to check that the data provided in the response is consistent with what Orange SI expects. To obtain the installation procedure and a user guide for this application, send an email at shine2.onboarding@orange.com.

Integration phase

Once your APIs are developed, tested and published, you will start a new phase: the integration tests.

Because, during this integration phase, the API calls are initiated by Orange, you must send an email at shine2.onboarding@orange.com to begin testing.

The integration phase is divided in two steps :

  • Step1: tests on a non-production environment on Orange side. All the use cases implemented are tested to validate the APIs developments done by the partner and to validate the use of the event implemented by Orange if the partner manages asynchronous response. On the partner side, we recommend performing the tests in a development environment.
  • Step2: once all the tests performed during step1 are OK, tests are now performed on the production environment on Orange side using a simulated customer. Only some functional tests are performed to verify that all is OK.

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 ?
  • 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, the average is about 15 man-day to integrate the two 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 Orange Business Applications 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 when the deployment of orders is terminated and/or changes done.

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

GS API context

Two APIs are used:

  • ProductOrdering for customer creation, first order to activate services or adding of services in one existing fleet.

  • UserService for service management (consult, change status, change offer, manage end user, delete license, renew login or change technical support of license). Notice that renew login, manage end user and change technical support of license is not done from Orange request, these operations are sent by partner to Orange, these operations are never sent by Orange to partner.

Inside each API, there are 2 main resources:

  • the main business resources exposed by partner and consumed by Orange (allowing Orange to transfer customer requests to the partner):
    • productOrder inside ProductOrdering API,
    • userService inside UserService API,
  • the 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 requests in an asynchronous way.

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

Nota: As the integration phase is performed on an Orange non-production environment and then on an Orange production environment, two offers are necessary. So, in the API call mentioned in the following table, the variable [offer] is valued at “mba2” for production or at mba2-beta (for beta version). This variable is only necessary in the case of the use of the event by the partner to manage an asynchronous response. During the integration/phase, the same sequence of activities described in the following table is done as in deployment phase but on a limited number of user services.

(*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
3 - Orangefollowing 2, instructs partner to create order and activate servicesOrange POST /productordering/v2/productOrder
only if partner has implemented asynchronous response (*1)Partner POST /[offer]/productordering/v2/event
4 - Orangefollowing 3, can consult details of customer's servicesOrange GET /userservice/v2/userService
5 - Customerwants to modify his services: suspend or activate, change product offering to migrate from one offer to another
6 - Orangefollowing 4, can modify services: suspend or activate, change product offering to migrate from one offer to anotherOrange POST /userservice/v2/userService/update
only if partner has implemented asynchronous response (*1)Partner POST /[offer]/userservice/v2/event
7 - Customerwants to suppress one or many services
8 - Orangefollowing 4, can suppress servicesOrange POST /userservice/v2/userService/update
only if partner has implemented asynchronous response (*1)Partner POST /[offer]/userservice/v2/event
9 - Customerwants to add services to their fleet
10 - Orangefollowing 4, can add services to their fleetOrange POST /productordering/v2/productOrder
only if partner has implemented asynchronous response (*1)Partner POST /[offer]/productordering/v2/event
11 - Partner (because Customer changes information using partner tools)associates/deassociates an end user to service, changes login, changes resources on which licence is builtPartner POST /[offer]/userservice/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 API

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

ProductOrdering API

Resource nameDescription
ProductOrderMain resource. a ProductOrder represents a customer order for a business application. It is composed of _orderItem sub-resources. It also defines a unique customer as an Organization sub-resource, and contacts as Individual sub-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 response . An Event is typed and composed of a unique ProductOrder Resource
ExternalReferenceReference given by Orange in opposite to ID attributes given by partner. Sub-Resources Organization, Individual, ProductOfferingRef have an external reference.
Contactrepresents a customer contact (customer fleet contact) or an Orange contact
ProductRefIt is the fleet of services for a customer. Contains the id of the fleet and the number of services to activate inside this fleet (number of services is provided in "delta" mode: the new ones to add)
ProductOfferingRefThe offer declared in the Orange Catalog identifying which is the service to activate
CustomerThe customer information (trading name, registration information, postal address, caharcateristic,... of the organization)
OrderItemAn order item in the product order defines the content of the order, there is one orderItem per product order

UserService API

Resource nameDescription
UserServiceMain resource. This is the implemented services created on partner side in the order process and delivered to a customer. It has a relatedProductRefId attribute which identifies the service's fleet (the group of services for the customer). One customer can have one or several fleets. Nota: the userService is also called license or application in this getting started.
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
EndUserThe person (Individual) who uses the userService. One or zero end user can be assigned to a user service.
RealizingResourceOperationOperation used to add, modify, swap, delete the RealizingResource of a service. A RealizingResource is a technical resource the service depends on, such as a mobile number for example. 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

Nota: [offer] = mba2 (for production) or mba2-beta (for beta version)

Use CaseCallerEnd pointMethod URL
UC1 - Creation of customer and contactsOrangePartnerPOST https://[partnerServer]/productordering/v2/productOrder
UC2 - Creation of customer fleet and activation of all servicesOrangePartnerPOST https://[partnerServer]/productordering/v2/productOrder
UC3 - Adding new services to an existing fleetOrangePartnerPOST https://[partnerServer]/productordering/v2/productOrder
UC4 - if partner has implemented asynchronous response , partner sends result to Orange for UC2, UC3PartnerOrangePOST https://ope.apibackbone.orange.com/[offer]/productordering/v2/event

UserService API

Nota: [offer] = mba2 (for production) or mba2-beta (for beta version)

Use CaseCallerEnd pointMethod URL
UC1 - Consultation of licensesOrangePartnerGET https://[partnerServer]/userservice/v2/userService
UC2 - Suspension or reactivation of licensesOrangePartnerPOST https://[partnerServer]/userservice/v2/userService/update
UC3 - Deletion of licenses within a customer fleetOrangePartnerPOST https://[partnerServer]/userservice/v2/userService/update
UC4 - Change product offering of licenses (use of ProductOfferingOperation)OrangePartnerPOST https://[partnerServer]/userservice/v2/userService/update
UC5 - Change of licenses through operations on end user (EndUserOperation), on login/password (RightOperation) and/or on technical resources (RealizingResourceOperation)PartnerOrangePOST https://ope.apibackbone.orange.com/[offer]/userservice/v2/event
UC6 - if partner has implemented asynchronous response, partner sends response to Orange for UC2, UC3 and UC4PartnerOrangePOST https://ope.apibackbone.orange.com/[offer]/userservice/v2/event

Go Up

POST /productOrder

POST /productordering/v2/productOrder

  • Request body resource : productOrder
  • Response body resource : productOrder

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

  • value is acknowledged if asynchronous response is provided,
  • value is completed or failed if synchronous response is provided.

Note: The order request contains only one order item.

UC1 - Partner creates the customer and contacts

Orange sends the partner a productOrder 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 - Partner creates the customer fleet and activates user services

Orange sends a productOrder to the partner with add action on orderItem. The category attribute of the productOrder is valued to 'production'. For each orderItem the externalReference of a product offering and an userServiceQuantity are provided to create the product. endUserConfiguration may also be provided in the orderItem depending on what was precised inside Annex 2 of the contract.

In a synchronous or asynchronous mode (see also UC4), the fleet with its licenses is created by the partner and the fleet ID (productRefId) is generated. The fleet ID returned to Orange in the final response will be used to get licenses using the UserService API for one dedicated customer and for next orders.

The partner creates the fleet and associated services for the customer.

In synchronous mode, the value of 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 value of productOrder.state returned synchronously is acknowledged if no error occurred. Then, asynchronously, the POST /event sends the value of the final state: completed or failed.

Notes:

  • The order request contains only one order item.
  • The licenses are created and returned with a GET only when the product order state is valued to "completed'.

UC3 - Customer adds new licenses

Same behavior as in UC2 except that the fleet id is provided by Orange (this is the fleet id collected at first order. Reminder: fleet id = productRefId

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.

The partner may choose to create a new productRefId or not for the added services. The rule is: the productRefId (ID of the customer fleet) known by Orange is used in the request and:

  • 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.

Go Up

POST /event on productOrder

POST /[offer]/productordering/v2/event with [offer] = mba2 (for production) or mba2-beta (for beta version)

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

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

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

The event has a state according to the value of the order final state: completedStateNotification or failedStateNotification.

Note: in this release, the order request contains only one order item.

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

  • Request query parameter:

  • id (a list of userService IDs, comma separated)

  • or path parameter: userService/{id} (to consult one service)

  • or productRefId (id of the fleet of user services)

  • Response body resource: array of userService corresponding to the parameter given in the request

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 fleet (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.

Nota: Only consultation with a fleet identifier (productRefId) is implemented.

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 value of state attribute of userServiceUpdate is acknowledged if the response is asynchronous, completed or failed if the response is synchronous and no error.

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

UC2 - Orange suspends or reactivates licenses

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

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

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

UC3 - Orange deletes licenses within one customer fleet

If Orange sends a list of user services with a value of userService.externalState equal to deleted then the partner terminates the corresponding userService.

UC4 - Orange manages change on licenses: product offering migration

Orange sends the partner a list of user services with a productOfferingOperation.

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

Go Up

POST /event on userService

POST /[offer]/userService/v2/event with [offer] = mba2 (for production) or mba2-beta (for beta version)

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

UC5 - Partner manages change on licenses through operations on the end user, on the login/password and on technical resources

These operations are sent by Partner to Orange using event of UserService API. The partner sends Orange a list of user services with a list of operations for each.

UC5.1 - Manage the end user of a user service

An endUserOperation consists of an action on enduser data:

  • action = add to link the service to a user if no user was already linked
    • 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)
UC5.2 - Manage the technical resources of a user service

A realizingResourceOperation consists of change on 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.
UC5.3 - Manage the login of a user service

A RightOperation consists of change on login information

  • 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

UC6 - if partner has implemented asynchronous response, partner sends response to Orange for UC1 and UC2

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

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

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 of the API

The "getting advanced (PDF)" document details the different use cases with sequence diagrams and examples : Advanced description of API

Go Up

Glossary

TermDefinition
Orange Business applicationsAn application produced by a partner and distributed by Orange to customer. This application is used by customer employees.
CustomerThe customer is a company or organization who has ordered Orange licenses for business applications
End userAn individual person, who uses the business application subscribed by his company.
ContactAn individual person, either a customer contact or an Orange contact who plays a role in the customer's order
Fleet of servicesSet of services owned by a customer. see also service (id of fleet is called ProductRef.id or ProductRefId
Fleet ManagerCustomer's contact who manages the business application and fleet of users for the company
PartnerThe application provider that has contracted with Orange to distribute their products to customers
ProductA product represents the subscription of a business application by a customer. It is quantified by a number of services. A service enables a user service. So the product is a fleet of services owned by the customer corresponding to one dedicated business application
Product OfferingOrange Business Application offering in Orange Catalog, contains a code
ServiceThis 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.017/05/2019initialOrange Business Applications Order and Service Management2.0
1.118/05/2020Go Up changes to make them available againOrange Business Applications Order and Service Management2.0
1.209/07/2020Precision in getting advanced: {} is not supported for optional node, optional node should not be provided at allrange Business Applications Order and Service Management2.0
1.327/01/2021Revision of getting started as no action on EndUserOperation exist inside ProductOrdering and no action on endUser comes from Orange (they can come only from partner side)Orange Business Applications Order and Service Management / ProductOrder2.1
1.425/02/2021Change of enum on productOfferingOperationOrange Business Applications Order and Service Management / UserService2.2
1.510/02/2022Update of the getting started to take into account feedback on the latest onboarded partnersOrange Business Applications Order and Service Management / UserService2.2
1.614/06/2022Update of the getting started version event with v2 and last FAQs on testingOrange Business Applications Order and Service Management / UserService2.2
Go Up