Softsale HTTP API

From aMember Pro Documentation
Jump to: navigation, search

Contents

Softsale HTTP API

In PHP applications we recommend to use the softsale-sample-app as we described above. To use Softsale from applications in other programming languages, you may use HTTP API directly to check/activate and de-activate license keys.

How to access the HTTP API

To access API, you need to make HTTP POST or GET call to URL http://www.example.com/amember/softsale/api/ACTION (replace www.example.com/amember with path to your aMember installation and ACTION to the API method).

Check-License

URL http://www.example.com/amember/softsale/api/check-license

When customer enters license key into your application, you need to make an HTTP call to this API to verify that license is valid. License checking does not check license activation, to deal with activation use #Activate License API.

Input Parameters:

key License key entered by customer

Positive Response - if license check is passed (returned in JSON format)

code ok
message OK
scheme_id Licensing scheme#
scheme_title Licensing scheme title
license_expires license expiration in yyyy-mm-dd hh:ii:ss format
next_check seconds to check license next time (if necessary for your licensing/activation logic)


Negative Response - if license check is failed (returned in JSON format)

code described below in [#HTTP API Error Codes]
message corresponds to the error code
next_check seconds to check license next time (if necessary for your licensing/activation logic)

Activate License

URL http://www.example.com/amember/softsale/api/activate

To activate software and tie it to specific installation you need to calculate "request" parameters of your software installation and send it to the "activate" API. aMember will check all variables and if all OK, new activation will be recorded. If you have "call-home" functionality enabled, you may store "next_check" time locally, and when time comes - make new call to #Check-Activation API to check that user license and activation are still valid.

Input Parameters:

key License key entered by customer
request[ip] IP Address of installation (activation will be tied to) (required if enabled in scheme settings)
request[url] URL of installation (activation will be tied to) (required if enabled in scheme settings)
request[domain] Domain of installation (activation will be tied to). You should use it somewhere in your application somehow that usage of different domain will break application logic. (required if enabled in scheme settings)
request[sdomain] Alternative domain of installation (activation will be tied to) (required if enabled in scheme settings)
request[hardware-id] Machine-ID of installation (activation will be tied to). Your software need to calculate it by some algorithm. (required if enabled in scheme settings)


Positive Response (returned in JSON format)

code ok
message OK
activation_code Activation Code returned by algorithm on the server
scheme_id Licensing scheme#
license_expires license expiration in yyyy-mm-dd hh:ii:ss format
next_check seconds to check license next time (if necessary for your licensing/activation logic)


Negative Response (returned in JSON format)

code described below in #Error Codes
message corresponds to the error code

Check-Activation

URL http://www.example.com/amember/softsale/api/check-activation

This call is necessary only if you have "call-home" functionality enabled, then you store "next_check" time locally, and when time comes - make new call to this API to check that user license and activation are still valid.

Input Parameters:

key License key entered by customer
request[ip] IP Address of installation (activation will be tied to) (required if enabled in scheme settings)
request[url] URL of installation (activation will be tied to) (required if enabled in scheme settings)
request[domain] Domain of installation (activation will be tied to). You should use it somewhere in your application somehow that usage of different domain will break application logic. (required if enabled in scheme settings)
request[sdomain] Alternative domain of installation (activation will be tied to) (required if enabled in scheme settings)
request[hardware-id] Machine-ID of installation (activation will be tied to). Your software need to calculate it by some algorithm. (required if enabled in scheme settings)


Positive Response (returned in JSON format)

code ok
message OK
activation_code Activation Code returned by algorithm on the server
scheme_id Licensing scheme#
license_expires license expiration in yyyy-mm-dd hh:ii:ss format
next_check seconds to check license next time (if necessary for your licensing/activation logic)


Negative Response (returned in JSON format)

code described below in #Error Codes
message corresponds to the error code

De-activate License

URL http://www.example.com/amember/softsale/api/deactivate

This call allows to de-activate installation, it will allow to activate another installation for same license key. It is only possible if enabled in license scheme settings. Your application logic must remove local records about activation so de-activated installation may not be used again.

Input Parameters:

key License key entered by customer
request[ip] IP Address of installation (activation will be tied to) (required if enabled in scheme settings)
request[url] URL of installation (activation will be tied to) (required if enabled in scheme settings)
request[domain] Domain of installation (activation will be tied to). You should use it somewhere in your application somehow that usage of different domain will break application logic. (required if enabled in scheme settings)
request[sdomain] Alternative domain of installation (activation will be tied to) (required if enabled in scheme settings)
request[hardware-id] Machine-ID of installation (activation will be tied to). Your software need to calculate it by some algorithm. (required if enabled in scheme settings)


Positive Response (returned in JSON format)

code ok
message OK
activation_code De-activation Code returned by algorithm on the server
scheme_id Licensing scheme#
license_expires license expiration in yyyy-mm-dd hh:ii:ss format


Negative Response (returned in JSON format)

code described below in #Error Codes
message corresponds to the error code

Error Codes

In case of failure SoftSale API will return error code in the code field. In the following table you may find description of error codes.

code message
ok Operation finished successfully
license_empty Empty or invalid license key submitted
license_not_found License key not found on licensing server
license_disabled License key has been disabled
license_expired License key expired
activation_server_error Activation server error
invalid_input Activation failed: invalid input
no_spare_activations No more activations allowed
no_activation_found No activation found for this installation
no_reactivation_allowed Re-activation is not allowed
other_error Error returned from activation server