Menu

## ApiClient
in package

ApiClient.php : 62

ApiClient class that encapsulates request methods for shipcloud API.

##### Tags

category

  Class

author

  Daniel Muenter info@msltns.com

version
  0.0.1
since
  0.0.1
license

  GPL 3 This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License, version 3, as published by the Free Software Foundation. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA

### Table of Contents

$max_redirects : int
  Maximum number of redirects.
$request_timeout : int
  Timeout for requests.
$affiliate_id : string
  Affiliate ID.
$api_key : string
  Key of the customer to access the API.
$base_url : string
  URL to the API.
$logger : Logger
  Logger.
__construct() : void
  ApiClient constructor.
address_exists() : array<string|int, mixed>
  Checks a given array of addresses if a certain address exists filtered by certain criteria.
create_address() : array<string|int, mixed>
  This method is to create an address. It forces a validation against required fields before sending the request to API.
create_pickup_request() : array<string|int, mixed>|bool
  There are two ways you can request shipments to be picked up by a specific carrier. By simply stating that all shipments that haven't been picked up already should be picked up or by specifying which shipments should by picked up.
create_shipment() : array<string|int, mixed>
  This method is to create a shipment.
create_shipment_quote() : array<string|int, mixed>|bool
  With this call you can find out how much we will charge you for a specific shipment.
create_tracker() : array<string|int, mixed>|bool
  If you want to create a tracker, this is the way to go.
create_webhook() : array<string|int, mixed>|bool
  If you want to create a webhook, this is the way to go.
delete_shipment() : array<string|int, mixed>|bool
  This method is to delete an existing shipment.
delete_webhook() : array<string|int, mixed>|bool
  This method is to delete an existing webhook.
get_address() : array<string|int, mixed>
  If you want to obtain a certain address, this is the way to go.
get_addresses() : array<string|int, mixed>
  If you want to obtain a list of addresses, this is the way to go.
get_carriers() : array<string|int, mixed>
  Get all carriers available for your account.
get_default_returns_address() : array<string|int, mixed>
  This is the default address that will be used for returns shipments when no address was specified using the 'to' attribute.
get_default_shipping_address() : array<string|int, mixed>
  This is the default address that will be used for shipments when no address was specified using the 'from' attribute.
get_invoice_address() : array<string|int, mixed>
  This is the address that a user has specified as being their invoice address.
get_me() : array<string|int, mixed>
  If you need more details about the current user that is making a request, you can get it by querying the /me endpoint.
get_pickup_request() : array<string|int, mixed>|bool
  Getting information about a certain pickup request.
get_pickup_requests() : array<string|int, mixed>
  Getting a list of pickup requests.
get_shipment() : array<string|int, mixed>
  If you want to obtain a certain shipment, this is the way to go.
get_shipments() : array<string|int, mixed>
  If you want to obtain a list of shipments, this is the way to go.
get_shipping_rate() : array<string|int, mixed>|bool
  With this call you can find out how much we will charge you for a specific shipment.
get_tracker() : array<string|int, mixed>|bool
  Getting information about a certain tracker.
get_trackers() : array<string|int, mixed>
  Getting a list of trackers.
get_webhook() : array<string|int, mixed>|bool
  Getting information about a certain webhook.
get_webhooks() : array<string|int, mixed>
  Getting a list of webhooks.
log() : void
  Output a debug message.
update_shipment() : array<string|int, mixed>
  This method is to update an existing shipment.
delete() : array<string|int, mixed>
  DELETE request.
get() : array<string|int, mixed>
  GET request.
post() : array<string|int, mixed>
  POST request.
put() : array<string|int, mixed>
  PUT request.
request() : array<string|int, mixed>
  The actual request function.
shipment_is_editable() : bool
  Precheck before updating a shipment.
validate_address() : bool
  Validates an array of address data.
validate_api_key() : bool
  Validates an id.
validate_carrier() : bool
  Validates a carrier string.
validate_country() : bool
  Validates a country string.
validate_id() : bool
  Validates an id.
validate_pickup() : bool
  Validates pickup data. It throws an ApiException if the validation fails. A message with concrete details is given then.
validate_shipment() : bool
  Validates shipment data. It throws an ApiException if the validation fails. A message with concrete details is given then.
validate_tracker() : bool
  Validates tracker data. It throws an ApiException if the validation fails. A message with concrete details is given then.
validate_webhook() : bool
  Validates webhook data. It throws an ApiException if the validation fails. A message with concrete details is given then.

### Properties

#### $max_redirects

