User Guide for uGiftCert - marketplace.magento.com€¦ · Unirgy's gift certificate extension is a...

User Guide for uGiftCert ®

uGiftCert ® by Unirgy ®

User Guide

for Magento 1

UNIRGY

UGIFTCERT ® FOR MAGENTO 1 | VERSION 1.1 | © UNIRGY ®

2

TABLE OF CONTENTS

INTRODUCTION ............................................................................................................. 3 GLOBAL UGIFTCERT CONFIGURATION ............................................................... 5 USING UGIFTCERT ..................................................................................................... 19 IMPORTING CERTIFICATES .................................................................................... 24 PDF PRINTOUTS .......................................................................................................... 29 UGIFTCERT AND CONDITIONS .............................................................................. 35 UGIFTCERT EXTERNAL API .................................................................................... 38


3

Introduction

Unirgy's gift certificate extension is a proven, flexible, fully featured gift card management system for Magento.

uGiftCert will allow you to own your data and to never pay a transaction fee for your gift certificates while boosting your online revenue. It is simple to integrate and manage and convenient for your shoppers to use when purchasing gift certificates from your store.

Features

• Create or import Gift Certificates (GC) to be purchased from your store(s)

• Offer fixed or selectable ranges of value denominations

• Full support for virtual or physical GCs

• Allow you customers to supply custom gift messages to be included on GCs

• GCs could be delivered via email or physical mail

• Virtual GC delivery can be scheduled by shopper or auto-delivered at the time of purchase

• Limit GC usage to specific stores, categories, SKUs or customer groups

• Customize your branded certificate template

• Customer can purchase multiple GCs per order

• Unique GC sequence numbers and pins based on configurable patterns

• Generate multiple GCs at once from the Administrative interface

• Shoppers can check GC balance from within their account or dedicated webpage

• Access certificate data with external API

• Ability to import all GC data from external sources

• Attach PDF version of certificate to emails or download printout from the admin interface

• Assign cart sales conditions for GC sales


4

• Comprehensive reporting on GC usage

• Refunds of GC funds are returned to GC accounts

• Configuration option to limit use of coupons with GCs

• 1 Year of Free Unlimited Support


5

Global uGiftCert Configuration Main configuration of uGiftCert can be found in System → Configuration → Customer section, Gift Certificates tab.

Entire configuration tab consists of 5 groups:

§ Defaults

§ Gift certificate totals

§ Gift certificate customer interface on catalog product view

§ Email delivery options

§ Physical delivery options

§ Administrative Configuration

We will cover all sections.


6

Defaults

Auto generate certificate number

If set to Yes all certificate codes will be auto-generated. If set to No, admin user will need to go to Customers → Gift Certificates menu and set certificate code manually before the certificate could be used. There is a chance that if payment for certificate order is received before code is set the customer will receive gift certificate email without certificate code. Generally it is recommended to auto generate codes.


7

Certificate number pattern

Simple pattern expression used for certificate code generation.

Use PIN

Should PINs be used for customer gift certificates balance checking. Is it used for anything else?

Auto generate PIN

Should PIN be auto generated or input by admin user (similar to Auto generate certificate number setting)?

PIN pattern

Simple pattern expression used for PIN generation

Default status


8

Default status for when certificate is generated - pending means certificate is valid, but cannot be used yet, active means certificate is valid and can be used, inactive means certificate cannot be used anymore.

Change status to active on payment completion

Should certificate status be changed to active automatically when payment is received? If set to No then certificates will have to be enabled manually.


9

Amount values configuration

Default certificate amounts. This setting can be overridden on by certificate basis. If using single value, make sure that it is just the value without semicolons or any other character following it. If using currency coded setting make sure you have at least 2 rows set. Setting only USD: 25; 50; 100 by it self will produce 3 prices with $0 for first entry. Generally if you use one currency then you should not use currency coding.

Default Expiration Timespan (in days)


10

Period after certificate creation during which certificate can be used. This setting can be overridden on by certificate basis on certificate management page. Is it possible to set this on by product basis???

Use certificate conditions

Enable usage of conditions similar to shopping cart coditions, which determine if certificate can be used with current cart items. These conditions can be set on per Gift Certificate product or per Certificate basis.

Add certifcate info to order details

This allows to add information for purchased and redeemed certifcates to order data. Mostly useful if you want to integrate this data with external accounting system.

Domains included in your license

Comma separated list of domains that the license of Giftcert is valid for.

Allow only one certificate per order (Single mode)


