Vous êtes sur la page 1sur 15

SDP Partner Document

Orange APIs AMEA

IMT/OLPS
28 Chemin du Vieux Chne
38240 Meylan
Phone +33(0) 4 76 76 40 00

Orange Group

Orange SA au capital de 10 457 395 644 - 6 place dAlleray - 75505 Paris Cedex 15 - 380 129 866 RCS Paris

Documentation Partenaire
Introduction au SDP

Orange SDP : document partenaire

26/03/2014

Table des matires


1

INTRODUCTION ............................................................................................................. 3

SDP ORANGE AMEA : VUE DENSEMBLE .................................................................. 3

2.1

SDP Orange AMEA : Quest-ce que cest ?.......................................................................................... 3

2.2

SDP Orange: les acteurs et les cas dutilisation ................................................................................. 4

2.3

SDP Orange: les API offertes ................................................................................................................ 5

2.4

SDP Orange : Couverture pays et ressources..................................................................................... 5

ORANGE SDP : PREREQUIS ........................................................................................ 7

3.1

Partenaire fournit Orange ................................................................................................................... 7

3.2

Orange fournira au partenaire ............................................................................................................... 7

SDP ORANGE : DESCRIPTION DES APIS ................................................................... 8

4.1
SMS API ................................................................................................................................................... 8
4.1.1
Description de lAPI .......................................................................................................................... 8
4.1.2
Opration : send SMS ...................................................................................................................... 8
4.1.3
Opration : SMS Notification ............................................................................................................ 9
4.1.4
Opration : SMS delivery notification ............................................................................................... 9
4.2
USSD ........................................................................................................................................................ 9
4.2.1
Description de lutilisation ................................................................................................................. 9
4.2.2
Opration USSD ............................................................................................................................. 10
4.3
Payment API .......................................................................................................................................... 10
4.3.1
Description de lAPI ........................................................................................................................ 10
4.3.2
Opration : Charge a user .............................................................................................................. 10
4.3.3
Opration : Reserve an amount for charging ................................................................................. 11
4.3.4
Opration : Charge against the reservation .................................................................................... 12
4.3.5
Opration : Release the reservation ............................................................................................... 13

5
5.1

ORANGE SDP EXEMPLES DUTILISATION ............................................................... 15


Orange Infotainment Hub use case .............................................................................................. 15

Page 2/15

Orange SDP : document partenaire

26/03/2014

1 Introduction
Ce document vise prsenter la plateforme Orange SDP ainsi que les services (= APIs) quelle offre aux
partenaires dOrange sur la zone AMEA. Il a t rdig dans le cadre du challenge PME .
Ce document ne fait pas office de spcification dinterface entre les partenaires et la plateforme SDP.

2 SDP Orange AMEA : Vue densemble


2.1

SDP Orange AMEA : Quest-ce que cest ?

Orange SDP est une plateforme centralise qui expose des services relatifs aux clients mobiles des filiales
dOrange dans toute la zone AMEA. SDP permet aux partenaires Orange de dployer et denrichir leurs
applications convergentes multi fonctionnels et multi pays en rduisant drastiquement leur Time-To-Market.
Le but est de crer un cosystme gagnant-gagnant entre Orange, ses partenaires et ses clients :
- Les partenaires en enrichissant leur offre de service, leur couverture gographique et leur visibilit
auprs des clients Orange.
- Orange, en offrant par lintermdiaire de ses partenaires des services plus riches que ses concurrents,
stimulera lutilisation des ressources Orange et amliorera la fidlisation de ses clients et la captation
de nouveaux clients.
- Les clients Orange voient leur offre de service senrichir.

Fig.1 - SDP vue Gnrale

Page 3/15

Orange SDP : document partenaire

2.2

26/03/2014

SDP Orange: les acteurs et les cas dutilisation

SDP permet aux applications partenaires daccder des services (APIs). Les services sont des oprations
effectues sur des ressources des filiales Orange. Les Utilisateurs sont la fois clients des Filiales Orange
et des applications partenaires. La plateforme Orange SDP est exploite par les administrateurs Orange.

Fig.2 Orange SDP acteurs et cas dutilisation macro

Page 4/15

Orange SDP : document partenaire

2.3

26/03/2014

SDP Orange: les API offertes

