@pinelab/vendure-plugin-qls-fulfillment 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -1,3 +1,7 @@
+# 3.3.0 (2026-09-24)
+
+- Handle the `shipment.barcode` webhook and store the QLS tracking code and tracking URL on the order's custom fields.
+
 # 3.2.0 (2026-08-12)
 
 - Restore the legacy Angular Admin UI extension alongside the React Dashboard.

package/README.md

@@ -34,6 +34,7 @@ The mutation returns the list of all existing EANs for the product in QLS after
 - Pushes orders to QLS automatically on order placement
 - Supports manual order push to QLS via Admin UI
 - Updates order status in Vendure based on QLS webhooks
+- Stores tracking codes and tracking URLs from incoming `shipment.barcode` webhooks on the order's (private) `qlsTrackingCodes` and `qlsTrackingUrls` custom fields. An order can have multiple shipments/parcels, so codes and URLs are accumulated in these lists.
 
 ## Getting started
 
@@ -93,6 +94,7 @@ You should set up webhooks for the following events:
 - `fulfillment_product.stock`
 - `fulfillment_order.status`
 - `fulfillment_order.completed`
+- `shipment.barcode`
 
 The URL for all these events should be `https://<YOUR_VENDURE_HOST>/qls/webhook/<CHANNEL_TOKEN>?secret=<PLUGIN_SECRET>`. E.g. `https://example.com/qls/webhook/your-channel-token?secret=121231`.
 

package/dist/api/qls-webhooks-controller.d.ts

@@ -3,7 +3,7 @@ import { Request } from 'express';
 import { QlsProductService } from '../services/qls-product.service';
 import { QlsPluginOptions } from '../types';
 import { QlsOrderService } from '../services/qls-order.service';
