UnirgyWiki

User Tools

Site Tools

You are here: start » ugiftcert » api
Trace:
ugiftcert:api

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
ugiftcert:api [2011/07/05 11:33]
jamby77 		ugiftcert:api [2011/07/05 12:35] (current)
jamby77
Line 1: Line 1:
 +===== 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.
 +
 +===V1 example:===
 +<code php>
 +$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, '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();
 +}
 +</code>
 +Sample result of above code is:
 +
 +<code>
 +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
 +        (
 +            [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
 +        )
 +)
 +</code>
 +
 +===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.
 +
 +<code php>
 +    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'
 +        );
 +        $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 = $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();
 +    }
 +</code>
 +
 +Sample result:
 +<code>
 +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] => jamby77@gmail.com
 +            [recipient_address] => 
 +            [recipient_message] => 
 +            [sender_name] => 
 +            [store_id] => 1
 +            [balance] => 255
 +        )
 +)
 +</code>
ugiftcert/api.1309865591.txt.bz2 · by jamby77

Page Tools

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Noncommercial-Share Alike 4.0 International
CC Attribution-Noncommercial-Share Alike 4.0 International Donate Powered by PHP Valid HTML5 Valid CSS Driven by DokuWiki