+813-444-3589+44 118 328 3220+49-231-976765-0 | Contact us

SOAP API

The FlickRocket platform consists of a shop frontend, an access backend, administration, preparation and client side modules. This document explains how to replace the shop frontend with a custom shop system while maintain all the functionality of the other modules.

The functionalities of the different modules are a follows:

Module

Responsibility

Shop Frontend

Presents available content to the customer, includes shopping cart functionality and performs the payment processing. After the purchase completes, the user is redirected to the Access Backend.

Access Backend

Enables the customer to access content by requesting software to be installed (if required) and offering access functionality using the installed software.

Administration

Enables the content owner to manage the content, licenses, pricing and all related shop functionality.

Preparation

Enables the customer to ingest content into the platform and does the required content preparation steps to support all different platforms.

Client Side

Works based on the Access Backend and enables the customer to access purchased content.

The shop frontend can be replaced by different shop systems. However, it is important to understand that these shop frontends should have at least the following options for being able to be used as replacement:

  • Needs to be able to present different license options (e.g. rental and purchase) for products
  • Needs to offer a login function for existing customers (the access to the content is managed by FlickRocket).
  • Needs support for SSL to accept payments
  • Needs to be able to use SOAP requests to communicate with the FlickRocket Access Backend
  • Customers must be forced to specify at least an email and password

The following explains the web services which must be used to integrate the custom shop frontend with the FlickRocket platform.

 

URLs

The FlickRocket OnDemandOrder web service (SOAP) can be accessed at the URLs below. We provide C# sample code but PHP may also be used.

 

Service URL: https://www.flickrocket.com/Services/OnDemandOrder/service.asmx

Service WSDL: https://www.flickrocket.com/Services/OnDemandOrder/service.asmx?WSDL

 

Sandbox Environment

For testing purposes a sandbox environment is provided. The sandbox environment is synced with the live servers from time to time (approx. all 48 hours). This means the following:

  • You can use the credentials from the live server
  • All settings, project, uploads etc. from the live server will be propagated to the sandbox.
  • Changes you do in the sandbox environment will be reset from time to time. You cannot do any permanent changes in the sandbox environment.

The sandbox has the following limitations:

  • You cannot upload content. The upload is only emulated and the content will never become available.
  • You cannot perform permanent transactions. Any content added to a user accounts is not permanent.

To use FluxPlayer for accessing content added to customer accounts via the Sandbox environment, the player needs to be switched to the Sandbox mode. To do This, open the “Help” menu with the version information and click 8 times on the version number. Select “Sandbox” from the list and click “OK”.

The URL of the sandbox environment is http://sandbox.flickrocket.com.

 

Shop Related Web Service Functions

Shop Related Web Service functions are functions which work based on a Shop user which is granted access to individual content items and licenses.

 

CheckAccount()

The CheckAccount function checks if the account data is valid and can access a certain theme.

bool CheckAccount(string EMail, string Password, int ThemeID, out int ErrorCode)

Return value

Returns true on success

EMail

FlickRocket admin user email (requires “shop management” right)

Password

FlickRocket admin user password

ThemeID

The identifier of a theme. Themes are used by other API functions and are defined in the FlickRocket web interface. ID 1 is a default theme which is accessible to all users. 

ErrorCode

Out Param

Returns an ErrorCode if CheckAccount failed:

-1: FlickRocket User not found

-2: FlickRocket User valid but theme does not exist

-3: FlickRocket User valid but has no access rights to theme

-4: API not enabled

 

CreateShopOrder()

The CreateShopOrder function is used to communicate new content rights for a user to the FlickRocket platform. Basically the rights can be specified in of two ways:

By specifying the content and associated license

This is typically used for shop integration in which the user has selected and paid for content). The Items node is used to specify content and associated license. If it is empty, it can also be used to create just a new user.

By specifying one or more UnlockCodes to be redeemed

This is typically used for scenarios where a web site offers code redemption. The UnlockCodes node is used to specify UnlockCodes to be redeemed.

CreateShopOrder may only the used with one of the before mentioned options at a time. Using multiple will result in an error.

bool CreateShopOrder(string EMail, string Password, string XML, out int ErrorCode)

Return value

