PHP

A PHP script that uses the API with the curl extension. It lists a template's labelled variables, measures the drawing it makes with the values given, and exports it as a PDF.

Download it: box.php.

<?php
// box.php: list a template's inputs, measure it and export it as a PDF with the PiQ SaaS API.
// PHP 8.0 or later, with the curl extension.

$key = getenv('PIQ_API_KEY');
$base = rtrim(getenv('PIQ_URL') ?: 'https://saas.parametriq.co.uk', '/');
$storage = getenv('PIQ_STORAGE'); // optional: a registered storage's name
if (!$key) {
    fwrite(STDERR, "Set PIQ_API_KEY to your API key.\n");
    exit(1);
}

const TEMPLATE = "L=400,\"Length\"\nW=300,\"Width\"\nP1=[L,0]\nP2=[L,W]\nP3=[0,W]\nPOLYLINE @1,[P0,P1,P2,P3],TRUE,0";
// the template itself, or (optional) where it is kept in your storage
$template = $storage ? ['source' => ['storage' => $storage, 'key' => 'templates/box.piq']] : ['template' => TEMPLATE];
$values = ['L' => 500, 'W' => 250];

/** Posts the body as JSON; returns the response body and headers, or stops with the problem. */
function post(string $path, array $body): array
{
    global $key, $base;
    $headers = [];
    $curl = curl_init($base . $path);
    curl_setopt_array($curl, [
        CURLOPT_POST => true,
        CURLOPT_POSTFIELDS => json_encode($body),
        CURLOPT_HTTPHEADER => ["X-API-KEY: $key", 'Content-Type: application/json'],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADERFUNCTION => function ($curl, $line) use (&$headers) {
            if (str_contains($line, ':')) {
                [$name, $value] = explode(':', $line, 2);
                $headers[strtolower(trim($name))] = trim($value);
            }
            return strlen($line);
        },
    ]);
    $response = curl_exec($curl);
    $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    if ($response === false) {
        fwrite(STDERR, curl_error($curl) . "\n");
        exit(1);
    }
    if ($status >= 300) {
        fwrite(STDERR, "Error $status\n");
        $problem = json_decode($response, true); // a 401 has no body
        if (!is_array($problem)) $problem = ['detail' => $response];
        foreach (['title', 'detail'] as $part)
            if (!empty($problem[$part])) fwrite(STDERR, $problem[$part] . "\n");
        foreach ($problem['errors'] ?? [] as $field => $messages)
            fwrite(STDERR, "  $field: " . implode(' ', $messages) . "\n");
        exit(1);
    }
    return [$response, $headers];
}

// 1. The template's labelled variables
[$json] = post('/inputs', $template);
foreach (json_decode($json, true)['inputs'] as $i)
    echo "{$i['name']}: {$i['label']} ({$i['kind']}, " . json_encode($i['value']) . ")\n";

// 2. The drawing measured, with the values given
[$json] = post('/measure', $template + ['values' => $values]);
$m = json_decode($json, true);
$cut = 0;
foreach ($m['layers'] as $layer)
    if ($layer['layer'] === 'Cut') $cut = $layer['length'];
echo "Size: {$m['width']} x {$m['height']}, cut length: $cut\n";

// 3. The drawing as a PDF
[$pdf, $headers] = post('/export/pdf', $template + ['values' => $values]);
file_put_contents('box.pdf', $pdf);
echo "Saved box.pdf ({$headers['x-piq-warnings']} warnings)\n";

// 4. Optional: the PDF saved to your storage instead of downloaded
if ($storage) {
    $destination = ['storage' => $storage, 'key' => 'drawings/box.pdf'];
    [$json] = post('/save/pdf', $template + ['values' => $values, 'destination' => $destination, 'overwrite' => true]);
    $saved = json_decode($json, true);
    echo "Saved {$saved['key']} to {$saved['storage']} ({$saved['size']} bytes)\n";
}

How it works

Settings. The key comes from PIQ_API_KEY, the address from PIQ_URL (the service itself if not set) and, optionally, a storage's name from PIQ_STORAGE. Without a key the script stops at once.
The template. $template is the body every request starts from: the template's text as template or, when PIQ_STORAGE is set, where it is kept in your storage as source. $values gives L and W by name. Each request adds to it with +.
post sends a body to an operation as JSON, with the key in the X-API-KEY header, and collects the response's headers (by lower-case name) as they come. It hands back the body and the headers.
Errors. A request that couldn't be sent prints why. A response that isn't a success has its status printed, then its problem description: its title, its detail, and each entry of errors, the field and what is wrong with it. A 401 has no body, so there is nothing more to print; a body that isn't JSON is printed as it is. The script then exits with 1.
Inputs. POST /inputs needs only the template. Each of its inputs has a name, label, kind and value.
Measure. POST /measure with the values gives the drawing's width and height, and its lines' lengths by layer in layers; the cut length is the length on the Cut layer.
Export. POST /export/pdf answers with the PDF itself, not JSON: it is written to box.pdf as it is. The X-PiQ-Warnings header says how many things couldn't be exported as they are.
Save (optional). With a storage, POST /save/pdf exports the same drawing and saves it to your storage at destination, 'overwrite' => true replacing a file already there. It answers with where it saved it and its size.

Running it

Save the script as box.php. It needs the curl extension: php -m lists curl when it is there (on Debian and Ubuntu it is the php-curl package; on Windows, uncomment extension=curl in php.ini). Then:

export PIQ_API_KEY=XXXX-XXXX-XXXX-XXXXX
php box.php

It prints the template's labelled variables, the drawing's size and cut length, and saves box.pdf:

L: Length (Number, 400)
W: Width (Number, 300)
D: Depth (Number, 300)
Size: 500 x 250, cut length: 1500
Saved box.pdf (0 warnings)

With a value the template can't use ("L": "long", say), it prints the problem and stops:

Error 400
One or more validation errors occurred.
Some of the values given can't be used.
  L: L is a number.

With a key that isn't right it prints only Error 401: a 401 has no problem description.

To try the storage part, register a storage (see Register a storage), put a template in it as templates/box.piq, and set PIQ_STORAGE to the storage's name. The template is then read from your storage, and the PDF is also saved to it as drawings/box.pdf, replacing any file already there.