Orders API: save order

12/09/2009

Creating a new web-to-print order via API is a 3-stage process:

  • generate previews
  • save an order
  • generate output files

This API function creates a “saved” web-to-print order for a template using the latest data from the user cache and the previews generated by the web-to-print user earlier.

Call parameters

URL: http://[your-domain]/api.aspx?page=api-order-save

Domain name: custom only.

Page: api.aspx

Required POST parameters:

  • ApiKey={your api key}
  • TemplateID={ID of a saved order}
  • ID={id of the user saving the order, impersonated}
  • Hash={an MD5 hash of the user password and callers IP address}
  • Previews={a comma separated list of preview files generated for the order}

Response:

  • on success: saved order id in GUID format
  • on error: a text error msg or 404 with additional info in X_ZP_API_Mgs header

Anything other than a GUID is an error msg.

Previews parameter

This call impersonates a user identified by ID parameter.  Preview file names should be specified in Previews parameter as a comma separated list.

  • Only file names with extensions should be included, no paths
  • The order of the IDs is unimportant
  • IDs of static pages and empty IDs are ignored

ZetaPrints web-to-print system compares the cached data in the user’s profile against the list of preview IDs and returns an error if they do not match. This check is absolutely necessary. Users may step back and forth between different versions of previews and what they see becomes different from what is in the cache. If an order is placed when the previews are out of sync the user will get a wrong product in the end.

Example 1:

A user generated a set of previews for a 2-page template and added the item to cart, which triggered a call to order-save.

Previews=efcee7e8-99ee-4895-a7af-9b5400d4c906-0.jpg,efcee7e8-99ee-4895-a7af-9b5400d4c906-1.jpg

Example 2:

A user generated a set of previews for a 3-page template and added the item to cart, but only 2 pages were updated (1 and 3). Note the empty string between the two IDs in the first line. Both lines are valid examples.

Previews=efcee7e8-99ee-4895-a7af-9b5400d4c906-0.jpg,,efcee7e8-99ee-4895-a7af-9b5400d4c906-2.jpg

Previews=efcee7e8-99ee-4895-a7af-9b5400d4c906-0.jpg,efcee7e8-99ee-4895-a7af-9b5400d4c906-2.jpg

Example 3:

A user generated a set of previews for a 3-page template. The IDs for the latest set are:

  • efcee7e8-99ee-4895-a7af-9b5400d4c906-0.jpg
  • efcee7e8-99ee-4895-a7af-9b5400d4c906-1.jpg
  • efcee7e8-99ee-4895-a7af-9b5400d4c906-2.jpg

Then the user clicks back button in the browser and attempts to place an order with an older set of previews:

  • aaaaaaaa-99ee-4895-a7af-9b5400d4c906-0.jpg
  • bbbbbbb-99ee-4895-a7af-9b5400d4c906-1.jpg
  • cccccccc-99ee-4895-a7af-9b5400d4c906-2.jpg

Now ZetaPrints is asked to generate output files using the latest user input, but the previews rely on an outdated data set. If ZetaPrints saves the order as requested the data in the cache wouldn’t match the previews. The PDF files wouldn’t match the previews either. This is why the client and server side data have to be checked for synchronization using preview IDs.

See also: