Sample Code

iframe

To include Authentise widget within your website it is recommended to use an <iframe> element. For example

<!DOCTYPE html>
<html>
<body>

<!-- sample iframe code to integrate Authentise widget within your website -->

<iframe src="https://widget.sendshapes.com/" width="400" height="400"></iframe>

</body>
</html>

The link used in the iframe is dynamically generated by each GET /api3/api_upload_partner_stl call.

HTML Forms

GET /api3/api_create_partner_token

Copy and paste the code below to any .html file and run. This will create a form and make a GET request to return a token.

<!DOCTYPE html>
<html>
<body>

<form action="http://widget.sendshapes.com:3000/api3/api_create_partner_token" method="get">
<!--
for ssl use:
<form action="https://widget.sendshapes.com:3443/api3/api_create_partner_token" method="get"> -->

  API KEY: <input type="text" name="api_key" size="66"><br>

<input type="submit" value="Submit">

</form>

<p>Enter API KEY and click Submit to get token back.</p>

</body>
</html>
../_images/form-get-create_partner_token.png

Form generated by the code above with filled out form-fields.

POST api_upload_partner_stl

Use the token from the GET request above, upload an STL file and get a token_link back.

<!DOCTYPE html>
<html>
<body>

<form action="http://widget.sendshapes.com:3000/api3/api_upload_partner_stl"
enctype="multipart/form-data" method="post">
<!--
for ssl use:
<form action="https://widget.sendshapes.com:3443/api3/api_upload_partner_stl"
enctype="multipart/form-data" method="post">
-->

API Key: <input type="text" name="api_key" size="66"><br>
Token: <input type="text" name="token" size="40"><br>
Print Value: <input type="text" name="print_value" size="10"><br>
Email: <input type="text" name="receiver_email" size="40"><br>
Job ID (optional): <input type="text" name="partner_job_id" size="20"><br>

<p>
Choose an STL file to upload*:<br>
<input type="file" name="stl_file" size="80">
</p>

<div>
<input type="submit" value="Submit">
</div>

</form>

<p>Enter API KEY, Token, Print Value, Email, (optional) Job ID, and choose STL file to upload*. Returned will be a token link that you can use within an iframe.
<p>*make sure the STL file is less than 0.5 MB in size for testing</p>

</body>
</html>
../_images/form-post-upload_partner_stl.png

Form generated by the code above with filled out form-fields.

PHP

Curl required

Note: On some servers, you will need to inject certificate authority root certificate. You can download it from here: https://s3-us-west-2.amazonaws.com/sendshapes-ca-root/CARoot.pem

<?php

class Curl
{
    public static function request ($url, $param = array(), $method = 'get')
    {
        $res = '';
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_HEADER, 0);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
        if ($method == 'post')
        {
            curl_setopt($ch, CURLOPT_POST, 1);
        // optional, enable it only if your curl build doesn’t include
            // certificate authority. Our CA Root certificate is available for
// download here:
     // https://s3-us-west-2.amazonaws.com/sendshapes-ca-root/CARoot.pem
      // define( 'SENDSHAPE_CA_ROOT', 'path/to/CARoot.pem' )
      // curl_setopt( $curl, CURLOPT_CAINFO, SENDSHAPE_CA_ROOT );
            curl_setopt($ch, CURLOPT_URL, $url);
            curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($param));
        }
        else
        {
            if(count($param))
            {
                $url .= '?' . http_build_query($param);
            }
        // optional, enable it only if your curl build doesn’t include
            // certificate authority. Our CA Root certificate is available for
// download here:
     // https://s3-us-west-2.amazonaws.com/sendshapes-ca-root/CARoot.pem
      // define( 'SENDSHAPE_CA_ROOT', 'path/to/CARoot.pem' )
      // curl_setopt( $curl, CURLOPT_CAINFO, SENDSHAPE_CA_ROOT );
            curl_setopt($ch, CURLOPT_URL, $url);
        }

        $res = curl_exec($ch);
        curl_close($ch);
        return $res;
    }


    public static function upload ($url, array $file, array $param = array())
    {
        $res = '';
        $ch = curl_init();
      // optional, enable it only if your curl build doesn’t include
        // certificate authority. Our CA Root certificate is available for
        // download here:
  // https://s3-us-west-2.amazonaws.com/sendshapes-ca-root/CARoot.pem
  // define( 'SENDSHAPE_CA_ROOT', 'path/to/CARoot.pem' )
  // curl_setopt( $curl, CURLOPT_CAINFO, SENDSHAPE_CA_ROOT );
        curl_setopt($ch, CURLOPT_HEADER, 0);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);

        curl_setopt($ch, CURLOPT_POST, 1);
        curl_setopt($ch, CURLOPT_URL, $url);

        curl_setopt($ch, CURLOPT_HTTPHEADER, array("Content-type: multipart/form-data"));

        $param[key($file)] = "@".realpath(current($file)).";type=text/stl";
        curl_setopt($ch, CURLOPT_POSTFIELDS, $param);

        $res = curl_exec($ch);
        curl_close($ch);
        return $res;
    }
}

