API Reference

This document provides a complete API reference for the Innosend Magento 2 modules.

PHP Interfaces

ClientInterface

The core API client interface for communicating with Innosend.

Namespace: Innosend\Integration\Api\ClientInterface

interface ClientInterface
{
    /**
     * Perform GET request to API
     *
     * @param string $endpoint API endpoint path
     * @param array $params Query parameters
     * @return array Response data
     * @throws \Exception On API error
     */
    public function get(string $endpoint, array $params = []): array;

    /**
     * Perform POST request to API
     *
     * @param string $endpoint API endpoint path
     * @param array $data Request body data
     * @return array Response data
     * @throws \Exception On API error
     */
    public function post(string $endpoint, array $data = []): array;

    /**
     * Perform PUT request to API
     *
     * @param string $endpoint API endpoint path
     * @param array $data Request body data
     * @return array Response data
     * @throws \Exception On API error
     */
    public function put(string $endpoint, array $data = []): array;

    /**
     * Perform DELETE request to API
     *
     * @param string $endpoint API endpoint path
     * @return array Response data
     * @throws \Exception On API error
     */
    public function delete(string $endpoint): array;

    /**
     * Check if API integration is enabled
     *
     * @return bool
     */
    public function isEnabled(): bool;
}

Usage Example

<?php

namespace Your\Module\Service;

use Innosend\Integration\Api\ClientInterface;

class MyService
{
    private ClientInterface $apiClient;

    public function __construct(ClientInterface $apiClient)
    {
        $this->apiClient = $apiClient;
    }

    public function fetchCarriers(): array
    {
        if (!$this->apiClient->isEnabled()) {
            throw new \Exception('Innosend API is not enabled');
        }

        return $this->apiClient->get('carriers');
    }

    public function createShipment(array $data): array
    {
        return $this->apiClient->post('shipments', $data);
    }
}

---

Config

Configuration provider for Innosend settings.

Namespace: Innosend\Integration\Model\Config

class Config
{
    /**
     * Check if API connection is enabled
     */
    public function isEnabled(): bool;

    /**
     * Get current mode (test/live)
     */
    public function getMode(): string;

    /**
     * Get active endpoint URL based on mode
     */
    public function getEndpointUrl(): string;

    /**
     * Get API Token for Bearer authentication (decrypted)
     * Used for all endpoints — no separate API Key/Secret required
     */
    public function getApiToken(): string;

    /**
     * Get request timeout in seconds
     */
    public function getTimeout(): int;

    /**
     * Check if configuration is valid (enabled + token present + endpoint set)
     */
    public function isValid(): bool;

    /**
     * Get organization path prefix (e.g. "organizations/42") or empty string
     */
    public function getOrganizationPath(): string;

    /**
     * Get organization ID (if configured)
     */
    public function getOrganizationId(): ?string;
}

Usage Example

<?php

namespace Your\Module\Service;

use Innosend\Integration\Model\Config;

class ConfigChecker
{
    private Config $config;

    public function __construct(Config $config)
    {
        $this->config = $config;
    }

    public function validateSetup(): array
    {
        $issues = [];

        if (!$this->config->isEnabled()) {
            $issues[] = 'API connection is disabled';
        }

        if (!$this->config->isValid()) {
            $issues[] = 'API Token is missing or invalid';
        }

        if ($this->config->getMode() === 'test') {
            $issues[] = 'Warning: Running in test mode';
        }

        return $issues;
    }
}

---

QuotePickupPointInterface

Data interface for pickup points on quotes (during checkout).

Namespace: Innosend\PickupPoints\Api\Data\QuotePickupPointInterface

interface QuotePickupPointInterface
{
    public function getEntityId(): ?int;
    public function setEntityId(int $entityId): self;

    public function getQuoteId(): int;
    public function setQuoteId(int $quoteId): self;

    public function getPickupPointId(): string;
    public function setPickupPointId(string $pickupPointId): self;

    public function getCarrierCode(): string;
    public function setCarrierCode(string $carrierCode): self;

    public function getName(): string;
    public function setName(string $name): self;

    public function getStreet(): string;
    public function setStreet(string $street): self;

    public function getHouseNumber(): ?string;
    public function setHouseNumber(?string $houseNumber): self;

    public function getPostalCode(): string;
    public function setPostalCode(string $postalCode): self;

    public function getCity(): string;
    public function setCity(string $city): self;