ApiClient.php : 83

Maximum number of redirects.

`protected int $max_redirects = 5`

#### $request_timeout

ApiClient.php : 90

Timeout for requests.

`protected int $request_timeout = 30`

#### $affiliate_id

ApiClient.php : 97

Affiliate ID.

`private string $affiliate_id`

#### $api_key

ApiClient.php : 76

Key of the customer to access the API.

`private string $api_key`

#### $base_url

ApiClient.php : 69

URL to the API.

`private string $base_url = 'https://api.shipcloud.io/v1'`

#### $logger

ApiClient.php : 104

Logger.

`private Logger $logger`

### Methods

#### __construct()

ApiClient.php : 115

ApiClient constructor.

`public __construct(string $api_key[, string $logfile = '' ][, string $affiliate_id = false ][, string $base_url = '' ]) : void`

##### Parameters

$api_key : string

  Key to access the API.

$logfile : string = ''

  Path to logfile.

$affiliate_id : string = false

  Affiliate ID (optional).

$base_url : string = ''

  URL to the API (optional).

##### Return values

void —

#### address_exists()

ApiClient.php : 194

Checks a given array of addresses if a certain address exists filtered by certain criteria.

`public address_exists(array<string|int, mixed> $addresses[, string $filter = [] ]) : array<string|int, mixed>`

##### Parameters

$addresses : array<string|int, mixed>

  The address list to search.

$filter : string = []

  The search criteria.

##### Return values

array<string|int, mixed> —

Address if found, otherwise false.

#### create_address()

ApiClient.php : 141

This method is to create an address. It forces a validation against required fields before sending the request to API.

`public create_address(Address $address) : array<string|int, mixed>`

##### Parameters

$address : Address

  The address to be created.

##### Return values

array<string|int, mixed> —

The created address including ID.

#### create_pickup_request()

ApiClient.php : 444

There are two ways you can request shipments to be picked up by a specific carrier. By simply stating that all shipments that haven't been picked up already should be picked up or by specifying which shipments should by picked up.

`public create_pickup_request(Pickup $pickup) : array<string|int, mixed>|bool`

Notice: If you don't supply a pickup_address in your request, we're using the default from address that's being defined in the shipcloud profile for requesting a pickup by the carrier. Please keep in mind there are carrier specific field lengths you have to take into account.

##### Parameters

$pickup : Pickup

  The pickup data.

##### Return values

array<string|int, mixed>|bool —

An array with pickup information if succeeded, false otherwise.

#### create_shipment()

ApiClient.php : 259

This method is to create a shipment.

`public create_shipment(Shipment $shipment) : array<string|int, mixed>`

    Response:
    {
      "id": "3a186c51d4281acbecf5ed38805b1db92a9d668b",
      "carrier_tracking_no": "84168117830018",
      "tracking_url": "https://track.shipcloud.io/3a186c51d4",
      "label_url": "https://shipping-labels.shipcloud.io/shipments/01370b4d/199f803bf8/label/shipping_label_199f803bf8.pdf",
      "price": 3.4
    }

##### Parameters

$shipment : Shipment

  The shipment to be created at API.

##### Return values

array<string|int, mixed> —

Shipment labeling, tracking and pricing information.

#### create_shipment_quote()

ApiClient.php : 381

With this call you can find out how much we will charge you for a specific shipment.

`public create_shipment_quote(Shipment $shipment) : array<string|int, mixed>|bool`

##### Parameters

$shipment : Shipment

  The shipment to get quote for.

##### Return values

array<string|int, mixed>|bool —

An array with shipment quote if succeeded, false otherwise.

#### create_tracker()

ApiClient.php : 539

If you want to create a tracker, this is the way to go.

`public create_tracker(Tracker $tracker) : array<string|int, mixed>|bool`

##### Parameters

$tracker : Tracker

  The tracker object.

##### Return values

array<string|int, mixed>|bool —

An array with tracker information if succeeded, false otherwise.

#### create_webhook()

ApiClient.php : 485

If you want to create a webhook, this is the way to go.

`public create_webhook(Webhook $webhook) : array<string|int, mixed>|bool`

##### Parameters

$webhook : Webhook

  The webhook object.

##### Return values

array<string|int, mixed>|bool —

An array with webhook information if succeeded, false otherwise.

#### delete_shipment()

ApiClient.php : 367

This method is to delete an existing shipment.

