Skip to main content
knowledgecenter.avangate.com

3rd Party Apps for the Avangate Platform

How do I build apps for the Avangate platform?

  1. Sign-up for an Avangate account
  2. Contact Avangate with your app proposal. 
  3. Avangate reviews your application plan, enables 3rd party apps for your account and creates a placeholder for your app. 
  4. Avangate supplies you with authentication credentials. 
  5. Build your application, integrate and test it with your account. 
  6. Submit your final application for review. 
  7. Avangate evaluates your application. Following the review process, Avangate can offer your app to all customers. 

Installation

Add the following lines of code at the end of the <body> tag.


<script type="text/javascript" src="https://secure.avangate.com/cpanel/js/third-party-apps/avangate.js"></script>
    <div id="avangate-hero" class="hide"></div>

Authentication

Contact Avangate directly to start building applications on top of the Avangate platform. Avangate supplies you with the public and private authentication keys for your application. 

Access requirements

Application authentication tokens work in tandem with user sessions for Avangate accounts. Users need to log into their account for 3rd party applications to have access to their data. Once account users log out, the application token expires and access is removed. By default, authentication tokens expire after one (1) hour.

 

Permanent authentication token

 Contact Avangate to enable this functionality for your application. Once enabled, to make the auth token permanent use the 'permanentToken' parameter. This cases token expiration to grow to one (1) year.

Client side

 

1. Include the script from the Installation section in your JavaScript file you to access a global object called avangateCPanel that you can use for all the methods available in the client side interface.

2. Next, set the PUBLIC_APP_ID and check that the scripts load in your JavaScript file.

 


var app = {
        cPanel  : false,
        appID   : 'PUBLIC_APP_ID',

        init : function()
        {
            this.cPanel = avangateCPanel;
            if (this.cPanel.init(this.appID)) {
                console.log('everything is ready to be used');
            }
        }
    };
    app.init();

3. Check Avangate account login by requesting the auth token via JavaScript.


    var app = {
        cPanel  : false,
        appID   : 'PUBLIC_APP_ID',

        init : function()
        {
            this.cPanel = avangateCPanel;
            if (this.cPanel.init(this.appID)) {
                console.log('everything is ready to be used');
                this.checkLogin();
            }
        },
        checkLogin : function()
        {
            this.cPanel.authentify({
                success: function(response) {
                    var authToken = response.value.authToken;
                },
                error: function(response) {
                    console.log(response.message); // something went wrong
                }
            });
        }
    };
    app.init();
 
4. Send the authToken to your server for validation.
 

var app = {
        cPanel  : false,
        appID   : 'PUBLIC_APP_ID',

        init : function()
        {
            this.cPanel = avangateCPanel;
            if (this.cPanel.init(this.appID)) {
                console.log('everything is ready to be used');
                this.checkLogin();
            }
        },
        checkLogin : function()
        {
            this.cPanel.authentify({
                success: function(response) {
                    var authToken = response.value.authToken; // object {authToken: 'the auth token string', expirationDate: 'the expiration date of the token'}
                    $.when(
                        $http('/validateToken').post(authToken)
                    ).then(
                        function() { //success
                            //user is logged
                        },
                        function() { //fail
                            // check what went wrong in the ajax call
                        }
                    );
                },
                error: function(response) {
                    console.log(response.message); // something went wrong
                }
            });
        }
    };
    app.init();
 

Server side

This example uses Laravel framework and Guzzle Http library


namespace App\Http\Controllers;

use Request;
use GuzzleHttp\Client as httpClient;
use App\Http\Controllers\Controller;

class MainController extends Controller {
    protected $authInfo   = false;
    protected $apiBaseUrl = 'https://apps.api.avangate.com/';

    // verifies and validates the auth token received via javascript
    public function validateToken()
    {
        $this->authInfo = [
            'authToken'         => Request::input('authToken'),
            'expirationDate'    => Request::input('expirationDate'),
        ];

        try {
            $httpClient = $this->getHttpClient();
            $response   = $httpClient->put('verify/');
            // to make the auth token permanent just apply the 'permanentToken' param (token expires in 1 year)
            // contact Avangate to enable this functionality for your app
            //$response = $httpClient->put('verify/', ['body' => ['permanentToken' => 1]]);
        } catch (\Exception $e) {
            $response = $e->getResponse();
        }

        return ($response->json() == true);
    }

    // http client configuration
    private function getHttpClient()
    {
        return new httpClient([
            'base_url'  => $this->apiBaseUrl,
            'timeout'  => 2.0,
            'defaults' => [
                'proxy'     => '',
                'verify'    => false,
                'headers'   => [
                    'authToken' => $this->authInfo['authToken'],
                    'secretID'  => env('APP_SECRET'), // your app secret id
                    'Accept'    => 'application/json'
                ]
            ]
        ]);
    }
}

Get logged user info

This example uses Laravel framework and Guzzle Http library

 


namespace App\Http\Controllers;

use Request;
use GuzzleHttp\Client as httpClient;
use App\Http\Controllers\Controller;

class MainController extends Controller {
    protected $authInfo   = false;
    protected $apiBaseUrl = 'https://apps.api.avangate.com/';

    // verifies and validates the auth token received via javascript
    public function validateToken()
    {
        $this->authInfo = [
            'authToken'         => Request::input('authToken'),
            'expirationDate'    => Request::input('expirationDate'),
        ];

        try {
            $httpClient = $this->getHttpClient();
            $response   = $httpClient->put('verify/');
        } catch (\Exception $e) {
            $response = $e->getResponse();
        }

        if ($response->json() == true) {
            $this->getAuthUserInfo();
        }
    }

