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

REST API

App Store

Once you have created an App, you can choose to offer it in the Flickrocket App Store.

To list your App in the store, you first need to fill out all sales related fields, such as pricing, availability, etc. as you would do with any other product. In addition, you need to specify the following:

api credentials

 

API Credentials

Authorization URL Enter the authorization URL which is called during the OAuth authorization process when a customer purchases the App. This needs to be identical to one of the allowed return URLs you have specified.
Permissions Select the permissions your app requires. In case the app is purchased via the App Store, the App will be given these permissions and they will also be passed as the “scope” parameter to the Authorization UR

 

App Approval

Any App which wants to be listed publicly in the App Store needs to go through an approval process, which can be requested under “App Approval”.

app approval

Before the App is approved, the “Shop Visibility” is limited to “Development (Only for related companies)”. This means that the App is only visible in the App store for the company, which has created the App.

Once the App is approved, it can be set to the following two Visibility States:

Status Description
Beta

In “Beta”, the App is visible to all companies but marked as Beta and available at no cost. Even after the “Beta” phase ends, customer who have installed the App will not be required to purchase the App.

Note: The Beta status is a great way to test the App under real conditions with customers. Flickrocket recommends a few weeks beta to iron out any bugs before an App is switched to Release mode.

Release

In release mode the App is visible to all and must be purchased.

Note: Flickrocket keeps 20% of all app sales. Payments for sold apps are made monthly

 

 

 

Embedded Apps

Embedded Apps can display their own UI in the admin interface under Extensions/Manage Apps/<App>.

To make an App an “Embedded App”, you need to enter the URL, which should be displayed under “Manage Apps” the in the API Credentials “Start URL” field.

api credentials start url

If a customer selects the App under “Manage Apps”, Flickrocket will load the URL in an iframe and pass UserID and CompanyID parameters to identify the User and Company. A typical URL looks like:

https://app.sample.com/dashboard?CompanyID=23128&UserID=2543&hmac=af2bdbe1aa9b6ec1e2ade1d694f41fc71a831d0268e9891562113d8a62add1bf

The app can then use this information to link the user to the OAuth authorization and display the corresponding information.

 

Validation

To validate that the embedded app is indeed running in the Flickrocket admin interface, the URL contains a “hmac” parameter in addition to the CompanyID and UserID parameters, which can be used to check if the request comes from the Flickrocket admin interface.

To validate the request, concatenate the parameters and create a SHA256 hash value using the Apps secret key and check if this signature matches the hmac passed to the app. Below is a short code sample using C#.

public static bool IsAuthenticRequest(NameValueCollection QueryString, string SecretKey)
{
string sParams = "?UserID=" + QueryString["UserID"] + "&CompanyID=" + QueryString["CompanyID"];

string result = "";
using (HMACSHA256 myhmacsha1 = new HMACSHA256(Encoding.UTF8.GetBytes(SecretKey)))
{
using (MemoryStream stream = new MemoryStream(Encoding.UTF8.GetBytes(Convert.ToBase64String(Encoding.UTF8.GetBytes(sParams)))))
{
result = myhmacsha1.ComputeHash(stream).Aggregate("", (s, o) => s + String.Format("{0:x2}", o), s => s);
}
}

if (result != QueryString["hmac"]) return false;
return true;
}

 

Webhooks

Apps can use webhooks to execute code after a certain event happens on the platform, for example after a new order or when customer data is modified.

Instead of periodically pulling objects via the API, the app can register webhooks which send an http(s) request to the app when the registered event occurs. This is easer to implement, uses less resources for API calls, allows for fast response after events and over all helps to create more robust apps.

Webhooks are scoped to the app and company they are bound to. A webkook does not receive events for other companies and other apps don’t influence triggering registered events.

Structure of a Webhook

If a webhook was registered to a certain event and the event happens, Flickrocket send a webhook notification to the specified URL. The notification contains a JSON payload with information which can be used to identify the event as well as event specific data and a signature which can be used to verify the validity of the notification.

