Document
API definition
The API definition for retrieving a Document as a byte stream is
https://services.cro.ie/cws/documentapi/help/operations/document
Flow Chart
The process of retrieving a document is outlined in the following flow chart
URL
The URL for getting the document is:
https://services.cro.ie/cws/documentapi/document/{DOC_ID}?key={KEY}
The verb used to call this URL must be Http GET. The value returned is
a byte stream. This byte stream can then be saved as a multi-page TIFF.
Streaming in other file formats is not currently available. If you need the document as a PDF, this conversion
must take place in your own application.
Variables
Value
|
Description |
DOC_ID |
The document id. This must be the doc_id that was supplied for
"doc_id" in the Request Body of the
preceeding call to permissionrequest . If it is not the same, a status code of
400 Bad Request will be returned.
Remember that the "doc_id" is available when you grab the SubmissionDoc
details. Please refer to the data dictionary and the
submission help pages for more info.
|
KEY |
This is the Authorization Key that is returned from the preceeding Http POST that was
made to permissionrequest . |
Response Status Codes
The following is the list of possible Status Codes returned in the Response.
If 200 OK
is not returned, the returned Status message will contain
details of the error message.
Response
|
Explanation |
200 OK |
Success. A byte stream is returned. This can be displayed directly to the user and saved as a multi-page TIFF.
It makes sense for you to perform your own archiving of documents which you order to prevent re-ordering the same document. |
400 Bad Request |
This can arise in a few situations, but most frequently it will be for one of the following reasons:
- The value supplied for {KEY} is invalid. Most likely, characters in the Authorization Key have been changed or missing
- There is a problem with one of the mandatory values encoded in the Authorization Key. The error message returned will specify exactly where the problem is.
- The query string value {DOC_ID} does not match the value "doc_id" that was posted in the Request Body when calling
permissionrequest . For example,
the value requested in permissionrequest was 12345555, but the value supplied for {DOC_ID} is 65413212. The value mismatch causes Status Code 400.
|
401 Unauthorized |
This can happen in any of the following situations:
- The credentials in your Authentication Header are invalid (i.e. the Base64 encoded version of emailaddress:apikey)
- The link has expired. If you specified a
time_to_live in the preceeding permissionrequest of a
few seconds, and tried to retrieve the account balance after the time has elapsed, you will get a 401
|
412 Precondition Failed |
This can occur in one of the following situations
-
The {KEY} is missing from the URL.
-
Insufficient balance in the Customer Account. The workaround is to deposit funds in your account using
the Company Search website.
|
Example: Getting a Document
The following is the sequence of steps to get the multi-page TIFF for doc_id 56566674:
1. Get the Authorization Key with permission request
To get the Authorization Key, refer to Example 2 in the permission request help page.
For demonstration purposes, let's assume that the key returned is
"EAAAAMCJlm%2flJlEUMSwjULtRey8uAO%2fkZRMWcLrEaiukHAb0pksSnYOb4OMY%2f2ECi%2bISqKqN1Pm3d6dblxOjLbo7acUilodR
pmI%2bKuGTxqI6NGEXF8WmYWUSNQxbO8lXZzKvrg%3d%3d"
2. Get the document
Using the key returned in step 1, we now execute an Http GET to the following URL:
https://services.cro.ie/cws/documentapi/document/56566674?key=EAAAAMCJlm%2flJlEUMSwjULtRey8uAO%2fkZRMWcLrEa
iukHAb0pksSnYOb4OMY%2f2ECi%2bISqKqN1Pm3d6dblxOjLbo7acUilodRpmI%2bKuGTxqI6NGEXF8WmYWUSNQxbO8lXZzKvrg%3d%3d
A byte stream will be returned. This can be saved as a multi-page TIFF.
At this point, the price of a document will be deducted from your Account Balance. You can see these orders
when you look at your Current Statement in the Company Search site.
Here is a sample of what the transactions would look like in your statement. The Customer Ref
makes it clear that the order was placed through Open Services. The number appearing after "OPEN SERVICES" is the doc_id of the
Document that was ordered.