UPS validation Api wrapper

Author: rgodiyal

.gitignore

@@ -0,0 +1 @@
+vendor/

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Rahul Godiyal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,47 @@
+
+# RahulGodiyal\PhpUpsApiWrapper
+
+API Wrapper for UPS web services.
+
+
+
+
+## Installation
+
+Install with composer
+
+```bash
+  composer install rahul-godiyal/php-ups-api-wrapper
+```
+    
+## Usage/Examples
+
+UPS Address Validation
+```php
+<?php
+
+use RahulGodiyal\PhpUpsApiWrapper\AddressValidation;
+
+require_once('./vendor/autoload.php');
+
+$client_id = "xxxxxxxxxxxxxxxx"; // UPS Client ID
+$client_secret = "xxxxxxxxxxxxxxx"; // UPS Client Secret
+
+// Address to be validated
+$address = [
+    "AddressLine" => [
+        "785 GODDARD CT"
+    ],
+    "PoliticalDivision2" => "ALPHARATTA",
+    "PoliticalDivision1" => "CA",
+    "PostcodePrimaryLow" => "30005",
+    "CountryCode" => "US"
+];
+
+echo '<pre>';
+print_r(AddressValidation::setAddress($address)->validate($client_id, $client_secret));
+echo '</pre>';
+die();
+
+```
+

composer.json

@@ -0,0 +1,19 @@
+{
+    "name": "rahul-godiyal/php-ups-api-wrapper",
+    "description": "API Wrapper for UPS web services",
+    "type": "library",
+    "license": "MIT",
+    "autoload": {
+        "psr-4": {
+            "RahulGodiyal\\PhpUpsApiWrapper\\": "src/"
+        }
+    },
+    "authors": [
+        {
+            "name": "Rahul Godiyal",
+            "email": "[email protected]"
+        }
+    ],
+    "minimum-stability": "stable",
+    "require": {}
+}

demo/validate-address.php

@@ -0,0 +1,23 @@
+<?php
+
+use RahulGodiyal\PhpUpsApiWrapper\AddressValidation;
+
+require_once('./vendor/autoload.php');
+
+$client_id = "xxxxxxxxxxxxxx";
+$client_secret = "xxxxxxxxxxxxxxxx";
+
+$address = [
+    "AddressLine" => [
+        "785 GODDARD CT"
+    ],
+    "PoliticalDivision2" => "ALPHARATTA",
+    "PoliticalDivision1" => "CA",
+    "PostcodePrimaryLow" => "30005",
+    "CountryCode" => "US"
+];
+
+echo '<pre>';
+print_r(AddressValidation::setAddress($address)->validate($client_id, $client_secret));
+echo '</pre>';
+die();

src/AddressValidation.php