As an example, the following JSON is sent as payload of the of the orders/create webhook.

{
"company_id": 1202,
"producer": "shop",
"scope": "order/create",
"data": {
"type": "order",
"id": "267227"
},
"hash": "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
}

Webhook Authentication

Each webhook payload includes a hash value which can be used to validate that the webhook originates from Flickrocket.

To verify this, all key/value pairs of the JASON with exception of the hash need to be concatenated from the beginning to the end and then a SHA256 hash with using the App Secret as salt is calculated. 

Respond to Webhook Callbacks

To acknowledge that you received the webhook without issue, your server should return a 200 HTTP status code. Any other information you return in the request headers or request body will be ignored. Any response code outside the 200 range, including 3_xx_ codes, will indicate to us that you did not receive the webhook. When a webhook is not received (for whatever reason), we will attempt to callback as described just below.

Callback Retry Mechanism

Webhooks will do their best to deliver the events to your callback URI. The dispatcher will attempt several retries until the maximum retry limit is reached, as follows:

Whenever a webhook gives a non-2_xx_ response, or times out, the app will be blocked for 60 seconds.
Webhooks created during that 60-second block will be queued up to send on the next scheduled retry attempt after the block expires, so that webhooks are not lost.

The dispatcher will then attempt several retries (at increasing intervals) until the maximum retry limit is reached, as follows:

Retry Intervals

  1. 60 seconds after the most recent failure
  2. 180 seconds after the most recent failure
  3. 300 seconds after the most recent failure
  4. 600 seconds after the most recent failure
  5. 900 seconds after the most recent failure
  6. 1800 seconds after the most recent failure
  7. 3600 seconds after the most recent failure
  8. 7200 seconds after the most recent failure
  9. 21600 seconds after the most recent failure
  10. 50400 seconds after the most recent failure
  11. 86400 seconds (24 hours) after the most recent failure

After the final retry attempt above (cumulatively, 48 hours after the first delivery attempt), the webhook will automatically be deactivated, and we will send an email to the developer’s email address registered on the subscribing app. Should you wish to reactivate the hook, you can set the is_active flag back to true via a PUT request to the hooks resource.

List of Webhook Events

Webhooks can be registered for the following events:

Events Topics
 Customer
customer/create, customer/update

This event is triggered when a new customer is created (e.g. during an order) or when customer data is updated.

 Subscriber
subscriber/create, subscriber/update
This event is triggered when a new subscriber is created, typically when someone signs up to a subscription or when subscriber data is updated.
 Groupmember
groupmember/create, groupmember/update
This event is triggered when a new group member is created, typically when someone is added to an access group or when a group member’s data is updated. 
 Newsrecipient
newsrecipient/create, newsrecipient/update
This event is triggered when a new newsletter recipient is created, typically when someone signs up to a newsletter or when recipient data is updated. 
 Order
order/create
This event is triggered when a new order is generated.
 Product
product/create, product/delete, product/update
This event is triggered when a new product is created, modified or a product is deleted.
 App
app/uninstalled, app/update
This event is triggered when an app is uninstalled, app permissions were removed.

 

What you can do with Webhook

The Flickrocket API lets you do the following with the Webhook resource. More detailed versions of these general actions may be available:

GET /admin/webhooks.json

Receive a list of all Webhooks

GET /admin/webhooks/#{id}.json

Receive a single Webhook

POST /admin/webhooks.json 

Create a new Webhook

PUT /admin/webhooks/#{id}.json 

Modify an existing Webhook

DELETE /admin/webhooks/#{id}.json

Remove a Webhook from the database

Webhook properties

address
"address": "http://someapp.com/uninstall"

The URI where the webhook should send the POST request when the event occurs.

 id
"id": 901431826

The unique numeric identifier for the webhook.

 topic
"topic": "app/uninstalled"

The event that will trigger the webhook. Valid values are listed above.

 updated_at
"updated_at": "2012-09-28T11:50:07-04:00"

The date and time when the webhook was updated.

 

Get a list of all webhooks for your shop

GET /admin/webhooks.json