-import { IncomingOrderWebhook, IncomingStockWebhook } from '../lib/client-types';
+import { IncomingOrderWebhook, IncomingShipmentWebhook, IncomingStockWebhook } from '../lib/client-types';
 export declare class QlsWebhooksController {
     private channelService;
     private qlsProductService;
@@ -13,6 +13,6 @@ export declare class QlsWebhooksController {
     /**
      * Endpoint for all incoming webhooks
      */
-    events(channelToken: string, webhookSecret: string, request: Request, body: IncomingStockWebhook | IncomingOrderWebhook): Promise<void>;
+    events(channelToken: string, webhookSecret: string, request: Request, body: IncomingStockWebhook | IncomingOrderWebhook | IncomingShipmentWebhook): Promise<void>;
     private getCtxForChannel;
 }

package/dist/api/qls-webhooks-controller.js

@@ -42,6 +42,9 @@ let QlsWebhooksController = class QlsWebhooksController {
             if (isStockWebhook(body)) {
                 await this.qlsProductService.handleStockWebhook(ctx, body);
             }
+            else if (isShipmentWebhook(body)) {
+                await this.qlsOrderService.handleShipmentBarcodeWebhook(ctx, body);
+            }
             else if (isOrderWebhook(body)) {
                 await this.qlsOrderService.handleOrderStatusUpdate(ctx, body);
             }
@@ -92,3 +95,6 @@ function isStockWebhook(body) {
 function isOrderWebhook(body) {
     return 'customer_reference' in body && 'status' in body;
 }
+function isShipmentWebhook(body) {
+    return 'carrier_id' in body && 'reference' in body;
+}

package/dist/custom-fields.d.ts

@@ -7,6 +7,8 @@ declare module '@vendure/core' {
     interface CustomOrderFields {
         qlsServicePointId?: string;
         qlsServicePointDetails?: string;
+        qlsTrackingCodes?: string[];
+        qlsTrackingUrls?: string[];
     }
 }
 /** Returns variant custom fields with the given Admin UI tab name. */

package/dist/custom-fields.js

@@ -44,4 +44,36 @@ exports.orderCustomFields = [
         readonly: false,
         ui: { tab: 'QLS' },
     },
+    {
+        name: 'qlsTrackingCodes',
+        type: 'string',
+        list: true,
+        label: [{ value: 'QLS Tracking Codes', languageCode: core_1.LanguageCode.en }],
+        description: [
+            {
+                value: 'Barcodes/tracking codes of all shipments/parcels created for this order in QLS.',
+                languageCode: core_1.LanguageCode.en,
+            },
+        ],
+        nullable: true,
+        public: false,
+        readonly: true,
+        ui: { tab: 'QLS' },
+    },
+    {
+        name: 'qlsTrackingUrls',
+        type: 'string',
+        list: true,
+        label: [{ value: 'QLS Tracking URLs', languageCode: core_1.LanguageCode.en }],
+        description: [
+            {
+                value: 'Tracking URLs of all shipments/parcels created for this order in QLS.',
+                languageCode: core_1.LanguageCode.en,
+            },
+        ],
+        nullable: true,
+        public: false,
+        readonly: true,
+        ui: { tab: 'QLS' },
+    },
 ];

package/dist/lib/client-types.d.ts

@@ -165,6 +165,26 @@ export interface FulfillmentOrder {
 }
 export type IncomingStockWebhook = FulfillmentProductDetail;
 export type IncomingOrderWebhook = Pick<FulfillmentOrder, 'customer_reference' | 'status' | 'cancelled' | 'amount_delivered' | 'amount_total'>;
+/**
+ * Incoming `shipment.barcode` webhook payload from QLS.
+ * `reference` matches the Vendure order code.
+ * Note: `barcode`/`tracking_url` on the root object are sometimes not yet populated,
+ * so we also fall back to the nested shipment with the same `id` under `deliveries[].shipments[]`.
+ */
+export interface IncomingShipmentWebhook {
+    id: string;
+    reference: string;
+    carrier_id: string;
+    barcode: string | null;
+    tracking_url: string | null;
+    deliveries?: Array<{
+        shipments?: Array<{
+            id: string;
+            barcode: string | null;
+            tracking_url: string | null;
+        }>;
+    }>;
+}
 /**
  * This is the full data returend by the QLS API when fetching a fulfillment product by ID
  * Getting via list, sku or filtering does NOT return this full object

package/dist/services/qls-order.service.d.ts

@@ -2,7 +2,7 @@ import { OnApplicationBootstrap, OnModuleInit } from '@nestjs/common';
 import { ModuleRef } from '@nestjs/core';
 import { EventBus, ID, Job, JobQueueService, OrderService, RequestContext, TransactionalConnection } from '@vendure/core';
 import { QlsServicePoint, QlsServicePointSearchInput } from '../api/generated/graphql';
-import { IncomingOrderWebhook } from '../lib/client-types';
+import { IncomingOrderWebhook, IncomingShipmentWebhook } from '../lib/client-types';
 import { QlsOrderJobData, QlsPluginOptions } from '../types';
 export declare class QlsOrderService implements OnModuleInit, OnApplicationBootstrap {
     private options;
@@ -31,6 +31,17 @@ export declare class QlsOrderService implements OnModuleInit, OnApplicationBoots
      * Update the status of an order in QLS based on the given order code and status
      */
     handleOrderStatusUpdate(ctx: RequestContext, body: IncomingOrderWebhook): Promise<void>;
+    /**
+     * Store the tracking code and tracking URL from an incoming `shipment.barcode` webhook
+     * on the order's custom fields. Codes/URLs are accumulated, because an order can have
+     * multiple shipments/parcels.
+     */
+    handleShipmentBarcodeWebhook(ctx: RequestContext, body: IncomingShipmentWebhook): Promise<void>;
+    /**
+     * The root `barcode`/`tracking_url` fields on the webhook payload are sometimes not yet
+     * populated, so fall back to the nested shipment with the same id under `deliveries[].shipments[]`.
+     */
+    private getShipmentTrackingInfo;
     triggerPushOrder(ctx: RequestContext, orderId: ID, orderCode?: string): Promise<Job<QlsOrderJobData> | undefined>;
     /**
      * Get QLS order id(s) for a Vendure order (for Order.qlsOrderIds field).

package/dist/services/qls-order.service.js

@@ -260,6 +260,54 @@ let QlsOrderService = class QlsOrderService {
         await this.orderService.transitionToState(ctx, order.id, vendureOrderState);
         core_2.Logger.info(`Successfully updated order '${orderCode}' to '${vendureOrderState}'`, constants_1.loggerCtx);
     }
+    /**
+     * Store the tracking code and tracking URL from an incoming `shipment.barcode` webhook
+     * on the order's custom fields. Codes/URLs are accumulated, because an order can have
+     * multiple shipments/parcels.
+     */
+    async handleShipmentBarcodeWebhook(ctx, body) {
+        const orderCode = body.reference;
+        const { barcode, trackingUrl } = this.getShipmentTrackingInfo(body);
+        if (!barcode) {
+            core_2.Logger.info(`Ignoring shipment.barcode webhook for order '${orderCode}', because no barcode was found in the payload`, constants_1.loggerCtx);
+            return;
+        }
+        const order = await this.orderService.findOneByCode(ctx, orderCode, []);
+        if (!order) {
+            return core_2.Logger.warn(`Order with code '${orderCode}' not found, ignoring shipment.barcode webhook`, constants_1.loggerCtx);
+        }
+        const existingCodes = order.customFields.qlsTrackingCodes ?? [];
+        if (existingCodes.includes(barcode)) {
+            core_2.Logger.info(`Tracking code '${barcode}' already stored for order '${orderCode}', ignoring duplicate shipment.barcode webhook`, constants_1.loggerCtx);
+            return;
+        }
+        const existingUrls = order.customFields.qlsTrackingUrls ?? [];
+        await this.connection.getRepository(ctx, core_2.Order).update({ id: order.id }, {
+            customFields: {
+                qlsTrackingCodes: [...existingCodes, barcode],
+                qlsTrackingUrls: trackingUrl
+                    ? [...existingUrls, trackingUrl]
+                    : existingUrls,
+            },
+        });
+        core_2.Logger.info(`Stored tracking code '${barcode}' for order '${orderCode}'`, constants_1.loggerCtx);
+    }
+    /**
+     * The root `barcode`/`tracking_url` fields on the webhook payload are sometimes not yet
+     * populated, so fall back to the nested shipment with the same id under `deliveries[].shipments[]`.
+     */
+    getShipmentTrackingInfo(body) {
+        if (body.barcode) {
+            return { barcode: body.barcode, trackingUrl: body.tracking_url };
+        }
+        const nestedShipment = body.deliveries
+            ?.flatMap((delivery) => delivery.shipments ?? [])
+            .find((shipment) => shipment.id === body.id);
+        return {
+            barcode: nestedShipment?.barcode ?? null,
+            trackingUrl: nestedShipment?.tracking_url ?? null,
+        };
+    }
     async triggerPushOrder(ctx, orderId, orderCode) {
         const client = await (0, qls_client_1.getQlsClient)(ctx, this.options);
         if (!client) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pinelab/vendure-plugin-qls-fulfillment",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Vendure plugin to fulfill orders via QLS.",
   "keywords": [
     "fulfillment",