Webservice API

<?php

require '/var/www/html/config/config.inc.php';

$key = new WebserviceKey();
$key->key = bin2hex(random_bytes(16)); // 32 characters, as required (the test used a fixed throw-away value)
$key->description = 'Pocket Coffee club sync';
$key->active = 1;
$key->save();

$all = ['GET' => 1, 'POST' => 1, 'PUT' => 1, 'PATCH' => 1, 'DELETE' => 1, 'HEAD' => 1];
WebserviceKey::setPermissionForAccount($key->id, [
    'customers' => $all,
    'groups' => $all,
    'products' => ['GET' => 1],        // read-only
    'languages' => ['GET' => 1],
]);
$key->associateTo([1]);                // shop ids (needed even without multistore)

curl -s -u "${PS_WS_KEY}:" http://localhost:8080/api/

<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
<api shopName="PrestaShop">
<customers xlink:href="http://localhost:8080/api/customers" get="true" put="true" post="true" patch="true" delete="true" head="true">
<description xlink:href="http://localhost:8080/api/customers" get="true" put="true" post="true" patch="true" delete="true" head="true">
The e-shop's customers</description>
<schema xlink:href="http://localhost:8080/api/customers?schema=blank" type="blank"/>
<schema xlink:href="http://localhost:8080/api/customers?schema=synopsis" type="synopsis"/>
</customers>
<products ... get="true" put="false" post="false" patch="false" delete="false" head="false">
...

<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
<group>
  <reduction format="isFloat"></reduction>
  <price_display_method required="true" format="isPriceDisplayMethod"></price_display_method>
  <show_prices format="isBool"></show_prices>
  <date_add format="isDate"></date_add>
  <date_upd format="isDate"></date_upd>
  <name required="true" maxSize="32" format="isGenericName">
    <language id="1" xlink:href="http://localhost:8080/api/languages/1" format="isUnsignedId"></language>
    <language id="2" xlink:href="http://localhost:8080/api/languages/2" format="isUnsignedId"></language>
  </name>
</group>
</prestashop>

KEY="${PS_WS_KEY}"
B=http://localhost:8080/api

# equal, with display and JSON
curl -s -g -u "$KEY:" "$B/customers?display=[id,firstname,email]&filter[email]=[ada@example.test]&output_format=JSON"
# {"customers":[{"id":3,"firstname":"Ada","email":"ada@example.test"}]}

# ends with a domain
curl -s -g -u "$KEY:" "$B/customers?display=[id,email]&filter[email]=%[example.test]&output_format=JSON"

# interval of ids, sorted descending, first row only
curl -s -g -u "$KEY:" "$B/customers?display=[id,email]&filter[id]=[1,3]&sort=[id_DESC]&limit=0,1&output_format=JSON"
# {"customers":[{"id":3,"email":"ada@example.test"}]}

# not equal, and greater than
curl -s -g -u "$KEY:" "$B/customers?display=[id,email]&filter[email]=![ada@example.test]&output_format=JSON"
curl -s -g -u "$KEY:" "$B/customers?display=[id,email]&filter[id]=>[1]&output_format=JSON"

# date range (the end of the interval is exclusive)
curl -s -g -u "$KEY:" "$B/customers?display=[id,email,date_add]&filter[date_add]=[2026-10-27%2016:00:00,2026-10-27%2017:00:00]&date=1&output_format=JSON"

# one language, then two
curl -s -g -u "$KEY:" "$B/groups/4?language=2&output_format=JSON"
# {"group":{"id":4,"reduction":"10.00","show_prices":"1",...,"name":"Club del Café"}}
curl -s -g -u "$KEY:" "$B/groups/4?language=[1,2]&output_format=JSON"
# ... "name":[{"id":"1","value":"Coffee Club"},{"id":2,"value":"Club del Café"}]

<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
<customers>
<customer id="1" xlink:href="http://localhost:8080/api/customers/1"/>
<customer id="2" xlink:href="http://localhost:8080/api/customers/2"/>
<customer id="3" xlink:href="http://localhost:8080/api/customers/3"/>
</customers>
</prestashop>

SHA=$(curl -s -D - -o /dev/null -u "${PS_WS_KEY}:" "http://localhost:8080/api/groups/4?output_format=JSON" | tr -d '\r' | awk -F': ' 'tolower($1)=="content-sha1"{print $2}')
curl -s -i -u "${PS_WS_KEY}:" -H "Local-Content-Sha1: ${SHA}" "http://localhost:8080/api/groups/4?output_format=JSON" | head -1
# HTTP/1.1 304 Not Modified

