ITBees.Prestashop 8.0.2

ITBees.Prestashop

PrestaShop 8.x Webservice API integration for FAS applications, in the same shape as ITBees.DeepL and ITBees.DzielnikIntegration: the shop address and the webservice key are edited by the platform operator in the admin panel and stored in the host database; the library provides the client, typed models of the shop resources, order / stock services, the settings endpoints and a connection test.

It talks to the classic webservice (https://shop/api/..., PrestaShop admin -> Zaawansowane -> API), which is enabled in PrestaShop 8 out of the box - no module has to be installed in the shop. The new OAuth "Admin API" is experimental in 8.x and is not used.

What is inside:

Element Purpose
Entities/PrestashopIntegrationSettings One row in the host database: Enabled, ShopUrl, ApiKey, ShopId (multistore), Modified, ModifiedByGuid
GET/PUT /PrestashopIntegrationSettings Settings for the admin panel (PlatformOperator only)
POST /PrestashopConnectionTest "Testuj połączenie": GET /api with the key from the form (or the saved one) - shop name, PrestaShop version, resources the key may read / write. Changes nothing in the shop
IPrestashopWebservice Generic Get / GetAll / Create / Update / Patch / Delete of every resource model with the saved settings
IPrestashopApiClient The same with an explicit PrestashopConnection per call (a shop that is not configured in the panel, tools, tests)
IPrestashopOrderStatusService Order status change through order_histories, optionally with the status e-mail
IPrestashopOrderTrackingNumberService Tracking number on the order's carrier (order_carriers)
IPrestashopStockService Read / set the available quantity of a product or a combination (stock_availables)
Resources/* Models of the shop resources (below)

Resource models

Model Webservice resource
PrestashopOrder (+ Associations.OrderRows) orders order, totals, status, addresses, lines
PrestashopOrderDetail order_details every detail of an order line
PrestashopOrderState order_states statuses (name per language, paid / shipped / delivery flags)
PrestashopOrderHistory order_histories status history; creating one changes the status
PrestashopOrderCarrier order_carriers carrier, shipping cost, weight, tracking number
PrestashopOrderPayment order_payments payments (linked by the order reference)
PrestashopCustomer customers customer accounts and guests
PrestashopAddress addresses delivery / invoice addresses
PrestashopCarrier carriers carriers (match by ReferenceId, the id changes on every edit)
PrestashopProduct (+ associations) products product, prices, texts per language, categories, images, combinations, stock rows
PrestashopCombination combinations variants (price / weight impacts, references, attribute values)
PrestashopStockAvailable stock_availables quantity per product / combination / shop
PrestashopCategory categories catalog tree
PrestashopManufacturer manufacturers brands
PrestashopProductOption / PrestashopProductOptionValue product_options / product_option_values attribute groups and values used by combinations
PrestashopSpecificPrice specific_prices promotions and customer / group / quantity prices
PrestashopLanguage, PrestashopCurrency, PrestashopCountry, PrestashopShop languages, currencies, countries, shops dictionaries

The fields and their names follow PrestaShop 8.2 ($definition and $webserviceParameters of the classes). Conventions of the models:

  • Every field except Id is nullable, and only non-null fields are sent on create / update.
  • Fields PrestaShop refuses on writes (a product's quantity and manufacturer_name, a category's level_depth ...), ignores (order lines, a product's stock rows) or re-applies on every write (a product's position_in_category) are marked [PrestashopReadOnly] and never sent.
  • Multilingual fields are PrestashopTranslations: product.Name.Get(languageId), new PrestashopTranslations().Set(1, "Karton").Set(2, "Karton"). Language ids come from languages.
  • Associations: a null list is left as it is in the shop, a list replaces the association (an empty list clears it; a product's combinations list deletes the combinations it does not contain).
  • Your own resource (e.g. one added by a module) is a class derived from PrestashopResource with [PrestashopResource("resources", "resource")] and [JsonPropertyName] on its fields.

PUT and PATCH

  • UpdateAsync is a PUT, and in PrestaShop a PUT replaces the whole resource: every field that is not sent is cleared (0, empty text, an empty date, empty text in every language, date_add reset to now) and a missing required field fails with 400. Use it only on a model read with GetAsync and changed; never PUT orders.
  • PatchAsync changes only the fields you pass and is the right call for almost every change. The key needs the PATCH permission, which the shop lists separately from PUT (keys made before PrestaShop 8 do not have it).
  • Reads ask for display=full, so a single resource comes back with every field - without it PrestaShop's JSON leaves out the fields whose value is "0" or empty, and a PUT of such a model would clear them.

Host registration

// DependencyRegistration
new PrestashopIntegrationSetup().Register(builder.Services);

// DbContext.OnModelCreating
ITBees.Prestashop.Setup.DbModelBuilder.Register(modelBuilder);

Then add a migration (dotnet ef migrations add AddPrestashopIntegration) - one table, PrestashopIntegrationSettings. The host must provide the generic ITBees repositories (IReadOnlyRepository<> / IWriteOnlyRepository<>, e.g. ITBees.MysqlRepository) and IHttpClientFactory (AddHttpClient is called by the setup). The controllers are discovered automatically by ASP.NET once the package is referenced.

Shop side

In the shop: Zaawansowane -> API -> "Dodaj nowy klucz API". Generate a key, give it only the resources and methods the integration needs (e.g. GET on orders, order_states, products, combinations, stock_availables, customers, addresses, order_carriers; POST on order_histories; PATCH on stock_availables and order_carriers) and, in multistore, assign it to the shops it serves. Use a separate key per integration so it can be switched off on its own. "Testuj połączenie" lists what the key may do.

Multistore: id_shop (settings or PrestashopQuery.InShop) selects the shop for stock rows and writes, but some per-shop values may still follow the shop of the domain the request goes to - for per-shop data, prefer the shop's own address as ShopUrl (not checked against a live multistore yet).

Usage

public class OrderImport
{
    private readonly IPrestashopWebservice _prestashopWebservice;
    private readonly IPrestashopOrderStatusService _prestashopOrderStatusService;

    public OrderImport(IPrestashopWebservice prestashopWebservice,
        IPrestashopOrderStatusService prestashopOrderStatusService)
    {
        _prestashopWebservice = prestashopWebservice;
        _prestashopOrderStatusService = prestashopOrderStatusService;
    }

    public async Task ImportAsync(DateTime lastSync, CancellationToken ct)
    {
        // Orders changed since the last run, 100 per call.
        for (var offset = 0; ; offset += 100)
        {
            var orders = await _prestashopWebservice.GetAllAsync<PrestashopOrder>(new PrestashopQuery()
                .FilterSince("date_upd", lastSync)
                .SortBy("id")
                .Page(offset, 100), ct);

            foreach (var order in orders)
            {
                // order.Reference, order.TotalPaidTaxIncl, order.Associations.OrderRows ...
            }

            if (orders.Count < 100) break;
        }

        // Status "Wysłane" (id from order_states) with the e-mail to the customer; null when the order already
        // has it (PrestaShop would otherwise add a duplicate history entry and repeat the side effects).
        await _prestashopOrderStatusService.UpdateAsync(orderId: 15, orderStateId: 4, sendEmail: true, ct);
    }
}

More:

// One product with its texts per language
var product = await _prestashopWebservice.GetAsync<PrestashopProduct>(5);
var polishName = product.Name?.Get(1);

// Only some fields of a list
var references = await _prestashopWebservice.GetAllAsync<PrestashopProduct>(
    new PrestashopQuery().Fields("id", "reference", "price").FilterEquals("active", 1));

// Change chosen fields of a product (PATCH)
await _prestashopWebservice.PatchAsync<PrestashopProduct>(5,
    new Dictionary<string, object?> { ["price"] = 12.5m, ["active"] = true });

// Stock of a combination in shop 2 (the product row becomes the sum of its combinations)
await _prestashopStockService.UpdateAsync(productId: 5, combinationId: 19, quantity: 40, shopId: 2);

// Tracking number of a parcel, with the "in transit" e-mail
await _prestashopOrderTrackingNumberService.UpdateAsync(orderId: 15, trackingNumber: "620000001", sendEmail: true);

// Cover image of a product (original file)
var image = await _prestashopWebservice.GetProductImageAsync(productId: 5, imageId: product.DefaultImageId!.Value);

Stock is only in stock_availables: a product's quantity is a legacy column PrestaShop does not keep in sync. A stock row managed by warehouses (depends_on_stock) cannot be set and gives depends_on_stock. A stock change through the webservice records no stock movement.

PrestashopQuery covers the webservice parameters: Fields (display), FilterEquals, FilterAnyOf, FilterBetween, FilterSince (dates add date=1 themselves), FilterContains, FilterStartsWith, SortBy, Page (limit), InShop / ShopId (multistore id_shop, otherwise the one from the settings), LanguageId (multilingual fields in one language) and WithParameter for anything else. Filtering or sorting by date_add / date_upd adds date=1 itself. Without Fields everything is read (display=full); page big resources and sort by id for stable pages - the webservice does not report a total count.

Calls throw PrestashopApiException with an ErrorCode: integration_disabled (switched off or incomplete), invalid_shop_url, unauthorized (401 - wrong key or no access to the resource), forbidden (403 - key not assigned to the shop), not_found, method_not_allowed (405 - the key may not use the method, e.g. PATCH not ticked, or the resource does not support it), bad_request (400 - missing required field, read-only field, validation), server_error (5xx - save failed, an error in a shop module), webservice_disabled (503), redirect (the shop redirects - save the address it redirects to), connection_failed, timeout, unexpected_response (e.g. an HTML page instead of the webservice), depends_on_stock. Messages are in Polish and can be shown to the operator as they are; PrestaShop's own error text is appended.

Wire format

Reads use output_format=JSON. PrestaShop sends nearly every value as a string ("61.800000", "1", "0000-00-00 00:00:00" for no date, "" for a missing number), a multilingual field as a list of {"id","value"} (or a plain string when one language is in scope) and an empty list as []; the models read all of that into decimal?, bool?, DateTime?, int? and PrestashopTranslations. Writes go as XML - JSON input is not supported by PrestaShop 8 - generated from the same field names. The connection test reads GET /api as XML, because the JSON variant of that call fails on PHP 8. The behaviour above was checked in the PrestaShop 8.2.0 sources; the tests use answers built from them, not recorded from a live shop. The key goes in the Basic auth header (never in the URL), only https shop addresses are called (plain http only on the loopback interface for a local docker shop), redirects are not followed, and the host can restrict the shops with PrestashopApiOptions.AllowedShopUrls.

Trying it against a shop

PrestashopTestConsoleApp only reads - nothing is created or changed:

$env:PRESTASHOP_SHOP_URL = "https://cartonhub.nl"
$env:PRESTASHOP_API_KEY = "<read-only key>"
$env:PRESTASHOP_SHOP_ID = "1"   # optional, multistore
dotnet run --project PrestashopTestConsoleApp -- info
dotnet run --project PrestashopTestConsoleApp -- orders 5
dotnet run --project PrestashopTestConsoleApp -- product 123

Releasing

The package metadata is in ITBees.Prestashop/ITBees.Prestashop.csproj (GeneratePackageOnBuild). Like the other ITBees libraries it is meant to be published to the ITBees feed (https://nugets.itbees.pl/v3/index.json) by the CI build, which assigns the version itself - <Version> only matters for a local dotnet pack.

No packages depend on ITBees.Prestashop.

Version Downloads Last updated
8.0.2 10 10/15/2026