Returns true on success

EMail

FlickRocket admin user email (requires “shop management” right)

Password

FlickRocket admin user password

XML

XML formatted content/rights, group information or UnlockCodes

ErrorCode

Out Param

Returns an ErrorCode if CreateShopOrder failed:

-1: FlickRocket User not found

-2: Malformed XML

-3: “Order” Root in XML not found

-4: Wrong email or password in XML

-5: Unknown Error

-6: No Customer Password in XML

-7: Invalid UnlockCode(s)

-8: Expired UnlockCode(s)

-9: UnlockCode(s) usage exceed

-10: API Usage not allowed. Please contact FlickRocket.

-11: Invalid project

-12: Project deleted

-13: New user cannot be created with PasswordHash

-14: No permission to create order for this product

The XML must be constructed as follows:

Node IdentifierValue TypeDescription

Order

   

  TransactionID

Alphanumeric (Mandatory)

TransactionID (supposed to be unique) to map this order in FlickRocket with an order in the 3rd party shop frontend.

The TransactionID is reported in the CSV exports.

  EMail

Email (Mandatory)

The email address of the customer. To access the content via the Access Backend or Client Side software, this email needs to be used.

  Password

Alphanumeric (Optional)

The clear text password of the customer. To access the content via the Access Backend or Client Side software, this password needs to be used. For new customers this field must be used.

“Password” or “PasswordHash” needs to be present in the XML.

  PasswordHash

Alphanumeric (Optional)

The SHA-1 password of the customer. To access the content via the Access Backend or Client Side software, this password needs to be used. For existing customers this field or the plain text Password might be used.

“Password” or “PasswordHash” needs to be present in the XML.

  ThemeID

Numeric (Mandatory)

The ThemeID of the theme to be associated with the order. On company may have multiple themes with different content. For any web interface design elements the user is presented, this theme is used.

The ThemeIDs are listed in the FlickRocket admin interface under Shop -> Themes -> Manage design and texts.

Firstname Alphanumeric (Optional) First name of the customer
Lastname Alphanumeric (Optional) Last name of the customer
Address1 Alphanumeric (Optional) Address of the customer
Address2 Alphanumeric (Optional) Additional address information
City Alphanumeric (Optional) City
ZIP Alphanumeric (Optional) ZIP code
State Alphanumeric (Optional) State for US/CA only. Specified in two characters, e.g. "CA" for Califonia
Country Alphanumeric (Optional) The two character country code. E.g. "US" for United States
Language   Alphanumeric (Optional) The two character language code. E.g. "en" for English

  Items

Item Node (Optional)

A list of item nodes which define the actual ordered items and associated licenses.

    Item

 

If no Items node is present, only the user is created on the FlickRocket platform.

      ProjectID

ProjectID (Mandatory)

The ProjectID of the content.

The format of ProjectIDs is always ABCD-ABCD-ABCD-ABCD and a list of all ProjectIDs are listed under Projects -> List projects.

      LicenseID

The LicenseID of the content.

The LicenseIDs are listed under Shop -> Licenses -> List licenses.

      Count

Numeric (Mandatory)

The number of ordered licenses for the project.

      HD

Numeric

(Optional)

Must be “1” if the content is video and the HD version is ordered. Muist be “0” if the content is video and the SD version is ordered.

 

   

  UnlockCodes

UnlockCode Node (Optional)

A list of UnlockCodes to be redeemed.

    UnlockCode

Alphanumeric (Mandatory)

One Unlockcode to be redeemed

Sample XML for items:

<?xml version="1.0" encoding="utf-8" ?>

<Order>

  <TransactionID>001</TransactionID>

  <EMail>This email address is being protected from spambots. You need JavaScript enabled to view it.</EMail>

  <Password>password</Password>

  <!-- <PasswordHash> </PasswordHash> --> <!-- SHA1 Encrypted, only for existing customers -->

  <ThemeID>32</ThemeID>

  <Items> <!—- Optional: If not included only a customer will be created -->

    <Item>

      <ProjectID>0000-1C80-33B9-7A42</ProjectID>

<!-- The project to be ordered with this item. Can be found in the web interface. -->

      <LicenseID>16</LicenseID>