Quick Start

Note: this sample combines api_create_partner_token with api_upload_partner_stl (where it passes token from api_create_partner_token to api_upload_partner_stl).

<?php

require 'Curl.php';

$query = array('api_key' => 'ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB==');

$server  = 'http://widget.sendshapes.com';
// For SSL uncomment the line below
// $server  = 'https://widget.sendshapes.com';
$port    = '3000';
// For SSL uncomment the line below
// $port    = '3443';
$url     = '/api3';
$command = 'api_create_partner_token';

$response = json_decode(Curl::request("{$server}:{$port}{$url}/{$command}",
                                      $query));

$query = array(
    'api_key'        => 'ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB==',
    'token'          => $response->{'data'}->{'token'},
    'print_value'    => '89.95',
    'receiver_email' => 'customerXYZ@gmail.com',
    'printer_job_id' => '123XYZ456-009');

$file = 'testcube_10mm.stl';


$command = 'api_upload_partner_stl';

$response = json_decode(Curl::upload("{$server}:{$port}{$url}/{$command}",
                                     array('stl_file' => $file),
                                     $query));

var_dump($response);

GET api_create_partner_token

<?php

require 'Curl.php';

$query = array('api_key' => 'ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB==');

$server  = 'http://widget.sendshapes.com';
// For SSL uncomment the line below
// $server  = 'https://widget.sendshapes.com';
$port    = '3000';
// For SSL uncomment the line below
// $port    = '3443';
$url     = '/api3';
$command = 'api_create_partner_token';

$response = json_decode(Curl::request("{$server}:{$port}{$url}/{$command}",
                                      $query));

print "Token: {$response->{'data'}->{'token'}} \n";

POST api_upload_partner_stl

Note: token value to use is returned from api_get_partner_token (above)

<?php

require 'Curl.php';

$query = array(
    'api_key'        => 'ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB==',
    'token'          => 'xxxxxxxxxxxxxxxxxxxxxx',
    'print_value'    => '89.95',
    'receiver_email' => 'customerXYZ@gmail.com',
    'printer_job_id' => '123XYZ456-009');

$file = 'testcube_10mm.stl';

$server  = 'http://widget.sendshapes.com';
// For SSL uncomment the line below
// $server  = 'https://widget.sendshapes.com';
$port    = '3000';
// For SSL uncomment the line below
// $port    = '3443';
$url     = '/api3';
$command = 'api_upload_partner_stl';

$response = json_decode(Curl::upload("{$server}:{$port}{$url}/{$command}",
                                     array('stl_file' => $file),
                                     $query));
var_dump($response);

CURL (raw)

Using curl is the simplest way to manually test all Authentise API calls.

GET api_create_partner_token

A call to generate a unique token.

The generated token should be stored in the partner’s database for reference to a specific customer purchase order.

Note: one token should be generate per one print of an STL file

The format of the curl GET request is as follows:

curl url api_key=<partner key>

Request GET:

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

SSL:

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

Response:

{"status":{"code":"ok"},"data":{"token":"fbb23d8ed166b190f502fe4fdeb3b4f5"}}

POST api_upload_partner_stl

Below is a sample curl call to upload an STL file to Authentise’s cloud.

The format of the curl POST request is as follows:

curl  -F “api_key=<partner key>”  -F “token=<token>”
-F “print_value=<purchase price>”
-F “partner_job_id=<optional unique partner purchase id>”
-F “receiver_email=<customer email>” -F “stl_file=@<stl file name>” url

Request:

curl -F "api_key=ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB==" -F "token=49b9798741e371bd402c078ac49715f5" -F "print_value=4.75" -F "partner_job_id=xyz12345" -F "receiver_email=user123@email.com" -F "stl_file=@testcube_10mm.stl" http://widget.sendshapes.com:3000/api3/api_upload_partner_stl

SSL:

