Event API

Environment

Name	base URL
local	http://localhost:8080	up on local dev laptop
dev staging	https://staging.oodev.io	up on remote dev server
preprod staging	unknown	unknow on remote preprod server
prod	https://internal-sharing.oodrive.com	up on remote prod server

Event

current

/api/threshold/account/event

future?

/api/billing/events

Request authorization

Type: OAuth 2.0

Access token URL: /auth/oauth/token?workspace=none

Grant type: password credentials

Client ID / Client Secret / Username / Password are mandatory

Request HTTP header

Mandatory headers configuration for Zuora event

Key	Value	Description
X-Client-Id	Zuora	Emitter client ID

Response HTTP type

OK type

HTTP 200

KO type

HTTP 400 (Bad Request)
HTTP 401 (Unauthorized)
HTTP 403 (Forbidden)
HTTP 500 (Internal Server Error)

API payloads

Request payloads

Upgrade auto

ZLINKUPDATED

Description

upgrade product quantity on:

a existing specific client
a existing specific subscription
a existing specific product

First implementation

{
    "typeEvent": "ZLINKUPDATED",                                    //enum
    "emitter": "ZUORA",                                             //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",                        //date
    "payload": [
        {
            "zlink": {
                "existingAccountNumber": "BA00206872",              //string
                "subscriptionNumber": "S00067808",                  //string
                "ratePlanId": "8adcd9eb76e114b10176e2a494396e41",   //string
                "chargeNumber": "C00347768"                         //string
            },
            "threshold": {
                "newCapacity": 10,                                  //double number
                "unit": "Giga"                                      //enum Licence, Byte, Kilo, Mega, Giga, Tera
            }
        }
    ]
}

Under development

{
    "typeEvent": "ZLINKUPDATED",         //enum
    "emitter": "ZUORA",            //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",      //date
    "payload": [
        {
            "zReference": "title",         //string
            
            "zaccount": "BA00206872",        //string
            "zsubscription": "S00067808",       //string
   "product": {
                "zcharge": "C00155760",       //string
             "family": "AdbackupEnt",       //string
             "threshold": {
                 "newCapacity": 10,        //double number
                 "unit": "Giga"         //enum Licence, Byte, Kilo, Mega, Giga, Tera
            
                }
            }
        }
    ]
}

Provisioning "Vente Directe"

CLIENTISCREATED

Description

create a unique account type client

First implementation

{
    "typeEvent": "CLIENTISCREATED",                                 //enum
    "emitter": "ZUORA",                                             //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",                        //date
    "payload": [
        {
            "zclient": {
                "accountNumber": "BA00206872",                      //string
                "firstName": "Arnaud",                              //string
                "lastName": "JOYE",                                 //string
                "email": "a.joye.ext13@oodrive.com",                //string
                "phone": "0665911317",                              //string
                "company": "SOAT",                                  //string
                "department": "IT",                                 //string
                "adresse": {
                    "adresse1": "2 rue des coléoptères",            //string
                    "adresse2": "bat 2",                            //string
                    "city": "Paris",                                //string
                    "zipCode": "75001",                             //string
                    "country": "France"                             //string
                }
            }
        }
    ]
}

Under development

{
    "typeEvent": "CLIENTISCREATED",         //enum
    "emitter": "ZUORA",            //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",      //date
    "payload": [
        {
            "zReference": "title",         //string
            
            "zaccount": "BA00206872",        //string
            "client": {
                "firstName": "Arnaud",        //string
                "lastName": "JOYE",         //string
                "email": "a.joye.ext13@oodrive.com",    //string
                "phone": "0665911317",        //string
                "name": "SOAT",          //string
                "department": "IT",         //string
    "adresse1": "2 rue des coléoptères",    //string
                "adresse2": "bat 2",        //string
                "city": "Paris",         //string
                "zipCode": "75001",         //string
                "country": "France"         //string
            }
        }
    ]
}

WORKSPACEISADDEDTOPCLIENT

Description

create a unique workspace on:

a existing specific account

First implementation

{
    "typeEvent": "WORKSPACEISADDEDTOPCLIENT",                       //enum
    "emitter": "ZUORA",                                             //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",                        //date
    "payload": [
        {
            "zclient": {
                "accountNumber": "BA00206872"                       //string
            },
            //"zlink": {
            //    "existingAccountNumber": "BA00206872",            //string ??
            //    "subscriptionNumber": "S00067808",                //string ??
            //},
            "workspace": "totoalaplage2"                            //string
        }
    ]
}

Under development