<?xml version="1.0" encoding="UTF-8"?>
<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
  <group>
    <reduction>10</reduction>
    <price_display_method>0</price_display_method>
    <show_prices>1</show_prices>
    <name>
      <language id="1">Coffee Club</language>
      <language id="2">Club del Café</language>
    </name>
  </group>
</prestashop>

curl -s -i -u "${PS_WS_KEY}:" -X POST --data-binary @group.xml http://localhost:8080/api/groups
# HTTP/1.1 201 Created ... <group><id><![CDATA[4]]></id> ...

<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
  <customer>
    <id_default_group>4</id_default_group>
    <id_lang>2</id_lang>
    <passwd>a-long-random-password</passwd>
    <lastname>Lovelace</lastname>
    <firstname>Ada</firstname>
    <email>ada@example.test</email>
    <newsletter>0</newsletter>
    <active>1</active>
    <associations>
      <groups>
        <group><id>3</id></group>
        <group><id>4</id></group>
      </groups>
    </associations>
  </customer>
</prestashop>

curl -s -u "${PS_WS_KEY}:" -X PATCH --data-binary @patch.xml http://localhost:8080/api/customers/3

<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
  <customer>
    <id>3</id>
    <note>Coffee Club since 2026</note>
  </customer>
</prestashop>

<prestashop xmlns:xlink="http://www.w3.org/1999/xlink">
<errors>
<error>
<code><![CDATA[85]]></code>
<message><![CDATA[Validation error: "Property Customer->email is not valid"]]></message>
</error>
</errors>
</prestashop>

<?php

declare(strict_types=1);

if (!defined('_PS_VERSION_')) {
    exit;
}

class PcfgRoastBatch extends ObjectModel
{
    public $sku;
    public $id_product;
    public $roast_date;
    public $weight_kg;
    public $note;
    public $date_add;
    public $date_upd;

    public static $definition = [
        'table' => 'pcfg_roast_batch',
        'primary' => 'id_pcfg_roast_batch',
        'multilang' => true,
        'fields' => [
            'sku' => ['type' => self::TYPE_STRING, 'validate' => 'isReference', 'required' => true, 'size' => 32],
            'id_product' => ['type' => self::TYPE_INT, 'validate' => 'isUnsignedId'],
            'roast_date' => ['type' => self::TYPE_DATE, 'validate' => 'isDate', 'required' => true],
            'weight_kg' => ['type' => self::TYPE_FLOAT, 'validate' => 'isUnsignedFloat'],
            'date_add' => ['type' => self::TYPE_DATE, 'validate' => 'isDate'],
            'date_upd' => ['type' => self::TYPE_DATE, 'validate' => 'isDate'],
            'note' => ['type' => self::TYPE_STRING, 'lang' => true, 'validate' => 'isCleanHtml', 'size' => 255],
        ],
    ];

    protected $webserviceParameters = [
        'objectNodeName' => 'roast_batch',
        'objectsNodeName' => 'roast_batches',
        'fields' => [
            'id_product' => ['xlink_resource' => 'products'],
            'days_since_roast' => ['getter' => 'getWsDaysSinceRoast', 'setter' => false],
        ],
    ];

    /**
     * Virtual, read-only field exposed as <days_since_roast> by the Webservice.
     */
    public function getWsDaysSinceRoast(): int
    {
        return (int) (new DateTimeImmutable($this->roast_date))->diff(new DateTimeImmutable('today'))->format('%a');
    }
}

<?php

declare(strict_types=1);

if (!defined('_PS_VERSION_')) {
    exit;
}

require_once __DIR__ . '/src/Entity/PcfgRoastBatch.php';

class Pcfgws extends Module
{
    public function __construct()
    {
        $this->name = 'pcfgws';
        $this->tab = 'administration';
        $this->version = '1.0.0';
        $this->author = 'Pocket Coffee';
        $this->need_instance = 0;
        $this->ps_versions_compliancy = ['min' => '9.0.0', 'max' => '9.99.99'];
        $this->bootstrap = true;

        parent::__construct();

        $this->displayName = $this->trans('Pocket Coffee roast batches (Webservice)', [], 'Modules.Pcfgws.Admin');
        $this->description = $this->trans('Exposes roast batches as a Webservice resource.', [], 'Modules.Pcfgws.Admin');
    }