<!-- Identifies the license to be used for the order. Can be found in the web interface. -->

      <Count>1</Count>

    </Item>

    <Item>

      <ProjectID>0000-1B18-685F-0DD8</ProjectID>

<!-- The project to be ordered with this item. Can be found in the web interface. -->

      <LicenseID>19</LicenseID>

<!-- Identifies the license to be used for the order. Can be found in the web interface. -->

      <Count>1</Count>

    </Item>

  </Items>

</Order>

or sample XML for UnlockCode redemption:

<?xml version="1.0" encoding="utf-8" ?>

<Order>

  <TransactionID>001</TransactionID>

  <EMail>This email address is being protected from spambots. You need JavaScript enabled to view it.<;/EMail>

  <Password>password</Password>

  <!-- <PasswordHash> </PasswordHash> --> <!-- SHA1 Encrypted -->

  <ThemeID>32</ThemeID>

  <UnlockCodes>   

    <UnlockCode>ABCD-ABCD-ABCD-ABCD</UnlockCode>

    <UnlockCode>BCDE-BCDE-BCDE-BCDE</UnlockCode>

  </UnlockCodes>

</Order>

 

CheckUserExists()

The CheckUserExists function is used to check if a user is already known to the backend. This is usually done in advance of calling the CreateShopOrder function to make sure the user is valid.

The function returns true if the email address is unknown or the email address is known and the password matches. In both cases the CreateShopOrder function can be used with the identical email and password.

The function returns false in case of an error. In case the ErrorCode is -5 the email is known to the backend but the password does not match. In this case the calling application should display a message to the user that his email is already known from his purchases in the shop list returned in the Companies parameter and he has to use the matching password.

bool CheckUserExists(string EMail, string Password, string XML, out int ErrorCode, out List<string> Companies)

Return value Returns true if the email address is unknown or the email address is known and the password matches
EMail FlickRocket admin user email (requires “shop management” right)
Password FlickRocket admin user password
XML XML formatted user data
ErrorCode

Out Param Returns an ErrorCode if CheckUserExists failed:

-1: Invalid User

-2: Malformed XML

-3: Customer Node not found

-4: Password or PasswordHash Node not found

-5: Email found but wrong Password. The companies from which the user data is known is available in the Companies parameter

-6: Empty user password

The XML must be constructed as follows:

Node IdentifierValue TypeDescription

Customer

   

  EMail

Email (Mandatory)

The email address of of the customer to be checked.

  Password

Alphanumeric (Optional)

The clear text password of the customer.

“Password” or “PasswordHash” needs to be present in the XML.

  PasswordHash

Alphanumeric (Optional)

The password hash of the customer.

“Password” or “PasswordHash” needs to be present in the XML.

Sample XML:

<?xml version="1.0" encoding="utf-8" ?>

<Customer>

  <EMail>This email address is being protected from spambots. You need JavaScript enabled to view it.<;/EMail>

  <Password>password</Password>

<!-- <PasswordHash>a1</PasswordHash> --> <!-- SHA1 Encrypted -->

</Customer>

 

CheckPreviewExists()

The CheckPreviewExists function is used to check if a preview/trailer exists for the specified project. The function returns true if a preview exists and false if no preview exists.

If a preview exists, it can be played back by navigating (typically in a pop up) to the following link with passing the ProjectID.

http://www.flickrocket.com/services/OnDemandOrder/Preview.aspx?PID=<ProjectID>

bool CheckPreviewExists(string EMail, string Password, string ProjectID)

Return value

Returns true if a preview exists and false if no preview exists

EMail

FlickRocket admin user email (requires “shop management” right)

Password

FlickRocket admin user password

ProjectID

The ProjectID of the project for which the preview availability is checked

Sample URL:

http://www.flickrocket.com/services/OnDemandOrder/Preview.aspx?PID=ABCD-ABCD-ABCD-ABCD

 

ChangeCustomerPassword()

The ChangeCustomerPassword function is used to update the FlickRocket platform with an updated password in case the user changes his password.

In case the original password is not known (e.g. for a “forgotten password” function) where the user is externally verified (e.g. by sending an email with a confirmation link) the function can be used with the magic value “_use_only_after_external_validation_” as original password parameter. However, this works only if the company using the API has created the user or has sold items to the user. THIS MUST NOT BE USED FOR REGULAR PASSWORD CHANGES.