curl -F "api_key=ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB==" -F "token=49b9798741e371bd402c078ac49715f5" -F "print_value=4.75" -F "partner_job_id=xyz12345" -F "receiver_email=user123@email.com" -F "stl_file=@testcube_10mm.stl" https://widget.sendshapes.com:3443/api3/api_upload_partner_stl

Response:

{"status":{"code":"ok"},"data":{"ssl_token_link":"https:\/\/widget.sendshapes.com\/?token=49b9798741e371bd402c078ac49715f5","token_link":"http:\/\/widget.sendshapes.com\/?token=49b9798741e371bd402c078ac49715f5"}}

At this point token_link may be used to call up the widget within an iframe. For instance, a link from the response above looks as follows:

http://widget.sendshapes.com/?token=49b9798741e371bd402c078ac49715f5

GET api_get_partner_print_status

Request:

curl "http://widget.sendshapes.com:3000/api3/api_get_partner_print_status?api_key=ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB==&token=49b9798741e371bd402c078ac49715f5"

SSL:

curl "https://widget.sendshapes.com:3443/api3/api_get_partner_print_status?api_key=ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB==&token=49b9798741e371bd402c078ac49715f5"

There are two possible responses depending on whether the customer has started printing or not.

Case 1: The print has not yet been started by the customer

In this case no information can be provided until the customer starts the print, thus only extended_description is available.:

{"status":{"extended_description":"not yet available\n","description":"System error","code":"error"}}

Case 2: The print has been started by the customer

In this case all the available information about the print status is provided.:

{"status":{"code":"ok"},"data":{"minutes_left":45,"printing_percentage":"22","message":null,"printing_job_status_name":"PRINTING"}}

Case 3: The print has finished printing and customer confirmed success:

{"status":{"code":"ok"},"data":{"minutes_left":0,"printing_percentage":"100","message":null,"printing_job_status_name":"CONFIRMED_SUCCESS"}}

Case 4: The print has finished printing, customer confirmed failure and left a feedback message

This case represents a scenario where a 3D object has been fully printed (100%) however it did not meet customer’s expectations.:

{"status":{"code":"ok"},"data":{"minutes_left":0,"printing_percentage":"100","message":"The 3D ornament split into two pieces during print. I'm very disappointed.", "printing_job_status_name":"CONFIRMED_FAILURE"}}

Case 5: The print has not finished printing and customer left a feedback message:

{"status":{"code":"ok"},"data":{"minutes_left":15,"printing_percentage":"92","message":"The print did not finish! I want a refund!!!","printing_job_status_name":"CONFIRMED_FAILURE"}}

Python

This is a simple sample that 1) obtains a token for a purchase order and 2) uploads an STL file testcube_10mm.stl and obtains a url (via the token_link json output parameter) to access the widget.

You can copy & paste the code below and run it using python.

#!/usr/bin/env python
import argparse
import logging
import pprint
import requests
import time
import uuid

API_KEY = 'ZSBzaG9y-dCB2ZWhl-bWVuY2Ug-b2YgYW55-IGNhcm5h-bCB=='
LOGGER = logging.getLogger('test')
RECEIVER_EMAIL = 'test@authentise.com'
ROOT = 'authentise.com'

def _create_token():
    url = 'https://widget.sendshapes.com:3443/api3/api_create_partner_token'
    response = requests.get(url, data={'api_key': API_KEY})
    if not response.ok:
        raise Exception("Failed to create token: {} {}".format(response.status_code, response.text))
    return response.json()

def _upload_stl(filename, token):
    payload = {
        'api_key'               : API_KEY,
        'token'                 : token,
        'receiver_email'        : RECEIVER_EMAIL,
        'print_value'           : 0,
        'print_value_currency'  : 'USD',
    }
    url = 'https://widget.sendshapes.com:3443/api3/api_upload_partner_stl'
    with open(filename, 'rb') as f:
        response = requests.post(url, data=payload, files={'stl_file': f})
    if not response.ok:
        raise Exception("Failed to upload {} to token {}: {} {}".format(filename, token, response.status_code, response.text))
    return response.json()

def main():
    logging.basicConfig()
    logging.getLogger().setLevel(logging.DEBUG)

    parser = argparse.ArgumentParser()
    parser.add_argument('stl', help="The STL file to upload")
    args = parser.parse_args()

    result = _create_token()
    token = result['data']['token']
    LOGGER.info("Received token %s", token)
    LOGGER.info("Uploading STL file")
    result = _upload_stl(args.stl, token)
    token_link = result['data']['ssl_token_link']
    LOGGER.info("Token link: %s", token_link)

if __name__ == '__main__':
    main()