    public function install(): bool
    {
        return parent::install()
            && $this->installDb()
            && $this->registerHook('addWebserviceResources');
    }

    public function uninstall(): bool
    {
        return $this->uninstallDb() && parent::uninstall();
    }

    private function installDb(): bool
    {
        $table = _DB_PREFIX_ . PcfgRoastBatch::$definition['table'];
        $queries = [
            'CREATE TABLE IF NOT EXISTS `' . $table . '` (
                `id_pcfg_roast_batch` INT UNSIGNED NOT NULL AUTO_INCREMENT,
                `sku` VARCHAR(32) NOT NULL,
                `id_product` INT UNSIGNED NOT NULL DEFAULT 0,
                `roast_date` DATE NOT NULL,
                `weight_kg` DECIMAL(10,3) NOT NULL DEFAULT 0,
                `date_add` DATETIME NOT NULL,
                `date_upd` DATETIME NOT NULL,
                PRIMARY KEY (`id_pcfg_roast_batch`)
            ) ENGINE=' . _MYSQL_ENGINE_ . ' DEFAULT CHARSET=utf8mb4',
            'CREATE TABLE IF NOT EXISTS `' . $table . '_lang` (
                `id_pcfg_roast_batch` INT UNSIGNED NOT NULL,
                `id_lang` INT UNSIGNED NOT NULL,
                `note` VARCHAR(255) NOT NULL DEFAULT \'\',
                PRIMARY KEY (`id_pcfg_roast_batch`, `id_lang`)
            ) ENGINE=' . _MYSQL_ENGINE_ . ' DEFAULT CHARSET=utf8mb4',
        ];

        foreach ($queries as $query) {
            if (!Db::getInstance()->execute($query)) {
                return false;
            }
        }

        return true;
    }

    private function uninstallDb(): bool
    {
        $table = _DB_PREFIX_ . PcfgRoastBatch::$definition['table'];

        return Db::getInstance()->execute('DROP TABLE IF EXISTS `' . $table . '`, `' . $table . '_lang`');
    }

    /**
     * @param array<string, mixed> $params
     *
     * @return array<string, array<string, mixed>>
     */
    public function hookAddWebserviceResources(array $params): array
    {
        return [
            'roast_batches' => [
                'description' => 'Roast batches of Pocket Coffee',
                'class' => 'PcfgRoastBatch',
                'forbidden_method' => ['DELETE'],
            ],
        ];
    }
}

<!-- GET /api/roast_batches?schema=synopsis -->
<roast_batch>
  <id_product format="isUnsignedId"></id_product>
  <sku required="true" maxSize="32" format="isReference"></sku>
  <roast_date required="true" format="isDate"></roast_date>
  <weight_kg format="isUnsignedFloat"></weight_kg>
  <date_add format="isDate"></date_add>
  <date_upd format="isDate"></date_upd>
  <days_since_roast notFilterable="true" read_only="true" readOnly="true"></days_since_roast>
  <note maxSize="255" format="isCleanHtml"> <language id="1" .../> <language id="2" .../> </note>
</roast_batch>

curl -s -u "${PS_WS_KEY}:" -X POST --data-binary @batch.xml http://localhost:8080/api/roast_batches
curl -s -g -u "${PS_WS_KEY}:" "http://localhost:8080/api/roast_batches?display=full&output_format=JSON"
# {"roast_batches":[{"id":1,"id_product":1,"days_since_roast":1,"sku":"PC-ETH-WHL-250","roast_date":"2026-10-26",
#   "weight_kg":"14.000","date_add":"...","date_upd":"...","note":[{"id":1,"value":"Light roast, floral"},{"id":2,"value":"Tueste claro, floral"}]}]}
curl -s -g -u "${PS_WS_KEY}:" "http://localhost:8080/api/roast_batches?filter[roast_date]=[2026-10-25,2026-10-27]&date=1&display=[id,sku]&output_format=JSON"
curl -s -g -u "${PS_WS_KEY}:" "http://localhost:8080/api/roast_batches?filter[sku]=[PC-ETH]%&display=[id,sku]&output_format=JSON"
curl -s -g -u "${PS_WS_KEY}:" "http://localhost:8080/api/roast_batches?filter[note]=%[floral]%&display=[id,sku]&output_format=JSON&language=1"