Design Streaming Technical Reference

This document covers all API calls required to create a 3D print order with the Authentise Design Streaming.

Overview

Ideally, the integration takes place right after you get the confirmation from the payment gateway.

At this moment, instead of pointing the user to a download link, your website will (1) authenticate itself and create a token, (2) upload the STL file and get the token link back and load it inside an iframe. Additionally, you can also retrieve information about the print status of a certain token (3).

Please see below the Authentise API calls highlighted in blue on this workflow.

../_images/integration-workflow.png

API Authentication & Access Restrictions

In order to keep the communication secure, you will need to use the API key provided by Authentise for the API calls. The authentication uses a 32 Character ID to identify you as a partner, it is communicated in HTTPS and is included in every call.

Creating a transaction

Each print intermediated by Authentise is called a transaction. For each design file, one transaction is created.

Even if your purchase order accounts for more than one design file, each design will require one separate transaction.

Each transaction requires you upload the STL file to be streamed and pass some particular information about the design file via API. When a new transaction is created, Authentise assign it an unique identifier number, named token.

api_create_partner_token()
api_upload_partner_stl()

How customers start streaming?

Once the transaction is created and the STL file is uploaded, Authentise will use the token of the transaction to prepare the token link.

The token link should be loaded in your website inside a 400px x 400px iframe. The printing process will take place in this iframe and your client won’t leave your website until the print is completed.

../_images/widget.png

Returning to the order

To let your costumers return to the order, simply link your Order History to the token link.

../_images/order-history.png

REST API Resources

API URL Format

This is a general url format used with all API calls:

http://widget.sendshapes.com:3000/api3/<resource_name>

Or, for SSL

https://widget.sendshapes.com:3000/api3/<resource_name>

Example

http://widget.sendshapes.com:3000/api3/api_create_partner_token?api_key=ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB==

Or, again, for SSL

https://widget.sendshapes.com:3000/api3/api_create_partner_token?api_key=ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB==

API Key

Note: A unique partner key will be provided.

Resources

GET /api3/api_create_partner_token

This resource is used to create a token for a specific purchase order of an stl file.

Query Parameters:
 
  • api_key – Required. Key provided by Authentise to uniquely identify each partner and provide authorization for all api calls
Response JSON Object:
 
  • token – unique token to be used with a specific purchase order

Example Request:

GET /api3/api_create_partner_token&api_key=foobar

Example response:

{"data":{"token":"6004f5248584a48f3ea677d89827ce35"},"status":{"code":"ok"}}
POST /api3/api_upload_partner_stl

This resource is used to upload an stl file and accompanying information.

Query Parameters:
 
  • api_key – Required. Key provided by Authentise to uniquely identify each partner and provide authorization for all api calls
  • token – Required. The token associated with the purchase order (and STL file). Obtained by calling GET /api3/api_create_partner_token
  • receiver_email – Required. Email of the customer who purchased the STL file
  • stl_file – Required. STL file purchased by the customer. This file is securely uploaded to Authentise cloud for post-processing (slicing) and printing by the customer/printer owner
  • print_value – Required. Value of the purchased STL file
  • print_value_currency – Optional. The currency used in print_value. This should be a currency identifier from ISO-4217 currency codes. Defaults to ‘USD’
  • partner_job_id – Optional. Partner ID associated with this purchase order
Response JSON Object:
 
  • token_link – Link to the widget that will display only purchase-order specific information. This link should b eused within an iframe element in the partner website integration
  • ssl_token_link – Same as token_link, but uses https

Example Response

{u'status': {u'code': u'ok'}, u'data': {u'token_link': u'http://tokens.sendshapes.com/?token=8583d29c0226169670e6f9835c9f7f8e', u'ssl_token_link': u'https://tokens.sendshapes.com/?token=8583d29c0226169670e6f9835c9f7f8e'}}
GET /api3/api_get_partner_print_status

This api call is used to get print status information for a specific purchase order.

Query Parameters:
 
  • api_key – Required. Key provided by Authentise to uniquely identify each partner and provide authorization for all api calls
  • token – Required. The token associated with the purchase order (and STL file). Obtained by calling GET /api3/api_create_partner_token
Response JSON Object:
 
  • printing_job_status – The status of the print (once the print has been started). Available status values: WARMING_UP, PRINTING, FAILURE, SUCCESS, CONFIRMED_SUCCESS and CONFIRMED_FAILURE
  • printing_percentage – Percentage of the print completed
  • minutes_left – Estimated minutes left until the print is completed
  • message – Printer owner/user generated comment or feedback on the print after completion
  • total_time – The total time the print has taken in seconds. This is updated periodically as the print continues until the print is completed or canceled.
  • printer_model – The model of printer that is being used for this print