orangeapisamea documentationpartenaire intro au sdp

SDP Partner Document

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

Orange Group

Ora

ng

e –

S

A a

u c

ap

ital d

e 1

0 4

57

39

5 6

44

€ -

6 p

lace d

’Alle

ray

- 7

55

05

Paris

Ced

ex

15

- 3

80

12

9 8

66

RC

S P

aris

Orange APIs AMEA

Documentation Partenaire

Introduction au SDP

Orange SDP : document partenaire 26/03/2014

/15

Table des matières

1 INTRODUCTION ............................................................................................................. 3

2 SDP ORANGE AMEA : VUE D’ENSEMBLE .................................................................. 3

2.1 SDP Orange AMEA : Qu’est-ce que c’est ? .......................................................................................... 3

2.2 SDP Orange: les acteurs et les cas d’utilisation ................................................................................. 4

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

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

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

3.1 Partenaire fournit à Orange ................................................................................................................... 7

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

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

4.1 SMS API ................................................................................................................................................... 8 4.1.1 Description de l’API .......................................................................................................................... 8 4.1.2 Opération : send SMS ...................................................................................................................... 8 4.1.3 Opération : SMS Notification ............................................................................................................ 9 4.1.4 Opération : SMS delivery notification ............................................................................................... 9

4.2 USSD ........................................................................................................................................................ 9 4.2.1 Description de l’utilisation ................................................................................................................. 9 4.2.2 Opération USSD ............................................................................................................................. 10

4.3 Payment API .......................................................................................................................................... 10 4.3.1 Description de l’API ........................................................................................................................ 10 4.3.2 Opération : Charge a user .............................................................................................................. 10 4.3.3 Opération : Reserve an amount for charging ................................................................................. 11 4.3.4 Opération : Charge against the reservation .................................................................................... 12 4.3.5 Opération : Release the reservation ............................................................................................... 13

5 ORANGE SDP EXEMPLES D’UTILISATION ............................................................... 15

5.1 « Orange Infotainment Hub » use case .............................................................................................. 15


/15

1 Introduction

Ce document vise à présenter la plateforme Orange SDP ainsi que les services (= APIs) qu’elle offre aux partenaires d’Orange sur la zone AMEA. Il a été rédigé dans le cadre du « challenge PME ». Ce document ne fait pas office de spécification d’interface entre les partenaires et la plateforme SDP.

2 SDP Orange AMEA : Vue d’ensemble

2.1 SDP Orange AMEA : Qu’est-ce que c’est ?

Orange SDP est une plateforme centralisée qui expose des services relatifs aux clients mobiles des filiales d’Orange dans toute la zone AMEA. SDP permet aux partenaires Orange de déployer et d’enrichir leurs applications convergentes multi fonctionnels et multi pays en réduisant drastiquement leur Time-To-Market. Le but est de créer un écosystème « gagnant-gagnant » entre Orange, ses partenaires et ses clients :

- Les partenaires en enrichissant leur offre de service, leur couverture géographique et leur visibilité auprès des clients Orange.

- Orange, en offrant par l’intermédiaire de ses partenaires des services plus riches que ses concurrents, stimulera l’utilisation des ressources Orange et améliorera la fidélisation de ses clients et la captation de nouveaux clients.

- Les clients Orange voient leur offre de service s’enrichir.

Fig.1 - SDP vue Générale


/15

2.2 SDP Orange: les acteurs et les cas d’utilisation

SDP permet aux applications partenaires d’accéder à des services (APIs). Les services sont des opérations effectuées sur des ressources des filiales Orange. Les Utilisateurs sont à la fois clients des Filiales Orange et des applications partenaires. La plateforme Orange SDP est exploitée par les administrateurs Orange.

Fig.2 – Orange SDP acteurs et cas d’utilisation « macro »


/15

2.3 SDP Orange: les API offertes

Orange SDP signifie Service Delivery Platform. En se connectant à cette plateforme, les partenaires d’Orange profitent donc d’une offre de services (= APIs) sécurisés et contrôlés 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 exposés sous forme d’APIs REST ou SOAP sur une adresse unique accessible depuis Internet. L’accès aux APIs est protégé par une authentification du partenaire et l’usage des API est contrôlé par des règles configurées dans la plateforme Orange SDP.

Fig.3 – Orange SDP : Services offerts

2.4 SDP Orange : Couverture pays et ressources

Les APIs Orange SDP couvrent aujourd’hui 6 filiales Orange : Côte d’Ivoire, Mali, Sénégal, Cameroun, République Démocratique du Congo, Botswana. Dans le cadre du Challenge PME, seuls les filiales suivantes seront accessibles aux PME participantes : Côte d’Ivoire, Sénégal, Mali.

