{eac}SoftwareRegistry Distribution SDK

API Parameters

API parameters are passed as an array:

$apiParams = [ 'registry_key' => 'unique ID', // * registration key (assigned by registry server) 'registry_name' => 'Firstname Lastname', // registrant's full name 'registry_email' => 'email@domain.com', // * registrant's email address 'registry_company' => 'Comapny/Organization Name', // registrant's company name 'registry_address' => 'Street\n City St Zip', // registrant's full address (textarea) 'registry_phone' => 'nnnnnnnnnn', // registrant's phone 'registry_product' => 'productId', // * your product name/id ((your_productid)) 'registry_title' => 'Product Title', // your product title 'registry_description' => 'Product Description', // your product description 'registry_version' => 'M.m.p', // your product version 'registry_license' => 'Lx', // 'L1'(Lite), 'L2'(Basic), 'L3'(Standard), 'L4'(Professional), 'L5'(Enterprise), 'LD'(Developer), 'LU'(Unlimited) 'registry_count' => int, // Number of licenses (users/seats/devices) 'registry_variations' => array('name'=>'value',...), // array of name/value pairs 'registry_options' => array('value',...), // array of registry options 'registry_domains' => array('domain',...), // array of valid/registered domains 'registry_sites' => array('url',...), // array of valid/registered sites/uris 'registry_transid' => '', // external transaction id 'registry_timezone' => '', // standard timezone string (client timezone) 'registry_locale' => '', // standard locale/language code ];

* Required values (registry_key not required when creating a new registration).

If setting registry_transid, the recommended (not required) format is {id}|{source}|{suffix} where {id} is the transaction id, {source} indicates the source of the transaction, and {suffix} may be used as needed.

Any additional fields passed wil be saved as custom fields.

Although typically set by the Software Registry server, with the proper option setting, the API may override:

[ 'registry_status' => 'status', // 'pending', 'trial', 'active', 'inactive', 'expired', 'terminated' 'registry_effective' => 'DD-MMM-YYYY', // Effective date 'registry_expires' => 'DD-MMM-YYYY', // Expiration date or term ('30 days', '1 year',... added to effective date) ];

Payment information may be posted with:

[ 'registry_paydue' => float, // amount to be paid/billed, 'registry_payamount' => float, // amount paid, 'registry_paydate' => 'DD-MMM-YYYY', // date paid 'registry_payid' => 'payment id' // transaction id/check #, etc. 'registry_nextpay' => 'DD-MMM-YYYY', // next payment/renewal date ];

API Requests

Create/request a new registration…

$response = $this->registryApiRequest('create',$apiParams);

Activate an existing registration…

$response = $this->registryApiRequest('activate',['registry_key' => '<registrationKeyValue>']);

Activate and Update an existing registration…

$response = $this->registryApiRequest('activate',$apiParams);

Deactivate an existing registration…

$response = $this->registryApiRequest('deactivate',['registry_key' => '<registrationKeyValue>']);

Verify or Refresh an existing registration…

$response = $this->registryApiRequest('verify',['registry_key' => '<registrationKeyValue>']); $response = $this->registryApiRequest('refresh',$apiParams);

Revise an existing registration…

$response = $this->registryApiRequest('revise',$apiParams);

API Response

The API response is a standard object. status->code is an http status, 200 indicating success.

status -> ( code -> 200, // HTTP status code message -> '(action) ok' // (action) = 'create', 'activate', 'deactivate', 'verify', 'revise' ), registration -> ( registry_key -> string // UUID, registry_status -> string, // 'pending', 'trial', 'active', 'inactive', 'expired', 'terminated', 'invalid' registry_effective -> string, // DD-MMM-YYYY effective date registry_expires -> string, // DD-MMM-YYYY expiration date registry_name -> string, registry_email -> string, registry_company -> string, registry_address -> string, registry_phone -> string, registry_product -> string, registry_title -> string, registry_description -> string, registry_version -> string, registry_license -> string, registry_count -> int, registry_variations -> array, registry_options -> array, registry_domains -> array, registry_sites -> array, registry_transid -> string, registry_timezone -> string, registry_locale -> string, registry_valid -> bool, ), registrar -> ( contact -> object( name -> string // Registrar Name email -> string // Registrar Support Email phone -> string // Registrar Telephone web -> string // Registrar Web Address ), timezone -> string, // standard timezone string locale -> string, // WordPress locale cacheTime -> int, // in seconds, time to cache the registration response (Default Cache Time) refreshInterval -> int, // in seconds, time before refreshing the registration (Default Refresh Time) refreshSchedule -> string, // 'hourly', 'twicedaily', 'daily', 'twiceweekly', 'weekly', 'twicemonthly', 'monthly' - corresponding to refreshInterval options -> array( // from settings page, registrar_options (Allow API to...) 'allow_set_key', 'allow_set_status', 'allow_set_effective', 'allow_set_expiration', 'allow_activation_update' ), licenseCodes -> object( // may be changed by filter on registration server L1 -> 'Lite' L2 -> 'Basic' L3 -> 'Standard' L4 -> 'Professional' L5 -> 'Enterprise' LD -> 'Developer' LU -> 'Unlimited' ), notices -> object( info -> string, // information message text warning -> string, // warning message text error -> string, // error message text success -> string, // success message text ), message -> string, // html message ), registryHtml -> string, // html (table) of human-readable registration values supplemental -> mixed, // supplemental data/html assigned via filters (developer's discretion).

On a successful response (status->code = 200), the SDK will automatically cache the registration data and schedule the next refresh event (you do not have to do this).

notices may be set (according to severity) to indicate an expiration or pending expiration and should be displayed to the user. Typically, only one notice will be set but they can be set via the eacSoftwareRegistry_api_registration_notices filter.

message is set via the eacSoftwareRegistry_api_registration_message filter.

supplemental is set via the eacSoftwareRegistry_api_registration_supplemental filter.

On an error response, an additional element is included:

error -> ( code -> 'error_code', message -> 'error message' ),

error->message may be more informative than status->message. Errors may be handled with something like:

if ($this->is_api_error($response)) { echo "<div class='notice notice-error'><h4>Error ".$response->error->code." : ".$response->error->message."</h4></div>"; }

Methods, Hooks, and Callbacks

Useful methods built into the SDK…

$this->isValidRegistration(); // Returns boolean if ( $this->isValidRegistration() ) {...} $this->getRegistrationKey(); // Returns the current registration key $registrationKey = $this->getRegistrationKey(); $this->getCurrentRegistration(); // Returns the current registration object (above response object) $currentRegistration = $this->getCurrentRegistration(); $this->isRegistryValue($keyName); // Returns the value of a specific registry key $regStatus = $this->isRegistryValue( 'status '); $this->isRegistryValue($keyName, $value, $test); // Returns boolean comparison of the value of a registry key ($test is '=|eq' (default), '<|lt', '>|gt', '<=|le', '>=|ge') if ( $this->isRegistryValue('license', 'L3', '>=') ) {...}

Several hooks are available to customize or react to registration events. In WordPresss, there are several actions and filters, for file based projects there are corresponding callback methods…

filter/callback: (your_productid)_api_remote_request( $request, $endpoint ) @param array $request ['method'=>, 'timeout'=>, 'redirection'=>, 'sslverify'=>, 'headers'=>, '