3PL Connections - Developer Resources

>>> Add 3PL Connection

STEP 1

  • To add a new 3PL connection - On Dashboard - Go to Settings -> Configuration -> 3PL Connections.
19261926

STEP 2

  • On 3PL Connections page, click on the Add 3PL Connection button.
19261926

STEP 3

  • This will open the 3PL connections form page where you can add a new connection.
15771577

  • Make the connection Active and fill in the configuration information of the 3PL and add API credentials. This will be used to send the order to that particular 3PL and also to receive the order status.

  • There is a button given for performing a test connection. Clicking on the Test Connection button will take the API Parameters and post them to the Test Connection URL which checks whether the API credentials passed are valid or not.

  • Once everything is done, click on Save.

15961596

  • If the API credentials are valid, a pop-up message will appear saying, 'Test Connection Successful'.
15731573

If the API credentials are invalid, a pop-up message will appear saying, 'Test Connection Failed'.

15731573

While saving any 3PL connection in the 3PL configuration, we are storing the following information.

  1. 3PL Connection Name - The name of the 3 party logistics service provider/connection
  2. API Parameter1 - API credentials (username)
  3. API Parameter2 - API credentials (password)
  4. API Parameter3 - Optional parameter if any
  5. Test Connection URL - This URL will have a code that will check whether the passed API Parameters are valid or not
  6. Submit Sales Order URL - This URL will have code to create Order by using the class files created in the module
  7. Pull Order Shipment Tracking Information URL - This URL will have code to get the shipment information and update the Agiliron order using the class files


  • To edit the 3PL connection, click on the name of the 3PL connection from the list.
  • To delete the 3PL connection, click on the 'x' sign.
15981598

📘

Note - After storing the API credentials, when we open the Shipping List view, the new 3PL connection created will be present in the drop-down list to send the order to 3PL based on the selected 3PL connection configuration.



STEP 4

  • We need to create a 3PL connection folder as below:
480480

STEP 5

  • Need to create class file 3pl as below:
441441

>>> Sending the order to the selected 3PL connection

To send the order to a particular 3PL Connection

  • Go to Shipping & Receiving -> Shipping.
  • Select order/orders from the list view by clicking the preceding check box.
  • Shipping via has a dropdown list. Select the 3PL Connection to which you need to send the order.
  • Once done click on the Process button.
19261926

  • Next, you can see the order ship list displaying the selected orders in the Multiple Order Shipping screen.

📘

Note - If the selected order is already sent to the 3PL connection it will be displayed with a red background and that order will not be selected.

If the order is not sent, you can change/select Carrier, Shipping Method, Deliver From for the selected order and then click on the Send Orders to 3pl button.

15921592

  • This will bring up a pop-up message to confirm sending. Click on OK.
15681568

  • Sending orders to 3PL connection process starts.
  • Later, you'll see a message saying, 'Transfer complete'.
15961596

The module has the following files for Developer reference:

1. CommitReservation.php

In this file, we read the request parameter and based on these parameters, we call commitReservation function which is defined in SampleMiddleware.php and return response.


2. SampleMiddleware.php

  • GetReservation - In this function, we call getReservation function which is defined in webservice file and return response.

  • CommitReservation - In this function, we call function from webservice commitReservation.

In this function, we call from webservice createSampleOrder and based on the response that comes, we check the status and return output in an array structure.

  • CreateSampleOrder - In this function we call createSampleOrder which is defined in webservice file.

Based on the output we get, we read status and return status and message array response.

  • getSOStatus - In this function, based on the SOnumber of the request parameter, we call getSampleOrderstatus, which is defined in the webservice file and based on XML create an array of response and return it.

  • CheckAuthentication - In this function, we call checkAuthentication which is defined in webservice file, and check the output and return success/error status.


3. SampleWebService.php

  • GetReservation - In this function, we simplify the array, and using the curl post method, we post a request and return response.

  • CommitReservation - In this function, we create an array based on the request parameter and post this request by curl call post method and return response.

📘

Note: This file depends on the 3pl connection request format, parameters, and its structure.

  • createSampleOrder - In this file, we call generatSampleOrderXML for generating XML string, defined in the same file and post request using curl post method and return response.

  • GeneratSamplekOrderXML - In this function, we read array and generate XML request and return it.

  • GetSampleOrderstatus - In this function, based on order number, we call curl get method and return response.

  • GetcheckAuthentication - In this function, based on the request parameter, we call the curl post method and post to the 3pl connection URL and return output.