    /*
        retrieves the logged user info
        return an array with following structure

        [
            'Email'         => (string),
            'FirstName'     => (string),
            'LastName'      => (string),
            'VendorInfo'    => [
                'ClientCode'        => (string),
                'CompanyName'       => (string),
                'CommercialName'    => (string),
                'Homepage'          => (string)
            ]
        ];
    */
    private function getAuthUserInfo()
    {
        try {
            $httpClient = $this->getHttpClient();
            $response   = $httpClient->get('user_info/');
        } catch (\Exception $e) {
            $response = $e->getResponse();
        }

        return $response->json();
    }

    // http client configuration
    private function getHttpClient()
    {
        return new httpClient([
            'base_url'  => $this->apiBaseUrl,
            'timeout'  => 2.0,
            'defaults' => [
                'proxy'     => '',
                'verify'    => false,
                'headers'   => [
                    'authToken' => $this->authInfo['authToken'],
                    'secretID'  => env('APP_SECRET'), // your app secret id
                    'Accept'    => 'application/json'
                ]
            ]
        ]);
    }
}

Get API data

The API documentation can be found here.

This example uses Laravel framework and Guzzle Http library. From the API we will use the retrieve subscriptions method. 


namespace App\Http\Controllers;

use Request;
use GuzzleHttp\Client as httpClient;
use App\Http\Controllers\Controller;

class MainController extends Controller {
    protected $authInfo   = false;
    protected $apiBaseUrl = 'https://apps.api.avangate.com/';

    // verifies and validates the auth token received via javascript
    public function validateToken()
    {
        $this->authInfo = [
            'authToken'         => Request::input('authToken'),
            'expirationDate'    => Request::input('expirationDate'),
        ];

        try {
            $httpClient = $this->getHttpClient();
            $response   = $httpClient->put('verify/');
        } catch (\Exception $e) {
            $response = $e->getResponse();
        }

        if ($response->json() == true) {
            $this->getSubscriptions();
        }
    }

    private function getSubscriptions()
    {
        try {
            $httpClient = $this->getHttpClient();
            $response   = $httpClient->get('subscriptions/');
        } catch (\Exception $e) {
            $response = $e->getResponse();
        }

        return $response->json();
    }

    // http client configuration
    private function getHttpClient()
    {
        return new httpClient([
            'base_url'  => $this->apiBaseUrl,
            'timeout'  => 2.0,
            'defaults' => [
                'proxy'     => '',
                'verify'    => false,
                'headers'   => [
                    'authToken' => $this->authInfo['authToken'],
                    'secretID'  => env('APP_SECRET'), // your app secret id
                    'Accept'    => 'application/json'
                ]
            ]
        ]);
    }
}

Get ISE data

The ISE (Instant Search Order Export) documentation can be found here.

This example uses Laravel framework and Guzzle Http library


namespace App;

use GuzzleHttp\Client as httpClient;
use Illuminate\Support\Facades\Session;

class Order
{
    private function generateQuery($data = [])
    {
        $authInfo       = Session::get('authInfo');
        $queryParams    = [
            //required
            'APP_CREDENTIALS_TOKEN'     => $authInfo['authToken'],
            'APP_CREDENTIALS_SECRET_ID' => env('APP_SECRET'),

            'STARTDATE'                 => '2015-01-21 00:00:00',
            'ENDDATE'                   => '2015-01-21 00:00:00',
            'ORDERSTATUS'               => 'ALL',
            'REQ_DATE'                  => date('YmdHis'),
            'PRODUCT_ID'                => '',
            'COUNTRY_CODE'              => '',
            'FILTER_STRING'             => '',
            'FILTER_FIELD'              => '',
            'HASH'                      => '',

            //optional
            'INCLUDE_DELIVERED_CODES'   => '',
            'INCLUDE_FINANCIAL_DETAILS' => '',
            'INCLUDE_EXCHANGE_RATES'    => '',
            'INCLUDE_PRICING_OPTIONS'   => '',
            'EXPORT_FORMAT'             => 'XML',
        ];

        $queryParams = array_merge($queryParams, $data);

        return $queryParams;
    }

    public function getOrders($searchParams = [])
    {
        if (!is_array($searchParams)) {
            $searchParams = [];
        }

        $queryParams = $this->generateQuery($searchParams);
        try {
            $httpClient = $this->getHttpClient();
            $response   = $httpClient->post('ise/', [
                'body' => $queryParams
            ]);
        } catch (\Exception $e) {
            $response = $e->getResponse();
        }

        if ($response->getBody()->getContents() != '') {
            $response = $response->xml();
            if (isset($response->RESPONSE_MSG)) {
                return ['success' => false, 'message' => (string)$response->RESPONSE_MSG];
            } else {
                return ['success' => true, 'value' => $response->Orders];
            }
        } else {
            return ['success' => false, 'message' => ''];
        }
    }

    private function getHttpClient()
    {
        return new httpClient([
            'base_url'  => 'https://secure.avangate.com/action/',
            'timeout'  => 2.0,
            'defaults' => [
                'proxy'     => '',
                'verify'    => false,
            ]
        ]);
    }
}

Download mock application

This example uses Laravel framework and Guzzle Http library

 

You can download the app from here.


The app uses an SQLite database for the information and it displays a list of items only if is a valid authentication session in the Avangate Control Panel.

 

Download documentation and mock application 

Click here to download the full documentation, including the mock application, as an archive that you can unpack and run locally.