API Place - Product Catalog Management

1.0

• 1.0 (current)
• 0.9 (deprecated)

Table of Contents

• Table of Contents
• Authentication prerequisite
  • Scopes
  • Important
• Base URL
• API Description
  • Introduction
  • Resources
    • Get productOffering information
      • Parameters
      • Request
      • Response
      • Fields description
    • Get ProductSpecification
      • Parameters
      • Request
      • Response
      • Fields description
    • Get productSpecCharacteristic
      • Parameters
      • Request
      • Response
      • Fields description
    • Get Category information
      • Parameters
      • Request
      • Response
      • Fields description
• Other Properties
• Understand a catalog offer ?
  • Catalog Offer Description
    • Visual representation of a catalog offer
    • Offer's commercial rules

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.

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

Get productOffering information

Parameters

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

Get ProductSpecification

Parameters

Request

curl -X GET ".../productSpecification/PS40150084001" 

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8

{
  "id": "PS40130085001",
  "href": ".../productSpecification/PS40130085001",
  "version": "2",
  "name": "Activation sur fibre optique",
  "productSpecCharacteristic": [
    {
      "id": "FONC40130085001",
      "href": ".../productSpecCharacteristic/FONC40130085001",
      "name": "Profil de CoS",
      "visible": "true",
      "configurable": "false",
      "productSpecCharacteristicValue": [
        {
          "systemValueCode": "VF0000240130085001",
          "value": "data entreprise"
        },
        {
          "systemValueCode": "VF0000340130085001",
          "value": "data garantie"
        },
        {
          "systemValueCode": "VF0000140130085001",
          "value": "business"
        },
        {
          "systemValueCode": "VF0000440130085001",
          "value": "premium"
        }
      ]
    }

Fields description

Get productSpecCharacteristic

Parameters

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

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

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

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:

Properties related to "RelatedParty"

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:

Properties related to "RelatedPlace"

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"

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

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 documents which describe commercial rules by offer:

• Fiche offre FTTH Access
• Fiche offre Optimum Ethernet Entreprises
• Fiche offre Optimum Ethernet LAN