4. createSampleDataSO.php

In this file, based on the request parameter, we simplify XML string with proper array structure and call the createSampleOrder function which is defined in SampleMiddleware.php.


5. getReservation.php

In this file, based on the request parameter of username and password, we call getReservation function which is defined in the middleware file and return response.


6. Ordershipment.php

In this file, based on the request parameter of username and password, we call the getSOStatus function defined in the middleware file and return response.


7. Test3plconnectorSample.php

In this file based on the request parameter of username and password, we call checkAuthentication function which is called in the middleware file and return status and failed connection response.

📘

Note: In the above files we also write logs using monolog.



>>> Sample Code

<?php
  
/*
 * call by following
 * https://company.agiliron.net/agiliron/index.php?action=createSampleSO&module=Orders&record=xxxx
 *
 * xxxx is the orderno(PO)
 
 */


  /*******************************


Sample XML from Agiliron for submit order.


<Order> 
    <OrderNo>155</OrderNo>
    <Domain>ilt2.agiliron.net</Domain>
    <CurrentKey>iwZ6H9hEV3sPAPbOq7WlvvfgJP_ka9jE_jvvUfaFMO4,</CurrentKey>
    <CustomersId>100364</CustomersId> 
    <CustomersCompany>UpdoerPOS</CustomersCompany> 
    <CustomersStreetAddress>Agiliron, 1515 Clay St</CustomersStreetAddress>
    <CustomersSuburb></CustomersSuburb>
    <CustomersCity>St Oakland</CustomersCity>
    <CustomersPostcode>94612</CustomersPostcode>
    <CustomersState>California</CustomersState>
    <CustomersCountry>United States</CustomersCountry>
    <CustomersTelephone></CustomersTelephone>
    <CustomersEmailAddress>[email protected]m</CustomersEmailAddress>
    <DeliveryName>UpdoerPOS</DeliveryName>
    <DeliveryCompany>UpdoerPOS</DeliveryCompany>
    <DeliveryStreetAddress>Agiliron, 1515 Clay St</DeliveryStreetAddress>
    <DeliverySuburb></DeliverySuburb>
    <DeliveryCity>St Oakland</DeliveryCity>
    <DeliveryPostcode>94612</DeliveryPostcode>
    <DeliveryState>California</DeliveryState>
    <DeliveryCountry>United States</DeliveryCountry>
    <Otherphone></Otherphone>
    <Email2></Email2>
    <BillingName></BillingName>
    <BillingStreetAddress>Agiliron 1515 Clay St</BillingStreetAddress>
    <BillingSuburb></BillingSuburb>
    <BillingCity>Oakland</BillingCity>
    <BillingPostcode>94612</BillingPostcode>
    <BillingState>California</BillingState>
    <BillingCountry>US</BillingCountry>
    <PaymentMethod>3</PaymentMethod>
    <CcType>visa</CcType>
    <CcOwner>Adeeb</CcOwner>
    <CcNumber>emTNPiulU_Pk-sMLr75p</CcNumber>
    <CcExpires>fmfOPQ</CcExpires>
    <CvvNumber></CvvNumber>
    <CheckNumber></CheckNumber>
    <CheckWriter></CheckWriter>
    <LastModified>2020-03-16 02:05:09</LastModified>
    <OrderCreatedDate>2020-03-16 02:05:09</OrderCreatedDate>
    <OrderSubject>Quote</OrderSubject>
    <OrdersStatus>1</OrdersStatus>
    <AssignedUserName>1</AssignedUserName>
    <Currency>1</Currency>
    <OtDiscountCoupon>5.5</OtDiscountCoupon>
    <OtSubtotal>11.510</OtSubtotal>
    <OtShipping>5.500</OtShipping>
    <OtTotal>17.440</OtTotal>
    <Trandate>0000-00-00</Trandate>
    <InvoiceNumber>155</InvoiceNumber>
    <InvoiceDate></InvoiceDate>
    <DateDue>2020-03-15</DateDue>
    <CallDate>0000-00-00</CallDate>
    <Type>DE</Type>
    <Priority>--None--</Priority>
    <Pending></Pending>
    <Salescommission>0.000</Salescommission>
    <OrdersTermsConditions>--NA--</OrdersTermsConditions>
    <CarrierName></CarrierName>
    <Fromstkloc>PDX</Fromstkloc>
    <SpecialHandling></SpecialHandling>
    <ShipPriority>--None--</ShipPriority>
    <Backorders>--None--</Backorders>
    <TaxAuthority>5</TaxAuthority>
    <ShippingMethod>17</ShippingMethod>
    <OtTax>0.430</OtTax>
    <CcAuthorization></CcAuthorization>
    <AdditionalFees>0</AdditionalFees>
    <PricebookName>631</PricebookName>
    <ExportToQuickbooks>0</ExportToQuickbooks>
    <CurrencyId>1</CurrencyId>
    <ExchangeRate>1.00000</ExchangeRate>
    <TrackingNo></TrackingNo>
    <PaymentAmount>12</PaymentAmount>
    <ShippingDate></ShippingDate>
    <ActualFreightCost>0.00</ActualFreightCost>
    <Cancelled>0</Cancelled>
    <OrderDetails>
        <OD>
            <OrdersId>1340</OrdersId>
            <ProductsId>31</ProductsId>
            <ProductsModel>*DEL31*Drop-Ship-Matrix</ProductsModel>
            <ProductsName>*DEL31*Drop-Ship-Matrix</ProductsName>
            <ProductsPrice>6</ProductsPrice>
            <ProductsTotal>6</ProductsTotal>
            <Discount>0.055</Discount>
            <ProductsQuantity>1</ProductsQuantity>
            <ProductsSerialNumber></ProductsSerialNumber>
            <DetailNotes></DetailNotes>
            <SKUCode></SKUCode>
        </OD>
        <OD>
            <OrdersId>1340</OrdersId>
            <ProductsId>31</ProductsId>
            <ProductsModel>*DEL31*Drop-Ship-Matrix</ProductsModel>
            <ProductsName>*DEL31*Drop-Ship-Matrix</ProductsName>
            <ProductsPrice>6</ProductsPrice>
            <ProductsTotal>6</ProductsTotal>
            <Discount>0.055</Discount>
            <ProductsQuantity>1</ProductsQuantity>
            <ProductsSerialNumber></ProductsSerialNumber>
            <DetailNotes></DetailNotes>
            <SKUCode></SKUCode>
        </OD>
        <OD>
            <OrdersId>1340</OrdersId>
            <ProductsId>31</ProductsId>
            <ProductsModel>*DEL31*Drop-Ship-Matrix</ProductsModel>
            <ProductsName>*DEL31*Drop-Ship-Matrix</ProductsName>
            <ProductsPrice>6</ProductsPrice>
            <ProductsTotal>6</ProductsTotal>
            <Discount>0.055</Discount>
            <ProductsQuantity>1</ProductsQuantity>
            <ProductsSerialNumber></ProductsSerialNumber>
            <DetailNotes></DetailNotes>
            <SKUCode></SKUCode>
        </OD>
    </OrderDetails>
 </Order>
 
 ***************************************/
 

  require_once('SampleMiddleware.php');

