Table of Contents
- Table of Contents
- Authentication prerequisite
- Base URL
- API Description
- Other Properties
- Understand a catalog offer ?
This document is a complement to TMF 632 documentation regarding the technical details mandated by the TM Forum applied to our application (https://www.tmforum.org/resources/standard/tmf632-party-management-api-rest-specification-r19-0-0/)
Authentication prerequisite
Access to this API is secured by the OAuth 2.0 framework with the Client Credentials grant type, which means that you will have to present an OAuth 2.0 access_token
whenever you want to request this API.
It's easy to negotiate this access_token
: just send a request to the proper token negotiation endpoint, with a Basic Authentication header valued with your own client_id
and client_secret
.
For this API, 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
.
SDK to manage token lifecycle could help you to implement cache token.
Scopes
Scopes restrict specific request verbs for any resource of this api. You must specify at least one when requesting for an access_token
. This is done by adding a scope
parameter within the access token request. Scopes are additive and shall be space separated.
As an example:
curl -X POST \
-H "Authorization: Basic NktSSHljksdj7P...Jjndb6UdnlrT2lOaA==" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "grant_type=client_credentials&scope=owf:united-way:scope1 owf:united-way:scope2" \
https://api.orange.com/oauth/v3/token
Scopes available in this api are explained below.
Scope | Description |
---|---|
owf:united-way:product-catalog:v1:readonly | Allow GET, HEAD http request for any resource of this api |
For your client to do GET
requests, you must request an access_token
with '&scope=owf:united-way:product-catalog:v1:readonly
'.
Scopes are not fine-grained permissions. While an access_token
can allows your client application to do GET or POST request, the request can be forbidden at the resource level.
We strongly encourage you to register a dedicated client application to subscribe to all API Place apis. You will be able to request an
access_token
with all scopes required to do a complete scenario over all needed apis.
Important
Please pay particular attention to properly handle authentication error responses in your application. See the section Errors
Base URL
The Base URL is the first part of the full invocation URL, just before the resource paths defined in the API reference.
The Base URL is comprised of the scheme ('https'), the authority (i.e. the Fully Qualified Domain Name) and the API base path.
Whenever you request this API and encounter a 404 NOT FOUND HTTP error response, please check first that the Base URL is correct.
The Base URL for this API is: https://api.orange.com/united-way/product-catalog-management/v1
The documentation below assumes that, whenever you make requests on this API, you are prepending the Base URL to the resource paths defined for this API.
API Description
Introduction
The catalog APIs allow to retrieve informations about commercial catalog. The APIs will cover not only the catalog itself as a container but also the catalog contents. A Product Catalog is a collection of Product Offerings, intended for one or several Distribution Channel(s), enhanced with additional information such as product offering tarification and classification details.
The APIs covers catalogs contents which are: product offerings, categories, productSpecification, productSpecCharacteristics.
Resources
Resource | Definitions |
---|---|
productOffering | The Product Offering represents entities that are orderable from the provider of the catalog, this resource includes productSpecification, productOfferingTerm, attachment, and ratingType. Note: isBundle determines whether a productOffering represents a single productOffering (false), or a bundle of productOfferings (true) |
category | A category is used to group product offerings in logical containers. Categories can contain other categories and/or product offerings |
productSpecification | A productSpecification hold productSpecCharacteristic and could be shared between several product offerings |
productSpecCharacteristic | A productSpecCharacteristic is linked to a product offering and allow to describe attribute to customize or configure the associated product |
Get productOffering information
Parameters
Name | Description | Type | Mandatory |
---|---|---|---|
categoryId | Identifier of category | String | No |
catalogContractualDate | date to consider for filtering catalog information (by default today date is used) | Date | No |
externalReferentielId | external catalogue identifier(ex: BSCS) | String | No |
externalId | identifier in the external catalogue | String | No |
Request
curl -X GET ".../productOffering/GOC40150084001"
Response
200 OK
Content-Type: application/json;charset=UTF-8
{
"id": "GOC40150084001",
"href": ".../productOffering/GOC40150084001",
"name": "Offre exemple",
"shortName": "Offre exemple",
"category": [
{
"id": "AERO",
"href": ".../category/AERO",
"name": "Aero"
},
{
"id": "FTTH",
"href": ".../category/FTTH",
"name": "FTTH"
},
],
"bundledProductOffering": [
{
"id": "OC40150084001",
"href": ".../productOffering/OC40150084001",
"name": "Offre exemple"
}
],
"visible": "true",
"isTopLevel": true,
"isBundle": true,
"isFulfillable": true,
"isInstallable": true,
"productOfferingType": "contract",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "DOA"
}
],
"viewProperty": {
"isHideInSynthesisView": false,
"isFoldedByDefault": false,
"isQuantityAllowed": false
},
"otherProperty": [
{
"id": "apiQuotable",
"simpleValue": "true"
},
{
"id": "apiOrderable",
"simpleValue": "false"
},
{
"id": "ihmOrderable",
"simpleValue": "false"
},
{
"id": "priceFrom",
"simpleValue": "42,60 €"
},
]
}
Fields description
Field name | Type | Description |
---|---|---|
id | String | id of productOffering |
name | String | Name of a productOffering |
visible | string | Specify if the productOffering should be visible for order capture |
selectable | String | Specify if the productOffering should be user-selectable during order capture |
isTopLevel | Boolean | Specify if the productOffering is a top-level offer (not part of a bundle) |
isBundle | Boolean | Specify if the productOffering is a 'head' bundle offer (could be itself part of a bundle) |
isFulfillable | Boolean | Specify if the productOffering has to be sent for fulfillment |
isInstallable | Boolean | Specify if the productOffering has to be installed |
productOfferingType | String | Describe the type of the product offering : contract, play, atomic offer, ... |
marketingWeight | String | Describe the weight of the product offering for marketing perspective |
valueType | String | Type of the value : 'string', 'number', 'date', ... |
category | ||
name | String | Name of category |
href | String | link to the category |
bundledProductOffering | ||
name | String | Name of the children |
href | String | link to the children |
productSpecCharacteristic | ||
id | String | unique identifier for the productSpecCharacteristic |
name | String | Name of the productSpecCharacteristic |
visible | String | Specify if the productSpecCharacteristic should be visible for order capture |
configurable | String | Specify if the productSpecCharacteristic should be configurable during order capture |
publicKey | String | publicKey if any (msisdn) |
valueType | String | type of the productSpecCharacteristic |
minValue | String | minValue of the productSpecCharacteristic |
maxValue | String | maxValue of the productSpecCharacteristic |
validationPattern | String | pattern to validate the productSpecCharacteristic |
isDisplayInSynthesisView | Boolean | Inform if this productSpecCharacteristic has to be displayed in the synthesis view |
property | ||
id | String | unique identifier of the property |
name | String | name of the property |
simpleValue | String | single value for the property |
multiplesvalues | String | array of values for the property |
value | ||
id | String | identifier of the value |
label | String | description of the value |
externalIdentifier | ||
id | String | name of the identifier |
referentialId | String | external catalogue identifier |
productOfferingRelationship | ||
id | String | identifier of the value |
name | String | name of the Relationship |
RelationshipType | String | type of the Relationship |
startDate | String | startDate of the RelationShip |
Get ProductSpecification
Parameters
Name | Description | Type | Mandatory |
---|---|---|---|
productSpecificationId | Identifier of the Product Specification | String | Yes |
Request
curl -X GET ".../productSpecification/PS40150084001"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": "PS40150084001",
"href": ".../productSpecification/PS40150084001",
"version": "1",
"name": "Activation des ressources",
"productSpecCharacteristic": [
{
"id": "FONC40140084004",
"href": ".../productSpecCharacteristic/FONC40140084004",
"name": "Débit d'accès Montant/Descendant",
"visible": "true",
"configurable": "false",
"productSpecCharacteristicValue": [
{
"systemValueCode": "VF0000340140084004",
"value": "500M/1000M",
},
{
"systemValueCode": "VF0000440140084004",
"value": "800M/1000M",
},
{
"systemValueCode": "VF0000640140084004",
"value": "800M/2000M",
}
]
}
]
}
Fields description
Field name | Type | Description |
---|---|---|
id | String | unique identifier for the productSpecification |
name | String | Name of the productSpecification |
version | String | Version of de productSpecification |
id | String | unique identifier for the productSpecCharacteristic |
visible | String | condition of visibility of productSpecCharacteristic |
configurable | String | Specify if the productSpecCharacteristic should be configurable during order capture |
publicKey | String | publicKey if any (msisdn) |
valueType | String | type of the productSpecCharacteristic |
Get productSpecCharacteristic
Parameters
Name | Description | Type | Mandatory |
---|---|---|---|
productSpecCharacteristicId | identifier of the productSpecCharacteristic | String | Yes |
Request
curl -X GET ".../productSpecCharacteristic/FONC40990080002"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": "FONC40990080002",
"href": ".../productSpecCharacteristic/FONC40990080002",
"name": "Intervention",
"visible": "true",
"configurable": "false",
"productSpecCharacteristicValue": [
{
"systemValueCode": "VF0000140990080002",
"value": "RDV court - Prise optique présente",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "ITC"
}
]
},
{
"systemValueCode": "VF0000240990080002",
"value": "RDV Immeuble (RDC) - Intervention complexe",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "ITR"
}
]
},
{
"systemValueCode": "VF0000340990080002",
"value": "RDV Immeuble - Prise optique à poser dans Immeuble",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "ITL"
}
]
},
{
"systemValueCode": "VF0000440990080002",
"value": "RDV pavillon - Prise optique à poser dans pavillon",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "ITP"
}
]
},
{
"systemValueCode": "VF0000540990080002",
"value": "Intervention sans pose ONT : Prise Optique présente",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "IQC"
}
]
},
{
"systemValueCode": "VF0000640990080002",
"value": "Intervention sans pose ONT : Prise Optique à poser dans Immeuble",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "IQL"
}
]
},
{
"systemValueCode": "VF0000740990080002",
"value": "Intervention sans pose ONT : Prise Optique à poser dans pavillon",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "IQP"
}
]
},
{
"systemValueCode": "VF0000840990080002",
"value": "Intervention avec pose ONT : Prise Optique présente",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "IOC"
}
]
},
{
"systemValueCode": "VF0000940990080002",
"value": "Intervention avec pose ONT : Prise Optique à poser dans Immeuble",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "IOL"
}
]
},
{
"systemValueCode": "VF0001040990080002",
"value": "Intervention avec pose ONT : Prise Optique à poser dans pavillon",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "IOP"
}
]
},
{
"systemValueCode": "VF0001140990080002",
"value": "Intervention sans pose ONT : Intervention Complexe en Immeuble (RDC)",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "IQR"
}
]
},
{
"systemValueCode": "VF0001240990080002",
"value": "Intervention avec pose ONT : Intervention Complexe en Immeuble (RDC)",
"externalIdentifier": [
{
"referentialId": "eRDV",
"id": "IOR"
}
]
}
]
}
Fields description
Field name | Type | Description |
---|---|---|
id | String | unique identifier for the productSpecCharacteristic |
name | String | Name of the productSpecCharacteristic |
visible | String | Specify if the productSpecCharacteristic should be visible for order capture |
configurable | String | Specify if the productSpecCharacteristic should be configurable during order capture |
validationPattern | String | pattern to validate the productSpecCharacteristic |
isDisplayInSynthesisView | Boolean | Inform if this productSpecCharacteristic has to be displayed in the synthesis view |
property | ||
id | String | unique identifier of the property |
name | String | name of the property |
simpleValue | String | single value for the property |
multiplesvalues | String | array of values for the property |
value | ||
id | String | identifier of the value |
label | String | description of the value |
externalIdentifier | ||
id | String | name of the identifier |
referentialId | String | external catalogue identifier |
Warning:the producSpecCharacteristic which are isVisible:false and isModifiable:false are for internal use of API Place, so mustn’t be used for quotation or order in API.
Get Category information
Parameters
Name | Description | Type | Mandatory |
---|---|---|---|
isRoot | True (default value) to return the first level only | Boolean | No |
catalogContractualDate | date to consider for filtering catalog information (by default today date is used) | Date | No |
Request
curl -X GET ".../category/AERO"
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": "AERO",
"href": ".../AERO",
"name": "Aero",
"isRoot": false,
"links": {
"child": [
{
"id": "FTTE",
"href": ".../category/FTTE"
},
{
"id": "FTTO",
"href": ".../category/FTTO"
},
{
"id": "FTTH",
"href": ".../category/FTTH"
}
]
}
}
Fields description
Field name | Type | Description |
---|---|---|
id | String | unique identifier for category |
name | String | name of category |
isRoot | Boolean | is the first level of category |
description | String | description of the category |
Other Properties
The field otherProperty
is used to describe general characteristics of offers and products. For each operationSpecification
, a list of properties is given. Those properties allow you to add necessary information in the quote or order about RelatedParty, RelatedPlace and Appointment. Depending on the type of operation, you have to provide a value in the body of the request for each property starting with expected*
(properties that do not start with expected*
are for internal use only). The format of the value depends on the type of the expected property. See below for details on each expected property.
OperationSpecification
This field is used in the body of a quote (attribute quoteSpecification
of the quote) or an order (attribute productOrderSpecification
of the productOrder) in order to indicate the type of operation. Below the list of existing type of operation:
Possible values | Description |
---|---|
Acquisition | quote or order for a new configuration |
Termination | quote or order for a termination of an existing contract |
gtrModification | quote or order to update the GTR of an existing contract |
speedCosModification | quote or order to update the speed or the profil voix if VLAN=TAG of an existing contract |
Properties related to "RelatedParty"
Code | Description | Possible values |
---|---|---|
expectedParty | "Role" possible values:user, buyer, operatorInterlocutor, operatorDeliveryDriver, customerInterlocutor, deliveryDriver, preSalesEngineer, recipient... and "Type" possible values:party, individual, organization, party role... |
If an expectedParty is expected for the process type and offer you want to quote or order, then you have to set a RelatedParty having the role given by the property expectedParty in the body of the quote or order.
Below the definition of the possible roles of party:
Role | Description |
---|---|
buyer | operator buyer (you) |
seller | Orange Wholesale |
operatorInterlocutor | operator interlocutor in charge of the follow and administration of orders |
operatorDeliveryDriver | technical interlocutor of the operator |
customerInterlocutor | interlocutor of the customer |
deliveryDriver | Orange Wholesale interlocutor in charge of the delivery |
preSalesEngineer | description of the category |
recipient | recipient of material |
Properties related to "RelatedPlace"
Code | Description | Possible values |
---|---|---|
expectedPlace | expectedPlace."Role":"Type" | "Role" possible values:deliveryAddress, appointmentAddress, shippingAddress... and "Type" possible values:place, geographicAddress, geographicLocation, geographicSiteBuilding |
expectedSubAddress | expectedSubAddress."Role":"Type" | "Role" possible values:deliveryAddress... and "Type" possible values:tradingName, building, staircase, floor |
expectedResource | If this property is resourcePto, then a reference PTO is mandatory to create an order | resourcePto |
If an expectedPlace is expected for the process type and offer you want to quote or order, then you have to set a place with the same type than the catalog property in the body of the quote or order.
Properties related to "Appointment"
Code | Description | Possible values |
---|---|---|
expectedAppointment | If this property is set to true, then an appointment is mandatory to create an order. In this case the id of the appointment must be set for the appointment property in the order body | true or false |
Understand a catalog offer ?
Catalog Offer Description
A catalog offer is composed of several bundles and product offerings with relationships. A catalog offer is broken down into 4 levels of product offerings:
- level 1: Contract
- level 2: Play
- level 3: Set
- level 4: atomicOffer
Here a sample of possible catalog offer structuration
Contract | Play | Set | atomicOffer | Relationship |
---|---|---|---|---|
ProductOffering Contract 1 | bundles "productOffering Play | |||
productOffering Play 1 | bundles "productOffering Set 1" | |||
productOffering Set 1 | bundles "productOffering atomicOffer 1", "productOffering atomicOffer 2" and "productOffering atomicOffer 3" | |||
productOffering atomicOffer 1 | ||||
productOffering atomicOffer 2 | ||||
productOffering atomicOffer 3 | ||||
productOffering Set 2 | bundles "productOffering atomicOffer 4" | |||
productOffering atomicOffer 4 |
Visual representation of a catalog offer
Offer's commercial rules
The product catalog management API retrieve all the fields and the possible values for each fields, but not the dependance rules between fields nor commercial rules linked to offer.
Bellow a document which describe commercial rules by offer: Fiche offre FTTH Access
- New: débit 8G symétrique dans les zones éligibles
- New: upgrade possible d'un débit 500M/1000M ou 800M/1000M avec ONT 1G Orange, vers un débit 800M/2000M avec renvoi ONT 2G Orange