Retailers API documentation
URL params
Param | Meaning |
---|---|
{id_Profile} | The id identifying a Profile |
{id_Account} | The id identifying a Console |
{id_Activation} | The id identifying the process to create a new console |
{id_Login} | The id identifying an available login on a console |
{id_Pack} | The id identifying a Pack |
{lang} | The Console culture. It is the TwoLetterISOLanguageName. |
La validazione di questi parametri, utilizzati nelle sezioni dell'URL per identificare risorse, sono validati dalla classe ResellerResourceValidationRequestAuthorizerBase.
AuthorizationCode params
Param | Meaning |
---|---|
ExternalUserId | The id identifying a reseller's customer on its platform |
ClientId | It uniquely identifies the Consumer application. NB: the record identified by ClientId MUST HAVE the IsReseller field equals to TRUE to access to reseller API. |
ResellerId | It is the DeveloperId field of the record identified by the ClientId into APIConsumerApplication table. It equals to:
It identifies the Reseller Console. |
Resources
Management
Get reseller's profiles
Get the ResellerProfile table records WHERE IdReseller field equals ResellerId authorization code value.
Http verb |
| ||||||||
---|---|---|---|---|---|---|---|---|---|
Resource URL | Management/Profile | ||||||||
Request API | - | ||||||||
Request ADM | - | ||||||||
Return value | A list of profile objects containing:
|
WHEN REQUESTS RUN:
- ExternalUserId is empty
- ExternalUserId has a value
Get reseller's available packages
Get the ResellerPack table records.
Http verb |
| ||||||||
---|---|---|---|---|---|---|---|---|---|
Resource URL | Management/Profile/{id_Profile}/Pack | ||||||||
Request API |
| ||||||||
Request ADM | - | ||||||||
Return value | A list of pack objects containing:
NOTE: The type is hidden for the reseller. |
WHEN REQUESTS RUN:
- ExternalUserId is empty
- ExternalUserId has a value
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
403 Forbidden | Unexisting id_profile | You cannot access to provided profile. |
id_profile not assigned to specified IdConsoleRetailer |
NOTE
- Min e Max sono il numero di pacchetti minimo e massimo gestibili dal profilo.
Get reseller's available languages by profile
Get the languages available by profile
Http verb |
| ||||||||
---|---|---|---|---|---|---|---|---|---|
Resource URL | Management/Profile/{id_Profile}/Lang | ||||||||
Request API |
| ||||||||
Request ADM | - | ||||||||
Return value | A list of language codes. |
WHEN REQUESTS RUN:
- ExternalUserId is empty
- ExternalUserId has a value
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
403 Forbidden | Unexisting id_profile | You cannot access to provided profile. |
id_profile not assigned to specified IdConsoleRetailer |
Account
Create a reseller's customer account
Http verb |
| ||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Resource URL | Account/Activation/Profile/{id_Profile}/Language/{lang} | ||||||||||||||||||||||||||||||||||||||||
Request API |
| ||||||||||||||||||||||||||||||||||||||||
Request ADM |
| ||||||||||||||||||||||||||||||||||||||||
Return value | An object containing these fields:
|
WHEN REQUESTS RUN:
- ExternalUserId, id_Profile, lang, IpAddress, Email, ServiceName, ServiceUrl, ServiceLogoutUrl CustomSubdomain and CustomDomain MUST HAVE a value
- UserAgent and Referer could be empty
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | Unexisting lang value into the TwoLetterISOLanguageName list. | Invalid language. |
ExternalUserId empty. | Invalid ExternalUserId. | |
403 Forbidden | No profiles for the ResellerId authentication code value. | You cannot access to provided profile. |
IpAddress is null, empty or IPAddress.TryParse fails | Code: 4 Description: IpAddress cannot be null, empty or invalid. | |
IpAddress is null, empty or EmailHelper.ValidateAddress fails | Code: 5 Description: Email cannot be null, empty or invalid. | |
CustomDomain is null, empty or invalid | Code: 6 Description: Custom domain cannot be null, empty or invalid. | |
Custom domain not available | Code = 7; Description = Custom domain not available. | |
ADM service checks the value is not allowed for reseller's editions | Code: 3 Description: Language '{lang}' is not available for profile {id_Profile}. |
NOTE:
- E' possibile creare UN SOLO account TRIAL per ExternalUserId. Se si cerca di creare un account trial utilizzando un ExternalUserId già utilizzato, la risposta conterrà Code: 1, Description: Processing fino a che il primo account non è stato creato, ed al termine della sua creazione conterrà Code: 2, Description: Error.
- E' possibile creare PIU' account ECONOMY o PREMIUM per ExternalUserId. Se si cerca di creare un account economy o premium utilizzando un ExternalUserId già utilizzato, la risposta conterrà Code: 1, Description: Processing fino a che il primo account non è stato creato, ed al termine della sua creazione conterrà Code: 0, Description: Ok.
Get reseller's customer account profile activation status
Http verb |
| ||||||||
---|---|---|---|---|---|---|---|---|---|
Resource URL | Account/Activation/{id_Activation}/Status NOTE: the id_Activation is the value returned with Create a reseller's customer account resource | ||||||||
Request API |
| ||||||||
Request ADM |
| ||||||||
Return value | An object (like ConsoleActivationStatusResponse object for PublicService) containing:
NOTE: the IdAccount field contains a value ONLY when the reseller's customer console is propertly created, so Code field contains the OK-CREATED code value. NOTE2: the IdAccount equals to ConsoleId |
WHEN REQUESTS RUN:
- ExternalUserId and id_Activation MUST HAVE a value
- id_Activation MUST be a numeric value
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails | ||
id_Activation is not a number | Invalid activation. |
Change reseller's customer account profile
Http verb |
| ||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Resource URL | Account/{id_Account}/Profile/{id_Profile} NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource | ||||||||||||
Request API |
| ||||||||||||
Request ADM |
| ||||||||||||
Return value | - NOTE: the return value is the HTTP Status code of the response. ADM executes this operation asynchronously. Every time the reseller invokes the resource, ADM returns a code. If this code tells that the operations are still in progress the resource returns an 202 Accepted status code; otherwise returns a 200 OK status code. If an error occurred it returns 500 Internal Server Error. NOTE 2: the reseller can invoke the resource as many times as it wants. |
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |
Disable reseller's customer account info
Http verb |
| |||||||||
---|---|---|---|---|---|---|---|---|---|---|
Resource URL | Account/{id_Account} or Account/{id_Account}?Enable=false NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource | |||||||||
Request API |
| |||||||||
Request ADM | None | |||||||||
Return value | The resource returns a 200 OK status code and and object containing account status properties. In detail the returned object actually contains:
|
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |
Enable reseller's customer account info
Http verb |
| |||||||||
---|---|---|---|---|---|---|---|---|---|---|
Resource URL | Account/{id_Account} or Account/{id_Account}?Enable=true NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource | |||||||||
Request API |
| |||||||||
Request ADM | None | |||||||||
Return value | The resource returns a 200 OK status code and and object containing account status properties. In detail the returned object actually contains:
|
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |
Unprovide reseller's customer account
Http verb |
| ||||||||
---|---|---|---|---|---|---|---|---|---|
Resource URL | Account/{id_Account} NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource | ||||||||
Request API |
| ||||||||
Request ADM | TBD | ||||||||
Return value | The resource returns a 200 OK status code. |
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |
Get reseller's customer account status
Http verb |
| ||||||||
---|---|---|---|---|---|---|---|---|---|
Resource URL | Account/{id_Account}/Status NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource | ||||||||
Request API |
| ||||||||
Request ADM | TBD | ||||||||
Return value | An object contains these fields:
|
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails | ||
403 Forbidden | Invalid Id_Account | You cannot access to provided account. |
NOTE:
- La chiamata ritorna -1 se il metodo GetAccountStatus dei servizi ADM ritorna come ReturnCode 1 (Processing) o 2 (Error). Tale descrizione del ReturnCode viene settata come description in modo che si possa capire il motivo del fallimento. In realtà ReturnCode, in questo caso, varrà 0 (Ok) oppure 2 (Error) e MAI 1 (Processing).
- La proprietà ActivePacks restituisce informazioni relative allo stato attuale dei pacchetti. Il campo Quantity restituisce la somma algebrica dei pacchetti aggiunti/rimossi, mentre CurrentQuantity fornisce informazioni relative a quanti pacchetti sono attualmente in uso (un pacchetto potrebbe essere stato rimosso, ma l'effettiva rimozione avverrà a fine mese)
Add package to reseller's customer account
Http verb |
| |||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Resource URL | Account/{id_Account}/Pack/{id_Pack} NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource | |||||||||||||||
Request API |
WorkMode should be "incremental" or "absolute" and refers to the way to manage packages. The "incremental" work mode allows client to add or remove packages as defined by Quantity field. If client calls the method 3 times with quantity equals to 1, API method adds 1 package each time. If client needs to remove a package it calls the method with quantity equals to -1 and API method removes a package. The "absolute" work mode allows client to define the total number of packages.If client calls the method with quantity equals to 4, API method adds 4 packages. If client needs to remove 2 packages from the current quantity (set to 4 by the previews call) it calls the method with quantity equals to 2 and the API method removes 2 packages. NB: "absolute" work mode allows only unsigned value for Quantity.
| |||||||||||||||
Request ADM |
| |||||||||||||||
Return value | In detail the returned object actually contains:
NOTE: the resource returns a 200 OK status code if the package was added succesfully and the response contains code = 0; if the addition does not end propertly, the resource returns a 403 Forbidden and the response contains code = 1 |
WHEN REQUESTS RUN:
- the response contains an object with:
- Code = 0
- Description = Ok
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | IdPack is not numeric | Invalid pack. |
ExternalUserId empty. | Invalid ExternalUserId. | |
ExternalUserId validation fails | ||
403 Forbidden | The package cannot be added | the response contains an object with:
|
NOTE
- Non si possono aggiungere/rimuovere pacchetti ad un profilo TRIAL
- Non di possono rimuovere pacchetti a consumo dai profili Economy e Premium
- La tabella RetailerProfilePack definisce il numero di pacchetti Massimo e Minimo previsti per il profilo. La visibilità del pacchetto per l'utente finale (e quindi la sua attivabilità) è gestita con il campo IsActivable.
- Nel caso la risposta abbia lo status code settato a 403 Forbidden si ottiene la risposta con Code=1 quando la richiesta non viene validata dai limiti previsti dalla tabella RetailerProfilePack, mentre Code=2 quando la validazione secondo i limiti della tabella retailerProfilePack è ok ma fallisce l'operazione lato ADM. Un caso in cui può essere ritornato Code=2 è quando s cerca di cancellare un pacchetto a consumo (crediti).
Get reseller's customer account logins
The resource allows to retrieve the logins available for this account/console. It is necessary if the reseller allows his customers to add more administrators to an account.
Http verb |
| ||||||||
---|---|---|---|---|---|---|---|---|---|
Resource URL | Account/{id_Account}/Login | ||||||||
Request API |
| ||||||||
Request ADM | - | ||||||||
Return value | A list of AccountLogin object containing:
NOTE: data come from Newsletters_Login table. idLogin is the id and UserName is the username fields |
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |
Get reseller's customer account login url
Http verb |
| ||||||||
---|---|---|---|---|---|---|---|---|---|
Resource URL | Account/{id_Account}/Login/{id_Login} NOTE: the id_Account is the value returned with Get reseller's customer account profile activation status resource | ||||||||
Request API |
| ||||||||
Request ADM | - | ||||||||
Return value | The reseller's customer account login url string |
WHEN REQUESTS FAIL:
HTTP Status Code | When | Message |
---|---|---|
400 BadRequest | ExternalUserId empty. | Invalid ExternalUserId. |
ExternalUserId validation fails |