$parameter1 = $_REQUEST['parameter1'];
$parameter2 = $_REQUEST['parameter2'];
$parameter3 = $_REQUEST['parameter3'];
$xml_string = $_REQUEST['sodata'];

$xml = simplexml_load_string($xml_string);
$json = json_encode($xml);
$SOdata = json_decode($json,TRUE);
if($parameter1 != '' && $parameter2 != ''){
    $SampleMiddleware = new SampleMiddleware($parameter1,$parameter2,$parameter3);
    $output = $SampleMiddleware->createSampleOrder($SOdata);  
}
echo json_encode($output);

?>
<?php
  
  
/*********************************************************************************


 * Agiliron Inc. (TM) - Accelerate Your Business. On Demand (SM)
 * Support: [email protected], 1-855-AGIL-IRON
 *
 * Portions created by Agiliron are Copyright (c) 2007-2020 Agiliron Inc. | All Rights Reserved.
 *
 * Unauthorized copying of this file, via any medium is strictly prohibited.
 * Proprietary and Confidential.
 ********************************************************************************/
require_once('SampleWebService.php');

class SampleMiddleware
{
    public $parameter1 = "";
    public $parameter2 = "";
    public $parameter3 = "";
    public $sample;
    public function __construct($parameter1, $parameter2, $parameter3)
    {
        $this->sample = new SampleWebService($parameter1, $parameter2, $parameter3);
    }

