talon-one/talon-one-client

The Talon.One API is used to manage applications and campaigns, as well as to integrate with your application. The operations in the _Integration API_ section are used to integrate with our platform, while the other operations are used to manage applications and campaigns.

3.4.0 2021-02-14 17:42 UTC

README

Use the Talon.One API to integrate with your application and to manage applications and campaigns:

Determining the base URL of the endpoints

The API is available at the same hostname as your Campaign Manager deployment. For example, if you are reading this page at https://mycompany.talon.one/docs/api/, the URL for the updateCustomerSession endpoint is https://mycompany.talon.one/v2/customer_sessions/{Id}

This PHP package is automatically generated by the OpenAPI Generator project:

  • API version: 1.0.0
  • Package version: 3.4.0
  • Build package: org.openapitools.codegen.languages.PhpClientCodegen

Requirements

PHP 5.5 and later

Installation & Usage

You can use Composer or simply Download the Release

Composer

The preferred method is via composer. Follow the installation instructions if you do not already have composer installed.

Once composer is installed, execute the following command in your project root to install this library:

composer require talon-one/talon-one-client

Finally, be sure to include the autoloader:

require_once '/path/to/your-project/vendor/autoload.php';

Download the Release's source

If you prefer not to use composer, you can download the package in its entirety. The Releases page lists all stable versions. Download the source code of the desired version, or checkout the source code directly from the repository.

Uncompress the zip file you downloaded, and include the autoloader in your project:

require_once '/path/to/talon-one-client/vendor/autoload.php';

Tests

To run the unit tests:

composer install
./vendor/bin/phpunit

Getting Started

Please follow the installation procedure and then run the following:

Integration API

Note: The Integration API's V1 Update customer session and Update customer profile endpoints are now deprecated. Use their V2 instead. See Migrating to V2 for more information.

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Host, API key, & API key prefix for integration authentication
$config = \TalonOne\Client\Configuration::getDefaultConfiguration()
    ->setHost('https://mycompany.talon.one')
    ->setApiKeyPrefix('Authorization', 'ApiKey-v1')
    ->setApiKey('Authorization', 'dbc644d33aa74d582bd9479c59e16f970fe13bf34a208c39d6c7fa7586968468');

// Initiating an integration api instance with the config
$this->apiInstance = new \TalonOne\Client\Api\IntegrationApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default when `null` is passed.
    null, // new YouClientImplementation(),
    $config
);

$customer_session_id = 'customer_session_id_example'; // string | The unique identifier for this session
$customer_session = new \TalonOne\Client\Model\NewCustomerSessionV2([
    'profileId' => 'example_prof_id',
    'couponCodes' => [
        'Cool-Summer!'
    ],
    'cartItems' => [
        new \TalonOne\Client\Model\CartItem([
            'name' => 'Hawaiian Pizza',
            'sku' => 'piz-hw-001',
            'quantity' => 1,
            'price' => 5.85
        ])
    ]
]);
$body = new \TalonOne\Client\Model\IntegrationRequest([
    'customerSession' => $customer_session,
    // Optional list of requested information to be present on the response.
    // See lib/Model/IntegrationRequest.php#getResponseContentAllowableValues for full list
    // 'responseContent' => [
    //     \TalonOne\Client\Model\IntegrationRequest::RESPONSE_CONTENT_CUSTOMER_SESSION,
    //     \TalonOne\Client\Model\IntegrationRequest::RESPONSE_CONTENT_COUPONS
    // ]
]);

try {
    // Create/Update a customer session using `updateCustomerSessionV2` function
    $integration_state = $this->apiInstance->updateCustomerSessionV2($customer_session_id, $body);
    print_r($integration_state);

    // Parsing the returned effects list, please consult https://developers.talon.one/Integration-API/handling-effects-v2 for the full list of effects and their corresponding properties
    foreach ($integration_state->getEffects() as $effect) {
        if ("addLoyaltyPoints" == $effect->getEffectType()) {
            // Initiating right props instance according to the effect type
            $props = new \TalonOne\Client\Model\AddLoyaltyPointsEffectProps((array) $effect->getProps());

            // Access the specific effect's properties
            echo $props->getName(), ':: ', $props->getRecipientIntegrationId(), ' just earned ',  $props->getValue(), ' points', PHP_EOL;
        }
        if ("acceptCoupon" == $effect->getEffectType()) {
            // Initiating right props instance according to the effect type
            $props = new \TalonOne\Client\Model\AcceptCouponEffectProps((array) $effect->getProps());
            // work with AcceptCouponEffectProps' properties
            // ...
        }
    }
} catch (Exception $e) {
    echo 'Exception when calling IntegrationApi->updateCustomerSessionV2: ', $e->getMessage(), PHP_EOL;
}