Orange SDP signifie Service Delivery Platform. En se connectant cette plateforme, les partenaires dOrange
profitent donc dune offre de services (= APIs) scuriss et contrls incluant notamment :
un service de facturation des clients Orange : Payment API
un service de communication avec les clients Orange par SMS : SMS API
un service de communication avec les clients Orange par USSD : USSD API
Tous ces services sont exposs sous forme dAPIs REST ou SOAP sur une adresse unique accessible depuis
Internet. Laccs aux APIs est protg par une authentification du partenaire et lusage des API est contrl
par des rgles configures dans la plateforme Orange SDP.

Fig.3 Orange SDP : Services offerts

2.4

SDP Orange : Couverture pays et ressources

Les APIs Orange SDP couvrent aujourdhui 6 filiales Orange : Cte dIvoire, Mali, Sngal, Cameroun,
Rpublique Dmocratique du Congo, Botswana. Dans le cadre du Challenge PME, seuls les filiales suivantes
seront accessibles aux PME participantes : Cte dIvoire, Sngal, Mali.

Fig.4 Couverture pays et ressources

Page 5/15

Orange SDP : document partenaire

26/03/2014

Afin doffrir les APIs prcdemment dcrits, la plateforme Orange SDP est interconnecte avec les lments
suivants dans chacune des filiales Orange :
- SMS-C
- USSD Portal
- IN (Systme de paiement pr-pays) et Systme de paiement post-pays

Page 6/15

Orange SDP : document partenaire

26/03/2014

3 Orange SDP : prrequis


Afin daccder aux APIs exposes par la plateforme Orange SDP, le partenaire et Orange doivent changer
les informations pr-requises suivantes :

3.1
-

3.2
-

Partenaire fournit Orange


IP du back end Partenaire accdant aux API Orange SDP via Internet (filtr lors de laccs aux API)
URL recevant les appels USSD mis par les utilisateurs
URL recevant les Notifications de SMS mis par les utilisateurs (exposition de lAPI SMS Notification :
Cf. Opration :SMS Notification : partnersmsurl dans les exemples)
Contact technique

Orange fournira au partenaire


Identifiant ASPID (spId dans les exemples)
Identifiant APPID (productId dans exemples de requtes)
mot de passe accs aux APIs (permettant de calculer le spPassword dans les exemples)
URL daccs aux API SDP (SDPURL dans les exemples)
Rgles dusage de chaque API (nombre de requtes autoriss)
Documentation dinterface, best practices
Contact technique

Dautres informations/ressources pourront tre fournies aux partenaires dans le cadre du challenge PME
(cartes SIMs par exemple)

Page 7/15

Orange SDP : document partenaire

26/03/2014

4 SDP Orange : description des APIs


Les requtes sont dites AOMT ou MOAT.
- AOMT (Application Originated Mobile Terminated) sont des requtes faites par lapplication partenaire
sur les API exposes par Orange SDP.
- MOAT (Mobile Originated Application Terminated) sont des requtes faites par Orange SDP sur les
API exposes par lapplication partenaire

Fig.5 APIs et requtes AOMT et MOAT

Authentication header :
Le header dauthentification AOMT est utilis par le partenaire quand il effectue une requte sur une API
Orange SDP. (par exemple send SMS : le partenaire envoie un SMS un utilisateur). Ce header permet
Orange SDP dauthentifier le partenaire et de lidentifier afin de lui autoriser laccs lAPI quil requiert.
Le header dauthentification MOAT est utilis par Orange SDP quand il effectue une requte sur les API de
lapplication partenaire (par exemple SMS Notification : SDP envoie au partenaire un SMS provenant dun
utilisateur).

4.1

SMS API

4.1.1

Description de lAPI

LAPI SMS Orange SDP permet au partenaire les requtes AOMT suivantes :
- send SMS (SMS MT Mobile Terminated) : envoyer un SMS un ou plusieurs utilisateurs
LAPI SMS expose par le partenaire permet Orange SDP les requtes MOAT suivantes :
- SMS notification (SMS MO Mobile Originated) : envoyer au partenaire un SMS mis par un
utilisateur
- SMS delivery notification (SMS DR Delivery Receipt) : envoyer au partenaire laccus de rception
dun SMS
4.1.2

Opration : send SMS

