Sections in this article:
The diagram below is a class diagram for the classes that makes up the PHP WS. The project consists of six classes. The ESWebIntegrationWSPHP class, which is the main class, contains the web methods we are going to call and it consumes the other five classes. The sample code in the project is an integration with the open source web shop osCommerce and the database engine is MySQL.
Lets take a look at the classes and ESWebIntegrationWS.php file and explain the use of the them. The LoginCredentials class handles the credentials for user authentication based on the credentials that is used in Consignor. Every web method has LoginCredentials as an input parameter. You can use the credentials UserName and Password to authenticate the user or just one of them. In the sample code is UserName used to assign the database prefix, so the user get access only to his tables in the database. $prefix = $Credentials['UserName'];.
The AddressData class handles the data we want to present on the receiver of the shipment. This class is used both in order (GetOrderData) and customer (GetCustomerData) lookup. Lines that are marked with * are mandatory and this means you have to assign a value to this AddressData class member in the functions GetOrderData and GetCustomerData. Edit the sample code to fit your needs of fields from the AddressData class.
|Number||* Unique key (order number, Customer number)|
|Name1||* Receivers name – Company or private person|
|Name2||C/O or department, not in use in Norway|
|StreetAddress1||Street/Road – must be delivery address|
|StreetAddress2||Department, building, port etc.|
|StreetAddress3||Not in use|
|Postcode||* Receivers postal code/Zip code|
|City||* Name of delivery city|
|Mobile||Used e.g. with SMS service for carrier Posten Norge|
|Phone||Required when sending COD shipments with bedriftspakke(Posten Norge)|
|Required if mail back function is used in Consignor|
|Fax||Receivers fax number|
|PostOfficeBoxCity||City name of receiver postbox|
|PostOfficeBoxPostcode||Postal code for receivers postbox|
|CountryName||Necessary for international deliveries. Format isoA2, isoA3, isoN3|
|CustomerOrigin||Not in use|
|Attention||Contact person name of sender or receiver|
|Contact||Not in use|
|ReceiverRef||Reference requested by the receiver. Order/requisitions/invoice number etc.|
|OurRef||Not in use|
|MessageToCarrier||Carrier may not support this. This will not be printed to the label|
|MessageToDriver||Carrier may not support this. This will not be printed to the label|
|MessageToReceiver||Carrier may not support this. This will be printed to the label.|
|PurchaseNo||Not in use|
|ShipmentTypeNo||Drop Point ID / the Id for the chosen drop point on an order.|
|DeliveryConditions||Not in use|
|DeliveryTime||Not in use|
|PaymentTerms||Not in use|
|Amount||Not in use|
|Account||Not in use|
|Reference||Not in use|
The LineData class is used in a combination with the AddressData class when you want to get data on an order (GetOrderData) function. LineData provides data members for the shipment.
|PackagesCount||Number of colli on the shipment|
|PackagesMarking||Marking of the goods, rarely used|
|PackagesContents||Parcel or pallet contents|
|PackagesWeight||Parcel or pallet weight (gram), used for volume calculation|
|PackagesHeight||Parcel or pallet height (mm), used for volume calculation|
|PackagesLength||Parcel or pallet length (mm), used for volume calculation|
|PackagesWidth||Parcel or pallet width (mm), used for volume calculation|
|PackagesVolume||Parcel or pallet volume (mm3)|
|CODAccount||Account number for COD payment(rarely used in integration)|
|CODAmount||COD amount, comma separated for decimal e.g. for øre.|
|CODReference||Number used for bookkeeping purpose.|
|InsuranceCategory||Insured package category|
|InsurancePolicyNo||Insurances policy number.|
|DeliveryTerms||Not in use|
|Department||Not in use|
|InvoiceNumber||Not in use|
|PaymentTerms||A code that determinates if the CODAmount is used on the shipment|
|PaymentType||Not in use|
|ProjectName||Name of a given project running between a sender and receiver|
|ProjectNumber||Number of a given project running between a sender and receiver|
|CarrierCode||One single code to select shipping method E.g. code 10 = Servicepakke|
AddressesAndPackages class consists of two data members that presents an instance of AdressData and LineData as arrays. These two members are used to return an array of the data members in AdressData and LineData from the functions GetOrderData and GetCustomerData.
The ReturnData class is used to return data on a shipment from Consignor and back to your system, so you are able to update your database based on the return data. The UpdateData function uses the ReturnData class for this purpose. ColliNumbers and PackageTrackUrl is semicolon( ; ) separated. ShipmentTrackUrl provides carriers track and trace URL with shipment number and PackageTrackUrl provides track and trace URL with colli numbers.
|PackagesCount||Number of packages||2|
|ShipmentNumber||Track & Trace shipment number, used for tracking shipment on carrier.||70716480125001002|
|ShipmentTrackUrl||Track & Trace URL with shipment number||http://sporing.bring.no/sporing/KMSporingslink.aspx?PackageNumber=70716480125001002|
|ColliNumbers||Track & Trace colli numbers used for tracking packages on carrier||00370716480125001010;00370716480125001027;|
|PackageTrackUrl||Track & Trace URL with colli numbers||http://sporing.bring.no/sporing/KMSporingslink.aspx?PackageNumber=370716480125001010; http://sporing.bring.no/sporing/KMSporingslink.aspx?PackageNumber=370716480125001027;|
|Price1||Calculated price on the shipment, nett or gross(Configured in Consignor)||168|
|Price2||Calculated price on the shipment, nett or gross(Configured in Consignor)||210|
The ESWebIntegrationWS.php file contains all the functions (web methods) that is consumed from Consignor and EDI-Soft`s WS. The function GetOrderData handles order requests. It connects to the database and fetches the order data from SQL query. The function takes two input parameters, OrderNumber as a string and Credentials as LoginCredentials.
As mentioned before, use credentials to authenticate the user in the way that suits your needs. Use the data members you want from the classes AddressData (remember to include the mandatory members) and LineData. Do not edit any of the classes and keep the namespace as it is in the code: $NAMESPACE = 'http://localhost/ESWebIntegrationWS'; I will not get into details on the functions, I think the comments in these functions and the sample code will cover it.
Deploying the Web Service
To deploy the WS, simply do as you usually would do with a ordinary site. Include the folder "lib" and the file ESWebIntegrationWS.php and dbCon if you are going to use this for your database connection. When your WS is up and running you should see a site as shown in the picture when you point to your URL.
Download PHP Project files
To get started, download the project files below. Note that the project files were created with PHP 5.6. It contains a ready made webservice with sample code. Change the code and SQL queries to fit your system and the data you wish to provide with the web service.