¶ Designer API
- Shopping cart server
- Personalization server
- User's browser
- User adds personalizable product to shopping cart
- Shopping cart server launches new personalization session via API method beginPersonalization
- Shopping cart server receives Personalization URL as response to API method beginPersonalization
- Shopping cart server redirects user to Personalization URL
- User's browser receives document information from Personalization server and launches Designer application
- User performs personalization of product inside Designer application
- User closes Designer application
- Personalization server redirects user to shopping cart
- Shopping cart server requests download URL and URLs to thumbnail images for newly created pdf document via API method getPreview
- Shopping cart server receives download URL and URLs to thumbnail images as response to API method getPreview
- Shopping cart server closes personalization session via API method endPersonalization
- User completes purchase of product in shopping cart.
- Owner of shopping cart downloads newly created pdf document via download URL.
¶ Version 4 (HTML)
The Print Science Designer offers a complete API that will allow integration of the Print Designer into any shopping cart system or workflow.
¶ Methods
These are the basic methods used for a complete personalization transaction. For a complete listing of the API, please contact Print Science.
| Method | Description |
| get_version | Return indicator that client will use desktop or mobile version |
| beginPersonalization | Launches a new personalization session. |
| getPreviewMulti | Get URL to newly created PDF and URLs to thumbnail images of newly created PDF |
| resumePersonalization | Resumes an earlier personalization session. |
| endPersonalization | Close personalization session. |
¶ beginPersonalization
This method call launches a new personalization session. The method will return a new personalization sessionID and a URL for the personalization session. You should store the sessionID received and redirect the user to the new URL.
Request Parameters
| Username | For user authentication |
| Key | For user authentication |
| Product ID |
ID of the PDF template for which to begin personalization. |
| Success URL | This is an URL to which the user should be redirected if the personalization is closed successfully. |
| Fail URL | This is an URL to which the user should be redirected if the personalization is closed with an error. For example insufficient credit.. |
| Close URL | The URL to which the user should be redirected if the Flex App is closed without approving any proof (i. e. the user cancels personalization) |
| Comment | A comment to be used when decrementing points with the Sweet Tooth API. |
|
Language ID |
This should be 2-character ISO language ID such as “en” or “de”. If no language indicator is provided, the default is english. |
Return Parameters
| Session ID | Session ID used for methods getPreview and endPersonalization |
| URL | URL that will display Flex application to user. |
¶ Sample request
<?xml version='1.0'?> <methodCall> <methodName>beginPersonalization</methodName> <params> <param> <value> <string>science</string> </value> </param> <param> <value> <string>e13a5e85d90244351ddb78559298983bad0bcb52</string> </value> </param> <param> <value> <string>272</string> </value> </param> <param> <value> <string>http://printscience.net/demo/success</string> </value> </param> <param> <value> <string>http://printscience.net/demo/fail</string> </value> </param> <param> <value> <string>http://printscience.net/demo/close</string> </value> </param> <param> <value> <string>Some comment ...</string> </value> </param> <param> <value> <string>en</string> </value> </param> <param> <value> <string>402</string> </value> </param> <param> <value> <array> <data> <value> <struct> <member> <name>field2</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'field2'</string> </value> </member> </struct> </value> </member> <member> <name>Block_1</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_1'</string> </value> </member> </struct> </value> </member> <member> <name>field1</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'field1'</string> </value> </member> </struct> </value> </member> <member> <name>Block_15</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_15'</string> </value> </member> </struct> </value> </member> <member> <name>Block_14</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_14'</string> </value> </member> </struct> </value> </member> <member> <name>Block_0</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_0'</string> </value> </member> </struct> </value> </member> <member> <name>field3</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'field3'</string> </value> </member> </struct> </value> </member> <member> <name>Block_5</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_5'</string> </value> </member> </struct> </value> </member> <member> <name>Block_4</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_4'</string> </value> </member> </struct> </value> </member> <member> <name>Block_6</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_6'</string> </value> </member> </struct> </value> </member> <member> <name>field_name</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'field_name'</string> </value> </member> </struct> </value> </member> <member> <name>big_text_label</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'big_text_label'</string> </value> </member> </struct> </value> </member> <member> <name>Block_3</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_3'</string> </value> </member> </struct> </value> </member> <member> <name>Block_2</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_2'</string> </value> </member> </struct> </value> </member> </struct> </value> </data> </array> </value> </param> </params> </methodCall>
¶ Sample response
Successful response
<?xml version='1.0'?> <methodResponse> <params> <param> <value> <array> <data> <value> <string>29d1351405bbf05a0d7e0366fb9a9522</string> </value> <value> <string>http://some.url/to/the/personalization/session</string> </value> </data> </array> </value> </param> </params> </methodResponse>
Fault response
<?xml version='1.0'?> <methodResponse> <fault> <value> <struct> <member> <name>faultCode</name> <value><int>4</int></value> </member> <member> <name>faultString</name> <value><string>Product Id is invalid!</string></value> </member> </struct> </value> </fault> </methodResponse>
¶ getPreview DEPRECATED
THIS METHOD HAS BEEN DEPRECATED. USE METHOD getPreviewMulti()
In the Designer user-interface, when the customer hits the button "Approve", the following actions occur:
1. The Designer server creates a new PDF file
2. For each page in the PDF file, the Designer server creates a thumbnail image
3. The user is redirected back to the shopping cart system from which the Designer session was launched
The getPreview() method allows you to recuperate URLs to the PDF file as well as URLs to the thumbnail images created by the Designer server.
Request Parameters
| SessionID | SessionID returned from method beginPersonalization |
Return Parameters
| pdf_url | The URL to the PDF proof identified by the proof ID. |
| preview_url | An array of tuples. Each tuple is itself an array (of 2 elements):
If no proof has been created yet, then a fault will be returned. |
¶ Sample Request
<?xml version='1.0'?> <methodCall> <methodName>beginPersonalization</methodName> <params> <param> <value> <string>science</string> </value> </param> <param> <value> <string>e13a5e85d90244351ddb78559298983bad0bcb52</string> </value> </param> <param> <value> <string>272</string> </value> </param> <param> <value> <string>http://printscience.net/demo/success</string> </value> </param> <param> <value> <string>http://printscience.net/demo/fail</string> </value> </param> <param> <value> <string>http://printscience.net/demo/close</string> </value> </param> <param> <value> <string>Some comment ...</string> </value> </param> <param> <value> <string>en</string> </value> </param> <param> <value> <string>402</string> </value> </param> <param> <value> <array> <data> <value> <struct> <member> <name>field2</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'field2'</string> </value> </member> </struct> </value> </member> <member> <name>Block_1</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_1'</string> </value> </member> </struct> </value> </member> <member> <name>field1</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'field1'</string> </value> </member> </struct> </value> </member> <member> <name>Block_15</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_15'</string> </value> </member> </struct> </value> </member> <member> <name>Block_14</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_14'</string> </value> </member> </struct> </value> </member> <member> <name>Block_0</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_0'</string> </value> </member> </struct> </value> </member> <member> <name>field3</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'field3'</string> </value> </member> </struct> </value> </member> <member> <name>Block_5</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_5'</string> </value> </member> </struct> </value> </member> <member> <name>Block_4</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_4'</string> </value> </member> </struct> </value> </member> <member> <name>Block_6</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_6'</string> </value> </member> </struct> </value> </member> <member> <name>field_name</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'field_name'</string> </value> </member> </struct> </value> </member> <member> <name>big_text_label</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'big_text_label'</string> </value> </member> </struct> </value> </member> <member> <name>Block_3</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_3'</string> </value> </member> </struct> </value> </member> <member> <name>Block_2</name> <value> <struct> <member> <name>value</name> <value> <string>Default value for field 'Block_2'</string> </value> </member> </struct> </value> </member> </struct> </value> </data> </array> </value> </param> </params> </methodCall>
¶ Sample response
¶ getPreviewMulti
In the Designer user-interface, when the customer hits the button "Approve", the following actions occur:
1. The Designer server creates a new PDF file
2. For each page in the PDF file, the Designer server creates a thumbnail image
3. The user is redirected back to the shopping cart system from which the Designer session was launched
The getPreviewMulti() method allows you to recuperate URLs to the PDF file as well as URLs to the thumbnail images created by the Designer server.
Request Parameters
| SessionID | SessionID returned from method beginPersonalization |
Response
|
getPreviewMulti
Returns the URLs to the generated proofs, and to the generated previews, for simple personalization sessions as well as for grouped products sessions. |
|
|
Parameter #1 |
Session key |
|
Return Result |
Returns an array of structures structure with following members: pdf_url – The URL to the PDF proof identified by the proof ID. preview_url – An array of tuples. Each tuple is itself an array (of 2 elements):
Each element in the array corresponds to a product in the product group.
Note: If no proof has yet been generated yet for a proof, then an empty structure will be returned for that product. |
¶ Sample request
<?xml version='1.0'?>
<methodCall>
<methodName>getPreviewMulti</methodName>
<params>
<param>
<value>
<string>5j5gs9leifhqurxopk0gwvb0n625nxdf</string>
</value>
</param>
</params>
</methodCall>
¶ Sample response
<?xml version='1.0'?><methodResponse>
<params>
<param>
<value>
<array>
<data>
<value>
<struct></struct>
</value>
<value>
<struct>
<member>
<name>pdf_url</name>
<value>
<string>https://he45.printscience.net/files/user_files/test/pdf_proof/proof_2016_02_22_11_53_55_299863.pdf</string>
</value>
</member>
<member>
<name>preview_url</name>
<value>
<array>
<data>
<value>
<array>
<data>
<value>
<int>0</int>
</value>
<value>
<string>https://he45.printscience.net/files/user_files/test/pdf_proof_preview/proof_2016_02_22_11_53_55_299863_0.jpg</string>
</value>
</data>
</array>
</value>
<value>
<array>
<data>
<value>
<int>1</int>
</value>
<value>
<string>https://he45.printscience.net/files/user_files/test/pdf_proof_preview/proof_2016_02_22_11_53_55_299863_1.jpg</string>
</value>
</data>
</array>
</value>
</data>
</array>
</value>
</member>
</struct>
</value>
<value>
<struct></struct>
</value>
</data>
</array>
</value>
</param>
</params>
</methodResponse>
¶ resumePersonalization
This method call resumes an earlier personalization session. The method will return a personalization sessionID and a URL for the personalization session. You should store the sessionID received and redirect the user to the new URL.
Request Parameters
| Username | For user authentication |
| Key | For user authentication |
| Session ID |
Session ID returned by beginPersonalization. |
| Product ID |
ID of the PDF template for which to resume personalization. |
| Success URL | This is an URL to which the user should be redirected if the personalization is closed successfully. |
| Fail URL | This is an URL to which the user should be redirected if the personalization is closed with an error. For example insufficient credit.. |
| Close URL | The URL to which the user should be redirected if the Flex App is closed without approving any proof (i. e. the user cancels personalization) |
| Comment | A comment to be used when decrementing points with the Sweet Tooth API. |
|
Language ID |
This should be 2-character ISO language ID such as “en” or “de”. If no language indicator is provided, the default is english. |
Return Parameters
| Session ID | Session ID used for methods getPreview and endPersonalization. This Session ID may be different from original Session ID sent as a request parameter. |
| URL | URL that will display Design Online session to user. |
| Boolean flag | If TRUE, then previous session was correctly retrieved. Redirecting to URL will launch a personalization session using stored data. If FALSE, then previous session could not be retrieved. Redirecting to URL will launch a new personalization session. |
¶ Sample request
<?xml version='1.0'?> <methodCall> <methodName>resumePersonalization</methodName> <params> <param> <value> <string>science</string> </value> </param> <param> <value> <string>e13a5e85d90244351ddb78559298983bad0bcb52</string> </value> </param> <param> <value> <string>1</string> </value> </param> <param> <value> <string>205455566e9c4250e3e4051770f7e13a</string> </value> </param> <param> <value> <string>http://printscience.net/demo/success</string> </value> </param> <param> <value> <string>http://printscience.net/demo/fail</string> </value> </param> <param> <value> <string>http://printscience.net/demo/close</string> </value> </param> <param> <value> <string>Some comment ...</string> </value> </param> <param> <value> <string>en</string> </value> </param> </params> </methodCall>
¶ Sample response
Successful response
<?xml version='1.0'?> <methodResponse> <params> <param> <value> <array> <data> <value> <string>64362784b500110432055d4d8a7e057d</string> </value> <value> <string>http://designerserver.com/personalization/app/64362784b500110432055d4d8a7e057d</string> </value> <value> <boolean>0</boolean> </value> </data> </array> </value> </param> </params> </methodResponse>
Fault response
<?xml version='1.0'?> <methodResponse> <fault> <value> <struct> <member> <name>faultCode</name> <value> <int>3</int> </value> </member> <member> <name>faultString</name> <value> <string>Authentication failed!</string> </value> </member> </struct> </value> </fault> </methodResponse>
¶ get_version
You may want to know whether the user is on a desktop or a mobile device. The Designer server is equipped with detection software it uses to determine whether it will server the desktop or mobile version of the Designer application.
You can poll the Designer server for with a simple API call like:
http://he11.printscience.net/pdf_admin/rpc_api_v_4_0_0/get_version/product/[productID]/
The productID you use may be the productID of any valid product in your account on the Designer server
The reponse will be a simple json string like:
{"app_type": "desktop"}
where the valid values for app_type are: "desktop" or "mobile"
¶ Sample request
The request is a simple URL call.
The session ID in the URL must be a valid session ID, that has been returned by the beginPersonalisation function:
http://he11.printscience.net/pdf_admin/rpc_api_v_4_0_0/get_version/041668d091d162828cb835014ccc1637/
¶ Sample response
The return value of get_version is a JSON object of the following form:
{"app_type": "desktop"}
¶ endPersonalization
Closes a personalization session. Subsequent calls to API methods that use this key, will result in failures.
Request Parameters
| SessionID | SessionID returned from method beginPersonalization |
Return Parameters
There are no parameters returned.
¶ Sample request
<?xml version='1.0'?> <methodCall> <methodName>endPersonalization</methodName> <params> <param> <value><string>69d44ba09eeac17047ecf3e6c75e0ddb</string></value> </param> </params> </methodCall>
¶ Sample response
<?xml version='1.0'?> <methodResponse> <params> <param> <value><nil/></value></param> </params> </methodResponse>
¶ Fault codes
Following error codes are the error codes that are used for the API methods:
| Code | Description |
|---|---|
| 0 | Success – No error |
| 1 | Insufficient credit |
| 2 | Proof not available. (Will be returned if user requests thumbnail for example yet no Proof is available) |
| 3 | Authentication failure |
| 4 | Product Id Invalid |
| 5 | Session Id is Invalid |
| 6 | User creation failed |
| 7 | Username already exists |
| 8 | Invalid upload data |
| 9 | Proof ID is Invalid |
| 10 | Merge data ID is invalid |
| 11 | PDF template ID is invalid |
| 12 | Image gallery ID is invalid |
| 13 | Image ID is invalid |
| 14 | Mapping ID is invalid |
| 15 | Mapping and Product ID mismatch (mapping has been specified for a different product) |
| 16 | Invalid image format |
| 17 | Invalid key column. One of these error might have occurred: column index is invalid or out of range (if CSV data has no row with column names) column name is invalid (if CSV data has row with column names) |
| 18 | Key value could not be found in key column. |
| 19 | An error has been encountered in the CSV file |
| 20 | Invalid DB object (CSV object) name. This error is usually issued if a client is trying to create a new object by uploading data and has provided a duplicate name. |
| 1000 | Internal error |