Download the PHP package gabrielbull/ups-api without Composer
On this page you can find all versions of the php package gabrielbull/ups-api. It is possible to download/install these versions without Composer. Possible dependencies are resolved automatically.
Download gabrielbull/ups-api
More information about gabrielbull/ups-api
Files in gabrielbull/ups-api
Informations about the package ups-api
This library wrap all the UPS API into a simple to use PHP Library. It currently covers the Quantum View®, Tracking API, Shipping API, Rating API and Time in Transit API. Feel free to contribute.
Table Of Content
- Requirements
- Installation
- Address Validation Class
- Example
- Parameters
- Simple Address Validation Class
- Example
- Parameters
- QuantumView Class
- Example
- Parameters
- Tracking Class
- Example
- Parameters
- Rate Class
- Example
- Parameters
- RateTimeInTransit Class
- Example
- Parameters
- TimeInTransit Class
- Example
- Parameters
- Locator Class
- Example
- Parameters
- Tradeability Class
- Example
- Parameters
- Shipping Class
- Example
- Parameters
- Shipment Service Options
- Example
- Logging
- License
Requirements
This library uses PHP 7.1+.
To use the UPS API, you have to request an access key from UPS. For every request, you will have to provide the Access Key, your UPS User ID and Password.
Installation
It is recommended that you install the PHP UPS API library through composer. To do so, run the Composer command to install the latest stable version of PHP UPS API:
If not using composer, you must also include these libraries: Guzzle, Guzzle Promises, [Guzzle PSR7] (https://github.com/guzzle/psr7), PHP-Fig PSR Log, and PHP-Fig HTTP Message.
Address Validation Class (Street Level)
The Address Validation Class allow you to validate an address at street level. Suggestions are given when address is invalid.
Note: UPS has two Address Validations. This is Street Level option, which includes all option of the normal Address Validation class and adds street level validation.
Currently, only US & Puerto Rico are supported.
Example
AddressValidation::validateReturnAVObject()
In the code above $xav->activateReturnObjectOnValidate()
is completely optional. Calling this method will cause
AddressValidation::validate()
to return an AddressValidationResponse
object. If you do not call this method, validate
continues to function as it has previously. If you do not call this method, a single object with either the matched
validated address, or the first candidate address if the address is ambiguous, will be returned.
The AddressValidationResponse object provides a number of methods to allow you to more easily query the API response to
determine the outcome. Continuing the example from above, returning an AddressValidationResponse
object will allow
you to be a bit more specific with how you handle the various outcomes:
Parameters
Address Validation parameters are:
address
Address object as constructed in examplerequestOption
One of the three request options. See documentation. Default = Address Validation.maxSuggestion
Maximum number of suggestions to be returned. Max = 50
Simple Address Validation Class
The Simple Address Validation Class allow you to validate less extensive as the previous class. It returns a quality score of the supplied address and provides alternatives.
Note: UPS has two Address Validations. This is the Simple option.
Currently, only US & Puerto Rico are supported.
Example
Parameters
Simple Address Validation parameters are:
address
Address object as constructed in example
QuantumView Class
The QuantumView Class allow you to request a Quantum View Data subscription.
Example
Parameters
QuantumView parameters are:
name
Name of subscription requested by user. If null, all events will be returned.beginDateTime
Beginning date time for the retrieval criteria of the subscriptions. Format: Y-m-d H:i:s or Unix timestamp.endDateTime
Ending date time for the retrieval criteria of the subscriptions. Format: Y-m-d H:i:s or Unix timestamp.fileName
File name of specific subscription requested by user.bookmark
Bookmarks the file for next retrieval.
If you provide a beginDateTime
, but no endDateTime
, the endDateTime
will default to the current date time.
To use the fileName
parameter, do not provide a beginDateTime
.
Tracking Class
The Tracking Class allow you to track a shipment using the UPS Tracking API.
Example using Tracking Number / Mail Innovations tracking number
Parameters
Tracking parameters are:
trackingNumber
The package’s tracking number.requestOption
Optional processing. For Mail Innovations the only valid options are Last Activity and All activity.
Example using Reference Number
Parameters
Tracking parameters are:
referenceNumber
The ability to track any UPS package or shipment by reference number. Reference numbers can be a purchase order number, job number, etc. Reference Number is supplied when generating a shipment.requestOption
Optional processing. For Mail Innovations the only valid options are Last Activity and All activity.
Example using Reference Number with additional parameters
The parameters shipperNumber, beginDate and endDate are optional. Either of the parameters can be set individually. These parameters can help to narrow the search field when tracking by reference, since it might happen that the reference number used is not unique. When using tracking by tracking number these parameters are not needed since the tracking number is unique.
Rate Class
The Rate Class allow you to get shipment rates using the UPS Rate API.
Example
Parameters
rateRequest
Mandatory. rateRequest Object with shipment details
This Rate class is not finished yet! Parameter should be added when it will be finished.
RateTimeInTransit Class
The RateTimeInTransit Class allow you to get shipment rates like the Rate Class, but the response will also include TimeInTransit data.
Example
Parameters
rateRequest
Mandatory. rateRequest Object with shipment details
This RateTimeInTransit extends the Rate class which is not finished yet! Parameter should be added when it will be finished.
TimeInTransit Class
The TimeInTransit Class allow you to get all transit times using the UPS TimeInTransit API.
Example
Parameters
timeInTransitRequest
Mandatory. timeInTransitRequest Object with shipment details, see example above.
Locator Class
The Locator class allows you to search for UPS Access Point locations.
Example
Parameters
Locator class parameters are:
locatorRequest
Mandatory. locatorRequest object with request details, see examplerequestOption
Optional. Type of locations you are searching for.
Tradeability Class
The Tradeability class allows you to get data for international shipments:
- Landed Costs (e.g. duties)
- Denied Party Screener
- Import Compliance
- Export License Detection
Note: only the Landed Costs API is currently implemented.
⚠️ Tradeability is only available through a SOAP API. Therefore you are required to have the SOAP extension installed on your system.
Example
Parameters
For the Landed Cost call, parameters are:
landedCostRequest
Mandatory. landedCostRequest object with request details, see example.
Shipping Class
The Shipping class allows you to register shipments. This also includes return shipments.
The shipping flow consists of 2 steps:
- Confirm: Send information to UPS to get it validated and get a digest you can use to accept the shipment.
- Accept: Finalise the shipment, mark it as it will be shipped. Get label and additional information.
Please note this is just an example. Your use case might demand more or less information to be sent to UPS.
In the example $return
is used to show how a return could be handled.
Example
If you wanted to create a printable file from the UPS Shipping label image data that came back with $accept, you would use something like the following:
Parameters
For the Shipping confirm
call, the parameters are:
- $validation A UPSShipping::REQ* constant (or null). Required
- $shipment Shipment data container. Required
- $labelSpec LabelSpecification data. Optional
- $receiptSpec ShipmentRequestReceiptSpecification data. Optional
For the Shipping accept
call, the parameters are:
- $shipmentDigest The UPS Shipment Digest received from a ShipConfirm request. Required
Shipment Service Options
The Shipment Service Options class allows you to register shipments additional options. This also includes.
- Add or Modify email notifications: Manage updates for this shipment.
- Saturday Commericial: Get weekend delivery of your shipment.
- Deliver only to receiver's address: Do not reroute for customer pickup at a UPS location.
- UPS Carbon Neutral Shipments Thanks for offsetting the environmental impact of your shipment! : at a nominal fee for domestic and international shipments.
In the example ShipmentServiceOptions class is used to show how a Shipment Additional Option can be added to Shipment.
Shipment Service Options Example
Logging
All constructors take a PSR-3 compatible logger.
Besides that, the main UPS class has a public method setLogger
to set it after the constructor ran.
Requests & responses (including XML, no access keys) are logged at DEBUG level. At INFO level only the event is reported, not the XML content. More severe problems (e.g. no connection) are logged with higher severity.
Example using Monolog
``
License
PHP UPS API is licensed under The MIT License (MIT).
All versions of ups-api with dependencies
ext-dom Version *
ext-simplexml Version *
guzzlehttp/guzzle Version ^6.0 || ^7.0
psr/log Version ^1.0 || ^2.0 || ^3.0