    public function createSampleOrder($SODATA)
    {
        $responseArr = array();
        $response = $this->sample->createSampleOrder($SODATA);
        if(isset($response['OrderDetails'])){
            if($responseArr['status']){
                $responseArr['status'] = $response['status'];
                $responseArr['OrderID'] = $response['OrderID'];
            }else{
                $responseArr['status'] = $response['status'];
                $responseArr['ErrorMessage'] = $response['ErrorMessage'];
            }
        }
        return $responseArr;
    }

    public function getSOStatus($sonumber, $startDate, $endDate)
    {
        $response = $this->sample->getSampleOrderstatus($sonumber, $startDate, $endDate);
        $orderdatails = array();
        if($response['status']){
            foreach ($response['orderdatails'] as $key => $value) {
                $orderdatails[] = array(
                    'status'=>true,
                    'sonumber'=>$sonumber,
                    'isReturnLabel'=>$value['isReturnLabel'],
                    'orderId'=>$value['orderId'],
                    'shipmentCost'=>$value['shipmentCost'],
                    'insuranceCost'=>$value['insuranceCost'],
                    'serviceCode'=>$value['serviceCode'],
                    'trackingNumber'=>$value['trackingNumber'],
                    'shipDate'=>$value['shipDate']
                );
            }
        }else{
            $orderdatails[] = array(
                'status' => false,
                'sonumber'=>$sonumber,
                'Message' => $response['ErrorMessage'],
            );
        }        
        return $orderdatails;
    }


    public function checkAuthentication(){
        $authReturn = $this->sample->getcheckAuthentication();
        return $authReturn;
    }
}

?>
<?php
  
/*********************************************************************************
 * Agiliron Inc. (TM) - Accelerate Your Business. On Demand (SM)
 * Support: [email protected], 1-855-AGIL-IRON
 *
 * Portions created by Agiliron are Copyright (c) 2007-2020 Agiliron Inc. | All Rights Reserved.
 *
 * Unauthorized copying of this file, via any medium is strictly prohibited.
 * Proprietary and Confidential.
 
 ********************************************************************************/

  /**

 * Class SampleWebService
 * This class will a handler that will be used to create order and get order status from Sample Services

*/

class SampleWebService {
    public $parameter1 = "";
    public $parameter2 = "";
    public $parameter3 = "";
    public $soapUrl = "";
    public $itemsurl = "";

    function __construct($parameter1,$parameter2,$parameter3){
        $this->parameter1 = $parameter1;
        $this->parameter2 = $parameter2;
        $this->parameter3 = $parameter3;
        $this->soapUrl = '';
        $this->itemsurl = '';
    }
    /**
     * @param $orderXML
     * @return mixed
     
     */
  
    public function generatSampleOrderXML($orderArr) {
        try{
            // put here create order XML
             $XPost = '';
            return $XPost;
        } catch (Exception $ex) {
            $error = "Error IN function generatSampleOrderXML ".$ex->errorMessage();
        }
    }

    
  /**
     * @param $orderXML
     * @return mixed
     
     
     */
    public function generatSamplegetstatusXML($orderNumber) {
        try{
            // put here create order status XML
            $strXML = '';
            return $strXML;
        } catch (Exception $ex) {
            $error = "Error IN function generatSamplegetstatusXML ".$ex->errorMessage();
        }
    }

    public function createSampleOrder($orderArr) {
        try{
            $OXML = $this->generatSampleOrderXML($orderArr);
            $return = $this->_post($this->soapUrl,$OXML);
            return $return;
        } catch (Exception $ex) {
            $error = "Error IN function createSampleOrder ".$ex->errorMessage();
        }
    }


   
  /**
  
     * @param $orderXML
     * @return mixed
     
     */
  
    public function getSampleOrderstatus($orderNumber) {
        try {
            $OXML= $this->generatSamplegetstatusXML($orderNumber);
            $return = $this->_post($this->soapUrl, $OXML);
            return $return;
        } catch (Exception $ex) {
            $error = "Error IN function getSampleOrderstatus ".$ex->errorMessage();
        }
    }

    
  /**
     *
     * @return mixed
     
     
   
     */
  