View Response

Get a single webhook by its id

GET/admin/webhooks/4759306.json

View Response

Create a new webhook

POST /admin/webhooks.json
{
"webhook": {
"topic": "orders\/create",
"address": "http:\/\/whatever.hostname.com\/",
"format": "json"
}
}

View Response

Update a webhook's topic and/or address URIs

Change a webhook so that it POSTs to a different address:

PUT /admin/webhooks/#{id}.json
{
"webhook": {
"id": 4759306,
"address": "http:\/\/somewhere-else.com\/"
}
}

View Response

Delete a webhook

DELETE/admin/webhooks/4759306.json

View Response

Troubleshooting

Below are remedies for certain errors commonly encountered with webhooks:

Not Receiving the POST Requests to My Callback URI

As noted above, if your app does not return an HTTP 2_xx_ to Flickrocket upon receipt of the POST request to the callback URI, Flickrocket considers it a failure. Flickrocket will keep trying for a little over 48 hours. At the end of that time, Flickrocket sends an email to the email address set during app registration and flips the is_active flag to false.

You can proactively check to make sure that everything is OK by periodically making a GET request and checking the is_active flag.

If you receive an email or discover that the is_active flag has been flipped to false, try the following:

• Check to see if your app is responding to the POST request with something other than HTTP 200.

• Check to make sure that your server has a valid TLS/SSL setup. One way to do this is by visiting the following website: https://sslcheck.globalsign.com. Any of the following will cause the TLS/SSL handshake to fail:

o Self-signed certificate.

o Host name of the certificate does not match the server’s DNS.

o Your server’s key or trust store has not been loaded up with the intermediate cer-tificates necessary to establish the chain of trust.

Once you have resolved the issue preventing the connection, send a PUT request to flip the is_active flag back to true. This will cause Flickrocket to start trying to send the POST requests to your callback URI again.

Not Receiving an HTTP 201 Response after Sending POST to Create Webhook

After sending a POST request to create a webhook, you should get an HTTP 200 back. If you do not, check your TLS/SSL setup and the HTTP header in your request. The requirements for the HTTP header are discussed in the introduction above.

 

OAuth

Your app cannot access FlickRocket data without authenticating first. It must get permission from a user before gaining access to any of the resources in the REST API. This guide will walk you through the authorization process (described in greater detail by the OAuth 2.0 specification).

Terminology

Before getting into the nitty-gritty of the authorization process, let’s go over some of the terms that we’ll be using for the rest of the guide.

  • Client - Any application that would like access to a shop’s data. A user (usually the shop’s owner) must grant permission before the client can access any data.
  • API - FlickRocket’s REST API. This is the place where the client can view and modify a shop’s data.
  • User - A Flickrocket account holder, usually a shop owner. This is the person giving permission to a client to access their shop’s data through the REST API.

Step 1: Get the client’s credentials

You will need to retrieve an Client ID and Shared Secret as the client uses them to identify itself during the authorization process. Also you'll need to specify one or more valid redirect_uris.

To do this, open Products/Manage Products and locate the “API Credentials” section

app credentials

Once you have created the credentials, the new app will also appear in the admin interface under "Extensions / Manage Apps".

Step 2: Asking for permission

The first step of the process is to get authorization from the user. This is done by displaying a prompt provided by Flickrocket:

oauth login 1

oauth login 2



To show the prompt, redirect the user to this URL:
https://admin.flickrocket.com/oauth2/auth?client_id={client_id}&scope={scopes}&access_type=offline&redirect_uri={redirect_uri}
With these substitutions made:

  • {client_id} - substitute this with the app's client id.
  • {scopes} - substitute this with a comma-separated list of scopes. For example, to read/write orders and read/write customers use scope=orders,customers.
  • {redirect_uri} - (Required) substitute this with the URL where you want to redirect the users after they authorize the client. The complete URL specified here must be identical to one of the Application Redirect URLs. Note: in older applications, this parameter was optional, and redirected to the Application Callback URL when no other value was specified.
