iSilo™
home | support | publishers
iSilo™
If you are a document publisher with an existing scriptable e-commerce system or one that you will be setting up and you want to be able to automate the generation of document registration codes, then you may be interested in the automated document registration code generation service. This pay-as-you-go service provides an interface to a registration code server on the Web that your e-commerce server can call with a normal HTTP URL containing the parameters for generating a registration code. In the body of the response to the HTTP URL call, the registration code server returns the generated registration code.
In order to utilize the service, you need to first establish an account with the document registration code server. The account keeps track of the number of document registration code generation credits left in your account and allows you to purchase additional credits. Each call by your e-commerce server to the document registration code server deducts one credit from your account.
To establish an account, visit the Document Registration Code Account Setup page of the online store. You will need the IP address of your server that will be calling the document registration code server and the email address where you want notices about your account sent. Currently the only notices that will go to that email are the number of credits you have left when the number of credits decreases to certain amounts as described below. The IP address is used for security so that only your server can request registration code generation with deductions from your account.
The initial account setup fee also includes an initial allotment of credits added to your account. After your account has been setup, you can purchase additional credits from the Document Registration Code Credits page of the online store.
Each time you request a document registration code, the document registration code server deducts one credit from your account. The credit is deducted even if the response is an error response.
After establishing your account, you will receive instructions on how to check at any time on the number of credits available in your account.
You will receive an email indicating the number of credits left at these times:
Your server requests the generation of a document registration code by sending an HTTP request to the document registration code server, which responds with the generated registration code or an error string. In both cases, the content type of the message is text/plain.
| http://accountURL?DID=documentID&UID=userID&SER=serialNumber&EXP=expiration |
The query portion of the URL has the following parameters:
| Parameter | Description |
|---|---|
| DID=documentID | This parameter is required for all requests. Replace documentID with the document ID of the document. In iSiloX, this is the value you entered in the Document ID field on the Security page of the Properties dialog for the document entry. The document ID can only consist of the characters 0-9, a-z, A-Z, and _. If spaces or other characters are used, it may result in an incorrect registration code. |
| UID=userID | For a document registration code keyed to a given user ID, such that the registration code will only work to unlock a document on a device having that user ID, this parameter specifies that user ID. Replace userID with the twelve digit user ID. The two hyphens that separate the three sets of four digits in the user ID are optional. This parameter must not be specified if the document registration code is not to be keyed to a specific user ID. |
| SER=serialNumber | For a document registration code not tied to a user ID but for which you want to generate a unique registration code, specify this parameter. Replace serialNumber with any value from one to 16 million. For a given document ID, this allows you to generate 16 million unique document registration codes. This parameter must not be specified if the document registration code is to be keyed to a specific user ID. |
| EXP=expiration | To have the document registration code expire on a given date, specify this parameter. Replace expiration with the expiration date in the eight digit format YYYYMMDD, where YYYY is the four-digit year, MM is the two-digit month, and DD is the two-digit day. The year can not be before the current year. If the registration code is not to have an expiration date, this parameter must not be specified. |
| Type | Description and Example | |
|---|---|---|
| Serialized | A serialized registration code is keyed only to the
document ID. For a given document ID, you can generate up
to 16 million unique registration codes for the document.
| |
| User ID | A user ID registration code is keyed to both the
document ID and the user ID of the reading device. This
restricts access to the document to only devices with the
given user ID. In iSilo™ 3.2 and later, you can
determine the user ID of the device using the System Information
dialog, usually available in the Tools or Help menu, depending
on the platform. The user ID will most likely be dependent
on the user or owner name of the device.
This means that two different devices with the same user or
owner name may have the same user ID. However, most people
will have different user IDs since most people base the user or
owner names of their devices on their own names.
| |
| Expiration only | An expiration only registration code is keyed to only
the document ID but will not work on or after a given expiration date.
In iSilo™, if the user attempts to open a document
with a registration code that has an expiration date and the current
date is on or after the expiration date, iSilo™ does not
allow opening of the document and reports to the user that the document
has expired.
| |
| Serialized with expiration | A serialized with expiration registration code is a
serialized registration code with an expiration date.
| |
| User ID with expiration | A user ID with expiration registration code is a
user ID registration code with an expiration date.
|
AB12-C34D-EFGH-789Z
|
| Error String | Explanation |
|---|---|
E_NO_MORE_CREDITS
| Your account does not have enough credits for generating additional document registration codes. You need to purchase additional credits. |
E_BAD_USER_ID
| The user ID either does not consist of 12 digits or is not a valid user ID. |
E_BAD_SERIAL_NUMBER
| The serial number is invalid. It must be in the range from one to 16 million. |
E_NO_INFORMATION
| Not enough information is present to generate the document registration code. The request parameters must specify at least the document ID and one of the other parameters. |
E_BAD_EXPIRATION
| The expiration date is not in the correct format or is not a valid date. |
Responses other than the above may also be possible in certain situations so you are recommended to have your server look for the success response and treat all other responses as error responses.