@@ -0,0 +1,113 @@
+<?php
+
+namespace RahulGodiyal\PhpUpsApiWrapper;
+
+use RahulGodiyal\PhpUpsApiWrapper\Auth;
+
+class AddressValidation extends Auth
+{
+    private static $_address;
+    private $_request_option;
+    private $_version;
+    private $_query;
+
+    public function __construct()
+    {
+        parent::__construct();
+        $this->_request_option = "3";
+        $this->_version = "v2";
+        $this->_query = [
+            "regionalrequestindicator" => "string",
+            "maximumcandidatelistsize" => "1"
+        ];
+    }
+
+    /**
+     * Set Address to validate
+     * @param array $address
+     * @return self
+     */
+    public static function setAddress(array $address)
+    {
+        self::$_address = $address;
+        return new self;
+    }
+
+    /**
+     * Validate the address
+     * @param string $client_id
+     * @param string $client_secret
+     * @return array of validated address
+     */
+    public function validate(String $client_id, String $client_secret)
+    {
+        $auth = $this->authenticate($client_id, $client_secret);
+
+        if ($auth['status'] == 'fail') {
+            return $auth;
+        }
+
+        $access_token = $auth['access_token'];
+        $curl = curl_init();
+
+        curl_setopt_array($curl, [
+            CURLOPT_HTTPHEADER => [
+                "Authorization: Bearer $access_token",
+                "Content-Type: application/json"
+            ],
+            CURLOPT_POSTFIELDS => json_encode($this->_payload()),
+            CURLOPT_URL => $this->_getAPIBaseURL() . "/api/addressvalidation/" . $this->_version . "/" . $this->_request_option . "?" . http_build_query($this->_query),
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_CUSTOMREQUEST => "POST",
+        ]);
+
+        $response = curl_exec($curl);
+        curl_close($curl);
+        $res = json_decode($response);
+
+        if (!isset($res->XAVResponse)) {
+            $error = $res->response->errors[0]->message;
+            return ['status' => 'fail', 'msg' => $error];
+        }
+
+        $addresses = $this->_getAddresses($res->XAVResponse->Candidate);
+        return ['status' => 'success', 'addresses' => $addresses];
+    }
+
+    /**
+     * Get Payload
+     * @return array $payload
+     */
+    private function _payload()
+    {
+        return [
+            "XAVRequest" => [
+                "AddressKeyFormat" => self::$_address
+            ]
+        ];
+    }
+
+    /**
+     * Get Addresses
+     * @param array of objects
+     * @return array of addresses
+     */
+    private function _getAddresses(Array $candidates)
+    {
+        $addresses = [];
+        foreach ($candidates as $candObj) {
+            $addressObj = $candObj->AddressKeyFormat;
+            $address = [
+                'address_line' => $addressObj->AddressLine,
+                'city' => $addressObj->PoliticalDivision2,
+                'state' => $addressObj->PoliticalDivision1,
+                'zipcode' => $addressObj->PostcodePrimaryLow,
+                'region' => $addressObj->Region,
+                'country' => $addressObj->CountryCode
+            ];
+            array_push($addresses, $address);
+        }
+
+        return $addresses;
+    }
+}

src/Auth.php

@@ -0,0 +1,87 @@
+<?php
+
+namespace RahulGodiyal\PhpUpsApiWrapper;
+
+class Auth
+{
+    private $_mode;
+    private $_dev_api_base_url;
+    private $_prod_api_base_url;
+
+    public function __construct()
+    {
+        $this->_mode = 'DEV';
+        $this->_dev_api_base_url = 'https://wwwcie.ups.com';
+        $this->_prod_api_base_url = 'https://onlinetools.ups.com';
+    }
+
+    /**
+     * Authenticate User
+     * @param string $client_id
+     * @param string $client_secret
+     * @return string $access_token
+     */
+    public function authenticate(String $client_id, String $client_secret)
+    {
+        $curl = curl_init();
+
+        curl_setopt_array($curl, [
+            CURLOPT_HTTPHEADER => [
+                "Content-Type: application/x-www-form-urlencoded",
+                "x-merchant-id: string",
+                "Authorization: Basic " . base64_encode($client_id . ":" . $client_secret)
+            ],
+            CURLOPT_POSTFIELDS => $this->_getPayload(),
+            CURLOPT_URL => $this->_getAPIBaseURL() . "/security/v1/oauth/token",
+            CURLOPT_RETURNTRANSFER => true,
+            CURLOPT_CUSTOMREQUEST => "POST",
+        ]);
+
+        $response = curl_exec($curl);
+        curl_close($curl);
+        $res = json_decode($response);
+
+        if (!isset($res->access_token)) {
+            $error = $res->response->errors[0]->message;
+            return ['status' => 'fail', 'msg' => $error];
+        }
+
+        $access_token = $res->access_token;
+        return ['status' => 'success', 'access_token' => $access_token];
+    }
+
+    /**
+     * Get Payload
+     * @return string
+     */
+    private function _getPayload()
+    {
+        return "grant_type=client_credentials";
+    }
+
+    /**
+     * Set Mode
+     * @param string DEV|PROD
+     */
+    public function setMode(String $mode)
+    {
+        if ($mode === 'PROD') {
+            $this->_mode = $mode;
+        }
+
+        $this->_mode = 'DEV';
+    }
+
+    /**
+     * Get Api Base URL
+     * @return string url
+     */
+    protected function _getAPIBaseURL()
+    {
+        if ($this->_mode === 'PROD') {
+            return $this->_prod_api_base_url;
+        }
+
+        return $this->_dev_api_base_url;
+    }
+}