iSilo Logo iSilo™
home | support | publishers
automated document registration codes

Introduction

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.

Establishing an account

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.

Email notices

You will receive an email indicating the number of credits left at these times:

Technical Details

This section gives a technical overview of how your server requests a document registration code. Complete details will be provided after your account has been setup.

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.

Request URL format

The HTTP request URL takes the following form:

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.

Example requests

The following table enumerates all possible document registration code types and provides an example request URL for each.

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.

Example: http://accountURL?DID=ARandomID&SER=234
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.

Example: http://accountURL?DID=U87_123Z&UID=1234-5678-9012
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.

Example: http://accountURL?DID=U87_123Z&EXP=20031202
Serialized with expiration A serialized with expiration registration code is a serialized registration code with an expiration date.

Example: http://accountURL?DID=Cutter9&SER=301239&EXP=20050131
User ID with expiration A user ID with expiration registration code is a user ID registration code with an expiration date.

Example: http://accountURL?DID=easy&UID=2109-8765-4321&EXP=20101031

Success response

On success, the document registration code server responds with the generated document registration code in the standard display format of four sets of four characters with the four sets of characters separated from one another by hyphens. An example successful response is the 19 character string:

AB12-C34D-EFGH-789Z

Error responses

On error, the document registration code server responds with an error string beginning with the two character sequence "E_". The following table lists the error strings that can be expected to be returned on error.

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.

Tips for a Better Customer Experience

When requesting the user ID from the customer, ask the user to enter the ID with the hyphens. The hyphens should help prevent the customer from entering the user ID incorrectly as they separate the user ID into three sets of four digits. This should makes it easier than having to enter a sequence of twelve digits in a row with no breaks.
©1999-2017 DC & Co. All rights reserved.