11

Enable this if you want to allow to your customers to be able to use only one certificate per order.

Error message in single mode

You can customize what is shown to customers when they try to use more than one certificate, when this is not allowed.

Disallow coupons with certifcates

Enable this when you want to prevent coupons and certifcates from being used together. This may not work out of the box with 3rd party checkout modules.

Error message when coupons are not allowed

Customize/translate error message here

Check certificate store

Enable this to limit certificate usage only to the store that is assigned to the certificate.


12

Gift certificate totals

As a beta feature this allows to exclude some totals from what certifcate covers from order totals

In case for example you don't want shipping to be paid with certifcates, you can select it in above list and it will be excluded from calcuations.

Gift certificate customer interface on catalog product view

Allow multiple recipients


13

Experimental. Enable to allow adding multiple certificates to different recipients from same product. All added certificates will have same settings, except for sender and recipient data.

Allow custom message

Allow custom gift message that will be attached to confirmation email. If physical shipping is used, store owner has to take care of printing out the message. What html are tags allowed???

Custom message max length

Maximum message length.

Enable custom message preview

Deprecated

Provide real time message preview. If Yes then text sample is shown above product image.

This setting will probably be removed as it does not show reliable preview, do not rely on it and best leave it to 'No'

Display full totals info in cart

If set to No then Gift Certificate applied in cart is allowed to be removed and its code is displayed.

Use customer group limitation


14

Enable this to have certifiate usage limited to specified customer group. Customer groups are specified in certificates or certificate products.

Balance check URL

Set this to whatever URL path fits your SEO or store needs. The page will show balance check form regardless of customer being logged in or not.

Email delivery options

Enable email notifications

Set this to Yes to have email notifications at all.

Allow recipient's email


15

If set to Yes customer will be allowed to fill in another recipient email address so that when order is completed, the other person receives Gift Certificate email straight away. If set to No and buyer wants to buy GC for someone else, she will need to manually forward details to that person, or use physical address for shipping.

Send new GC confirmation

When to send GC confirmation email

1. On order completion - right after order is placed, or

2. On payment completion - after payment is made or

3. Never - (send confirmation manually).

Beware that if you set this to On order completion buyer can get Gift Certificate details before paying for it. Best to use this option if your payment method submits order after receiving payment. If set to Never no notifications will be sent

Allow scheduled sending

Enable schedule for certifcates. If this is set to 'Yes', customers will get a calendar widget via which they can choose a date for sending certifcate. For this to work, Magento cron jobs must be configured and running for the site.

Gift Certificate Email Sender

Email contact on whose behalf GC emails will be sent. Configurable in System→Configuration→General→Store Email Addresses

Gift Certificate Email Template for Someone Else


16

Transactional email template to be used when GC is bought for someone else but the customer. This and above setting templates can be edited in Transactional email menu. You can edit template files directly, but this is not recommended because your changes will be lost upon extension update. Since in v.2 we have opted for explicit sender and recipient names, we only need one email template. Template for someone else has fileds for both sender and recipient and is more suitable that template for self was. Name of this field will probably be changed to only Gift Certificate Email Temaplate

Enable PDF printouts

Enable PDF printouts for certificates. If set to Yes, PDFs will be generated and attached to each certifcate email.

Gift Certificate PDF Template

Default PDF template to use. PDF templates can be set per store, per product and per certifcate level. If certifcate does not have a template assigned, it will use default one for its store. When gift products are sold, their PDF template setting is inherited by created certifcates. If product does not have a template configured, then store template is used.

PIN format for email confirmations

Text format to be used for representing PIN code in customer email.

Enable email and PDF variants

This feature is available only in Pro add-on, if it is enabled customers will be able to choose from variations of certifcate looks. These variations are configured by admin in product settings.


17

Delivery options

Allow recipient's address

If set to yes and recipient address is provided, then order process will be conducted as per simple product type (a product that has physical representation and needs to be shipped to customer). If this is No then gift certificates will always be treated as virtual products, that don't need to be shipped.

Always handle GC as virtual products

If set to 'Yes' then products will always be treated as virtual and no shipping will be calculated during checkout. Still if “Allow recipient's address” is “Yes”, customer will be able to fill in recipient physical address.

Recipient address options

Select how to provide recipient address

§ Use customer entry means that user will enter recipient email or physical address.

§ Use billing address means to use checkout billing address for recipient addresses.

§ Use shipping address means to use shipping address. It is usable only if certificate product is not virtual.

