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
Idis nullable, and only non-null fields are sent on create / update. - Fields PrestaShop refuses on writes (a product's
quantityandmanufacturer_name, a category'slevel_depth...), ignores (order lines, a product's stock rows) or re-applies on every write (a product'sposition_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 fromlanguages. - 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
combinationslist deletes the combinations it does not contain). - Your own resource (e.g. one added by a module) is a class derived from
PrestashopResourcewith[PrestashopResource("resources", "resource")]and[JsonPropertyName]on its fields.
PUT and PATCH
UpdateAsyncis 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_addreset to now) and a missing required field fails with 400. Use it only on a model read withGetAsyncand changed; never PUT orders.PatchAsyncchanges 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.
.NET 8.0
- ITBees.Interfaces (>= 8.0.72)
- ITBees.RestfulApiControllers (>= 8.0.31)
- Microsoft.EntityFrameworkCore (>= 8.0.10)
- Microsoft.Extensions.DependencyInjection (>= 8.0.1)
- Microsoft.Extensions.Http (>= 8.0.0)
| Version | Downloads | Last updated |
|---|---|---|
| 8.0.2 | 10 | 10/15/2026 |