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:

  • login

login of the user to bill

  • password

password of the user to bill

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:

  • ship_addressee

first name and last name of the customer, or company name

  • ship_street1

street address to ship to, first line

  • ship_street2

street address to ship to, second line

  • ship_city

city

  • ship_state

state or province

  • ship_postal_code

postal code of the city

  • ship_country

ISO 3166-1 alpha-2 country code

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:

  • ship_method

express (force UPS shipping), quick (FR only: force Colissimo shipping)

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

  • item[<i>]

<uuid>:<qty>:<scale>:<unit>:<material>

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.

  • notification_url

It corresponds to the url on which you wish to be notified by a POST request, each time there is change in the status of your order. The request contains the reference of your order. At the time of shipping, you can use the TRACKING_URL to obtain the tracking number of the parcel.

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:

  • Billed

order has been made and will be validated by our commercial team after payment has been received

  • New

order is ready to be produced

  • In Process

order is being produced

  • Shipped

the order was produced and shipped to the recipient

  • Blocked

an error on the order is currently blocking its production, customer support may contact you to decide how to proceed

  • Cancelled

the order was cancelled

  • API Test

the order is a test and is not to be produced or billed (see parameter “fake=1”)

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.

Sample Request

By using the following HTML form and PHP code, you can issue a correct POST Request.

The following HTML form asks the user for information. This form only contains the mendatory parameters but can be extanted easily.

<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 code that specifies the right POST parameters to issue a correct request.

<?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;
	}
?>	
Prev: Obtaining the 3D printing price of a design Next: Creating Parametric Designs

» webapi documentation » Managing 3D printing orders » Ordering designs via API

Last update: 1970-01-01 01:00 (CET)