?>

Management API

<?php
require_once(__DIR__ . '/vendor/autoload.php');


// Configure Host & API key prefix for management authentication
$config = \TalonOne\Client\Configuration::getDefaultConfiguration()
    ->setHost('https://mycompany.talon.one')
    ->setApiKeyPrefix('Authorization', 'Bearer');

// Initiating a management api instance with the config
$apiInstance = new \TalonOne\Client\Api\ManagementApi(
    // If you want use custom http client, pass your client which implements `GuzzleHttp\ClientInterface`.
    // This is optional, `GuzzleHttp\Client` will be used as default when `null` is passed.
    null, // new YouClientImplementation(),
    $config
);

try {
    $loginParams = new \TalonOne\Client\Model\LoginParams([
        'email' => 'admin@talon.one',
        'password' => 'VerySecurePa$$word!'
    ]);

    // create a session (login) in order to get a token
    $session = $apiInstance->createSession($loginParams);

    // Save token in the configuration as API key
    $config->setApiKey('Authorization', $session->getToken());

    $application_id = 7; // int | desired application identifier
    // Calling `getApplication` function
    $application = $apiInstance->getApplication($application_id);
    print_r($application);
} catch (Exception $e) {
    echo 'Exception when calling ManagementApi->getApplication: ', $e->getMessage(), PHP_EOL;
}

?>

Documentation for API Endpoints

All URIs are relative to http://localhost

