dan-rogers/shiptheory-php

An API client to communicate with the Shiptheory API

v2.2.1 2023-01-26 16:16 UTC

This package is auto-updated.

Last update: 2024-02-07 15:19:28 UTC


README

A Python version exists: Shiptheory API library for Python

  • To create pull requests fork this repository (Please adhere to the guidelines in the pull request template).
  • Use GitHub issues to detail any problems encountered.

Features

  • Build Shiptheory request bodies and queries with ease.
  • Dedicated methods to query each Shiptheory endpoint.
  • Automatic token authentication. Just provide your credentials and the library will keep your tokens valid for as long as you need.
  • Standardised error messaging.
  • Configuration via .env

Installation

Require with composer:

composer require dan-rogers/shiptheory-php

Configuration

The library currently utilises a .env file to configure certain aspects of the library.

IMPORTANT: It does not use any version of phpdotenv and instead uses its own custom implementation to keep it lightweight.

Copy values from .env.example into a new or existing .env file in the root of your project.

Currently supported configuration options:

  • SHIPTHEORY_PHP_LOG_REQUESTS - (Boolean) When set to true requests are logged. When false or nonexistent requests are not logged.
  • SHIPTHEORY_PHP_SSL_VERIFY_PEER - (Boolean) When set to true SSL verification is enabled. When false or nonexistent requests do not use SSL verification.
  • SHIPTHEORY_PHP_LOG_PATH - (String) When a string is set it is used as the path to the folder where log files are generated.

Using a Shiptheory Partner Tag

"If you are developing an application that will be used by more than 1 company, or an application that you intend to distribute in anyway, you must include the Shiptheory-Partner-Tag http request header in all of your requests. Please contact Shiptheory support to obtain a partner tag. There is no charge for this, tags are used to provide better support to customers and partners." - API Docs

In order to add a partner tag to your API requests add it as the third argument when instantiating a new ShiptheoryClient.

$client = new ShiptheoryClient('test@test.com', 'Password123!', 'my_partner_tag');

Usage

The workflow is similar for all endpoints, queries and bookings. Examples exist in the file Examples. If you want to see all endpoint methods, then look in src/Http/ShiptheoryClient.php.

It is recommended that you use the objects provied to build your requests as they will result with a perfect request body every time. However, if you wish you can just provide the query parameters or the JSON body (depending on request type) as a string to the method you are calling.

Example of viewing a shipment

$client = new ShiptheoryClient('test@test.com', 'Password123!');
$result = $client->viewShipment('Test1234')

Example of listing shipments

$client = new ShiptheoryClient('test@test.com', 'Password123!');
$list_fields = [
    'channel_name' => 'Api',
    'status' => 'Ignored',
    'limit' => 1
];
$list_query = new ListShipmentQuery($list_fields);
$params = $list_query->toQueryParams();
$client->listShipment($params);

Example of searching for shipments

$client = new ShiptheoryClient('test@test.com', 'Password123!');
$search_fields = [
    'created_from' => '2022-04-01',
    'created_to' => '2022-04-30',
    'include_products' => 1,
];
$search_query = new SearchShipmentQuery($search_fields);
$params = $search_query->toQueryParams();
$client->searchShipment($params);

Example of booking a shipment

$client = new ShiptheoryClient('test@test.com', 'Password123!');
//Start new shipment data object
$shipment = new Shipment();
$shipment->setReference('Test1234');
$shipment->setReference2('Test5678');

// Set Shipment Details
$shipment_detail = new ShipmentDetail();
$shipment_detail->setWeight(1);
$shipment_detail->setParcels(1);
$shipment_detail->setValue(1);
$shipment_detail->setShippingPrice(2.99);
$shipment_detail->setReference3('ORDERREF3');
$shipment_detail->setSalesSource('My Store');
$shipment_detail->setShipDate('2022-04-30');
$shipment_detail->setCurrencyCode('GBP');

// Set Recipient
$reciever = new Recipient();
$reciever->setCompany('Shiptheory');
$reciever->setFirstname('Test');
$reciever->setLastname('Customer');
$reciever->setAddressLine1('Unit 4.1 Paintworks');
$reciever->setAddressLine2('Bath Road');
$reciever->setCity('Bristol');
$reciever->setCountry('GB');
$reciever->setPostcode('BS4 3EH');
$reciever->setEmail('recipient@test.com');
$reciever->setTelephone('01234567890');
$reciever->setWhat3Words('///what.three.words');
$eori = new TaxNumber('GB205672212000', AddressTaxNumberTypes::EORI);
$vat = new TaxNumber('GB123456789', AddressTaxNumberTypes::VAT);
$reciever->setTaxNumbers([$eori, $vat]);

// Set sender
$sender = new Sender();
$sender->setCompany('Shiptheory');
$sender->setFirstname('Test');
$sender->setLastname('Shipper');
$sender->setAddressLine1('Bristol Old Vic');
$sender->setAddressLine2('King Street');
$sender->setCity('Bristol');
$sender->setCountry('GB');
$sender->setPostcode('BS1 4ED');
$sender->setEmail('sender@test.com');
$sender->setTelephone('01234567890');

// Set Product
$product = new Product();
$product->setName('My Test Product');
$product->setSku('TestProd1');
$product->setQty(1);
$product->setValue(1);
$product->setWeight(1);
$product->setCommodityCode('8443991000');
$product->setCommodityManucountry('PL');

// Add all elements to the shipment
$shipment->setShipmentDetail($shipment_detail);
$shipment->setRecipient($reciever);
$shipment->setSender($sender);
$shipment->setProducts([$product]);

// Send shipment to Shiptheory
$data = $shipment->toJson(true);
$result = $client->bookShipment($data);