Fig.4 – Couverture pays et ressources


/15

Afin d’offrir les APIs précédemment décrits, la plateforme Orange SDP est interconnectée avec les éléments suivants dans chacune des filiales Orange :

- SMS-C - USSD Portal - IN (Système de paiement pré-payés) et Système de paiement post-payés


/15

3 Orange SDP : prérequis

Afin d’accéder aux APIs exposées par la plateforme Orange SDP, le partenaire et Orange doivent échanger les informations pré-requises suivantes :

3.1 Partenaire fournit à Orange

- IP du back end Partenaire accédant aux API Orange SDP via Internet (filtré lors de l’accès aux API) - URL recevant les appels USSD émis par les utilisateurs - URL recevant les Notifications de SMS émis par les utilisateurs (exposition de l’API SMS Notification :

Cf. Opération :SMS Notification : partnersmsurl dans les exemples)

- Contact technique

3.2 Orange fournira au partenaire

- Identifiant ASPID (spId dans les exemples)

- Identifiant APPID (productId dans exemples de requêtes)

- mot de passe accès aux APIs (permettant de calculer le spPassword dans les exemples)

- URL d’accès aux API SDP (SDPURL dans les exemples)

- Règles d’usage de chaque API (nombre de requêtes autorisés…) - Documentation d’interface, best practices - Contact technique

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


/15

4 SDP Orange : description des APIs

Les requêtes sont dites AOMT ou MOAT. - AOMT (Application Originated Mobile Terminated) sont des requêtes faites par l’application partenaire

sur les API exposées par Orange SDP. - MOAT (Mobile Originated Application Terminated) sont des requêtes faites par Orange SDP sur les

API exposées par l’application partenaire

Fig.5 – APIs et requêtes AOMT et MOAT

Authentication header : Le header d’authentification AOMT est utilisé par le partenaire quand il effectue une requête sur une API Orange SDP. (par exemple « send SMS » : le partenaire envoie un SMS à un utilisateur). Ce header permet à Orange SDP d’authentifier le partenaire et de l’identifier afin de lui autoriser l’accès à l’API qu’il requiert. Le header d’authentification MOAT est utilisé par Orange SDP quand il effectue une requête sur les API de l’application partenaire (par exemple « SMS Notification » : SDP envoie au partenaire un SMS provenant d’un utilisateur).

4.1 SMS API

4.1.1 Description de l’API

L’API SMS Orange SDP permet au partenaire les requêtes AOMT suivantes :

- send SMS (SMS MT – Mobile Terminated) : envoyer un SMS à un ou plusieurs utilisateurs L’API SMS exposée par le partenaire permet à Orange SDP les requêtes 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 l’accusé de réception d’un SMS

4.1.2 Opération : send SMS

Requête (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"


/15

}

Réponse :

HTTP/1.1 201 Created [XXXOSE]

Server: XXXOSE


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 Opération : SMS Notification

Requête (MOAT) :

POST http://<partnersmsurl>/restSmsService/reception HTTP/1.1

Host: 10.99.171.131:5050


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" } } }

Réponse :

HTTP/1.1 200 OK

Date: Thu, 04 Jun 2013 02:51:59 GMT

4.1.4 Opération : SMS delivery notification

Requête (MOAT) :

POST http://<partnersmsurl>/restSmsService/delivery HTTP/1.1

Host: 10.99.171.131:5050


Content-Length: 165

Connection: close

Authorization: AUTH spId="1234567890"