Requte (AOMT) :
POST https://<SDPURL>/1/smsmessaging/outbound/tel%3A%2B225xxxxxxxx/requests
HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: AUTH
spId="1234567890",spPassword="cdd8065ad7acb3654b084e554dd331aa",timeStamp="XXXXXX
XXXX",productId="12345678912345"
User-Agent: Jakarta Commons-HttpClient/3.1
Host: 10.99.163.149:7601
Content-Length: 116
{"address":["tel:+225xxxxxxxx","tel:+225yyyyyyyy"],
"message":"Bonjour ceci est un message de test",
"clientCorrelator":"1234567890",
"senderName":"7788"
Page 8/15

Orange SDP : document partenaire

26/03/2014

}
Rponse :
HTTP/1.1 201 Created [XXXOSE]
Server: XXXOSE
Content-Type: application/json
Location:
http://<SDPURL>/1/smsmessaging/outbound/tel%3A%2B225xxxxxxxx/requests/00JZM143135
55526Z1010222212
Content-Length: 136
{"resourceReference":{"resourceURL":"http://<SDPURL>/1/smsmessaging/outbound/tel%
3A%2B225xxxxxxxx/requests/00JZM14313555526Z1010222212"}}
4.1.3

Opration : SMS Notification

Requte (MOAT) :
POST http://<partnersmsurl>/restSmsService/reception HTTP/1.1
Host: 10.99.171.131:5050
Content-Type: application/json
Content-Length: 203
Connection: close
Authorization: AUTH spId="1234567890",san="+225xxxxxxxx"
{ "inboundSMSMessageNotification": { "inboundSMSMessage": { "senderAddress":
"tel:+225xxxxxxxx", "destinationAddress": "+2257788 ", "message": " Bonjour ceci
est un message de test ", "dateTime": "2012-10-10T11:17:27+02:00" } } }
Rponse :
HTTP/1.1 200 OK
Date: Thu, 04 Jun 2013 02:51:59 GMT
4.1.4

Opration : SMS delivery notification

Requte (MOAT) :
POST http://<partnersmsurl>/restSmsService/delivery HTTP/1.1
Host: 10.99.171.131:5050
Content-Type: application/json
Content-Length: 165
Connection: close
Authorization: AUTH spId="1234567890"
{ "deliveryInfoNotification": { "deliveryInfo": { "address": "tel+225xxxxxxxx",
"deliveryStatus": "DeliveredToTerminal" }, "callbackData": "3093301370275764097"
}
Rponse :
HTTP/1.1 200 OK
Date: Thu, 04 Jun 2013 02:51:59 GMT

4.2

USSD

4.2.1

Description de lutilisation
Page 9/15

Orange SDP : document partenaire

26/03/2014

Afin de pouvoir se connecter dans le portail USSD de loprateur, les oprations USSD sont traits sous forme
de client serveur entre le mobile de labonn et le serveur back-end du service.
En effet, les changes entre le composant USSD du pays et le back-end partenaire se fera travers des
GET http://<partnersmsurl>/ussd/index.php
Et le back-end devra gnrer un XML qui doit tre compatible du composant USSD.
4.2.2

Opration USSD

Requte (MOAT) :
GET http://<partnersmsurl>/ussd/index.php HTTP/1.1
Host: ProxyModeMO
Connection: close
Accept: text/xml
User-Language: fr
User-MSISDN: 225xxxxxxxx
User-IMSI: xxxxxxxxxxxxxxx
Rponse :
HTTP/1.1 200 OK
Connection: close
resultCode: 0
errorInfo: success
Content-Type: text/xml;charset=utf-8
Content-Length: 29738
Connection: close
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE pages SYSTEM "cellflash.dtd">
<pages descr="startup_challenge">
<page ismenu="true" volatile="false" count="true">
Bienvenue sur mon service
<br/>
<a href="http://<partnersmsurl>/ussd/souscrire.php" key="1">Souscrire au
service</a>
<br/>
<a href="http://<partnersmsurl>/ussd/info.php" key="2">+ dinfo</a>
<br/>
</page>
</pages>

4.3

Payment API

4.3.1

Description de lAPI

LAPI Payment Orange SDP permet au partenaire les requtes AOMT suivantes :
- Charge a user : facturer un utilisateur dun montant donn
- Reserve an amount for charging to an end user : rserver un montant pour une facturation ultrieure
- Charge against the reservation : facturer une rservation antrieure
- Release the reservation : abandonner une rservation
4.3.2

Opration : Charge a user

Requte :
POST https://<GOSURL>/1/payment/tel%3A%2B22507588125/transactions/amount HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json

Page 10/15

Orange SDP : document partenaire

26/03/2014

Authorization: AUTH
transEnd="1",FA="tel:+225xxxxxxxx",linkId="",SAN="",transactionId="",spId="123456
7890",spPassword="f0d80041b8acb3471c084e591dd3f984",timeStamp=" XXXXXXXXXX
",productId="12345678912345"
User-Agent: Jakarta Commons-HttpClient/3.1
Host: 10.99.163.149:7601
Content-Length: 262
{
"endUserId" : "tel:+225xxxxxxxx",
"transactionOperationStatus" : "Charged",
"chargingInformation" : {
"description" : " Alien Invaders Game ",
"amount" : "10",
"currency" : "XOF"
},
"referenceCode" : "REF-36984966",
"clientCorrelator" : "3698496627511015936"
}
Rponse :
HTTP/1.1 201 Created [OSE]
Server: OSE
Location:
http://10.99.163.149:7601/1/payment/tel%3A%2B22507588125/transactions/amount/REF36984966
Content-Type: application/json
Content-Length: 423
{
"amountTransaction" : {
"endUserId" : "tel:+225xxxxxxxx",
"transactionOperationStatus" : "Charged",
"referenceCode" : "REF-36984966",
"paymentAmount" : {
"chargingInformation" : {
"description" : "Alien Invaders Game",
"currency" : "XOF",
"amount" : 10.000000
}
},
"serverReferenceCode" : "REF-36984966",
"resourceURL" :
"http:\/\/10.99.163.149:7601\/1\/payment\/tel%3A%2B22507588125\/transactions\/amo
unt\/REF-36984966"
}
}
4.3.3

Opration : Reserve an amount for charging

Requte :
POST
https://<GOSURL>/1/payment/tel%3A%2B22507099573/transactions/amountReservation
HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: AUTH
transEnd="1",FA="tel:+225xxxxxxxx",linkId="",SAN="",transactionId="",spId="123456
7890",spPassword="f0d80041b8acb3471c084e591dd3f984",timeStamp=" XXXXXXXXXX
",productId="12345678912345"
User-Agent: Jakarta Commons-HttpClient/3.1
Page 11/15

Orange SDP : document partenaire

26/03/2014

Host: 10.99.163.149:7601
Content-Length: 255
{
"endUserId" : "tel:+225xxxxxxxx",
"transactionOperationStatus" : "Reserved",
"chargingInformation" : {
"description" : "Streaming",
"currency" : "XOF",
"amount" : 6
},
"referenceCode" : "REF-27702381",
"referenceSequence" : 1,
"clientCorrelator" : "3640373030137751544"
}
Rponse :
HTTP/1.1 201 Created [OSE]
Server: OSE
Location:
http://10.99.163.149:7601/1/payment/tel%3A%2B22507099573/transactions/amountReser
vation/59257338392570016
Content-Type: application/json
Content-Length: 328
{
"amountReservationTransaction" : {
"endUserId" : "tel:+225xxxxxxxx",
"transactionOperationStatus" : "Reserved",
"referenceCode" : "REF-27702381",
"paymentAmount" : {
"chargingInformation" : {
"description" : "Streaming",
"currency" : "XOF",
"amount" : 6.000000
}
},
"referenceSequence" : 1,
"clientCorrelator" : "3640373030137751544"
}
}
4.3.4

Opration : Charge against the reservation

Requte :
POST
https://<GOSURL>/1/payment/tel%3A%2B22507099573/transactions/amountReservation/59
257338392570016 HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: AUTH
transEnd="1",FA="tel:+225xxxxxxxx",linkId="",SAN="",transactionId="",spId="123456
7890",spPassword="f0d80041b8acb3471c084e591dd3f984",timeStamp=" XXXXXXXXXX
",productId="12345678912345"
User-Agent: Jakarta Commons-HttpClient/3.1
Host: 10.99.163.149:7601
Content-Length: 199
{
"transactionOperationStatus" : "Charged",
"chargingInformation" : {
"description" : "Three rounds of the Big Fight",
Page 12/15

Orange SDP : document partenaire

26/03/2014

"amount" : 6,
"currency" : "XOF"
},
"referenceCode" : "REF-36403730",
"referenceSequence" : 3
}
Rponse :
HTTP/1.1 200 OK [OSE]
Server: OSE
Content-Type: application/json
Content-Length: 491
{
"amountReservationTransaction" : {
"endUserId" : "tel:+225xxxxxxxx",
"transactionOperationStatus" : "Charged",
"referenceCode" : "REF-36403730",
"paymentAmount" : {
"amountReserved" : 11.000000,
"chargingInformation" : {
"description" : "Three rounds of the Big Fight",
"currency" : "XOF",
"amount" : 6.000000
},
"totalAmountCharged" : 6.000000
},
"referenceSequence" : 3,
"resourceURL" :
"http:\/\/10.99.163.149:7601\/1\/payment\/tel%3A%2B22507099573\/transactions\/amo
untReservation\/59257338392570016"
}
}

4.3.5

Opration : Release the reservation

Requte :
POST
https://<GOSURL>/1/payment/tel%3A%2B22507099573/transactions/amountReservation/59
257369355562149 HTTP/1.1
Accept-Encoding: gzip,deflate
Content-Type: application/json
Authorization: AUTH
transEnd="1",FA="tel:+225xxxxxxxx",linkId="",SAN="",transactionId="",spId="123456
7890",spPassword="f0d80041b8acb3471c084e591dd3f984",timeStamp=" XXXXXXXXXX
",productId="12345678912345"
User-Agent: Jakarta Commons-HttpClient/3.1
Host: 10.99.163.149:7601
Content-Length: 97
{
"transactionOperationStatus" : "Released",
"referenceCode" : "REF-17422661",
"referenceSequence" : 4
}
Rponse :
HTTP/1.1 200 OK [OSE]
Page 13/15

Orange SDP : document partenaire

26/03/2014

Server: OSE
Content-Type: application/json
Content-Length: 462
{
"amountReservationTransaction" : {
"endUserId" : "tel:+225xxxxxxxx",
"transactionOperationStatus" : "Released",
"referenceCode" : "",
"paymentAmount" : {
"amountReserved" : 6.000000,
"chargingInformation" : {
"description" : "0",
"currency" : "0",
"amount" : 0.000000,
"code" : "0"
},
"totalAmountCharged" : 0.000000
},
"referenceSequence" : 4,
"resourceURL" :
"http:\/\/10.99.163.149:7601\/1\/payment\/tel%3A%2B22507099573\/transactions\/amo
untReservation\/59257369355562149"
}
}

Page 14/15

Orange SDP : document partenaire

26/03/2014

5 Orange SDP Exemples dutilisation


5.1

Orange Infotainment Hub use case

Infotainment Hub est une plateforme de services Orange permettant aux clients Orange de sabonner des
contenus qui leurs sont pousss par SMS. Ces contenus sont des alertes dactualit, des blagues, des
conseils Infotainment est connect Orange SDP pour fournir ces services toutes les filiales Orange.
Diagramme de squence
IdSoftw are_Sequence Infotainment
System
Orange SDP
Infotainment :ASP
External system

User Device
(from Contexte)
Subscription SMS(message)

notifySMS(user identifier, message)

charge(user identifier, amount)

sendSMS(user identifier, service)

SMS MT(service)

sendSMS(user Identifier, service)

SMS MT(service)

Explications :
-

Subscription SMS est un SMS envoy par lutilisateur pour sabonner au service : lutilisateur envoie le
SMS SBLAGUE au 7700.
NotifySMS est le message envoy par SDP Infotainment Hub. Il contient le message envoy par
lutilisateur ( SBLAGUE ) et lidentifiant (MSISDN) de lutilisateur. (Cf.Opration :SMS Notification)
Charge est le message envoy par Infotainment Hub SDP pour facturer lutilisateur pour
labonnement au service blague la semaine . (Cf. Opration : charge a user)
sendSMS sont les messages envoys chaque jour par infotainment Hub (les blagues) pendant toute
la dure de labonnement souscrit par lutilisateur. (Cf. Opration : send SMS)

Page 15/15