Softsale HTTP API
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 |