If only selected option is billing or shipping address, that will effectively send the certificate to the customer who byes it. This is equivalent to previous send to my self option.

If you would like to provide customer with option to choose to send to him self or to someone else, select both billing address and customer entry, this will present customer with dropdown to choose from.

Sender address options

Select how to provide sender address

§ Use customer entry means that user will enter sender email or physical address.

§ Use billing address means to use checkout billing address for sender addresses.

§ Use shipping address means to use shipping address. It is usable only if certificate product is not virtual.


18

Always handle GC as virtual products

If set to Yes GC will always be treated as virtual products regardless if above setting is set to Yes and recipient address is provided.

Administrative Configuration

Subscribe for extension update notifications

If set to Yes store will receive notification whenever new extension version is available, the same type of notifications as per new Magento releases


19

Using uGiftCert Gift Certificate products

Gift certificate products (GC) are created in the same way any other product is created. Only difference is how do you setup prices and some specific to Gift Certificate attributes. To show Gift Certificate product on frontend, its inventory settings should allow this - both add some QTY and set it to be in stock, or set it not to manage stock. Next you should assign the product to a category where it will be listed. Price details of Gift Certificate products can be edited from product's Price tab. Gift Certificate specific attributes are on Gift Certificate settings tab. There you can decide which email template will current product use and which PDF template too. When installing Gift Certificate module you get 4 predefined PDF templates with matching email templates. Plus you have default template files in locale folders.

Gift certificate pricing configuration

Gift Certificate (Gift Certificate) pricing can be set either globally for entire store, or per product. In both cases setting is called 'Gift Certificate Amount Configuration' This setting can be configured in 4 different ways.

1. You can allow only fixed price certificates; in this case you simply set your desired price, for example 10

2. You can allow customers to choose from list of options, you set them as a row with numeric values separated by semicolon (;), for example 10;20;30;40;50. Amounts can have fractions.

3. You can allow for a range of amounts, with low and high limit. You set these using low values-high value, for example, 10-50 will allow for minimum of $10 and maximum of $50

4. You can allow for any value by giving only a dash (-), example, -

If your store uses multiple currencies you can do different options for different currencies. For this purpose you prefix each currency code to one row of values. For example if you have store, which sells in US, Canada and EU, you can have one set of prices for US and Canada and different for EU:

USD,CAD: 50;100;200 EU: 60;120;240


20

You can have more than one currency per row. Currency string is separated by price values with : (colons) You can use each pricing type with currency prefixes, and even mix types for different currencies:

USD,CAD: 50;100;200 EU: 60-‐240

In above case, US and Canada customers will get a dropdown, and EU customers will get a range option.

Support for virtual or physical Gift Certificates

Gift Certificate (Gift Certificate) products can be treated either as simple or virtual products. In first case, shipping will need to be calculated and in second case, it will not be calculated. You allow for either or both options in main settings for Gift Certificate. In case that both options are allowed, your customers will be presented with option to choose which type of delivery to use, by e-mail or physical (post mail) If just one of the options is enabled, then only its form will be shown. If none is enabled, then virtual (e-mail) option form is shown, however emails will not be sent if this is not explicitly set in admin. When customer uses virtual option, they will be required to fill in recipient name and email, however sender email and name could be empty, they are not required for the email to be sent. When physical option is used, recipient name is still required but instead physical address needs to be filled in. NB: even though customer can fill in recipient address here, shipping charges will be calculated based on shipping address used during checkout. It is not currently possible to use address from product page to calculate shipping cost.

Setup Gift Certificate delivery type

To allow only for physical sending, you need to enable physical mail address in main settings and disable email sending in:


21

To do the opposite, enable “Enable email notifications” and “Allow recipient's email” and disable “Allow recipient's address”


22

To enable both, set both settings to 'Yes'

Allow you customers to supply custom gift messages to be included on Gift Certificates

If enabled in main settings, customers can add message that can be included in email and PDF templates. Message length is limited to 320 characters. No formatting is supported.

Virtual Gift Certificate delivery can be scheduled by shopper or auto-delivered at the time of purchase

If enabled in main settings, customers can schedule sending of virtual messages on a later date. This is done using Magento built in calendar widget. Sending it self is performed via cron script. So for this feature to work you need to enable cron jobs for your store.

Limit Gift Certificate usage to specific stores, categories, SKUs or customer groups

Customize your branded certificate template

Customer can purchase multiple Gift Certificates per order

Generate multiple Gift Certificates at once from the Administrative interface

