Skip to content

Commit 64ae564

Browse files
squizzdevsquizzdev
committed
Fixes #6
--README.md Added section to detail the Sender Delivery Notice To Customer API Endpoint and provide a coding example. --APIv1Constants.php Added constanst containing the name of API endpoint for an org to send a delivery notice --APIv1EndpointOrgSendDeliveryNoticeToCustomer.php Created class to handle calling the Squizz API for sending a delivery notice to a customer in the Squizz platform. --APIv1EndpointRunnerRetreiveOrgESDDataProducts.php Fixed coding example for retrieving product data from another organisation to retrieve product data, instead of make model mapping data which was incorrectly copied into this file when previously committed. --APIv1EndpointRunnerSendDeliveryNoticeToCustomer.php Created class to show an example of how to call the SQUIZZ API endpoint for an organisation to send a delivery notice to a customer.
1 parent 6092238 commit 64ae564

5 files changed

+425
-284
lines changed

‎README.md

+157
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,7 @@ If you are a software developer writing a PHP application then we recommend that
2828
* [Retrieve Customer Account Record Endpoint](#retrieve-customer-account-record-endpoint)
2929
* [Send and Procure Purchase Order From Supplier Endpoint](#send-and-procure-purchase-order-from-supplier-endpoint)
3030
* [Send Customer Invoice To Customer Endpoint](#send-customer-invoice-to-customer-endpoint)
31+
* [Send Delivery Notice to Customer Endpoint](#send-delivery-notice-to-customer-endpoint)
3132
* [Create Organisation Notification Endpoint](#create-organisation-notification-endpoint)
3233
* [Import Organisation Data Endpoint](#import-organisation-data-endpoint)
3334
* [Import Organisation Sales Order Endpoint](#import-organisation-sales-order-endpoint)
@@ -1861,6 +1862,162 @@ See the example below on how the call the Send Customer Invoice To Customer endp
18611862
?>
18621863
```
18631864

1865+
### Send Delivery Notice to Customer Endpoint
1866+
1867+
The SQUIZZ.com platform's API has an endpoint that allows an orgnisation to send delivery notices (also known as shipping notices, freight notices, advanced shipping notices) for goods it having delivered to a customer, notifying where the ordered goods are being handled in the dispatch and delivery/shipping process.
1868+
This endpoint allows a supplier organisation to automate the sending out of delivery notices to its customers, allowing either individuals ordering in squizz to receive these notices, as well as allow customer organisations to automate the receiving of delivery notices and importing them back into their own systems.
1869+
Many delivery notices may be sent for the same delivery of ordered goods, containing a status and message outlining where the goods are currently located. This can allow customers to receive many notifications as it progresses. It's up to you to determine how often the customer should be aware of delivery progression.
1870+
- The endpoint relies upon a supplier organisations first importing customer accounts within the SQUIZZ.com platform that the delivery notices are associated to.
1871+
- If the delivery notices needs to be forwarded onto customer organisations, then endpoint either relies upon a connection first being setup between the supplier and customer organisations within the SQUIZZ.com platform, or the supplying organisation setting up a data adaptor to export the customer delivery notices to the customers external system. The first option is preferred since the supplying org then doesn't need to know what system the customer organisation is running.
1872+
- The endpoint has a number of other requirements. See the endpoint documentation for more details on these requirements.
1873+
1874+
Each delivery notice needs to be imported within a "Ecommerce Standards Document" that contains a record for each delivery notice. Use the Ecommerce Standards library to easily create these documents and records.
1875+
It is recommended to only import one delivery notice at a time, since if an array of delivery notice is imported and one notice failed to import, then no other notices in the list will be attempted to import.
1876+
Read [https://www.squizz.com/docs/squizz/Platform-API.html#section1550](https://www.squizz.com/docs/squizz/Platform-API.html#section1550) for more documentation about the endpoint and its requirements.
1877+
See the example below on how the call the Send Delivery Notice To Customer endpoint. Note that a session must first be created in the API before calling the endpoint.
1878+
1879+
```php
1880+
<?php
1881+
require_once __DIR__ . '/../../../../../3rd-party/jsonmapper/JsonMapper/Exception.php';
1882+
1883+
//set automatic loader of the library's classes
1884+
spl_autoload_register(function($className) {
1885+
$className = ltrim($className, '\\');
1886+
$fileName = '';
1887+
$namespace = '';
1888+
if ($lastNsPos = strripos($className, '\\')) {
1889+
$namespace = substr($className, 0, $lastNsPos);
1890+
$className = substr($className, $lastNsPos + 1);
1891+
$fileName = str_replace('\\', DIRECTORY_SEPARATOR, $namespace) . DIRECTORY_SEPARATOR;
1892+
}
1893+
$fileName .= str_replace('_', DIRECTORY_SEPARATOR, $className) . '.php';
1894+
1895+
$apiNamespace = "squizz\\api\\v1";
1896+
$esdNamespace = "EcommerceStandardsDocuments";
1897+
$esdInstallPath = "/opt/squizz/esd-php-library/src/";
1898+
1899+
//set absolute path to API php class files
1900+
if(substr($namespace, 0, strlen($apiNamespace)) === $apiNamespace){
1901+
$fileName = $_SERVER['DOCUMENT_ROOT']. '/src/' . $fileName;
1902+
}
1903+
//set absolute path to ESD library files
1904+
else if(substr($namespace, 0, strlen($esdNamespace)) === $esdNamespace){
1905+
$fileName = $esdInstallPath . $fileName;
1906+
}
1907+
1908+
require $fileName;
1909+
});
1910+
1911+
use squizz\api\v1\endpoint\APIv1EndpointResponse;
1912+
use squizz\api\v1\endpoint\APIv1EndpointResponseESD;
1913+
use squizz\api\v1\endpoint\APIv1EndpointOrgSendDeliveryNoticeToCustomer;
1914+
use squizz\api\v1\APIv1OrgSession;
1915+
use squizz\api\v1\APIv1Constants;
1916+
use EcommerceStandardsDocuments\ESDRecordDeliveryNotice;
1917+
use EcommerceStandardsDocuments\ESDocumentConstants;
1918+
use EcommerceStandardsDocuments\ESDocumentDeliveryNotice;
1919+
1920+
//obtain or load in an organisation's API credentials, in this example from command line arguments
1921+
$orgID = $_GET["orgID"];
1922+
$orgAPIKey = $_GET["orgAPIKey"];
1923+
$orgAPIPass = $_GET["orgAPIPass"];
1924+
$customerOrgID = $_GET["customerOrgID"];
1925+
$supplierAccountCode = $_GET["supplierAccountCode"];
1926+
$useDeliveryNoticeExport = ($_GET["useDeliveryNoticeExport"] == ESDocumentConstants::ESD_VALUE_YES? true: false);
1927+
1928+
$sessionTimeoutMilliseconds = 60000;
1929+
1930+
echo "<div>Making a request to the SQUIZZ.com API</div><br/>";
1931+
1932+
//create an API session instance
1933+
$apiOrgSession = new APIv1OrgSession($orgID, $orgAPIKey, $orgAPIPass, $sessionTimeoutMilliseconds, APIv1Constants::SUPPORTED_LOCALES_EN_AU);
1934+
1935+
//call the platform's API to request that a session is created
1936+
$endpointResponse = $apiOrgSession->createOrgSession();
1937+
1938+
//check if the organisation's credentials were correct and that a session was created in the platform's API
1939+
$result = "FAIL";
1940+
$resultMessage = "";
1941+
if($endpointResponse->result != APIv1EndpointResponse::ENDPOINT_RESULT_SUCCESS)
1942+
{
1943+
//session failed to be created
1944+
$resultMessage = "API session failed to be created. Reason: " . $endpointResponse->result_message . " Error Code: " . $endpointResponse->result_code;
1945+
}
1946+
1947+
//send the delivery notice if the API was successfully created
1948+
if($apiOrgSession->sessionExists())
1949+
{
1950+
//create customer invoice record to import
1951+
$deliveryNoticeRecord = new ESDRecordDeliveryNotice();
1952+
1953+
//set data within the delivery notice
1954+
$deliveryNoticeRecord->keyDeliveryNoticeID = "DN123";
1955+
$deliveryNoticeRecord->deliveryNoticeCode = "CUSDELNUM-123-A";
1956+
$deliveryNoticeRecord->deliveryStatus = ESDocumentConstants::DELIVERY_STATUS_IN_TRANSIT;
1957+
$deliveryNoticeRecord->deliveryStatusMessage = "Currently en-route to receiver.";
1958+
1959+
//set information about the freight carrier currently performing the delivery
1960+
$deliveryNoticeRecord->freightCarrierName = "ACME Freight Logistics Inc.";
1961+
$deliveryNoticeRecord->freightCarrierCode = "ACFLI";
1962+
$deliveryNoticeRecord->freightCarrierTrackingCode = "34320-ACFLI-34324-234";
1963+
$deliveryNoticeRecord->freightCarrierAccountCode = "VIP00012";
1964+
$deliveryNoticeRecord->freightCarrierConsignCode = "42343-242344";
1965+
$deliveryNoticeRecord->freightCarrierServiceCode = "SUPER-SMART-FREIGHT-FACILITATOR";
1966+
$deliveryNoticeRecord->freightSystemRefCode = "SSFF-3421";
1967+
1968+
// add references to other records (sales order, customer invoice, purchase order, customer account) that this delivery is associated to
1969+
$deliveryNoticeRecord->keyCustomerInvoiceID = "4";
1970+
$deliveryNoticeRecord->customerInvoiceCode = "CINV-22";
1971+
$deliveryNoticeRecord->customerInvoiceNumber = "22";
1972+
$deliveryNoticeRecord->keySalesOrderID = "121-332";
1973+
$deliveryNoticeRecord->salesOrderCode = "SSO-332-ABC";
1974+
$deliveryNoticeRecord->salesOrderNumber = "332";
1975+
$deliveryNoticeRecord->purchaseOrderCode = "PO-345";
1976+
$deliveryNoticeRecord->purchaseOrderNumber = "345";
1977+
$deliveryNoticeRecord->instructions = "Please leave goods via the back driveway";
1978+
$deliveryNoticeRecord->keyCustomerAccountID = "1";
1979+
1980+
// set where the delivery is currently located geographically
1981+
$deliveryNoticeRecord->atGeographicLocation = ESDocumentConstants::ESD_VALUE_YES;
1982+
$deliveryNoticeRecord->locationLatitude = -37.8277324706811;
1983+
$deliveryNoticeRecord->locationLongitude = 144.92382897158126;
1984+
1985+
//create delivery notice records list and add delivery notice to it
1986+
$deliveryNoticeRecords = array();
1987+
array_push($deliveryNoticeRecords, $deliveryNoticeRecord);
1988+
1989+
//after 60 seconds give up on waiting for a response from the API when sending the delivery notice
1990+
$timeoutMilliseconds = 60000;
1991+
1992+
//create delivery notice Ecommerce Standards document and add delivery notice records to the document
1993+
$deliveryNoticeESD = new ESDocumentDeliveryNotice(ESDocumentConstants::RESULT_SUCCESS, "successfully obtained data", $deliveryNoticeRecords, array());
1994+
1995+
//send delivery notice document to the API for sending onto the customer organisation
1996+
$endpointResponseESD = APIv1EndpointOrgSendDeliveryNoticeToCustomer::call($apiOrgSession, $timeoutMilliseconds, $customerOrgID, $supplierAccountCode, $useDeliveryNoticeExport, $deliveryNoticeESD);
1997+
1998+
//check the result of sending the delivery notice
1999+
if($endpointResponseESD->result == APIv1EndpointResponse::ENDPOINT_RESULT_SUCCESS){
2000+
$result = "SUCCESS";
2001+
$resultMessage = "Organisation delivery notice(s) have successfully been sent to customer.";
2002+
2003+
}else{
2004+
$result = "FAIL";
2005+
$resultMessage = "Organisation delivery notice failed to be processed. Reason: " . $endpointResponseESD->result_message . " Error Code: " . $endpointResponseESD->result_code . "<br/>";
2006+
}
2007+
}
2008+
2009+
//next steps
2010+
//call other API endpoints...
2011+
//destroy API session when done...
2012+
$apiOrgSession->destroyOrgSession();
2013+
2014+
echo "<div>Result:<div>";
2015+
echo "<div><b>$result</b><div><br/>";
2016+
echo "<div>Message:<div>";
2017+
echo "<div><b>$resultMessage</b><div><br/>";
2018+
?>
2019+
```
2020+
18642021
### Create Organisation Notification Endpoint
18652022
The SQUIZZ.com platform's API has an endpoint that allows organisation notifications to be created in the platform. allowing people assigned to an organisation's notification category to receive a notification.
18662023
This can be used to advise such people of events happening external to the platform, such as sales, enquires, tasks completed through websites and other software.

‎src/squizz/api/v1/APIv1Constants.php

+6-1
Original file line numberDiff line numberDiff line change
@@ -90,7 +90,12 @@ class APIv1Constants
9090
/**
9191
* name of the platform's API endpoint to call to send a customer invoice from a supplier organisation to a customer organisation
9292
*/
93-
const API_ORG_ENDPOINT_SEND_CUSTOMER_INVOICE_TO_CUSTOMER = "send_customer_invoice_to_customer";
93+
const API_ORG_ENDPOINT_SEND_CUSTOMER_INVOICE_TO_CUSTOMER = "send_customer_invoice_to_customer";
94+
95+
/**
96+
* name of the platform's API endpoint to call to send a delivery from a supplier organisation to a customer organisation or person
97+
*/
98+
const API_ORG_ENDPOINT_SEND_DELIVERY_NOTICE_TO_CUSTOMER = "send_delivery_notice_to_customer";
9499

95100
/**
96101
* name of the endpoint attribute in the API endpoint response that contains the result code

‎src/squizz/api/v1/endpoint/APIv1EndpointOrgSendDeliveryNoticeToCustomer.php

+83
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,83 @@
1+
<?php
2+
/**
3+
* Copyright (C) Squizz PTY LTD
4+
* This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
5+
* 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.
6+
* You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
7+
*/
8+
namespace squizz\api\v1\endpoint;
9+
require_once __DIR__ . '/../../../../../3rd-party/jsonmapper/JsonMapper.php';
10+
11+
use squizz\api\v1\APIv1Constants;
12+
use squizz\api\v1\APIv1HTTPRequest;
13+
use squizz\api\v1\APIv1OrgSession;
14+
use squizz\api\v1\endpoint\APIv1EndpointResponseESD;
15+
use EcommerceStandardsDocuments\ESDocument;
16+
use EcommerceStandardsDocuments\ESDocumentConstants;
17+
use EcommerceStandardsDocuments\ESDocumentDeliveryNotice;
18+
use \JsonMapper;
19+
use \JsonMapper\Exception;
20+
21+
/**
22+
* Class handles calling the SQUIZZ.com API endpoint to send one more of an organisation's delivery notices to the platform, where they are then sent to a customer person, or organisation (optionally for importing and processing)
23+
* This endpoint allows the notifications of ordered goods from a supplying organisation logged into the API session, to be sent their chosen customer on squizz. These notices can advise how the goods are tracking through dispatch and delivery processes.
24+
*/
25+
class APIv1EndpointOrgSendDeliveryNoticeToCustomer
26+
{
27+
/**
28+
* Calls the platform's API endpoint to push up a delivery notice and have it be sent to a connected customer organisation or person
29+
* @param apiOrgSession existing organisation API session
30+
* @param endpointTimeoutMilliseconds amount of milliseconds to wait after calling the the API before giving up, set a positive number
31+
* @param customerOrgID unique ID of the customer organisation in the SQUIZZ.com platform
32+
* @param supplierAccountCode code of the customer organisation's supplier account. Supplier account only needs to be set if the customer organisation has assigned multiple accounts to the supplier organisation logged into the API session (supplier org)
33+
* @param useDeliveryNoticeExport if true then after the delivery notice is imported into Squizz it will be exported across to another system, using Customer Delivery Notice data export configured with the default data adaptor
34+
* @param esDocumentDeliveryNotice Delivery Notice Ecommerce Standards Document that contains one or more delivery notice records
35+
* @return response response from calling the API endpoint containing a Ecommerce Standards Document enclosed within it
36+
*/
37+
public static function call($apiOrgSession, $endpointTimeoutMilliseconds, $customerOrgID, $supplierAccountCode, $useDeliveryNoticeExport, $esDocumentDeliveryNotice)
38+
{
39+
$requestHeaders = array();
40+
$endpointResponse = new APIv1EndpointResponseESD();
41+
42+
try{
43+
//set request parameters
44+
$endpointParams = "customer_org_id=". urlencode(utf8_encode($customerOrgID)) . "&supplier_account_code=".urlencode(utf8_encode($supplierAccountCode)) . "&use_delivery_notice_export=" . ($useDeliveryNoticeExport? ESDocumentConstants::ESD_VALUE_YES: ESDocumentConstants::ESD_VALUE_NO);
45+
46+
//set function used to read the response from the endpoint
47+
$endpointJSONReader = function($jsonArray, $endpointResponse){
48+
$endpointResponse->jsonDeserialize($jsonArray);
49+
50+
//deserialize array into delivery notice ESD
51+
$jsonMapper = new JsonMapper();
52+
$jsonMapper->bEnforceMapType = false;
53+
$esDocumentDeliveryNotice = $jsonMapper->map($jsonArray, new ESDocumentDeliveryNotice());
54+
55+
//add ESDocument to endpoint response and return the response
56+
$endpointResponse->esDocument = $esDocumentDeliveryNotice;
57+
return $endpointResponse;
58+
};
59+
60+
//make a HTTP request to the platform's API endpoint to send the ESD containing the delivery notices
61+
$endpointResponse = APIv1HTTPRequest::sendESDocumentHTTPRequest(APIv1Constants::HTTP_REQUEST_METHOD_POST, APIv1Constants::API_ORG_ENDPOINT_SEND_DELIVERY_NOTICE_TO_CUSTOMER . APIv1Constants::API_PATH_SLASH . $apiOrgSession->getSessionID(), $endpointParams, $requestHeaders, "", $esDocumentDeliveryNotice, $endpointTimeoutMilliseconds, $apiOrgSession->getLangBundle(), $endpointJSONReader, $endpointResponse);
62+
63+
//check that the data was successfully pushed up
64+
if(strcasecmp($endpointResponse->result, APIv1EndpointResponse::ENDPOINT_RESULT_SUCCESS) != 0)
65+
{
66+
//check if the session still exists
67+
if(strcasecmp($endpointResponse->result, APIv1EndpointResponse::ENDPOINT_RESULT_CODE_ERROR_SESSION_INVALID) != 0){
68+
//mark that the session has expired
69+
$apiOrgSession->markSessionExpired();
70+
}
71+
}
72+
}
73+
catch(Exception $ex)
74+
{
75+
$endpointResponse->result = APIv1EndpointResponse::ENDPOINT_RESULT_FAILURE;
76+
$endpointResponse->result_code = APIv1EndpointResponse::ENDPOINT_RESULT_CODE_ERROR_UNKNOWN;
77+
$endpointResponse->result_message = $apiOrgSession->getLangBundle()->getString($endpointResponse->result_code) . "\n" . $ex.getMessage();
78+
}
79+
80+
return $endpointResponse;
81+
}
82+
}
83+
?>

0 commit comments

Comments
 (0)