Class Method HTTP request Description
IntegrationApi createCouponReservation POST /v1/coupon_reservations/{couponValue} Create a new coupon reservation
IntegrationApi createReferral POST /v1/referrals Create a referral code for an advocate
IntegrationApi deleteCouponReservation DELETE /v1/coupon_reservations/{couponValue} Delete coupon reservations
IntegrationApi deleteCustomerData DELETE /v1/customer_data/{integrationId} Delete the personal data of a customer
IntegrationApi getCustomerInventory GET /v1/customer_profiles/{integrationId}/inventory Get an inventory of all data associated with a specific customer profile
IntegrationApi getReservedCustomers GET /v1/coupon_reservations/customerprofiles/{couponValue} Get the users that have this coupon reserved
IntegrationApi trackEvent POST /v1/events Track an Event
IntegrationApi updateCustomerProfileAudiences POST /v2/customer_audiences Update a Customer Profile Audiences
IntegrationApi updateCustomerProfileV2 PUT /v2/customer_profiles/{integrationId} Update a Customer Profile
IntegrationApi updateCustomerProfilesV2 PUT /v2/customer_profiles Update multiple Customer Profiles
IntegrationApi updateCustomerSessionV2 PUT /v2/customer_sessions/{customerSessionId} Update a Customer Session
ManagementApi addLoyaltyPoints PUT /v1/loyalty_programs/{programID}/profile/{integrationID}/add_points Add points in a certain loyalty program for the specified customer
ManagementApi copyCampaignToApplications POST /v1/applications/{applicationId}/campaigns/{campaignId}/copy Copy the campaign into every specified application
ManagementApi createAdditionalCost POST /v1/additional_costs Define a new additional cost
ManagementApi createAttribute POST /v1/attributes Define a new custom attribute
ManagementApi createCampaign POST /v1/applications/{applicationId}/campaigns Create a Campaign
ManagementApi createCoupons POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons Create Coupons
ManagementApi createCouponsForMultipleRecipients POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_with_recipients Create Coupons for Multiple Recipients
ManagementApi createPasswordRecoveryEmail POST /v1/password_recovery_emails Request a password reset
ManagementApi createRuleset POST /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets Create a Ruleset
ManagementApi createSession POST /v1/sessions Create a Session
ManagementApi deleteCampaign DELETE /v1/applications/{applicationId}/campaigns/{campaignId} Delete a Campaign
ManagementApi deleteCoupon DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/{couponId} Delete one Coupon
ManagementApi deleteCoupons DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/coupons Delete Coupons
ManagementApi deleteReferral DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/referrals/{referralId} Delete one Referral
ManagementApi deleteRuleset DELETE /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId} Delete a Ruleset
ManagementApi destroySession DELETE /v1/sessions Destroy a Session
ManagementApi exportCoupons GET /v1/applications/{applicationId}/export_coupons Export Coupons to a CSV file
ManagementApi exportCustomerSessions GET /v1/applications/{applicationId}/export_customer_sessions Export Customer Sessions to a CSV file
ManagementApi exportEffects GET /v1/applications/{applicationId}/export_effects Export triggered Effects to a CSV file
ManagementApi exportLoyaltyBalance GET /v1/loyalty_programs/{programID}/export_customer_balance Export customer loyalty balance to a CSV file
ManagementApi exportLoyaltyLedger GET /v1/loyalty_programs/{programID}/profile/{integrationID}/export_log Export a customer's loyalty ledger log to a CSV file
ManagementApi getAccessLogs GET /v1/applications/{applicationId}/access_logs Get access logs for application (with total count)
ManagementApi getAccessLogsWithoutTotalCount GET /v1/applications/{applicationId}/access_logs/no_total Get access logs for application
ManagementApi getAccount GET /v1/accounts/{accountId} Get Account Details
ManagementApi getAccountAnalytics GET /v1/accounts/{accountId}/analytics Get Account Analytics
ManagementApi getAdditionalCost GET /v1/additional_costs/{additionalCostId} Get an additional cost
ManagementApi getAdditionalCosts GET /v1/additional_costs List additional costs
ManagementApi getAllAccessLogs GET /v1/access_logs Get all access logs
ManagementApi getAllRoles GET /v1/roles Get all roles
ManagementApi getApplication GET /v1/applications/{applicationId} Get Application
ManagementApi getApplicationApiHealth GET /v1/applications/{applicationId}/health_report Get report of health of application API
ManagementApi getApplicationCustomer GET /v1/applications/{applicationId}/customers/{customerId} Get Application Customer
ManagementApi getApplicationCustomers GET /v1/applications/{applicationId}/customers List Application Customers
ManagementApi getApplicationCustomersByAttributes POST /v1/application_customer_search Get a list of the customer profiles that match the given attributes (with total count)
ManagementApi getApplicationEventTypes GET /v1/applications/{applicationId}/event_types List Applications Event Types
ManagementApi getApplicationEvents GET /v1/applications/{applicationId}/events List Applications Events (with total count)
ManagementApi getApplicationEventsWithoutTotalCount GET /v1/applications/{applicationId}/events/no_total List Applications Events
ManagementApi getApplicationSession GET /v1/applications/{applicationId}/sessions/{sessionId} Get Application Session
ManagementApi getApplicationSessions GET /v1/applications/{applicationId}/sessions List Application Sessions
ManagementApi getApplications GET /v1/applications List Applications
ManagementApi getAttribute GET /v1/attributes/{attributeId} Get a custom attribute
ManagementApi getAttributes GET /v1/attributes List custom attributes
ManagementApi getAudiences GET /v1/audiences Get all audiences
ManagementApi getCampaign GET /v1/applications/{applicationId}/campaigns/{campaignId} Get a Campaign
ManagementApi getCampaignAnalytics GET /v1/applications/{applicationId}/campaigns/{campaignId}/analytics Get analytics of campaigns
ManagementApi getCampaignByAttributes POST /v1/applications/{applicationId}/campaigns_search Get a list of all campaigns that match the given attributes
ManagementApi getCampaigns GET /v1/applications/{applicationId}/campaigns List your Campaigns
ManagementApi getChanges GET /v1/changes Get audit log for an account
ManagementApi getCoupons GET /v1/applications/{applicationId}/campaigns/{campaignId}/coupons List Coupons (with total count)
ManagementApi getCouponsByAttributes POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_search Get a list of the coupons that match the given attributes
ManagementApi getCouponsByAttributesApplicationWide POST /v1/applications/{applicationId}/coupons_search Get a list of the coupons that match the given attributes in all active campaigns of an application (with total count)
ManagementApi getCouponsWithoutTotalCount GET /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/no_total List Coupons
ManagementApi getCustomerActivityReport GET /v1/applications/{applicationId}/customer_activity_reports/{customerId} Get Activity Report for Single Customer
ManagementApi getCustomerActivityReports GET /v1/applications/{applicationId}/customer_activity_reports Get Activity Reports for Application Customers (with total count)
ManagementApi getCustomerActivityReportsWithoutTotalCount GET /v1/applications/{applicationId}/customer_activity_reports/no_total Get Activity Reports for Application Customers
ManagementApi getCustomerAnalytics GET /v1/applications/{applicationId}/customers/{customerId}/analytics Get Analytics Report for a Customer
ManagementApi getCustomerProfile GET /v1/customers/{customerId} Get Customer Profile
ManagementApi getCustomerProfiles GET /v1/customers/no_total List Customer Profiles
ManagementApi getCustomersByAttributes POST /v1/customer_search/no_total Get a list of the customer profiles that match the given attributes
ManagementApi getEventTypes GET /v1/event_types List Event Types
ManagementApi getExports GET /v1/exports Get Exports
ManagementApi getLoyaltyPoints GET /v1/loyalty_programs/{programID}/profile/{integrationID} get the Loyalty Ledger for this integrationID
ManagementApi getLoyaltyProgram GET /v1/loyalty_programs/{programID} Get a loyalty program
ManagementApi getLoyaltyPrograms GET /v1/loyalty_programs List all loyalty Programs
ManagementApi getLoyaltyStatistics GET /v1/loyalty_programs/{programID}/statistics Get loyalty program statistics by loyalty program ID
ManagementApi getReferrals GET /v1/applications/{applicationId}/campaigns/{campaignId}/referrals List Referrals (with total count)
ManagementApi getReferralsWithoutTotalCount GET /v1/applications/{applicationId}/campaigns/{campaignId}/referrals/no_total List Referrals
ManagementApi getRole GET /v1/roles/{roleId} Get information for the specified role
ManagementApi getRuleset GET /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId} Get a Ruleset
ManagementApi getRulesets GET /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets List Campaign Rulesets
ManagementApi getUser GET /v1/users/{userId} Get a single User
ManagementApi getUsers GET /v1/users List Users in your account
ManagementApi getWebhook GET /v1/webhooks/{webhookId} Get Webhook
ManagementApi getWebhookActivationLogs GET /v1/webhook_activation_logs List Webhook activation Log Entries
ManagementApi getWebhookLogs GET /v1/webhook_logs List Webhook Log Entries
ManagementApi getWebhooks GET /v1/webhooks List Webhooks
ManagementApi removeLoyaltyPoints PUT /v1/loyalty_programs/{programID}/profile/{integrationID}/deduct_points Deduct points in a certain loyalty program for the specified customer
ManagementApi resetPassword POST /v1/reset_password Reset password
ManagementApi searchCouponsAdvanced POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_search_advanced Get a list of the coupons that match the given attributes (with total count)
ManagementApi searchCouponsAdvancedApplicationWide POST /v1/applications/{applicationId}/coupons_search_advanced Get a list of the coupons that match the given attributes in all active campaigns of an application (with total count)
ManagementApi searchCouponsAdvancedApplicationWideWithoutTotalCount POST /v1/applications/{applicationId}/coupons_search_advanced/no_total Get a list of the coupons that match the given attributes in all active campaigns of an application
ManagementApi searchCouponsAdvancedWithoutTotalCount POST /v1/applications/{applicationId}/campaigns/{campaignId}/coupons_search_advanced/no_total Get a list of the coupons that match the given attributes
ManagementApi updateAdditionalCost PUT /v1/additional_costs/{additionalCostId} Update an additional cost
ManagementApi updateAttribute PUT /v1/attributes/{attributeId} Update a custom attribute
ManagementApi updateCampaign PUT /v1/applications/{applicationId}/campaigns/{campaignId} Update a Campaign
ManagementApi updateCoupon PUT /v1/applications/{applicationId}/campaigns/{campaignId}/coupons/{couponId} Update a Coupon
ManagementApi updateCouponBatch PUT /v1/applications/{applicationId}/campaigns/{campaignId}/coupons Update a Batch of Coupons
ManagementApi updateRuleset PUT /v1/applications/{applicationId}/campaigns/{campaignId}/rulesets/{rulesetId} Update a Ruleset

Documentation For Models

Documentation For Authorization

api_key_v1

  • Type: API key
  • API key parameter name: Authorization
  • Location: HTTP header

integration_auth

  • Type: API key
  • API key parameter name: Content-Signature
  • Location: HTTP header

manager_auth

  • Type: API key
  • API key parameter name: Authorization
  • Location: HTTP header

Author