Shoppers can check Gift Certificate balance from within their account or dedicated webpage

Canceling Purchased certificate

To cancel purchased Gift Certificate without canceling the order, you should edit the certificate in admin and set it to be in Inactive state. Canceling an order, which purchases certificates, will put them in inactive state automatically.

Refunding certificates

If an order, which involves gift certificates, is canceled, then all purchased with it certificates are set in inactive state. All certificates that were used to pay for the order get their amounts restored.

If such order is credited instead, the same things happen to certificates.

Redeeming certificates

By default certificates can be redeemed via coupon box on cart page. With v.2.x there is the option to have a dedicated field that can be used to redeem certificates. To use it you need to update corresponding page layout. For example for default cart page:


23

<checkout_cart_index> <reference name="checkout.cart"> <block type="core/template" name="checkout.cart.ugiftcert" as="ugiftcert" template="unirgy/giftcert/cart/form.phtml"/> </reference> </checkout_cart_index>

Then if corresponding template of parent block does not automatically render all its children you should do:

<?php echo $this-‐>getChildHtml('ugiftcert') ?>

If page renders all its child elements, then 'ugiftcert' block will be rendered too and the above code does not need to go in parent template.

Gift Certificate payment method

Gift certificate payment method cannot be chosen as option directly. It only becomes available when customer pays for entire order with certificate. Since Magento does not allow using multiple payment methods per order, it is not possible to use certificates themselves as payment methods, unless 100% of order value is covered. Status of orders paid with certificates depends on setting in System » Configuration » Payment Methods » Gift certificate. Recognized options are 'pending', 'processing' or 'complete', if it is 'processing' or 'complete' an invoice will be generated otherwise it will not be generated.

Limiting module to specific domains

You can explicitly allow domains in main settings of the module:

Enter babywit.com and only it will be considered. The module will not be disabled for other modules, only some of it features. So you should make sure to not allow gift products to be assigned to that domain.


24

Importing certificates With this feature it is possible to import pre-created certificates into the system.

Using import

Import page can be reached via Customers→Gift Certificates→Gift Certificate Import

The page itself is very simple to use. You can edit your settings and save them, or you can edit and click 'Save and Import' button to perform the import. Simply clicking that button without any changes will result in an import in case that the file you have inputted exists. Files used for import should be in CSV format (Comma Separated Values). This format represents plain text files where first row gives column names and every next row gives column values. Fields are separated by separator character and optionally surrounded with enclosure character. By default separator is comma (,) and enclosing character is double quote (“). You can change this on import page.


25

Settings that you can change are:

1. CSV field delimiter - this is field separator character

2. CSV field enclosure - this is enclosure character, you may omit it if the field text does not contain the separator character

3. CSV file name - file name of the file to be used for import. You have the option to upload many import files, either to create new certificates or update existing ones. With this option you can choose which of the uploaded files to import.

4. When importing allow only: - this field allows to choose whether to only create new certificates (you can simply add your new data to existing file), only update existing certificates or do both.

Bellow settings form is an upload widget, the same as the one used to upload product images. It allows you to select multiple files to upload, which can be time saver. The widget is set to allow filtering by file type (.txt and .csv files) which will help if you have to look for import files in a big folder with many files in it. It also allows only txt and csv file types to be actually saved to server. Files are saved in var/ugiftcert/import folder of the website. As for any other Magento installation you should make sure that var/ folder is writable by web-server.


26

When you click Save and Import button, the file name you entered is looked up and if it exists, import is made. This means that you don't have to use on page widget for uploads, you can do this via FTP or any other means you want. After clicking the button you don't need to do anything else but wait for the import to finish. How long would that be depends on the number of certificates that you import. Our test imports showed good creation and update rate.


27

If you have very great numbers to import, it might be good idea to separate import files to smaller size files which will be easier on your server memory consumption.

Allowed fields

§ cert_number - code of certificate. When certificates are created this is used as is, patterns are not taken in consideration. This is the only required field, it is used for certificate look-up when updating certificates;

§ pin - PIN number, also no patterns considered, used literally as provided. If omitted null is used;

§ balance - certificate amount. Should be a numeric value. If no value is given or it is not numeric then 0 is used;

§ expire_at - expiration date - should be a string parse-able by strtotime function. Some examples here;

§ currency_code - currency used for certificate - should be three character currency code as accepted by Magento. If empty or non valid value is provided, default store currency is used.;

§ store_id - store id for which certificate is valid - should be a number representing store id or store code. If empty value is given, then current store id is used;