`public delete_shipment( $id) : array<string|int, mixed>|bool`

    NOTE:
    Prepared shipments (create_shipping_label is false) can be deleted
    at any time, because no transaction with the carrier has happened
    until this point and no actual shipping label has been created. In
    case you've created a shipping label you can delete it before the
    cutoff time of the carrier. Cutoff times differ from carrier to
    carrier and are some time between 5pm and 8pm.

##### Parameters

$id :

  The id attribute that was returned when creating the shipment.

##### Return values

array<string|int, mixed>|bool —

An empty array if succeeded, false otherwise.

#### delete_webhook()

ApiClient.php : 520

This method is to delete an existing webhook.

`public delete_webhook( $id) : array<string|int, mixed>|bool`

##### Parameters

$id :

  The id attribute that was returned when creating the webhook.

##### Return values

array<string|int, mixed>|bool —

An empty array if succeeded, false otherwise.

#### get_address()

ApiClient.php : 154

If you want to obtain a certain address, this is the way to go.

`public get_address(string $id) : array<string|int, mixed>`

##### Parameters

$id : string

  The id attribute that was returned when creating the address.

##### Return values

array<string|int, mixed> —

The address if existing.

#### get_addresses()

ApiClient.php : 183

If you want to obtain a list of addresses, this is the way to go.

`public get_addresses([array<string|int, mixed> $filter = [] ]) : array<string|int, mixed>`

You can filter the addresses list using one or more of the following URL parameters:

first_name, e.g. 'first_name=Max' last_name, e.g. 'last_name=Mustermann' company, e.g. 'company=Example%20Company' care_of, e.g. 'care_of=Roger%20Receiver' street, e.g. 'street_no=Musterstraße' street_no, e.g. 'street_no=42' zip_code, e.g. 'zip_code=12345' state, e.g. 'state=CA' city, e.g. 'city=Musterstadt' country, e.g. 'country=DE' phone, e.g. 'phone=555-555' page, show page number x, e.g. 'page=2' per_page, show x number of shipments on a page (default & max: 100), e.g. 'per_page=25'

##### Parameters

$filter : array<string|int, mixed> = []

  A list of filter criteria.

##### Return values

array<string|int, mixed> —

A list of all created addresses.

#### get_carriers()

ApiClient.php : 401

Get all carriers available for your account.

`public get_carriers() : array<string|int, mixed>`

##### Return values

array<string|int, mixed> —

A list of all carriers available for your account.

#### get_default_returns_address()

ApiClient.php : 214

This is the default address that will be used for returns shipments when no address was specified using the 'to' attribute.

`public get_default_returns_address() : array<string|int, mixed>`

##### Return values

array<string|int, mixed> —

The default returns address.

#### get_default_shipping_address()

ApiClient.php : 224

This is the default address that will be used for shipments when no address was specified using the 'from' attribute.

`public get_default_shipping_address() : array<string|int, mixed>`

##### Return values

array<string|int, mixed> —

The default shipping address.

#### get_invoice_address()

ApiClient.php : 233

This is the address that a user has specified as being their invoice address.

`public get_invoice_address() : array<string|int, mixed>`

##### Return values

array<string|int, mixed> —

The invoice address.

#### get_me()

ApiClient.php : 580

If you need more details about the current user that is making a request, you can get it by querying the /me endpoint.

`public get_me() : array<string|int, mixed>`

##### Return values

array<string|int, mixed> —

Details about the current API user.

#### get_pickup_request()

ApiClient.php : 466

Getting information about a certain pickup request.

`public get_pickup_request(string $id) : array<string|int, mixed>|bool`

##### Parameters

$id : string

  The id attribute that was returned when creating the pickup request.

##### Return values

array<string|int, mixed>|bool —

The pickup request if existing, false otherwise.

#### get_pickup_requests()

ApiClient.php : 456

Getting a list of pickup requests.

`public get_pickup_requests() : array<string|int, mixed>`

##### Return values

array<string|int, mixed> —

A list of pickup requests.

#### get_shipment()

ApiClient.php : 272

If you want to obtain a certain shipment, this is the way to go.

`public get_shipment(string $id) : array<string|int, mixed>`

##### Parameters

$id : string

  The id attribute that was returned when creating the shipment.

##### Return values

array<string|int, mixed> —

The shipment if existing.

#### get_shipments()

ApiClient.php : 319

If you want to obtain a list of shipments, this is the way to go.

`public get_shipments([array<string|int, mixed> $filter = [] ]) : array<string|int, mixed>`

