Ordering designs via API¶

The order API allows to order the 3D printing of designs directly from Sculpteo and request their shipment to the specified address when produced. The shipping address may be that of a customer or a warehouse. A list of items identified by their UUID is given, along with the quantity requested.

The only payment method available so far is invoice payment, where an invoice is sent to the billing address of the user performing the API call. In order to use it you must contact us first so that the corresponding account is allowed to perform invoice payments. The order API should also be secured by performing it over HTTPS transport, so as not to leak the user password.

The API may be called by issuing a POST request to the following url:

ORDER_URL : https://www.sculpteo.com/en/api/store/3D/order/

The following POST data must be filled in:

In case the item should be shipped to a different address than the shipping address of the API user, the following POST data should be filled in:

Please contact us to get the list of our shipping modes and associated costs. From this list, we select the cheapest shipping method by default. In case you want to select another shipping method, you can use:

The items to orders are then given using the following format:

where <i> should be replaced by an integer incrementing from 0 to the number of items - 1, and each <uuid> and <qty> should be replaced by the UUID of the design to order and the quantity required. The <scale>, <unit>, <material> are optional and may be skipped to use the default value. The list of material identifiers to use for <material> is available in Materials.

N.B.: ship_street1 is limited to 80 characters, you can also expand your address on ship_street2 if your shipping address is too long.

Upon successful completion of the request, the API call returns the Sculpteo order reference as a string, which may be used to track the status of the order at the following URL:

TRACKING_URL : https://www.sculpteo.com/shop/tracking/reference/<reference>

where <reference> is replaced by the order reference obtained from API call.

Upon error, a corresponding HTTP status code is returned along with a blank response.

You can get the information provided in this page in a JSON format with a POST request with an XTMLHttpRequest Header.

Also, we may send a POST to your server upon order status change. The url to POST to is given in the optional “notification_url” parameter, and the POST data will contain a single field “reference” whose value is our order reference. Your server may then use the tracking URL above to get more information on the new status of the order (including parcel tracking numbers when order is shipped).

The current list of order statuses is:

Additionally, any number of string-valued ‘comment’ keys may be provided to attach comments to the order (your own reference for example).

When shipping directly to the customer, you may customize the packing slip and invoice sent along with the packages. The items may be sent as multiple packages, therefore the packing slips must be generated dynamically at our factories. To customize them, we need to be given the information (logo, business address, etc…) that you wish to see on the packing slip. Please contact us at contact@sculpteo.com for this. Once we have this information, your specific packing slip template may be selected by providing an extra “theme” key whose value we will have agreed upon.

For custom invoices, you may send an extra PDF document file as the value of the “ship_invoice” key while performing this API call. In this case, the POST query must be made using multipart form-data, as is usually required when sending files.

For testing purposes, it is possible to perform the API call with an additional fake=1 argument, which will create an order that will not be produced or charged. The API call will otherwise work as described above, and a order reference will be returned if the call is successful.

<form action="order.php" method="post"> <!-- Type of form: POST -->
Login   <input type="text" name="login"/><br/>
Password        <input type="password" name="password"/><br/>
UUID    <input type="text" name="uuid"/><br/>
Quantity        <input type="text" name="qty"/><br/>
<input type="submit" name="submit" value="Order"/>
</form>

<?php
	if (isset($_POST['submit'])) { //if the form has been submitted

		# CURL REQUEST
		$ch = curl_init();   //Initialisation
		curl_setopt($ch,CURLOPT_URL, 'https://www.sculpteo.com/en/api/store/3D/order/'); //Order Url
		curl_setopt($ch, CURLOPT_POSTFIELDS, array( //Upload parameters from the form
				'login' => $_POST['login'],
				'password' => $_POST['password'],
				'item[0]' => $_POST['uuid'] . ":" . $_POST['qty'],
				'fake' => '1'
			));
		curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); //To obtain the answer from our servers
		curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false); //No HTTPS certificate
		$result = curl_exec($ch) //Launches the request
		curl_close($ch);

		# RESULT
		echo $result;
	}
?>