bool ChangeCustomerPassword(string EMail, string Password, string XML, out int ErrorCode)

Return value

Returns true on success

Email

FlickRocket admin user email

Password

FlickRocket admin user password (requires “shop management” right)

XML

Formatted user data

ErrorCode

Out Param

Returns an ErrorCode if ChangeCustomerPassword failed:

-1: FlickRocket user not found

-2: Malformed XML

-3: “Customer” Root in XML not found

-4: Customer user not found

-5: No Password or PasswordHash in XML

-6: No NewPassword or NewPasswordHash in XML

-7: New PasswordHash not supported

The XML must be constructed as follows:

Node IdentifierValue TypeDescription

Customer

   

  EMail

Email (Mandatory)

The email address of of the customer for which the password is changed.

  Password

Alphanumeric (Optional)

The old clear text password of of the customer (for regular passord changes) or “_use_only_after_external_validation_” if the orginal password is unknown and the email has been externally validated, e.g. by sending an email with a confirmation link.

“Password” or “PasswordHash” needs to be present in the XML.

  NewPassword

Alphanumeric (Optional)

The new clear text password of the customer.

“NewPassword” or “NewPasswordHash” needs to be present in the XML.

  PasswordHash

Alphanumeric (Optional)

The old SHA-1 password of the customer.

“Password” or “PasswordHash” needs to be present in the XML.

Sample XML for regular password change:

<?xml version="1.0" encoding="utf-8" ?>

<Customer>

  <EMail>This email address is being protected from spambots. You need JavaScript enabled to view it.<;/EMail>

  <Password>password</Password>

  <NewPassword>newpassword</NewPassword>

<!-- <PasswordHash>a1</PasswordHash> --> <!-- SHA1 Encrypted -->

</Customer>

Sample XML for password reset after external email validation:

<?xml version="1.0" encoding="utf-8" ?>

<Customer>

  <EMail>This email address is being protected from spambots. You need JavaScript enabled to view it.<;/EMail>

  <Password>_use_only_after_external_validation_</Password>

  <NewPassword>newpassword</NewPassword>

<!-- <PasswordHash>a1</PasswordHash> --> <!-- SHA1 Encrypted -->

</Customer>

 

ChangeCustomerEmail()

The ChangeCustomerEmail function is used to update the FlickRocket platform with an updated email in case the user changes his email.

bool ChangeCustomerEmail(string EMail, string Password, string XML, out int ErrorCode)

Return value

Returns true on success

EMail

FlickRocket admin user email

Password

FlickRocket admin user password (requires “shop management” right)

XML

Formatted user data

ErrorCode

Out Param

Returns an ErrorCode if ChangeCustomerEmail failed:

-1: Invalid user

-2: Invalid XML

-3: Customer node in XML not found

-4: Customer not found

-5: Password node in XML not found

-7: New email node in XML not found

-8: New email already exists

The XML must be constructed as follows:

Node IdentifierValue TypeDescription

Customer

   

  EMail

Email (Mandatory)

The email address of the customer for which the email is changed.

  NewEMail

Email (Mandatory)

  Password

Alphanumeric (Optional)

The clear text password of the customer.

“Password” or “PasswordHash” needs to be present in the XML.

  PasswordHash

Alphanumeric (Optional)

The SHA-1 password of the customer.

“Password” or “PasswordHash” needs to be present in the XML.

Sample XML:

<?xml version="1.0" encoding="utf-8" ?>

<Customer>

  <EMail>This email address is being protected from spambots. You need JavaScript enabled to view it.<;/EMail>

  <NewEMail>This email address is being protected from spambots. You need JavaScript enabled to view it.<;/NewEMail>

  <Password>password</Password>

<!--<PasswordHash>a1</PasswordHash>--> <!-- SHA1 Encrypted -->

</Customer>

 

PrepareLoginEx()

The PrepareLoginEx function is used to get a unqiue URL for the Access Backend which can be embedded via iframe or to which the user can be redirected after purchase or at login.