    public function getCountryCode(): string;
    public function setCountryCode(string $countryCode): self;

    public function getLatitude(): ?float;
    public function setLatitude(?float $latitude): self;

    public function getLongitude(): ?float;
    public function setLongitude(?float $longitude): self;

    public function getOpeningHours(): ?string;
    public function setOpeningHours(?string $openingHours): self;

    public function getDistance(): ?float;
    public function setDistance(?float $distance): self;
}

---

OrderPickupPointInterface

Data interface for pickup points on orders (after placement).

Namespace: Innosend\PickupPoints\Api\Data\OrderPickupPointInterface

Same structure as QuotePickupPointInterface but with order_id instead of quote_id.

---

REST API Endpoints

Magento REST API

The module exposes the following REST endpoints:

Save Pickup Point (Authenticated)

POST /rest/V1/innosend/pickup-points

Headers:

Authorization: Bearer {customer_token}
Content-Type: application/json

Request Body:

{
    "cartId": "12345",
    "pickupPoint": {
        "pickup_point_id": "PP123",
        "carrier_code": "postnl",
        "name": "PostNL Pickup Point",
        "street": "Hoofdstraat",
        "house_number": "1",
        "postal_code": "1234AB",
        "city": "Amsterdam",
        "country_code": "NL",
        "latitude": 52.3676,
        "longitude": 4.9041,
        "opening_hours": "{\"monday\":\"09:00-18:00\"}",
        "distance": 0.5
    }
}

Response:

{
    "success": true,
    "message": "Pickup point saved successfully"
}

Save Pickup Point (Guest)

POST /rest/V1/innosend/guest-pickup-points

Headers:

Content-Type: application/json

Request Body:

{
    "cartId": "guest-cart-mask-id",
    "pickupPoint": {
        // Same structure as authenticated endpoint
    }
}

---

Internal AJAX Endpoints

Get Pickup Points

GET /innosend/ajax/getPickupPoints

Parameters:

Parameter	Type	Required	Description
postcode	string	Yes	Postal code to search around
country	string	Yes	Country code (e.g. NL)
carrier	string	No	Filter by carrier code

Response:

{
    "success": true,
    "data": [
        {
            "id": "PP123",
            "carrier": "postnl",
            "name": "PostNL Servicepoint",
            "street": "Hoofdstraat",
            "house_number": "1",
            "postal_code": "1234AB",
            "city": "Amsterdam",
            "country": "NL",
            "latitude": 52.3676,
            "longitude": 4.9041,
            "distance": 0.5,
            "opening_hours": {
                "monday": "09:00-18:00",
                "tuesday": "09:00-18:00"
            }
        }
    ]
}

Save Pickup Point

POST /innosend/ajax/savePickupPoint

Request Body:

{
    "pickup_point": {
        "id": "PP123",
        "carrier": "postnl",
        "name": "PostNL Servicepoint",
        // ... full pickup point data
    }
}

Response:

{
    "success": true,
    "message": "Pickup point saved"
}

Health Check

GET /innosend/api/ping

Response (Success):

{
    "status": "success",
    "message": "API connection successful"
}

Response (Error):

{
    "status": "error",
    "message": "API connection failed: Invalid credentials"
}

---

JavaScript Components

pickup-points Component

The main Knockout.js component for pickup point selection.

Location: view/frontend/web/js/pickup-points.js

define([
    'uiComponent',
    'ko',
    'jquery',
    'mage/storage',
    'Magento_Checkout/js/model/quote',
    'Magento_Checkout/js/model/shipping-service'
], function (Component, ko, $, storage, quote, shippingService) {
    'use strict';

    return Component.extend({
        defaults: {
            template: 'Innosend_PickupPoints/pickup-points/wrapper',
            pickupPoints: ko.observableArray([]),
            selectedPickupPoint: ko.observable(null),
            isLoading: ko.observable(false),
            isModalOpen: ko.observable(false),
            searchQuery: ko.observable(''),
            selectedCarrier: ko.observable(null)
        },

        /**
         * Initialize component
         */
        initialize: function () {
            this._super();

            // Subscribe to address changes
            quote.shippingAddress.subscribe(this.onAddressChange.bind(this));

            return this;
        },

        /**
         * Load pickup points from API
         * @param {string} postcode
         * @param {string} country
         */
        loadPickupPoints: function (postcode, country) {
            // Implementation
        },

        /**
         * Select a pickup point
         * @param {Object} pickupPoint
         */
        selectPickupPoint: function (pickupPoint) {
            // Implementation
        },

        /**
         * Open pickup point selection modal
         */
        openModal: function () {
            // Implementation
        },

        /**
         * Close pickup point selection modal
         */
        closeModal: function () {
            // Implementation
        },

        /**
         * Filter pickup points by carrier
         * @param {string} carrier
         */
        filterByCarrier: function (carrier) {
            // Implementation
        }
    });
});

