To get started you will need to retrieve your web_api_key and app_key. Both can be found when you login to your FinerWorks account. These should be included in as request parameters in the header of any request. Alternatively you can include these as querystring paramaters in the request uri.
You can build on the platform of your choice. For initial development we recommend POSTMAN which allows you to test your calls and even generate sample code you can use in your application. FinerWorks does not provide direct programming support so will not be able to tell you how to “code”. If coding is beyond your abilities, we recommend finding someone with experience in building apps using RESTful Apis.
While you are building and testing your app, your app credentials should be marked as in test mode or your api calls should be in a "test_mode = true" status.
While in such a testing mode nothing will be processed or billed from orders originating from that particular app. All responses will be valid and simulate what you receive in a live environment so you can build your app accordingly.
When you have completed testing and are ready to go live, switch your app_key to a "live" mode or change your api calls to "test_mode = false". Changing your app_key from test mode can be done by going to your FinerWorks account's where you retrieved your api Authentication Credentials. Once your App is live any orders you place will be processed unless you cancel or place an order on hold.
You are responsible for insuring the privacy of your customer's data when being submitted therefore SSL is recommended however at this time is not required. View the Help page for the full list of endpoint and method combinations.
Click here for a list of endpoint uris and examples.
When submitting orders you will be required to provide either a "sku" from your FinerWorks virtual inventory. Alternatively you can provide a Product Code in place of a sku which represents the style to print and options along with the appropriate image files. Product codes can be found within the various product pages or when ever you setup a print online at FinerWorks.com.
Below are available generic shipping codes however you can choose more specific shipping codes by retrieving them via an endpoint call.
| shipping_code | description | Transit Time Avg | Notes |
|---|---|---|---|
| EC | Economy | 3-7 days | Goes the least expensive method |
| SD | Standard | 2-5 days | Usually goes via UPS ground or USPS Priority |
| EX | Express | 2-3 days | Usually goes via UPS 2 day or Pruirity Mail (which ever is estimated faster) |
| ON | Overnight | 1-2 days | Usually goes via Next Day Air or Express Mail. May not be available for some orders in which case the fastest method will be selected. |
Overtime FinerWorks will offer additional options and make structural changes based on products and services being offered. Structural changes should not create any disruption to existing applications.
There are no fees to develop or use the API however once you go live and submit valid orders, you will be required to have a credit card on file in which we will bill you for all pending orders submitted prior to noon of that day. In the advent that a card is declined for any reason you will be notified by email so that appropriate arrangements can be made to update your account with either a new card. We will attempt to rebill the following business day for those orders and any new orders. If after a 3rd attempt or no response after the 4th business day, any pending orders will be cancelled and need to be resubmitted.
Below is some actual example code formatted for popular programing languages. The samples utlize the endpoint to Get Product Details as an example. You can use this as a template for calling the other endpoints or use the sample code provided with each endpoint documentation page. In many cases you will only need to change the endpoint uri and the JSON in the body of the request. All endpoints can be found here.
curl --location --request POST 'https://api.finerworks.com/v3/get_product_details' \
--header 'Content-Type: application/json' \
--header 'web_api_key: my-web-api-key-goes-here' \
--header 'app_key: my-app-key-goes-here' \
--data-raw '[{
"product_order_po":null,
"product_qty": 3,
"product_sku": "AP6543P49875",
},
{
"product_order_po":null,
"product_qty": 3,
"product_sku": "AP6543P58353",
}]'
setUrl('https://api.finerworks.com/v3/get_product_details');
$request->setMethod(HTTP_Request2::METHOD_POST);
$request->setConfig(array(
'follow_redirects' => TRUE
));
$request->setHeader(array(
'Content-Type' => 'application/json',
'web_api_key' => 'my-web-api-key-goes-here',
'app_key' => 'my-app-key-goes-here'
));
$request->setBody('[{
\n "product_order_po":null,
\n "product_qty": 3,
\n "product_sku": "AP6543P49875"
\n},
\n{
\n "product_order_po":null,
\n "product_qty": 3,
\n "product_sku": "AP6543P58353"
\n}
\n]');
try {
$response = $request->send();
if ($response->getStatus() == 200) {
echo $response->getBody();
}
else {
echo 'Unexpected HTTP status: ' . $response->getStatus() . ' ' .
$response->getReasonPhrase();
}
}
catch(HTTP_Request2_Exception $e) {
echo 'Error: ' . $e->getMessage();
}
var client = new RestClient("https://api.finerworks.com/v3/get_product_details");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Content-Type", "application/json");
request.AddHeader("web_api_key", "my-web-api-key-goes-here");
request.AddHeader("app_key", "my-app-key-goes-here");
request.AddParameter("application/json", "[{\r\n \"product_order_po\":null,\r\n \"product_qty\": 3,\r\n \"product_sku\": \"AP6543P49875\"\r\n},\r\n{\r\n \"product_order_po\":null,\r\n \"product_qty\": 3,\r\n \"product_sku\": \"AP6543P58353\"\r\n}\r\n]", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
var settings = {
"url": "https://api.finerworks.com/v3/get_product_details",
"method": "POST",
"timeout": 0,
"headers": {
"Content-Type": "application/json",
"web_api_key": "my-web-api-key-goes-here",
"app_key": "my-app-key-goes-here"
},
"data": JSON.stringify([{"product_order_po":null,"product_qty":3,"product_sku":"AP6543P49875"},{"product_order_po":null,"product_qty":3,"product_sku":"AP6543P58353"}]),
};
$.ajax(settings).done(function (response) {
console.log(response);
});
var https = require('follow-redirects').https;
var fs = require('fs');
var options = {
'method': 'POST',
'hostname': 'api.finerworks.com',
'path': '/v3/get_product_details',
'headers': {
'Content-Type': 'application/json',
'web_api_key': 'my-web-api-key-goes-here',
'app_key': 'my-app-key-goes-here'
},
'maxRedirects': 20
};
var req = https.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function (chunk) {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
res.on("error", function (error) {
console.error(error);
});
});
var postData = JSON.stringify([{"product_order_po":null,"product_qty":3,"product_sku":"AP6543P49875"},{"product_order_po":null,"product_qty":3,"product_sku":"AP6543P58353"}]);
req.write(postData);
req.end();
require "uri"
require "net/http"
url = URI("https://api.finerworks.com/v3/get_product_details")
https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = "application/json"
request["web_api_key"] = "my-web-api-key-goes-here"
request["app_key"] = "my-app-key-goes-here"
request.body = "[{\r\n \"product_order_po\":null,\r\n \"product_qty\": 3,\r\n \"product_sku\": \"AP6543P49875\"\r\n},\r\n{\r\n \"product_order_po\":null,\r\n \"product_qty\": 3,\r\n \"product_sku\": \"AP6543P58353\"\r\n}\r\n]"
response = https.request(request)
puts response.read_body
Product codes and SKUs serve distinct purposes in managing and ordering products.
Product codes are used when supplying images for printing during the ordering process. They help specify the desired printing surface and are particularly useful for obtaining pricing information, shipping rates, or creating test orders. FinerWorks employs product codes to indicate the composition of a print product, encompassing the media type, mounting, and framing options. These codes consist of a series of ID numbers separated by delimiters, with each ID type representing a specific attribute (see example futher below).
SKUs are entered in the "product_sku" field of various API calls when ordering or managing products from your inventory. SKUs are beneficial when you have identical printed items to submit for ordering at different times. Similar to wish lists on other websites, SKUs are unique identifiers generated for each inventory item. They encompass all the relevant details, including the designated image for printing, allowing for efficient tracking and management of your inventory.
By leveraging product codes and SKUs, you can streamline the ordering process and effectively manage your inventory of printed items.
5M6M9S16X20
| Product Type ID | Delimiter | Media ID | Delimiter | Mounting/Style ID | Delimiter | Width | Height |
|---|---|---|---|---|---|---|---|
| 5 | M | 6 | M | 9 | S | 16 | 20 |
F96S20X24J1S16X20G1
| Delimiter | Frame ID | Delimiter | Width | Height | Delimiter | Mat ID | Delimiter | Window Width | Window Height | Delimiter | Glazing ID |
|---|---|---|---|---|---|---|---|---|---|---|---|
| F | 96 | S | 20 | 24 | J | 1 | S | 16 | 20 | G | 1 |
5M6M9S16X20F96S20X24J1S16X20G1