bool PrepareLoginEx(string EMail, string Password, string XML, int ThemeID, out int ErrorCode, out string sURL)

Return value

Returns true on success

EMail

FlickRocket admin user email (requires “shop management” right)

Password

FlickRocket admin user password

XML

XML formatted user description

ThemeID

The Id of the theme to be used

ErrorCode

Out Param

Returns an ErrorCode if PrepareLogin failed:

-1: FlickRocket user not found

-2: Malformed XML

-3: “Customer” root in XML not found

-4: Customer user not found

-5: Email and password do not match

-6: Invalid theme

sURL

Returns a URL to be embedded via iframe or to be redirected to.

The XML must be constructed as follows:

Node IdentifierValue TypeDescription

Customer

   

  Email

Email (Mandatory)

The email address of the customer who should be logged in.

  Password

Alphanumeric (Optional)

The clear text password of the customer.

“Password” or “PasswordHash” needs to be present in the XML.

  PasswordHash

Alphanumeric (Optional)

The SHA-1 password of the customer.

“Password” or “PasswordHash” needs to be present in the XML.

Sample XML:

<?xml version="1.0" encoding="utf-8" ?>

<Customer>

  <EMail>This email address is being protected from spambots. You need JavaScript enabled to view it.<;/EMail>

  <Password>password</Password>

  <!-- <PasswordHash>a1</PasswordHash> --> <!-- SHA1 Encrypted -->

</Customer>

 

GetProjects()

The GetProjects function is used to retrieve a list of projects. The function returns true if a valid list of projects is returned.

bool GetProjects (string EMail, string Password, int ThemeID, out List<string> Projects, out int ErrorCode)

Return value

Returns true if the list of projects is returned and can be used

Email

FlickRocket admin user email (requires “shop management” right)

Password

FlickRocket admin user password

ThemeID

The ThemeID to which the projects needs to be assigend which will be returned back. If theme is -1, all projects are returned.

Projects

Out Param

For each project the following structure is returned:

    public struct stProject

    {

        public string LongProjectID;

        public string Name;

        public DateTime CreationDate;

        public eContentType ContentType;

        public bool Complete;

    }

    public enum eContentType

    {

        Unknown = -1,

        fluxDVD = 1,

        Silverlight = 2, //Reserved

        WebProject = 3,

        Software = 4,

        AudioCollection = 5,

        Physisch = 6, //Physical item

        fluxPackage = 7,

        ProjectCollection = 8,

        fluxDVD_HD = 9,

        SmartTV_Video = 10, //Reserved

        SmartTV_Audio = 11, //Reserved

        ProjectBased = 15, //Reserved

        eBook = 16,

   }

ErrorCode

Out Param

Returns an ErrorCode if GetProjects failed:

-1: Invalid User

-2: No projects found

-3: Unknown error

GetLicenses()

The GetLicenses function is used to retrieve a list of licenses. The function returns true if a valid list of licenses is returned.

bool GetProjects (string EMail, string Password, out List<stLicense> Licenses, out int ErrorCode)

Return value

Returns true if the list of licenses is returned and can be used

Email

FlickRocket admin user email (requires “shop management” right)

Password

FlickRocket admin user password

Licenses

For each license the following structure is returned:

    publicstructstLicense

    {

        publicint ID;

        publicstring Name;

    }

ErrorCode

Out Param

Returns an ErrorCode if GetLicenses failed:

-1: Invalid User

-2: No licenses found

-3: Unknown error

 

GetThemes()

The GetThemes function is used to retrieve a list of themes. The function returns true if a valid list of themes is returned.

bool GetThemes (string EMail, string Password, out List<stTheme> Themes, out int ErrorCode)

Return value

Returns true if the list of themes is returned and can be used

Email

FlickRocket admin user email (requires “shop management” right)

Password

FlickRocket admin user password

Themes

Out Param

For each license the following structure is returned:

    public struct stTheme

    {

        publicint ID;

        publicstring Name;

        public string Domain;

        public string Settings;

    }

ErrorCode

Out Param

Returns an ErrorCode if GetThemes failed:

-1: Invalid User

-2: No themes found

-3: Unknown error

 

GetTrailer()