pickup-points-map Component

Map integration component using Leaflet.js or Google Maps.

Location: view/frontend/web/js/pickup-points-map.js

define([
    'jquery',
    'leaflet'
], function ($, L) {
    'use strict';

    return {
        map: null,
        markers: [],

        /**
         * Initialize the map
         * @param {string} containerId
         * @param {Object} options
         */
        init: function (containerId, options) {
            this.map = L.map(containerId).setView(
                [options.lat || 52.1326, options.lng || 5.2913],
                options.zoom || 8
            );

            L.tileLayer('https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png', {
                attribution: '© OpenStreetMap contributors'
            }).addTo(this.map);
        },

        /**
         * Add pickup point markers to map
         * @param {Array} pickupPoints
         */
        addMarkers: function (pickupPoints) {
            // Clear existing markers
            this.clearMarkers();

            pickupPoints.forEach(function (point) {
                var marker = L.marker([point.latitude, point.longitude])
                    .addTo(this.map)
                    .bindPopup(this.createPopup(point));

                this.markers.push(marker);
            }, this);

            // Fit bounds to show all markers
            if (this.markers.length > 0) {
                var group = L.featureGroup(this.markers);
                this.map.fitBounds(group.getBounds().pad(0.1));
            }
        },

        /**
         * Clear all markers from map
         */
        clearMarkers: function () {
            this.markers.forEach(function (marker) {
                this.map.removeLayer(marker);
            }, this);
            this.markers = [];
        },

        /**
         * Create popup content for marker
         * @param {Object} pickupPoint
         * @returns {string}
         */
        createPopup: function (pickupPoint) {
            return '<div class="pickup-point-popup">' +
                '<strong>' + pickupPoint.name + '</strong><br>' +
                pickupPoint.street + ' ' + pickupPoint.house_number + '<br>' +
                pickupPoint.postal_code + ' ' + pickupPoint.city +
                '</div>';
        }
    };
});

---

Events

PHP Events

Event Name	Dispatched When	Available Data
sales_order_place_after	Order is placed	order
checkout_submit_before	Before quote becomes order	quote

JavaScript Events

Event Name	Triggered When	Data
innosend:pickuppoint:selected	Pickup point selected	{ pickupPoint: {...} }
innosend:pickuppoints:loaded	Points loaded from API	{ points: [...] }
innosend:modal:open	Modal opens	{}
innosend:modal:close	Modal closes	{}

Listening to Events

require(['jquery'], function ($) {
    $(document).on('innosend:pickuppoint:selected', function (event, data) {
        console.log('Selected pickup point:', data.pickupPoint);
    });
});

---

Dependency Injection

Registering Custom Implementation

To replace the default API client:

<!-- etc/di.xml -->
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">

    <preference for="Innosend\Integration\Api\ClientInterface"
                type="Your\Module\Model\Api\CustomClient"/>
</config>

Injecting Dependencies

<?php

namespace Your\Module\Model;

use Innosend\Integration\Api\ClientInterface;
use Innosend\Integration\Model\Config;
use Psr\Log\LoggerInterface;

class MyCustomService
{
    private ClientInterface $apiClient;
    private Config $config;
    private LoggerInterface $logger;

    public function __construct(
        ClientInterface $apiClient,
        Config $config,
        LoggerInterface $logger
    ) {
        $this->apiClient = $apiClient;
        $this->config = $config;
        $this->logger = $logger;
    }

    public function execute(): void
    {
        // Your implementation
    }
}

---

Error Codes

Code	Description	Resolution
INNOSEND_001	API connection failed	Check credentials and endpoint
INNOSEND_002	Invalid API response	Check API status
INNOSEND_003	Pickup point not found	Verify pickup point ID
INNOSEND_004	Order sync failed	Check order data validity
INNOSEND_005	Rate limit exceeded	Reduce request frequency