28

§ status - certificate status. Should be a string one of - active or A, pending or P, inactive or I. Lower or upper case is not important. If empty or non valid value is provided, status is set to Inactive;

§ sender_name - sender name, string. If empty it is set to null;

§ recipient_name - recipient name, string. If empty it is set to null;

§ recipient_email - recipient email, string. If empty it is set to null;

§ recipient_address - recipient address, string. If empty it is set to null;

§ recipient_message - recipient message, string. If empty it is set to null;

§ comments - creation or update comment, string. If empty it is set to null;

§ conditions_serialized - you can also import certificate conditions, but they have to be in PHP serialized format, which makes them hard to manually edit. This is useful if you can copy conditions that you like from database and use them to mass update or add certificate conditions.

NOTE: about date formats

Dates in the m/d/y or d-m-y formats are disambiguated by looking at the separator between the various components: if the separator is a slash (/), then the American m/d/y is assumed; whereas if the separator is a dash (-) or a dot (.), then the European d-m-y format is assumed.

Example:

sample.csv

"cert_number","pin","balance","expire_at","currency_code","store_id","status","sender_name","recipient_name","recipient_email","recipient_address","recipient_message","comments" "A0002","1001","26","8.09.2012","USD","1","Active","Myself","Test User","[email protected]","123 Some Street","Cheers","Some comment" "A0003","1002","27","8.10.2012","USD","","Active","","","","","","" "A0004","1003","28","8.11.2012","USD","1","P","","","","","","" "A0005","1004","29","8.12.2012","USD","1","i","","","","","",""


29

PDF Printouts

PDF Printouts

Overview

PDF printouts are meant to give customers printable version of their Gift Certificates. PDFs are stored as template settings in ugiftcert_pdf table in Magento database. Before you can apply certain look to your PDFs you need to create it in Admin > Customers > Gift Certificates > PDF Printout Settings

When you navigate to above page, you will be presented with a list of all currently existing pdf templates. By default Gift Certificate module comes with 4 pre-generated templates. Use them as starting points for your custom templates.


30

When you click “Add New” button you will be taken to PDF template details page.

Settings have 4 sections:

1. Main PDF Settings

2. Page Settings

3. Text Settings

4. Image Settings

Bellow we'll explain what each of those settings mean.

How PDF templates work

Constructing PDF templates in Magento is very different from say CMS page content writing. PDF page is not structured document as HTML page is and nesting elements in one another or styling them is not as easy.

PDF pages have fixed sizes, they are meant to be printed and must have dimensions. All elements on the page are placed using absolute coordinates which begin from lower left corner of the page. If you set x and y of an element to be 0, the element will be displayed in page bottom left corner.

It is up to template editor to figure out exact placement of each editable element.


31

Text can be displayed in different fonts, sizes and color. To simplify template configuration, we set font per page. There are few choices that are guaranteed to work on all PDF readers - Courier, Helvetica and Times New Roman. Any other font has to be provided as separate file and be embedded in PDF file to guarantee its correct display. This also increases PDF file size, and in case of Unicode fonts, that can be many MegaBytes. Therefore we only allow 3 common options plus the font that Magento bundles (the one used for invoices)

Size and color can be changed per text setting.

Each template can have multiple number of images assigned to it.

Note that more images assign the larger result file will be.

Last image added will be top most.

Settings

Available settings:

Main PDF Settings

Here you set template title, font to use and which units you will be using in the rest of the settings.

Units can be “Points” (default in PDF measurement), “Inches”(72 points in an Inch) and “Millimeters”(2.83 points in a millimeter)

Page Settings


32

In page settings you set page dimensions. You use units defined in Main settings and just set the values for page size here.

Text Settings

Text settings are used to display various Gift Certificate properties in PDF template. You can see which properties you can use in the drop-down menu under Field column. Template column allows to wrap field content in some other text and apply some basic formatting. For the purpose sprintf syntax is used.

Next columns are used to position content on the PDF file, refer to How PDF templates work for details.

Font size, here you set font size in points. NOTE Font size is always in points regardless of what you have chosen in Main settings for unit.

Color, set required color here. Clicking in the box should enable simple color chooser to help with selecting correct color.


33

Images Settings

In image settings, you can upload images you want to use either as background or details for the template. You can use multiple images. Images will be stacked in order they are added.

As for text, you can set position of the image but you can also set its width and height, so that it fits in the template. Note that too big difference with actual image dimensions will cause deterioration of the image. Try to use images with 150 and more PPI.

