.wpb_animate_when_almost_visible { opacity: 1; }
United Way - Product Catalog Management
Get information on Orange Wholesale offers and management rules.

Table of Contents

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.

ScopeDescription
owf:united-way:product-catalog:v1:readonlyAllow 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 United Way 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

ResourceDefinitions
productOfferingThe 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)
categoryA category is used to group product offerings in logical containers. Categories can contain other categories and/or product offerings
productSpecificationA productSpecification hold productSpecCharacteristic and could be shared between several product offerings
productSpecCharacteristicA productSpecCharacteristic is linked to a product offering and allow to describe attribute to customize or configure the associated product

Get productOffering information

Parameters
NameDescriptionTypeMandatory
categoryIdIdentifier of categoryStringNo
catalogContractualDatedate to consider for filtering catalog information (by default today date is used)DateNo
externalReferentielIdexternal catalogue identifier(ex: BSCS)StringNo
externalIdidentifier in the external catalogueStringNo
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 nameTypeDescription
idStringid of productOffering
nameStringName of a productOffering
visiblestringSpecify if the productOffering should be visible for order capture
selectableStringSpecify if the productOffering should be user-selectable during order capture
isTopLevelBooleanSpecify if the productOffering is a top-level offer (not part of a bundle)
isBundleBooleanSpecify if the productOffering is a 'head' bundle offer (could be itself part of a bundle)
isFulfillableBooleanSpecify if the productOffering has to be sent for fulfillment
isInstallableBooleanSpecify if the productOffering has to be installed
productOfferingTypeStringDescribe the type of the product offering : contract, play, atomic offer, ...
marketingWeightStringDescribe the weight of the product offering for marketing perspective
valueTypeStringType of the value : 'string', 'number', 'date', ...
category
nameStringName of category
hrefStringlink to the category
bundledProductOffering
nameStringName of the children
hrefStringlink to the children
productSpecCharacteristic
idStringunique identifier for the productSpecCharacteristic
nameStringName of the productSpecCharacteristic
visibleStringSpecify if the productSpecCharacteristic should be visible for order capture
configurableStringSpecify if the productSpecCharacteristic should be configurable during order capture
publicKeyStringpublicKey if any (msisdn)
valueTypeStringtype of the productSpecCharacteristic
minValueStringminValue of the productSpecCharacteristic
maxValueStringmaxValue of the productSpecCharacteristic
validationPatternStringpattern to validate the productSpecCharacteristic
isDisplayInSynthesisViewBooleanInform if this productSpecCharacteristic has to be displayed in the synthesis view
property
idStringunique identifier of the property
nameStringname of the property
simpleValueStringsingle value for the property
multiplesvaluesStringarray of values for the property
value
idStringidentifier of the value
labelStringdescription of the value
externalIdentifier
idStringname of the identifier
referentialIdStringexternal catalogue identifier
productOfferingRelationship
idStringidentifier of the value
nameStringname of the Relationship
RelationshipTypeStringtype of the Relationship
startDateStringstartDate of the RelationShip

Get ProductSpecification

Parameters
NameDescriptionTypeMandatory
productSpecificationIdIdentifier of the Product SpecificationStringYes
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 nameTypeDescription
idStringunique identifier for the productSpecification
nameStringName of the productSpecification
versionStringVersion of de productSpecification
idStringunique identifier for the productSpecCharacteristic
visibleStringcondition of visibility of productSpecCharacteristic
configurableStringSpecify if the productSpecCharacteristic should be configurable during order capture
publicKeyStringpublicKey if any (msisdn)
valueTypeStringtype of the productSpecCharacteristic

Get productSpecCharacteristic

Parameters
NameDescriptionTypeMandatory
productSpecCharacteristicIdidentifier of the productSpecCharacteristicStringYes
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 nameTypeDescription
idStringunique identifier for the productSpecCharacteristic
nameStringName of the productSpecCharacteristic
visibleStringSpecify if the productSpecCharacteristic should be visible for order capture
configurableStringSpecify if the productSpecCharacteristic should be configurable during order capture
validationPatternStringpattern to validate the productSpecCharacteristic
isDisplayInSynthesisViewBooleanInform if this productSpecCharacteristic has to be displayed in the synthesis view
property
idStringunique identifier of the property
nameStringname of the property
simpleValueStringsingle value for the property
multiplesvaluesStringarray of values for the property
value
idStringidentifier of the value
labelStringdescription of the value
externalIdentifier
idStringname of the identifier
referentialIdStringexternal catalogue identifier

Warning:the producSpecCharacteristic which are isVisible:false and isModifiable:false are for internal use of United Way, so mustn’t be used for quotation or order in API.

Get Category information

Parameters
NameDescriptionTypeMandatory
isRootTrue (default value) to return the first level onlyBooleanNo
catalogContractualDatedate to consider for filtering catalog information (by default today date is used)DateNo
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 nameTypeDescription
idStringunique identifier for category
nameStringname of category
isRootBooleanis the first level of category
descriptionStringdescription 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 valuesDescription
Acquisitionquote or order for a new configuration
Terminationquote or order for a termination of an existing contract
gtrModificationquote or order to update the GTR of an existing contract
speedCosModificationquote or order to update the speed or the profil voix if VLAN=TAG of an existing contract

Properties related to "RelatedParty"

CodeDescriptionPossible 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:

RoleDescription
buyeroperator buyer (you)
sellerOrange Wholesale
operatorInterlocutoroperator interlocutor in charge of the follow and administration of orders
operatorDeliveryDrivertechnical interlocutor of the operator
customerInterlocutorinterlocutor of the customer
deliveryDriverOrange Wholesale interlocutor in charge of the delivery
preSalesEngineerdescription of the category
recipientrecipient of material

Properties related to "RelatedPlace"

CodeDescriptionPossible values
expectedPlaceexpectedPlace."Role":"Type""Role" possible values:deliveryAddress, appointmentAddress, shippingAddress... and "Type" possible values:place, geographicAddress, geographicLocation, geographicSiteBuilding
expectedSubAddressexpectedSubAddress."Role":"Type""Role" possible values:deliveryAddress... and "Type" possible values:tradingName, building, staircase, floor
expectedResourceIf this property is resourcePto, then a reference PTO is mandatory to create an orderresourcePto

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"

CodeDescriptionPossible values
expectedAppointmentIf 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 bodytrue 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

ContractPlaySetatomicOfferRelationship
ProductOffering Contract 1bundles "productOffering Play
productOffering Play 1bundles "productOffering Set 1"
productOffering Set 1bundles "productOffering atomicOffer 1", "productOffering atomicOffer 2" and "productOffering atomicOffer 3"
productOffering atomicOffer 1
productOffering atomicOffer 2
productOffering atomicOffer 3
productOffering Set 2bundles "productOffering atomicOffer 4"
productOffering atomicOffer 4

Visual representation of a catalog offer

enter image description here

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 produit FTTH Access nouveau débit 4G/8G