For example:
https://admin.flickrocket.com/oauth2/auth?client_id=FRWebApp&scope=products&access_type=offline&redirect_uri=api_tester.html

Step 3: Confirming installation

During the installation will the user will be redirected to the client server as specified above. One of the parameters passed in the confirmation redirect is the Authorization Code (the other parameters will be covered later in the guide).

https://example.org/some/redirect/uri?code={refresh_token}&companyid={company_id}

After this, the refresh_token can be exchanged once for an access_token, which expires after some time. The exchange is made as follows.

POST https://admin.flickrocket.com/token/grant_type=refresh_token&refresh_token={refresh_token}&client_id={client_id}

The server will respond with the following JSON containing an access_token and related information:

{ expires:"Thu, 21 Apr 2016 14:00:22 GMT", issued:"Thu, 21 Apr 2016 13:30:22 GMT", access_token:"gjRiyX1zl4JsmOSm_Hi3YMZo1vonyCylDDMBvW7H9iNfxCvFUdZLedxwCzGle7PSlmgFlSr-fHYlzybXaPsiuFZ0yKblYNuyvnSH-lDXPEeezfvGxijtdbT_H54HxE6aiESGmPGE0DgBN6lCxQQ7H7bsbez2OntawK8AboZqw3wKqbectPvqzV569hlIfuwn3uMAS46qLxuzTFn-0PVLQ5szd1PfLpRZmeH0pHcxEV6qVcoxIedup0tC6cY4kJnFDeqqKC3x3F5wrvH2gPPxkGal1ZfcH9MK3CYxEUETt6O3AaxjFBCqME2Y0BykPNFXikxL3vF7_O3Fq3AMAy_pcHIdqrbS8wGaGKdPEgIUTOpLaHvccsY4LluYR0TvyQf458ae0qxQyS4gIWPOIbfU3r4hMAwP1O9zBC5R_cHplL1QpfpIaKfu3zOK1AibRVES8VBOtvMRsF5a4LYXq60g6oEzmIg", access_type:"offline", as:client_id:"FRWebApp", expires_in:1799, refresh_token:"686ef3e7410b41858237daeaf4dc550b", scope:"products,orders,customers,themes,files", token_type:"bearer", userName:"This email address is being protected from spambots. You need JavaScript enabled to view it." }

It is important that the new refresh_token from the JSON above is always stored permanetly, as this is the only way to retrieve a new access_token, which is then used for authorization when calling the REST interface.

Important: If the refresh_token is lost, the only way to get access again is by manually removing permissions in the admin interface and start over again.

Step 4: Making authenticated requests

After the application obtains an access token, it can use the token to make calls to the FlickRocket REST API on behalf of a given user account or service account. To do this, you must include the access token in a request to the API by including either an access_token query parameter or an Authorization: Bearer HTTP header. When possible, the HTTP header is preferable, because query strings tend to be visible in server logs. In some cases you can use a client library to set up your calls to FlickRocket APIs.

Validating an access_token

You can validate and retrieve information for an access_token with the following get:

GET http://admin.flickrocket.com/api/tokeninfo?access_token={access_token}

If the access_token is valid, information as follows is returned.

{
"issued_to": "SomeWebApp",
"user_id": "This email address is being protected from spambots. You need JavaScript enabled to view it.",
"scope": "products,orders,customers",
"expires_in": "1738",
"access_type": "offline"
}

The expires_in time is specified in seconds. If the access_token is not valid, an error is returned. Possible error values are: expired, access_token required, invalid access_token.

Scopes

Part of the authorization process requires specifying which parts of a shop’s data the client would like access to (see the “Getting permission” part of this guide). A client can ask for any of the following scopes:

products The application can get, modifiy, create and delete products and categories.
customers The application can get, modifiy, create and delete customers.
orders The application can get, modifiy and create orders.
themes The application can get, modifiy, create and delete themes.
files The application can get and create content files.
companies The application can get, modifiy, create and delete company data (own and associated)
statistics The application can get company/shop statistics.
webhooks The application can get, modify, create, delete and use webhooks