The GetTrailer function is used to retrieve a list of trailers for projects. Please note that trailers are optional and may not exist. If a trailer does not exist, it is not returned as part the stTrailers list. The function returns true if a valid list of trailers is returned.

bool GetTrailer (string EMail, string Password, List<string> ProjectIDs, out List<stTrailer> Trailer, out int ErrorCode)

Return value

Returns true if the list of trailers is returned and can be used

Email

FlickRocket admin user email (requires “shop management” right)

Password

FlickRocket admin user password

ProjectIDs A list of the ProjectIDs for wich trailers should be returned. If no ProjectID is specified, all trailers are returned.

Trailer

Out Param

For each trailer the following structure is returned:

    public struct stTrailer

    {

        public string URL;

        public string ProjectID;

    }

ErrorCode

Out Param

Returns an ErrorCode if GetTrailer failed:

-1: Invalid User

-2: No trailer(s) found

-3: Unknown error


User data changes syncback

The following describes the process how FlickRocket communicates user information changes (E-Mail/Password changes) to 3rd party shop platforms which are related to the user whose information is updated.

To utilize this functionality, a number of settings has to be done in the related App Settings of the FlickRocket Backend. This is done in the admin interface under Extensions / Mage Apps / <Settings for the App>.

Setting Description
UserDataChangeURL The URL to which the change notifications get requests are sent.
Hash Type The type of the password has to be communicated for password changes.
Secret The secret to be used for signing the request. This must also be known on the receiving end.

If a change in the email or password occurs, a get request to the UserDataChangeURL with the following parameters is invoked.

 

Parameter Description
user_token token identifying the customer (reserved / empty)
email email address identifying the user (mandatory)
new_email new email address of the user (optional)
old_pw_hash old password hash of the user (optional but required for verification purposes if new new_pw_hash is specified)
new_pw_hash new password hash of the user (optional)
pw_hash_type

int identifying the password hash algorithm (required if old_pw_hash and/or new_pw_hash is specified)

  • 1 = SHA1
  • 2 = MD5 (Salted)
  • 5 = SHA_256
  • 6 = Plain (requires permission)
signature signature to validate the post as described below

The signature used is calculated as SHA-1 hash (hexadecimal output) from the request parameters. The first parameter has to be your secret, followed by the parameters ordered alphabetically by their names. Optional arguments that are used (have value) must be contained in the signature calculation. Optional arguments that are not used must not be contained in the signature calculation.

It is mandatory to convert arguments values into UTF-8 before computing the signature.

Example:

signature = sha1_hex( secret + ":email=" + email + ":new_email=" + new_email + ":new_pw_hash=" + new_pw_hash + ":old_pw_hash=" + old_pw_hash + ":pw_hash_type=" + pw_hash_type)

Example calculation:

Value Description
Secret BddJxtUBkDgFB9kj7Zwguxde4gAqha
email This email address is being protected from spambots. You need JavaScript enabled to view it.
new_email This email address is being protected from spambots. You need JavaScript enabled to view it.
new_pw_hash a2a1e3f447524d73729d972db3f837c5:MD
old_pw_hash cc3469055de99a54451507fdf66a3a00:MD
pw_hash_type int identifying the password hash algorithm (required if old_pw_hash and/or new_pw_hash is specified)

Signature calculation using the values above:

signature = sha1_hex(BddJxtUBkDgFB9kj7Zwguxde4gAqha:email=This email address is being protected from spambots. You need JavaScript enabled to view it.:new_email=This email address is being protected from spambots. You need JavaScript enabled to view it.:new_pw_hash=a2a1e3f447524d73729d972db3f837c5:MD:old_pw_hash=cc3469055de99a54451507fdf66a3a00:MD:pw_hash_type=4) => a043071d3db1d3bbacee04e1eaf07da0d3ab1d17

The request then is:

https://sample.update.com/update?email=This email address is being protected from spambots. You need JavaScript enabled to view it.&new_email=This email address is being protected from spambots. You need JavaScript enabled to view it.&new_pw_hash=a2a1e3f447524d73729d972db3f837c5:MD&old_pw_hash=cc3469055de99a54451507fdf66a3a00:MD&pw_hash_type=4&signature=a043071 d3db1d3bbacee04e1eaf07da0d3ab1d17