myparcelnl/sdk

MyParcel PHP SDK

Requirements

• PHP >=7.4
• Composer

composer require myparcelnl/sdk

Quick start

Most v11 services take an API key in the constructor and wrap the generated API client. MyParcel Connect is the exception, see MyParcel Connect.

use MyParcelNL\Sdk\Collection\ShipmentCollection;
use MyParcelNL\Sdk\Model\Shipment\Shipment;
use MyParcelNL\Sdk\Services\Shipment\ShipmentCreateService;

// Build a shipment
$shipment = (new Shipment())
    ->setRecipient([
        'cc'          => 'NL',
        'street'      => 'Antareslaan',
        'number'      => 31,
        'person'      => 'John Doe',
        'city'        => 'Hoofddorp',
        'postal_code' => '2132 JE',
    ])
    ->setCarrier(1)
    ->withPackageType('PACKAGE');

// Create it
$service = new ShipmentCreateService('your-api-key');
$mapping = $service->create((new ShipmentCollection())->push($shipment));
// $mapping = [shipmentId => referenceIdentifier, ...]

Services

See UPGRADE.md for detailed before/after examples per service.

MyParcel Connect

ConnectService authorises a shop in the merchant's browser instead of taking an API key. It is for integrations you publish and other people install, rather than a single shop you run yourself. EcommerceApiFactory then builds an e-commerce client that signs every call, which is how orders are pushed.

Connect covers one call for now, POST /webhook/orders. Every other service in this SDK still takes an API key.

See PHP SDK v11 on the developer portal for how to use it. dev/connect-poc in this repository is a page that runs the whole flow.

Value mapping

Use ApiMapperService to convert between delivery-options names, v1 IDs and v2 names.

use MyParcelNL\Sdk\Services\Mapping\ApiMapperService;

$mapper = ApiMapperService::forCarrier();

$mapper->idFromLegacyName('dhlforyou'); // 9
$mapper->v2NameFromId(9);              // 'DHL_FOR_YOU'
$mapper->legacyNameFromV2Name('DPD');  // 'dpd'

Use forDeliveryType() or forPackageType() for the other categories. Conversion methods return null if no mapping exists. Use allRows() for one category or allDomains() for all three.

Shipment option names are handled by Services\Mapping\ShipmentOptionMapper. Its v2PropertyFromName() method returns the generated capabilities v2 model property, or null. For example, signature and requiresSignature both map to requires_signature.

Unsupported capabilities options

Capabilities requests omit unknown or unsupported option names. Check the request before sending it so your application can report these options or change the request.

use MyParcelNL\Sdk\Model\Capabilities\CapabilitiesRequest;

$request = CapabilitiesRequest::forCountry('NL')
    ->withOptions(['signature' => null, 'tracked' => null]);

$request->getUnsupportedOptions(); // ['tracked']

This check validates option names accepted by the request model. It does not validate option values or determine which options a carrier offers.

Legacy services

The following are still available but will be replaced in a future release:

• Web services (@internal): AccountWebService, CarrierOptionsWebService, PrinterGroupWebService
• Order v1 fulfilment: OrderCollection (@internal), OrderNotesCollection (@internal), Order, OrderLine, OrderNote, Product
• Carrier models, shared models, helpers (@internal) — see UPGRADE.md for the full list

Use CarrierContractDefinitionsService for new account-level carrier contract definition lookups instead of CarrierOptionsWebService.

Testing

# Run all tests
./vendor/bin/phpunit

# Run without live API tests
./vendor/bin/phpunit --exclude-group=live

Tests use two mocking strategies:

• Legacy web services: Mockery via $this->mockCurl() in TestCase
• v11 service wrappers: Constructor injection of a mock API instance

Existing tests serve as examples for both patterns.

Support

For questions and support please contact us via support@myparcel.nl or chat with our developers directly on Slack.

Contribute

1. Check for open issues or open a new issue to start a discussion
2. Fork the repository and branch off from main
3. Write tests for the new feature or bug fix
4. Ensure all tests pass: ./vendor/bin/phpunit
5. Submit a pull request