You can filter the shipments list using one or more of the following URL parameters:

    carrier, e.g. 'carrier=dhl'
    carrier_tracking_no, e.g. 'carrier_tracking_no=43128000105'
    created_at_gt, e.g. 'created_at_gt=20180712T1300Z'
    created_at_lt, e.g. 'created_at_lt=20180712T1400Z'
    page, show page number x, e.g. 'page=2'
    per_page, show x number of shipments on a page (default & max: 100), e.g. 'per_page=25'
    reference_number, e.g. 'reference_number=ref123456'
    service, e.g. 'service=returns'
    shipcloud_tracking_no, e.g. 'shipcloud_tracking_no=86afb143f9c9c0cfd4eb7a7c26a5c616585a6271'
    shipment_type, e.g. 'shipment_type=prepared'
    source, e.g. 'source=api'
    tracking_status, e.g. 'tracking_status=out_for_delivery'
    tracking_status_not, e.g. 'tracking_status_not=delivered'

    shipment_type: Specifies the type of a shipment. The following types are available:

    prepared: a shipment which was saved in shipcloud but doesn't have a shipping label yet
    label_created: a shipment containing a shipping label.
    tracking_only: a shipment that was imported via its carrier tracking number (see trackers for more details)

    created_at_gt / created_at_lt: You can filter the list by using these parameters to specify a timerange to
    find the shipments that were created during this time. The timestamp will be evaluated as ISO 8601 using the
    following format: YYYYMMDDThhmmZ.

    source: Filter shipments by platform they were created through. The following keys can be used:

    api: a shipment created through our api
    webui: a shipment created using the shipcloud ui
    return_portal: a shipment created using the shipcloud return portal

##### Parameters

$filter : array<string|int, mixed> = []

  A list of filter criteria.

##### Return values

array<string|int, mixed> —

A list of all created shipments.

#### get_shipping_rate()

ApiClient.php : 420

With this call you can find out how much we will charge you for a specific shipment.

`public get_shipping_rate(Shipment $shipment) : array<string|int, mixed>|bool`

##### Parameters

$shipment : Shipment

  The shipment to get quote for.

##### Tags

deprecated

  The rates call is deprecated. Please use method create_shipment_quote() instead.

see
  ApiClient::create_shipment_quote()

##### Return values

array<string|int, mixed>|bool —

An array with shipment quote if succeeded, false otherwise.

#### get_tracker()

ApiClient.php : 561

Getting information about a certain tracker.

`public get_tracker(string $id) : array<string|int, mixed>|bool`

##### Parameters

$id : string

  The id attribute that was returned when creating the tracker.

##### Return values

array<string|int, mixed>|bool —

The tracker if existing, false otherwise.

#### get_trackers()

ApiClient.php : 551

Getting a list of trackers.

`public get_trackers() : array<string|int, mixed>`

##### Return values

array<string|int, mixed> —

A list of trackers.

#### get_webhook()

ApiClient.php : 507

Getting information about a certain webhook.

`public get_webhook(string $id) : array<string|int, mixed>|bool`

##### Parameters

$id : string

  The id attribute that was returned when creating the webhook.

##### Return values

array<string|int, mixed>|bool —

The webhook if existing, false otherwise.

#### get_webhooks()

ApiClient.php : 497

Getting a list of webhooks.

`public get_webhooks() : array<string|int, mixed>`

##### Return values

array<string|int, mixed> —

A list of webhooks.

#### log()

ApiClient.php : 1013

Output a debug message.

`public log(string $message[, string $level = 'info' ][, mixed $context = [] ]) : void`

##### Parameters

$message : string

  Debug message.

$level : string = 'info'

  Debug level.

$context : mixed = []

  The Debug context.

##### Return values

void —

#### update_shipment()

ApiClient.php : 344

This method is to update an existing shipment.

`public update_shipment(Shipment $shipment) : array<string|int, mixed>`

NOTE: API returns code 400 (The requested URL returned error: 400 Bad Request) if a label has already been created. Therefore a precheck will be processed.

    Response:
    {
      "id": "3a186c51d4281acbecf5ed38805b1db92a9d668b",
      "carrier_tracking_no": "84168117830018",
      "tracking_url": "https://track.shipcloud.io/3a186c51d4",
      "label_url": "https://shipping-labels.shipcloud.io/shipments/01370b4d/199f803bf8/label/shipping_label_199f803bf8.pdf",
      "price": 3.4
    }

##### Parameters

$shipment : Shipment

  The shipment to edit.

##### Return values

array<string|int, mixed> —

Shipment labeling, tracking and pricing information.

#### delete()

ApiClient.php : 882

DELETE request.

