This shows you the differences between two versions of the page.
Both sides previous revision Previous revision | |||
ugiftcert:api [2011/07/05 12:24] 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, | ||
+ | |||
+ | **Note:** When creating certificates using above method, you can pass field **// | ||
+ | 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, | ||
+ | * 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(' | ||
+ | try { | ||
+ | $session = $client-> | ||
+ | |||
+ | $createData1 = array( | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | $createData2 = array( | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | $updateData1 = array( | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | $updateData2 = array( | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | |||
+ | $certIds = array( | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | |||
+ | // Filters should be composed in same way as magento collection filters, | ||
+ | // this filter will retrieve all certificates whose code begins with ' | ||
+ | $filters = array(' | ||
+ | |||
+ | // 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 ' | ||
+ | |||
+ | $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | |||
+ | echo '< | ||
+ | print_r($result); | ||
+ | echo '</ | ||
+ | |||
+ | $client-> | ||
+ | } catch (Exception $e) { | ||
+ | echo $e-> | ||
+ | } | ||
+ | </ | ||
+ | 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 | ||
+ | ( | ||
+ | [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 [' | ||
+ | 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: | ||
+ | // | ||
+ | of not using '' | ||
+ | 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/ | ||
+ | |||
+ | 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(' | ||
+ | $session = $client-> | ||
+ | $data = array( | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | $data = (object)$data; | ||
+ | // in other programming languages, you should provide a simple value object as argument. | ||
+ | // data.balance = 155.5; | ||
+ | // data.status = ' | ||
+ | // data.cert_number = ' | ||
+ | |||
+ | $createData1 = array( | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | $createData1 = (object)$createData1; | ||
+ | |||
+ | $createData2 = array( | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | $createData2 = (object)$createData2; | ||
+ | |||
+ | $updateData1 = array( | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | |||
+ | $updateData1 = (object)$updateData1; | ||
+ | |||
+ | $updateData2 = array( | ||
+ | ' | ||
+ | ' | ||
+ | ); | ||
+ | |||
+ | $updateData2 = (object)$updateData2; | ||
+ | |||
+ | $certIds = array( | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ' | ||
+ | ); // simple indexed arrays need not to be changed. | ||
+ | |||
+ | |||
+ | // To provide filters they should be constructed as value object | ||
+ | // with public properties ' | ||
+ | $filter = new stdClass(); | ||
+ | $filter-> | ||
+ | $filter-> | ||
+ | |||
+ | // sample status filter | ||
+ | $status = new stdClass(); | ||
+ | $status-> | ||
+ | $status-> | ||
+ | |||
+ | // sample complex filter | ||
+ | $balance = new stdClass(); | ||
+ | $balance-> | ||
+ | $balance-> | ||
+ | $balance-> | ||
+ | $balance-> | ||
+ | |||
+ | $filter-> | ||
+ | $filter-> | ||
+ | |||
+ | $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | // $result = $client-> | ||
+ | echo '< | ||
+ | print_r($result); | ||
+ | echo '</ | ||
+ | |||
+ | $client-> | ||
+ | } catch (Exception $e) { | ||
+ | echo $e-> | ||
+ | } | ||
+ | </ | ||
+ | |||
+ | 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] => jamby77@gmail.com | ||
+ | [recipient_address] => | ||
+ | [recipient_message] => | ||
+ | [sender_name] => | ||
+ | [store_id] => 1 | ||
+ | [balance] => 255 | ||
+ | ) | ||
+ | ) | ||
+ | </ |