Lab connector for store developers¶

An online store, or any other system that takes print orders, can send them straight to a Picsha Lab. The Lab treats them like any other order: the same queue, the same product routing and printers, the same status reporting. This page is for the developer of the connecting system. If your store runs on the Picsha App suite, nothing here is needed: connect it from the store's Lab card, or once for every product from your Picsha Hub, with a key from the Lab (see Lab Connector).

Credentials and address¶

An administrator of the Lab issues a connector key under Settings, Lab Connector. The key is a pck_ token shown once at issue; keep it on your server and never in a browser. It belongs to one organization and may only create and read that organization's orders. Revoking it in the Lab stops it at once.

Every call goes to the Lab's address followed by /lab/connector/, for example https://acme.dam.picsha.com/lab/connector/orders, with the key as a bearer token:

Authorization: Bearer pck_…

A wrong or revoked key answers 401. A route the key may not call answers 403. Answers are JSON.

Routes¶

Route	Use
`GET products/storefront`	The organization's products: name, width and height in thousandths of an inch, price in cents and price breaks. Also the cheapest call to check a key. Specialty products are left out unless you add `?getall=1`.
`PUT products/storefront`	Push your own sizes as the Lab's products (below).
`GET locations/storefront`	The organization's pickup locations, by name.
`POST orders`	Create an order.
`PATCH order/job/<job id>`	Upload one job's print-ready file.
`PATCH orders/<order id>`	Set the order's status: `Submitted` when every file is in, `Cancelled` to cancel.
`GET orders`	Read orders: one by `?orderid=<id>&fetch=1`, or the ones changed since a time with `?modtime=<ISO time>&fetch=500&sort=modified-desc`.

Sending an order¶

An order is three steps, so that a store that crashes halfway can pick up where it left off.

Create. POST orders with orderType: "app", initialStatus: "Received", an externalRef (source, account and orderId: your system's name, your store's identifier and your order number), the customer and delivery details, one cart.items[] entry per job (the product name, copies, the job's display name, jobType: "image", fileType: "jpg", the unit price in cents) and a cart.summary with subtotal, tax, shipping and total in cents. The answer carries the Lab's orderId and one job id per cart item, in order. Sending the same externalRef again answers the same order and job ids with duplicate: true instead of creating a second order, so a retry is always safe.
Upload. For each job, PATCH order/job/<job id> with the print-ready JPEG as base64 in finalRender. The Lab makes the thumbnails. Record which jobs are done; a retry after a failure uploads only the rest.
Finish. PATCH orders/<order id> with { "status": "Submitted" }. Until then the order is Received: it exists, but the Lab's queue does not show it and automatic printing leaves it alone, so a half-sent order is never printed.

Send details on the create when your order has structure the Lab should show, such as one line per size with its finishing, the store's name, your order number and the customer's instructions. The Lab merges it over what it works out itself, and the order summary shows it.

Products: push your sizes¶

The Lab routes each product to a printer, so it needs a product row for each size you sell. Push your catalog with PUT products/storefront on connect and whenever your sizes change:

{ "source": "mystore", "store": "downtown",
  "products": [ { "externalId": "4x6", "name": "4 × 6", "widthMils": 4000, "heightMils": 6000, "priceCents": 49, "active": true } ] }

Products are matched on your source, store and externalId, so a renamed size keeps its row and its printer route. A size missing from the list is set inactive, never deleted. The answer lists each product with whether it is routed yet. The Lab administrator routes your products under Settings, Printers, where they appear under your source's name. An order naming a product the Lab has not seen creates it, unrouted, so a new size never blocks an order; it just does not print until it is routed.

Statuses¶

The Lab's statuses are its own: Received, Submitted, Harvested, Processing, Error Printing, Printed OK, Rework, Complete, Ready for Pickup, On Hold, Cancelled and the rest listed in Order statuses. A PATCH orders/<id> with a status the organization does not have answers 400.

Read status back by polling GET orders?modtime=<the last time you looked>&fetch=500&sort=modified-desc, once per connected store every few minutes, and match rows to your orders by external_ref. A sensible mapping for a customer-facing order page: Harvested and Processing mean in production; Printed OK, Complete, Ready for Pickup and Ship to DG85 mean ready or shipped; Error Printing and Rework need attention in your admin; Cancelled is cancelled.

What the Lab shows¶

A store order appears in the queue with type app, the customer's name under Ordered By, the delivery method, the products you named, and the files you uploaded. The store's own order number and customer email are not shown on the order yet.

The Picsha App suite's implementation of this protocol, including a mock Lab for tests, is the reference: ask Picsha support for access.