    public function getcheckAuthentication() {
        try {
            //put here check Authentication XML
            $XPost = '';
            $return = $this->_post($this->soapUrl,$XPost);
            return $return;
        } catch (Exception $ex) {
            $error = "Error IN function getcheckAuthentication ".$ex->errorMessage();
        }
    }

    /**
    
     * @param $uri
     * @param $XML
     * @return mixed
     
     */
  
    public function _get($uri,$XML) {
        return $this->_call("GET",$uri,$XML);
    }

    /**
    
     * @param $uri
     * @param $XML
     * @return mixed
     
     */
  
    public function _post($uri,$XML) {
        return $this->_call("POST",$uri,$XML);
    }

    /**
    
     * @param $type
     * @param $uri
     * @param $XML
     * @return mixed
     
     */
  
    public function _call($type,$uri,$XML) {
        try {
            if ($XML !== '') {
                ob_clean();
                $ch = curl_init ();
                // Set required CURL options
                curl_setopt ( $ch, CURLOPT_URL, $uri );
                curl_setopt ( $ch, CURLOPT_POST, true );
                curl_setopt ( $ch, CURLOPT_HTTPHEADER, array (
                        'Content-Type: text/xml',
                        'Content-length: ' . strlen( $XML ) 
                ) );
                curl_setopt ( $ch, CURLOPT_RETURNTRANSFER, true );
                curl_setopt ( $ch, CURLOPT_POSTFIELDS, $XML );
                curl_setopt ( $ch, CURLOPT_SSL_VERIFYPEER, false );
                $response = curl_exec($ch);
                $error = curl_error($ch);
                if ($error !== '') {
                    $response = 'Error : ' . $$error;
                } else {
                    $loadxml = simplexml_load_string($response);
                    if ($loadxml === FALSE) {
                        return $response;
                    }
                    $loadxml = simplexml_load_string($response);
                    $loadjson = json_encode($loadxml);
                    $response = json_decode($loadjson, TRUE);
                    return $response;
                }

            } else {
                $response =  'no input';
            }
        } catch ( Exception $e ) {
            $response = 'Error: ' . $e->getMessage ();
        }
        return $response;
    }
}
?>
<?php
  
/*

 * call by following
 * https://company.agiliron.net/agiliron/index.php?action=createTechDataSalesOrder&module=Orders&record=xxxx
 *
 * xxxx is the orderno(PO)
 
 */
  
  
ob_start();
require_once('SampleMiddleware.php');

$parameter1 = $_REQUEST['parameter1'];
$parameter2 = $_REQUEST['parameter2'];
$parameter3 = $_REQUEST['parameter3'];
$sonumber = $_REQUEST['sonumber'];
$startDate = $_REQUEST['startDate'];
$endDate = $_REQUEST['endDate'];
if($parameter1 != '' && $parameter2 != '') {
    $SampleMiddleware = new SampleMiddleware($parameter1,$parameter2,$parameter3);
    $response = $SampleMiddleware->getSOStatus($sonumber, $startDate, $endDate);
    ob_clean();
    echo json_encode($response);
}

?>
<?php


  /*********************************************************************************
 
 
 * Agiliron Inc. (TM) - Accelerate Your Business. On Demand (SM)
 * Support: [email protected], 1-855-AGIL-IRON
 *
 * Portions created by Agiliron are Copyright � 2007-2020 Agiliron Inc. | All Rights Reserved.
 *
 * Unauthorized copying of this file, via any medium is strictly prohibited.
 * Proprietary and Confidential.
 
 
 ********************************************************************************/

 ob_start();
require_once('SampleMiddleware.php');

$parameter1 = $_REQUEST['parameter1'];
$parameter2 = $_REQUEST['parameter2'];
$parameter3 = $_REQUEST['parameter3'];
$responseArr = array();

$sampleMiddleware = new SampleMiddleware($parameter1, $parameter2, $parameter3);
$returnAuth = $sampleMiddleware->checkAuthentication();
if($returnAuth){
    $statusMessage = 'Test connection successful';
    $status = true;
}else{
    $statusMessage = 'Test connection failed';
    $status = false;
}

$responseArr['status'] = $status;
$responseArr['msg'] = $statusMessage;
ob_clean();
echo json_encode($responseArr);
exit;
?>