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

REST API

Fulfillment

The fulfillment resource represents fulfillment of orders. Every physical order is associated with a fulfillment.

The fulfillment resource can be used directly by shop owners and also by shipping partners on behalf of shop owners.

What can you do with Fulfillment?

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

GET /api/fulfillments.json

Receive a list of all order fulfillments of the current shop.

GET /api/fulfillments.json?created_at_min=2015-07-01T00:00:00&created_at_max=2015-07-02T00:00:00

Receive a list of order fulfillments of the current shop for orders made between 2017-07-01 to 2015-07-02.

GET /api/fulfillments/count.json

Receive the current shop's physical order count. 

GET /api/fulfillments/open.json

Receive a list of all order fulfillments of the current shop which are still open.

GET /api/fulfillments/complete.json

Receive a list of all completed order fulfillments.

GET /api/fulfillments/#{token}.json

Receive specific fulfillment identified by Order ID.

PUT /api/fulfillments/#{token}.json

Modify a specific fulfillment identified by Order ID.

 

Fulfillment Properties

created_at
"2014-07-02T13:25:26"

The date/time the order for this fulfilment was made.

customer

Customer data for shipment. 

{
"country_name":"United States of America"
"country_code":"US"
"default":true
"province_code":"California"
"province":"CA"
"name":"John Doe"
"id":15475
"first_name":"John"
"last_name":"Doe",
"company":""
"address1":"18914, Coast Street"
"address2":""
"zip":"77073"
"city":"Houston"
"token":"NNYAHQNTOAPYBNAK"
}
id
"105489"

The unique id of this fulfillment/order.

line_items

Array of line items for fulfillment

[{

"id":75501

The internal ID of this product.

"product_id":"0001-26ED-EA4F-AA32"

The long ID of the products as displayed in the admin interface

"title":"TheGoodFather"

The title of this product.

"version":"1.0"

The version of this product (if specified)

"Quantity":2

The ordered quantity of this product.

"gtin":""

The GTIN number of this product (if specified).

"weight":160 

The weight of the product in gram 

}]

owner_company
1212345

The company id of the company for which the shipping must be done.

status

100

0 = Not shipped / 100 = Shipped 

tracking_company
 "DHL"

The name of the shipping model (read-only).

tracking_number
"122ur4538ef29, 122fr4539gh27" 

The tracking number(s) for this fulfillment. Max. 64 characters.

tracking_url
"http://www.dhl.com/en/express/tracking.html"

The URL used for tracking this shipment (if possible) as defined in the selected shipping model (read only)

 

Price

The price resource represents prices of products. Every product must associated with at least one price/price per license to appear in the shop. 

What can you do with Price?

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

GET /api/prices.json

Receive a list of all price models defined for the company.

GET /api/prices/#{token}.json

Receive a single price model identified via token (Price ID). 

Price Properties

countries

Array of countries and corresponding price for the country (in cent)

[{

"country_name": "United Kingdom"

The name of the country

"country_code": "GB"

The country code of thsi country

"price": 19800

Price in cent for this country.

}]

created_at
"2014-07-02T13:25:26"

The date/time the price model was initially created.

currencies

Array of currencies the correspondig price for the currency (in cent)

[{

"currency": "eur"

Curency identifier

"price": 19800

Price in cent for the currency

}]

 id
 672

The unique id used to reference this price model

modified_at
"2015-08-02T16:22:21"

The last date/time the price model was modified.

title
"Default pricing for new items"

The name of the price model as shown in the admin interface.

valid
1

Set to 1 for valid price models. Set to 0 for invalid price models.

Get all prices

GET /api/prices.json
View Response

Receive a single price identified by Price ID token

GET /api/prices/#{token}.json
View Response

Receive a count of all prices

GET /api/prices/count.json
View Response

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

 

 

 

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.

 

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