{ "deliveryInfoNotification": { "deliveryInfo": { "address": "tel+225xxxxxxxx",

"deliveryStatus": "DeliveredToTerminal" }, "callbackData": "3093301370275764097"

}

Réponse :

HTTP/1.1 200 OK

Date: Thu, 04 Jun 2013 02:51:59 GMT

4.2 USSD

4.2.1 Description de l’utilisation


/15

Afin de pouvoir se connecter dans le portail USSD de l’opérateur, les opérations USSD sont traités sous forme de client serveur entre le mobile de l’abonné 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 générer un XML qui doit être compatible du composant USSD.

4.2.2 Opération USSD

Requête (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

Réponse :

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">+ d’info</a>

<br/>

</page>

</pages>

4.3 Payment API

4.3.1 Description de l’API

L’API Payment Orange SDP permet au partenaire les requêtes AOMT suivantes :

- Charge a user : facturer un utilisateur d’un montant donné - Reserve an amount for charging to an end user : réserver un montant pour une facturation ultérieure - Charge against the reservation : facturer une réservation antérieure - Release the reservation : abandonner une réservation

4.3.2 Opération : Charge a user

Requête :

POST https://<GOSURL>/1/payment/tel%3A%2B22507588125/transactions/amount HTTP/1.1




/15

Authorization: AUTH

transEnd="1",FA="tel:+225xxxxxxxx",linkId="",SAN="",transactionId="",spId="123456

7890",spPassword="f0d80041b8acb3471c084e591dd3f984",timeStamp=" XXXXXXXXXX ",productId="12345678912345"


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"

}

Réponse :

HTTP/1.1 201 Created [OSE]

Server: OSE

Location:

http://10.99.163.149:7601/1/payment/tel%3A%2B22507588125/transactions/amount/REF-

36984966


Content-Length: 423

{

"amountTransaction" : {




"paymentAmount" : {


"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 Opération : Reserve an amount for charging

Requête :

POST

https://<GOSURL>/1/payment/tel%3A%2B22507099573/transactions/amountReservation

HTTP/1.1



Authorization: AUTH





/15

Host: 10.99.163.149:7601

Content-Length: 255

{


"transactionOperationStatus" : "Reserved",


"description" : "Streaming",

"currency" : "XOF",

"amount" : 6

},


"referenceSequence" : 1,


}

Réponse :

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-Length: 328

{

"amountReservationTransaction" : {


"transactionOperationStatus" : "Reserved",


"paymentAmount" : {


"description" : "Streaming",

"currency" : "XOF",

"amount" : 6.000000

}

},



}

}

4.3.4 Opération : Charge against the reservation

Requête :

POST

https://<GOSURL>/1/payment/tel%3A%2B22507099573/transactions/amountReservation/59

257338392570016 HTTP/1.1



Authorization: AUTH




Host: 10.99.163.149:7601

Content-Length: 199

{



"description" : "Three rounds of the Big Fight",


/15

"amount" : 6,

"currency" : "XOF"

},


"referenceSequence" : 3

}

Réponse :

HTTP/1.1 200 OK [OSE]

Server: OSE


Content-Length: 491

{





"paymentAmount" : {

"amountReserved" : 11.000000,


"description" : "Three rounds of the Big Fight",

"currency" : "XOF",

"amount" : 6.000000

},

"totalAmountCharged" : 6.000000

},


"resourceURL" :


untReservation\/59257338392570016"

}

}

4.3.5 Opération : Release the reservation

Requête :

POST

https://<GOSURL>/1/payment/tel%3A%2B22507099573/transactions/amountReservation/59

257369355562149 HTTP/1.1



Authorization: AUTH




Host: 10.99.163.149:7601

Content-Length: 97

{

"transactionOperationStatus" : "Released",


"referenceSequence" : 4

}

Réponse :

HTTP/1.1 200 OK [OSE]


/15

Server: OSE


Content-Length: 462

{



"transactionOperationStatus" : "Released",

"referenceCode" : "",

"paymentAmount" : {

"amountReserved" : 6.000000,


"description" : "0",

"currency" : "0",

"amount" : 0.000000,

"code" : "0"

},

"totalAmountCharged" : 0.000000

},


"resourceURL" :


untReservation\/59257369355562149"

}

}


/15

5 Orange SDP Exemples d’utilisation

5.1 « Orange Infotainment Hub » use case

Infotainment Hub est une plateforme de services Orange permettant aux clients Orange de s’abonner à des contenus qui leurs sont poussés par SMS. Ces contenus sont des alertes d’actualité, des blagues, des conseils… Infotainment est connecté à Orange SDP pour fournir ces services à toutes les filiales Orange. Diagramme de séquence

IdSoftware_Sequence Infotainment

User Device(from Contexte)

«System»

Orange SDP

Infotainment :ASP

«External system»

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 l’utilisateur pour s’abonner au service : l’utilisateur envoie le SMS « SBLAGUE » au 7700.

- NotifySMS est le message envoyé par SDP à Infotainment Hub. Il contient le message envoyé par l’utilisateur (« SBLAGUE ») et l’identifiant (MSISDN) de l’utilisateur. (Cf.Opération :SMS Notification)

- Charge est le message envoyé par Infotainment Hub à SDP pour facturer l’utilisateur pour l’abonnement au service « blague à la semaine ». (Cf. Opération : charge a user)

- sendSMS sont les messages envoyés chaque jour par infotainment Hub (les blagues) pendant toute la durée de l’abonnement souscrit par l’utilisateur. (Cf. Opération : send SMS)

orangeapisamea documentationpartenaire intro au sdp

Documents

orange group orange

sdp orange amea

sdporange sdp

sms api

opration ussd

sdp partner document

document partenaire

description des apis