Skip to content

Document Reader

A document reader is a periphery to read and analyze documents. This could be ca document scanner or a card reader. This interface does not care about the type of hardware. We expect only information in a scanner independent format which is described below. After the scan process in the hardware is finished, we immediately expect to receive this information.

How document readers are connected

Operationcode: DR

DR

Direction

IF Partner → SIHOT.PMS

Message

Activation of the document reader

We are going to send an activation request for a scanner to a server which is connected to the scanner.

<?xml version="1.0" encoding="iso-8859-1"?>
<SIHOT-Document>
  <OC>DR-SCAN</OC>
  <TN></TN>
  <HN></HN>
  <WS></WS>
  <SCANNER_NAME></SCANNER_NAME>
  <ECHOTOKEN></ECHOTOKEN>
  <ORG></ORG>
</SIHOT-Document>

Attributes Message

Attribute Denotation Type
OC Action Type:DR-SCAN = Activation of the document reader String, fix
WS Name of the workstation, where this data should be processed, needs to be returned in the response. String
SCANNER_NAME Name or ID of the scanner which should be activated. String
ECHOTOKEN Any data which needs to be returned in every response which is related to this activation request. String
ORG The SIHOT client which initiated the request. This value needs to be returned in the response. String
HN Hotel number Integer
TN Transaction number Integer

Response

After we have sent the activation request, the scanner has to send the scanned document data in this format:

<?xml version="1.0" encoding="iso-8859-1"?>
<SIHOT-Document>
  <OC>DR</OC>
  <HN></HN>
  <TN></TN>
  <DATA_DOCUMENT>
    <DOCUMENT_TYPE></DOCUMENT_TYPE>
    <ISSUECOUNTRY coding="3">ABC</ISSUECOUNTRY>
    <NATIONALITY coding="2">AB</NATIONALITY>
    <CN></CN>
    <SN></SN>
    <SN2></SN2>
    <CN_BIRTH></CN_BIRTH>
    <SN_BIRTH></SN_BIRTH>
    <DOCUMENT_NO></DOCUMENT_NO>
    <DOCUMENT_ID></DOCUMENT_ID>
    <STREET></STREET>
    <CITY></CITY>
    <ZIP></ZIP>
    <REGION></REGION>
    <DISTRICT></DISTRICT>
    <SEX></SEX>
    <DOB></DOB>
    <POB></POB>
    <EXPIRE></EXPIRE>
    <ISSUEDATE></ISSUEDATE>
    <TAX_NUMBER></TAX_NUMBER>
    <ISSUED_BY></ISSUED_BY>
    <PHONE></PHONE>
    <EMAIL></EMAIL>
    <MOTHER>
      <CN></CN>
      <SN></SN>
    </MOTHER>
    <FATHER>
      <CN></CN>
      <SN></SN>
    </FATHER>
  </DATA_DOCUMENT>
  <IMAGE_DOCUMENT></IMAGE_DOCUMENT>
  <IMAGE_DOCUMENT_BACK></IMAGE_DOCUMENT_BACK>
  <IMAGE_PHOTO></IMAGE_PHOTO>
  <IMAGE_SIGNATURE></IMAGE_SIGNATURE>
  <MSG></MSG>
  <WS></WS> <!--value from the activation request -->
  <ECHOTOKEN></ECHOTOKEN> <!--value from the activation request -->
  <ORG></ORG> <!--value from the activation request -->
</SIHOT-Document>

Attributes Response

The record consists of the parts:

  • <DATA_DOCUMENT>: The plain text data of the client. This is obligatory.
  • <IMAGE_DOCUMENT>: The complete image in DIB-Format of the document, front side. This is transferred in Base 64 Coding.
  • <IMAGE_DOCUMENT_BACK>: The complete image in DIB-Format of the document, only the second side. This is transferred in Base 64 Coding.
  • <IMAGE_PHOTO>: Only the photo of the client in DIB-Format out of the document. This data is also transferred in Base 64 Coding.
  • <IMAGE_SIGNATURE>: Only the photo of the client’s signature in DIB-Format out of the document. This data is also transferred in Base 64 Coding.
Attribute Denotation Type
OC Action Type:
DR = Document reader		 String
HN Hotel number Integer
TN Transaction number Integer
DOCUMENT_TYPE Possible values are:
IDENTITY
PASSPORT
DRIVER_LICENCE
DRIVER_LICENSE
VISA
TRIPULATION		 String
ISSUECOUNTRY Identifying the issuing country String
ISSUED_BY Identifying the office that issued the document String
NATIONALITY The bearer’s nationality. See also EXPEDITOR String
DOCUMENT_NO Unique number of the document to identify this document String
DOCUMENT_ID The unique identification for this client (VAT/tax identification number) String
EXPIRE Expire date of the document, format: YYYY-MM-DD Date
MSG Additional data to be displayed on the client screen String
WS Name of the workstation, where this data should be processed, needs to have the content from the activation request. String
ECHOTOKEN Needs to have the same content like sent in the activation request. String
ORG Needs to have the same content like sent in the activation request. String
ISSUEDATE Issuing date of the document, format YYYY-MM-DD Date
CN Christian name String
SN Surname String
SN2 Surname (if applicable) String
CN_BIRTH Christian name/given name at birth String
SN_BIRTH Surname/family name at birth String
CITY City String
ZIP Postal code String
REGION Region or state String
DISTRICT District or county String
STREET Street String
SEX Gender Char
DOB Date of birth, format: YYYY-MM-DD Date
POB Place of birth String
TAX_NUMBER Tax number String
ISSUED_BY Issuing authority String
PHONE Phone number of the guest String
EMAIL Email address of the guest String
Block Denotation
MOTHER Information about the mother
FATHER Information about the father

Intermediate messages

In case the user needs to turn the document, the scanner can send a message with the <MSG> element including a user friendly message.

<?xml version="1.0" encoding="iso-8859-1"?>
<SIHOT-Document>
  <OC>DR</OC>
  <HN></HN>
  <TN></TN>
  <MSG>Please turn the document to read the second page</MSG>
  <WS></WS> <!--value from the activation request -->
  <ECHOTOKEN></ECHOTOKEN> <!--value from the activation request -->
  <ORG></ORG> <!--value from the activation request -->
</SIHOT-Document>

Special notes on the communication layer

There are several things to consider:

  1. This interface on SIHOT side runs as client and server at the same time! See Communication.
  2. The activation request is sent to a server on the scanner side.
  3. The answer could either be sent directly back to the client as response of the activation request OR can be sent to the server port of this interface.
  4. In any case, the connection with the activation request is closed automatically after the first response is received. If you have to send a second request, you have to send it to the server port.
  5. Every response to an activation request needs to have the same <WS>, <ECHOTOKEN> and <ORG> elements content like the according activation request.
  6. If there is one server for all scanners on the document reader side, we send the <SCANNER_NAME> element for the scanner which needs to be activated.