`protected delete(string $method) : array<string|int, mixed>`

##### Parameters

$method : string

  The API method to request.

##### Return values

array<string|int, mixed> —

The response payload.

#### get()

ApiClient.php : 846

GET request.

`protected get(string $method[, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>`

##### Parameters

$method : string

  The API method to request.

$params : array<string|int, mixed> = []

  The request parameters.

##### Return values

array<string|int, mixed> —

The response payload.

#### post()

ApiClient.php : 860

POST request.

`protected post(string $method[, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>`

##### Parameters

$method : string

  The API method to request.

$params : array<string|int, mixed> = []

  The request parameters.

##### Return values

array<string|int, mixed> —

The response payload.

#### put()

ApiClient.php : 871

PUT request.

`protected put(string $method[, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>`

##### Parameters

$method : string

  The API method to request.

$params : array<string|int, mixed> = []

  The request parameters.

##### Return values

array<string|int, mixed> —

The response payload.

#### request()

ApiClient.php : 895

The actual request function.

`private request(string $method[, string $rtype = 'GET' ][, array<string|int, mixed> $params = [] ]) : array<string|int, mixed>`

##### Parameters

$method : string

  The API method to request.

$rtype : string = 'GET'

  The request type (GET|POST|PUT|DELETE).

$params : array<string|int, mixed> = []

  The request parameters.

##### Tags

throws
  ApiException

##### Return values

array<string|int, mixed> —

The response payload.

#### shipment_is_editable()

ApiClient.php : 732

Precheck before updating a shipment.

`private shipment_is_editable(string $shipment_id) : bool`

##### Parameters

$shipment_id : string

  The id of a shipment to be prechecked.

##### Tags

throws
  ApiException

##### Return values

bool —

True if shipment is editable.

#### validate_address()

ApiClient.php : 625

Validates an array of address data.

`private validate_address(array<string|int, mixed> $address) : bool`

##### Parameters

$address : array<string|int, mixed>

  The address to be validated.

##### Tags

throws
  ApiException

##### Return values

bool —

True if validation succeeded.

#### validate_api_key()

ApiClient.php : 597

Validates an id.

`private validate_api_key(string $api_key) : bool`

##### Parameters

$api_key : string

  The api key to be validated.

##### Tags

throws
  ApiException

##### Return values

bool —

True if validation succeeded.

#### validate_carrier()

ApiClient.php : 670

Validates a carrier string.

`private validate_carrier(string $carrier) : bool`

##### Parameters

$carrier : string

  The carrier string to be validated.

##### Tags

throws
  ApiException

##### Return values

bool —

True if validation succeeded.

#### validate_country()

ApiClient.php : 655

Validates a country string.

`private validate_country(string $country) : bool`

##### Parameters

$country : string

  The country string to be validated.

##### Return values

bool —

True if validation succeeded, false otherwise.

#### validate_id()

ApiClient.php : 611

Validates an id.

`private validate_id(string $id) : bool`

##### Parameters

$id : string

  The id to be validated.

##### Tags

throws
  ApiException

##### Return values

bool —

True if validation succeeded.

#### validate_pickup()

ApiClient.php : 752

Validates pickup data. It throws an ApiException if the validation fails. A message with concrete details is given then.

`private validate_pickup(Pickup $pickup) : bool`

##### Parameters

$pickup : Pickup

  The pickup data to be validated.

##### Tags

throws
  ApiException

##### Return values

bool —

True if validation succeeded.

#### validate_shipment()

ApiClient.php : 689

Validates shipment data. It throws an ApiException if the validation fails. A message with concrete details is given then.

`private validate_shipment(Shipment $shipment) : bool`

##### Parameters

$shipment : Shipment

  The shipment to be validated.

##### Tags

throws
  ApiException

##### Return values

bool —

True if validation succeeded.

#### validate_tracker()

ApiClient.php : 815

Validates tracker data. It throws an ApiException if the validation fails. A message with concrete details is given then.

`private validate_tracker(Tracker $tracker) : bool`

##### Parameters

$tracker : Tracker

  The tracker to be validated.

##### Tags

throws
  ApiException

##### Return values

bool —

True if validation succeeded.

#### validate_webhook()

ApiClient.php : 788

Validates webhook data. It throws an ApiException if the validation fails. A message with concrete details is given then.

`private validate_webhook(Webhook $webhook) : bool`

##### Parameters

$webhook : Webhook

  The webhook to be validated.

##### Tags

throws
  ApiException

##### Return values

bool —

True if validation succeeded.

## Search results