{
    "typeEvent": "WORKSPACEISADDEDTOPCLIENT",      //enum
    "emitter": "ZUORA",            //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",      //date
    "payload": [
        {
            "zReference": "title",         //string
            
   "zaccount": "BA00206872",        //string
            "zworkspace": "totoalaplage2"       //string
        }
    ]
}

SUBSCRIPTIONISCREATED

Description

create subscription:

with first product to initialize
on:
- a existing specific account
- a existing specific workspace

First implementation

{
    "typeEvent": "SUBSCRIPTIONISCREATED",                           //enum
    "emitter": "ZUORA",                                             //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",                        //date
    "payload": [
        {
            "zlink": {
                "existingAccountNumber": "BA00206872",              //string
                "subscriptionNumber": "S00067808",                  //string
                "ratePlanId": "8adcd9eb76e114b10176e2a494396e41",   //string //productFamilyId
                "chargeNumber": "C00347768"                         //string //productQuantityId
            },
            "workspace": "totoalaplage2",                           //string
            "productFamily": "Adbackup",                            //string
            "threshold": {
                "newCapacity": 1,                                   //double number
                "unit": "Giga"                                      //enum Licence, Byte, Kilo, Mega, Giga, Tera
            }
        }
    ]
}

Under development

{
    "typeEvent": "SUBSCRIPTIONISCREATED",       //enum
    "emitter": "ZUORA",            //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",      //date
    "payload": [
        {
            "zReference": "title",         //string
            
            "zaccount": "BA00206872",        //string
            "zworkspace": "totoalaplage2",       //string
            "zsubscription": "S00067808",       //string
            "products": [
                {
                    "zcharge": "C00347768",       //string
                    "family": "AdbackupPro",      //string
                    "threshold": {
                        "newCapacity": 1,       //double number
                        "unit": "Giga"        //enum Licence, Byte, Kilo, Mega, Giga, ...
                    }
             },
                {
                    "zcharge": "C00155760",       //string
                    "family": "AdbackupEnt",      //string
                    "threshold": {
                        "newCapacity": 5,       //double number
                        "unit": "Giga"        //enum Licence, Byte, Kilo, Mega, Giga, ...
                    }
                }
   ]
        }
    ]
}

Provisioning "Cross Sell"

PRODUCTISADDED

Description

add/modify/delete products

on:
- a existing specific account
- a existing specific workspace
- existing specific subscription