Applying templates

Templates can be assigned either to specific certificates or to products.

Gift Certificate

To assign it to certificate, open the certificate, scroll towards end of “Gift Certificate Info” sections and in “Certificate PDF Template” select template you want to use.

Product

To assign template to product, open product for editing, navigate to GC Settings section, and in “GC PDF Template” select template you want to use.


34

Giftcert Pro add-on

In Gift Certificate Pro add on, you will also have “Personalization options” table where you can add combinations of PDF and Email templates to be presented to customer to choose from.


35

uGiftCert and Conditions Conditions

Since version 1.1.1 it is possible to assign conditions to gift certificates. Those conditions are added and processed in similar fashion as Shopping Cart Rules conditions. To use this feature you have to enable it in global configuration settings.

After it is enabled you will get a new tab on certificate edit page.

On the page you will see a widget that allows admin to set various conditions which have to be valid for the cart when certificate is applied for it to be accepted.


36

Configuring conditions is the same as configuring Shopping Cart Rules conditions.

For any product attributes to be available in conditions they have to have 'Use for Promo Rule Conditions' set to 'Yes'

Stores

You can also limit certifcate usage to selected store.


37

For this setting to have an effect, you must have this setting enabled.


38

uGiftCert External API Our external API provides means to operate with certificates from remote systems.

With API you can:

§ retrieve list of certificates filtered by any certificate property. If no filter is passed all certificates are returned - method list($filters = null);

§ fetch single certificate data by passing certificate code - method fetch($code);

§ create certificate, by passing an associative array of data - method create($data)

Note: When creating certificates using above method, you can pass field qty, which will result in qty number of certificates being created with same data. If you use this feature, you should make sure that cert_number is passed as pattern and not fixed value. Repeating certificate code is not allowed.

§ you can create multiple certificates by passing an array of data arrays - method massCreate($items)

Note: Same concerns as for individual certificates are valid here. Each array of data can have qty field and can create multiple certificates. Advantage here is that you can pass different code patterns, amounts and periods.

§ you can update single certificate by passing its certificate code and array of update data - method update($code, $data)

§ you can update multiple certificates by passing an array of data arrays. Each data array should have cert_number field. - method massUpdate($items)

§ you can delete single certificate by passing its code - method delete($code)

§ you can delete multiple certificates by passing an array of certificate codes - method massDelete($items)

Magento currently has 2 versions of its SOAP API, uGiftCert can operate with both.

Those versions differ in how methods are called and in what form arguments should be passed.


39

V1 example:

$client = new SoapClient('http://example.com/api/soap/?wsdl'); // replace 'example.com' with domain name which you need to access try { $session = $client-‐>login('user', 'pass'); // replace login and user with actual magento web-‐service credentials.