Cross-sell : Offre initial vente direct pour clients déjà existant par l’ajout d’un nouveau produit dans un abonnement/subsc déjà existant (qui peux être de la même famille mais avec des paramètres différent (exemple une subsc (instance11) avec un produit AdBackup 5Go (Instance16) et un produit AdBackup 20Go (Instance17))

HER/CR-2021-01-08 : https://confluence.oodrive.net/display/HER/CR-2021-01-08

Under development

{
    "typeEvent": "PRODUCTLISTISMODIFIED",       //enum
    "emitter": "ZUORA",            //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",      //date
    "payload": [
        {
   ...as in SUBSCRIPTIONISCREATED payload
        }
    ]
}

Response payloads

Payload type OK

First implementation

{
    "success": true,
    "message": null,
    "errorDTOS": null
}

Current implementation

{
    "typeEvent": "SUBSCRIPTIONISCREATED",      //enum
    "emitter": "ZUORA",           //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",     //date
    "success": true,
    "message": "created",
    "details": [
        {
            "zReference": "title1",        //string
            "calculedHash": "6f503b5d1e92398b6265b3790b0ff", //string
            
            "success": true,         //boolean
            "name": "CREATED",         //enum CREATED, MODIFIED, DELETED, UPGRADED 
            "message": "10485"          //string
        },
        {
            "zReference": "title2",      
            "calculedHash": "1f553b55ue92398b6265b3490b0f2",
            
            "success": true,
            "name": "CREATED",          
            "message": "1035"          
        }
    ]
}

Payload type KO

First implementation

{
    "success": false,           //boolean
    "message": "errors while executing",      //string
    "errorDTOS": [
        {
            "name": "UNPROCESSABLE_ENTITY",      //enum BAD_REQUEST, NOT_FOUND, 
                         //UNPROCESSABLE_ENTITY, INTERNAL_SERVER_ERROR
            "message": "event downgrade or so is not in scope"  //string
        }
    ]
}

Current implementation

2 KO

{
    "typeEvent": "SUBSCRIPTIONISCREATED",      //enum
    "emitter": "ZUORA",           //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",     //date
    "success": false,           //boolean
    "message": "errors while executing",      //string
    "details": [
        {
            "zReference": "title1",        //string
            "calculedHash": "6f503b5d1e92398b6265b3790b0ff", //string
            
            "success": false,         //boolean
            "name": "UNPROCESSABLE_ENTITY",      //enum BAD_REQUEST, NOT_FOUND, 
                         //UNPROCESSABLE_ENTITY, INTERNAL_SERVER_ERROR
            "message": "event downgrade or so is not in scope"  //string
        },
        {
            "zReference": "title2",
            "calculedHash": "1f553b55ue92398b6265b3490b0f2",
            
            "success": false,
            "name": "INTERNAL_SERVER_ERROR",      
            "message": "Client creationis throwing internal server error"
        }
    ]
}

1 KO and 1 OK

{
    "typeEvent": "SUBSCRIPTIONISCREATED",      //enum
    "emitter": "ZUORA",           //enum ZUORA, PLATEFORME
    "timestamp": "2020-11-20T10:52:23.131Z",     //date
    "success": false,           //boolean
    "message": "errors while executing",      //string
    "details": [
        {
            "zReference": "title1",        //string
            "calculedHash": "6f503b5d1e92398b6265b3790b0ff", //string
            
            "success": false,         //boolean
            "name": "UNPROCESSABLE_ENTITY",      //enum BAD_REQUEST, NOT_FOUND, 
                         //UNPROCESSABLE_ENTITY, INTERNAL_SERVER_ERROR
            "message": "event downgrade or so is not in scope"  //string
        },
        {
            "zReference": "title2",
            "calculedHash": "1f553b55ue92398b6265b3490b0f2",
            
            "success": false,
            "name": "CREATED",         
            "message": "1035"          
        }
    ]
}

first call response, proofing

{
    "typeEvent": "ZLINKUPDATED",
    "emitter": "ZUORA",
    "timestamp": "2020-11-20T10:52:23.131",
    "success": false,
    "message": "errors while executing",
    "details": [
        {
            "zReference": "title1",        //string
            "calculedHash": null,        //@nullable boolean
            "success": false,         //boolean
            "name": "UNPROCESSABLE_ENTITY",      //enum BAD_REQUEST, NOT_FOUND, 
                         //UNPROCESSABLE_ENTITY, INTERNAL_SERVER_ERROR
            "message": "event downgrade or so is not in scope" //string
        },
        {
            "zReference": "title2",
            "calculedHash": "995953119",
            "success": true,
            "name": "UPDATED",
            "message": null
        }
    ]

NB: "calculedHash" can't be present in failed element (because we are not aware of the state of payload's field or payload nullity)

API DB

First implementation

zuora_client

client_uuid	existingaccountnumber
94120dcb-fee0-4718-943a-d16724de574b	BA00206871
fe95f3d9-5c77-4c11-a258-6ad48af29f99	BA00206872

zuora_subscription

subscription_uuid	existingaccountnumber	subscriptionnumber	rateplanid	chargenumber
6c3d67e9-fe77-41d3-818f-90cf0ef9fa61	BA00206870	S00043361	8adcd9eb75e5c7040175fa14e9971d9f	C00208720
b4fc29a1-29d5-48e9-932d-d7dd804a6507	BA00024007	S00043361	8adcd9eb75e5c7040175fa14e9971d9f	C00002561

Current

"zuora_subscription" table gets product's information with field "rateplanid" and "chargenumber"; Subscription and product are two notions, which needs to be decoupled with specific table;

In current DB, product could be identified with field "rateplanid" and "chargenumber".

Problems :

"rateplanid" is transient (has no constant value over time)
"rateplanid" is unnecessary for almost every single API call to Zuora
only "chargenumber" have repository value, so can be the ID

Solution:

only use "chargenumber"
if necessary ask for "rateplanid" from Zuora given "chargenumber"

zuora_client

client_uuid	zaccountnumber
bb0b01df-7695-4a63-8fe0-bc6a2d4a402a	BA00257046
110b01df-5695-4a63-8450-1c6a2d4a402b	BA00297148

zuora_subscription

subscription_uuid	client_uuid	zsubscriptionnumber
08601fae-c10f-4118-885f-cbe9bef73c35	bb0b01df-7695-4a63-8fe0-bc6a2d4a402a	S00073342
bb0b01df-7695-4a63-8fe0-bc6a2d4a4022	bb0b01df-7695-4a63-8fe0-bc6a2d4a402a	S00067807

zuora_product

marketing_product_id	subscription_uuid	zchargenumber
101	08601fae-c10f-4118-885f-cbe9bef73c35	C00002561
102	08601fae-c10f-4118-885f-cbe9bef73c35	C00379785

Backlinks