$createData1 = array( 'cert_number' => '[AN*8]', // if creating single certificate, you can pass fixed code here. But it should not exist on the system. 'balance' => 25, 'currency_code' => 'USD', 'store_id' => 1, 'status' => 'P', 'expire_at' => '2012-‐06-‐28' ,// yyyy-‐mm-‐dd 'sender_name' => 'admin', 'pin' => '[N*4]', 'recipient_name' => null, 'recipient_email' => null, 'recipient_message' => null, 'recipient_address' => null, 'comments' => null );

$createData2 = array( 'cert_number' => 'API-‐[A*5]-‐[AN*5]', // when creating multiple certificates, pass a pattern as code. 'balance' => 26.99, 'currency_code' => 'USD', 'store_id' => 1, 'status' => 'P', 'expire_at' => '2012-‐06-‐28' , 'sender_name' => 'admin', 'pin' => '[N*4]', 'recipient_name' => null, 'recipient_email' => null, 'recipient_message' => null, 'recipient_address' => null, 'comments' => null, 'qty' => 3 // this will create 3 certificates with above settings, only difference will be auto generated code. ); $updateData1 = array( 'cert_number' => 'SBU99MG6', // updating does NOT require passing cert_number, in fact if it is found, it is ignored. 'balance' => 25.55, ); $updateData2 = array( 'cert_number' => 'API-‐XQPLE-‐ER3ER', 'balance' => 29.99, ); $certIds = array( 'VOU-‐LXCUE-‐PZ6Y2', // for mass deletion, pass simple array of codes to be deleted. 'VOU-‐MHPDP-‐559FR' ); // Filters should be composed in same way as magento collection filters, // this filter will retrieve all certificates whose code begins with 'API' string $filters = array('cert_number' => array('like' => 'API%')); // passing arguments to call method can be done by passing single value (like above) // or an array of values. In second case all array items are treated as arguments to // called method and are passed to it. That is why when we need to pass an array as // argument we need to include it in another array first. // With V1 of Magento API all method names should be namespaced with preconfigured prefix. // For uGiftCert extension this is 'ugiftcert' $result = $client-‐>call($session, 'ugiftcert.list', array($filters)); // $result = $client-‐>call($session, 'ugiftcert.fetch', 'API-‐XQPLE-‐ER3ER'); // $result = $client-‐>call($session, 'ugiftcert.create', array($createData1)); // $result = $client-‐>call($session,


40

'ugiftcert.massCreate', array( array($createData1, $createData2) )); // $result = $client-‐>call($session, 'ugiftcert.update', array('API-‐XQPLE-‐ER3ER', $updateData1)); // $result = $client-‐>call($session, 'ugiftcert.massCreate', array( array($updateData1, $updateData2) )); // $result = $client-‐>call($session, 'ugiftcert.delete', 'API-‐XQPLE-‐ER3ER'); // $result = $client-‐>call($session, 'ugiftcert.massDelete', array( $certIds ) ); echo '<pre>'; print_r($result); echo '</pre>'; $client-‐>endSession($session); } catch (Exception $e) { echo $e-‐>getMessage(); }

Sample result of above code is:

Array (

[0] => Array

( [cert_id] => 95 [cert_number] => API-‐ALXWB-‐KXHLR [balance] => 26.9900 [currency_code] => USD [pin] => 7757 [status] => P [expire_at] => 2012-‐06-‐28 [recipient_name] => [recipient_email] => [recipient_address] => [recipient_message] => [store_id] => 1 [sender_name] => admin ) [1] => Array ( [cert_id] => 97 [cert_number] => API-‐CCQEY-‐HF97E [balance] => 26.9900 [currency_code] => USD [pin] => 8325 [status] => P [expire_at] => 2012-‐06-‐28 [recipient_name] => [recipient_email] => [recipient_address] => [recipient_message] => [store_id] => 1 [sender_name] => admin ) [2] => Array (


41

[cert_id] => 93 [cert_number] => API-‐CRHUR-‐FLHDR [balance] => 26.9900 [currency_code] => USD [pin] => 5748 [status] => P [expire_at] => 2012-‐06-‐28 [recipient_name] => [recipient_email] => [recipient_address] => [recipient_message] => [store_id] => 1 [sender_name] => admin

) )

V2 example:

V2 of Magento API was created mainly to improve on integration of the API with non PHP platforms. While V1 of the API accepts any PHP built in data type as argument, and could possibly return any such type, it is not very friendly to non PHP platforms. With V2 of the API arguments passed should be either scalar types (int, string, float, bool), indexed arrays ['one', 'two', 'three'] or objects whose public properties are used. Also in V2 method calling is changed, for method to be callable, it should be declared in WSDL file and general rule of method naming is: methodPrefix + upper cased method name. So with prefix ugiftcert and method list the call becomes ugiftcertList. This has the benefit of not using $client→call($session, 'ugiftcert.list'); but $client→ugiftcertList($session);. There is also difference how method arguments are passed, with V2 arguments are declared in WSDL and are being passed directly to method call. No need to wrap in arrays anything and multiple arguments are passed as with any normal function/method call.

So to use V2 API all associative arrays should become stdClass objects with property names the keys of arrays and property values - values of arrays.

try {

$client = new SoapClient('http://example.org/api/v2_soap/?wsdl=1'); // note usage of different WSDL url $session = $client-‐>login('user', 'pass'); $data = array( 'balance' => 155.5, 'status' => 'A', 'cert_number' => 'VOU-‐LXCUE-‐PZ6Y2'


42

); $data = (object)$data; // easiest way to convert associative array in object we need is to cast it to one // in other programming languages, you should provide a simple value object as argument. // data.balance = 155.5; // data.status = 'A'; // data.cert_number = 'VOU-‐LXCUE-‐PZ6Y2'; $createData1 = array( 'cert_number' => '[AN*8]', 'balance' => 25, 'currency_code' => 'USD', 'store_id' => 1, 'status' => 'P', 'expire_at' => '2012-‐06-‐28', 'sender_name' => 'admin', 'pin' => '[N*4]', 'recipient_name' => null, 'recipient_email' => null, 'recipient_message' => null, 'recipient_address' => null, 'comments' => null ); $createData1 = (object)$createData1; $createData2 = array( 'cert_number' => 'API-‐[A*5]-‐[AN*5]', 'balance' => 26.99, 'currency_code' => 'USD', 'store_id' => 1, 'status' => 'P', 'expire_at' => '2012-‐06-‐28', 'sender_name' => 'admin', 'pin' => '[N*4]', 'recipient_name' => null, 'recipient_email' => null, 'recipient_message' => null, 'recipient_address' => null, 'comments' => null, 'qty' => 3 ); $createData2 = (object)$createData2; $updateData1 = array( 'cert_number' => 'API-‐CRZWF-‐ANCP2', 'balance' => 25.55, ); $updateData1 = (object)$updateData1; $updateData2 = array( 'cert_number' => 'E34JU4EE', 'balance' => 29.99, ); $updateData2 = (object)$updateData2; $certIds = array( 'API-‐CRZWF-‐ANCP2', 'E34JU4EE', '8ZR8ERQ9', 'API-‐FYEKA-‐M5ADP', 'API-‐DDPLL-‐NSDXP', 'API-‐NWXFY-‐5ENJP' ); // simple indexed arrays need not to be changed. // To provide filters they should be constructed as value object // with public properties 'filter' and 'complex_filter' (optionally) $filter = new stdClass(); $filter-‐>filter = array(); // filter should be indexed array of filter objects $filter-‐>complex_filter = array(); // sample status filter $status = new stdClass(); $status-‐>key = 'status'; // filter key or attribute name to filter $status-‐>value = 'A'; // filter value or the value of filtered attribute // sample complex filter $balance = new stdClass(); $balance-‐>key = 'balance'; // filter by 'balance' attribute $balance-‐>value = new stdClass(); // filtering value should be an object $balance-‐>value-‐>key = 'gt'; // with key -‐ condition to match -‐ gt = greater than $balance-‐>value-‐>value = '30'; // and value to use in condition matching $filter-‐>filter[] = $status; // add simple filters to filter property $filter-‐>complex_filter[] = $balance; // add complex filters to complex_filter property $result = $client-‐>ugiftcertList($session, $filter); // get all 'A'ctive certificates with more than 30 balance (currency independent) // $result = $client-‐>ugiftcertFetch($session, 'API-‐FNJBS-‐QPMVG');// input valid certificate number for your setup // $result =


43

$client-‐>ugiftcertUpdate($session, 'VOU-‐MHPDP-‐559FR', $data); // input valid certificate number for your setup // $result = $client-‐>ugiftcertCreate($session, $createData2); // $result = $client-‐>ugiftcertDelete($session, 'API-‐FNJBS-‐QPMVG');// input valid certificate number for your setup // $result = $client-‐>ugiftcertMassCreate($session, array($createData1, $createData2)); // $result = $client-‐>ugiftcertMassUpdate($session, array($updateData1, $updateData2)); // $result = $client-‐>ugiftcertMassDelete($session, $certIds); echo '<pre>'; print_r($result); echo '</pre>'; $client-‐>endSession($session); } catch (Exception $e) { echo $e-‐>getMessage(); }


44

Sample result:

Array (

[0] => stdClass Object

( [cert_number] => VOU-‐FDZTT-‐9U4QK [currency_code] => USD [pin] => 5756 [status] => A [expire_at] => 2011-‐08-‐13 [sender_name] => [store_id] => 1 [balance] => 150 ) [1] => stdClass Object

( [cert_number] => VOU-‐NRHJJ-‐FMVRS [currency_code] => USD [pin] => 3249 [status] => A [expire_at] => 2011-‐08-‐13 [sender_name] => [store_id] => 1 [balance] => 150 ) [2] => stdClass Object ( [cert_number] => VOU-‐FTZNQ-‐V6KK3 [currency_code] => USD [pin] => 8734 [status] => A [recipient_name] => Petar [recipient_email] => [email protected] [recipient_address] => [recipient_message] => [sender_name] => [store_id] => 1 [balance] => 255 ) )


45

12042 SE Sunnyside Rd Suite #300

Clackamas, OR 97015

www.unirgy.com

[email protected]

+1 (503) 298-6894

User Guide for uGiftCert - marketplace.magento.com€¦ · Unirgy's gift certificate extension is a...

Documents

Transcript of User Guide for uGiftCert - marketplace.magento.com€¦ · Unirgy's gift certificate extension is a...