doc/user_web_services

   1 User web services specification
   2 ===============================
   3
   4 Source: Provozní řád ISDS, version 2008-30-06, Pages 12–13
   5 Source: Webové služby ISDS pro manipulaci s datovými zprávami,
   6     version 2 (2009-06-25)
   7 Source: Webové služby ISDS pro vyhledávání datových schránek,
   8     version 2 (2009-06-26)
   9
  10
  11
  12 These services are intended for working with messages inside a box by
  13 a regular user.
  14
  15 SOAP web services defined in: dm_operations.wsdl, dm_info.wsdl, db_search.wsdl
  16 (Appendix 2 of Provozní řád ISDS)
  17
  18 Data types: dmBaseTypes.xsd (Appendix 1)
  19
  20 Documentation: DataMessage_ws.pdf, DBSeatch_ws.pdf (Appendix 2)
  21
  22 List of SOAP requests follows. Those marked with asterisk DOES NOT MARK
  23 incoming messages as delivered.
  24
  25
  26 dm_operations.wsdl
  27 ==================
  28
  29 URL postfix: dz
  30 Constraints: Client must be autenticated in Access Manager
  31
  32 CreateMessage (*)
  33     Create and send a message
  34 MessageDownload
  35     Download incoming message
  36 SignedMessageDownload
  37     Download incoming message with digital signature of ministery of interiors
  38 SignedSentMessageDownload
  39     Download outgoing message with digital signature of ministery of interiors
  40 DummyOperation
  41     Void operation used to log in and to keep connection alive
  42
  43
  44 dm_info.wsdl
  45 ============
  46
  47 URL postfix: dx
  48 Constraints: Client must be autenticated in Access Manager
  49
  50 VerifyMessage
  51     Verify local copy of message with remote original stored in ISDS
  52 MessageEnvelopeDownload
  53     Download envelope of incoming message
  54 MarkMessageAsDownloaded
  55     Mark message as read
  56 GetDeliveryInfo
  57     Dowload infosheet about message post and delivery
  58 GetSignedDeliveryInfo
  59     Dowload infosheet about message post and delivery with signature of
  60     ministery of interiors
  61 GetListOfRecievedMessages
  62     Download list of incoming messages
  63 GetListOfSentMessages
  64     Download list of outgoing messages
  65
  66
  67 db_search.wsdl
  68 ==============
  69
  70 URL postfix: df
  71
  72 FindDataBox (*)
  73     Find boxes conforming to serch criteria
  74 CheckDataBox (*)
  75     Return state of given box
  76
  77
  78 CreateMessage (*)
  79 =============
  80
  81 Create and send a message.
  82
  83 Envelope of outgoing message must contain dbIDRecipient and dmAnnotation.
  84 Other elements are optional (dmRecipientOrgUnit, dmRecipientOrgUnitNum,
  85 dmSenderOrgUnit, dmSenderOrgUnitNum, dmToHands, dmPersonalDelivery,
  86 dmAllowSubstDelivery, dmRecipientRefNumber, dmRecipientIdent,
  87 dmSenderRefNumber, dmSenderIdent, dmLegalTitleLaw, dmLegalTitleYear,
  88 dmLegalTitleSect, dmLegalTitlePar, dmLegalTitlePoint, dmOVM).
  89
  90 Constraints: Sender must have PRIVIL_CREATE_DM permission.
  91 Constraints: Exactly one document in message must be main type.
  92 Constraints: Total size of all documents must not be bigger than 10 MB.
  93
  94 Identifier of just sent message assigned by system is returned.
  95
  96 Error codes:
  97     0000    Message sent successfully
  98 Non-normative error codes:
  99     1214    Document desciption is not a filename with acceptable file name
 100             extension
 101     1214    Document description extension does not match document content
 102     1214    Provided MIME type does not match document
 103     2010    First document structure invalid
 104     2032    Message does not carry any document
 105     9005    Message not valid (probably)
 106
 107 In case of positive virus detection (processed after sending), infected
 108 document is removed, message state is set to value 3 (from point of view of
 109 recipient) and sender get new message originated by server.
 110
 111
 112 MessageDownload
 113 ===============
 114
 115 Retrieve incoming message identified by message ID.
 116
 117 Error codes:
 118     0000    Message sent successfully
 119 Non-normative error codes:
 120     1219    Message with ID does not exist in ISDS in current box.
 121
 122
 123 SignedMessageDownload
 124 =====================
 125
 126 Download incoming message with digital signature of ministery of interiors
 127 identified by message ID.
 128
 129 Return PKCS#7 structure containing data as defined in MessageDownload and
 130 digital signature of the message by ministery.
 131
 132 The data are XML document with mangled ISDS name space:
 133 http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/message:
 134
 135 <q:MessageDownloadResponse
 136      xmlns:q="http://isds.czechpoint.cz/v20/message">
 137   <q:dmReturnedMessage>
 138      <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 139          <p:dmID>151916</p:dmID>
 140          ...
 141      </p:dmDm>
 142      <q:dmHash algorithm="SHA-1">...</q:dmHash>
 143      ...
 144      <q:dmAttachmentSize>260</q:dmAttachmentSize>
 145   </q:dmReturnedMessage>
 146 </q:MessageDownloadResponse>
 147
 148
 149 SignedSentMessageDownload
 150 =========================
 151
 152 Download outgoing message with digital signature of ministery of interiors
 153 identified by ID.
 154
 155 Return PKCS#7 structure containing data as defined in MessageDownload and
 156 digital signature of the message by ministery.
 157
 158 The data are XML document with mangled ISDS name space:
 159 http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/SentMessage:
 160
 161 <q:MessageDownloadResponse
 162      xmlns:q="http://isds.czechpoint.cz/v20/SentMessage">
 163   <q:dmReturnedMessage>
 164      <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 165          <p:dmID>151916</p:dmID>
 166          ...
 167      </p:dmDm>
 168      <q:dmHash algorithm="SHA-1">...</q:dmHash>
 169      ...
 170      <q:dmAttachmentSize>260</q:dmAttachmentSize>
 171   </q:dmReturnedMessage>
 172 </q:MessageDownloadResponse>
 173
 174
 175 GetListOfRecievedMessages
 176 =========================
 177
 178 Download list of incoming messages matching search criteria.
 179
 180 See GetListOfSentMessages for more details.
 181
 182
 183 GetListOfSentMessages
 184 =====================
 185
 186 Download list of outgoing messages matching search criteria.
 187
 188 Non-normative error codes:
 189     2017    Syntax error in date-time
 190
 191
 192 VerifyMessage
 193 =============
 194
 195 Retrieve message hash (dmHash element) for given message from ISDS.
 196
 197 Works for not yet deleted messages only.
 198
 199 Only SHA-1 algorithm is in use currently. SHA-2 family is expected after
 200 2010 year begining.
 201
 202 Hash input is isds:dmDM subtree procesed as raw bit stream without XML
 203 canonicalization. Authoritative isds:dmDM element can be get via
 204 MessageDownload service. God bless ISDS developers not change XML
 205 serialization.
 206
 207 Non-normative error codes:
 208     1219    Message with ID does not exist in ISDS.
 209
 210
 211 MessageEnvelopeDownload
 212 =======================
 213
 214 Download envelope of incoming message. That is message without documents.
 215
 216 Returend hash and timestamp are computed from whole message. You must get
 217 complete message inluding documents to be able to verify them.
 218
 219
 220 MarkMessageAsDownloaded
 221 =======================
 222
 223 Change status of a message identidied by its ID as read.
 224
 225 That means next GetListOfRecievedMessages service can exclude such message if
 226 only unread messages requested.
 227
 228
 229 FindDataBox (*)
 230 ===========
 231
 232 Find boxes conforming to serch criteria or exact ID and returns corresponding
 233 (possibly truncated) list of boxes.
 234
 235 Returned boxes exist, but it does not mean they can recieve messages. Use
 236 CheckDataBox to figure out.
 237
 238 If dbID filled in request, search only to exact box.
 239 If identifier and registryCode filled, search only to exact box.
 240 Otherwise search against other criteria.
 241
 242 Returns list of boxes (possibly empty).
 243
 244 Error codes:
 245     0002    No box suits to search request (by other criteria)
 246     0003    To much boxes suit to search request (by other criteria),
 247             response truncated. Returned list of boxes is still valid.
 248     5001    No such box exists (by box ID or registry identifier)
 249 Non-normative error codes:
 250     1101    Box type (dbType) must be specified
 251     2017    Syntax error in date (biDate)
 252
 253
 254 CheckDataBox (*)
 255 ============
 256
 257 Return state of one box identified by dbID.
 258
 259 State of the box is stored in dbStatus element:
 260     0 or empty  Error occurred
 261     1           Box is accessible.
 262     2           Temporarily unaccesible
 263     3           Not yet active
 264     4           Permanently unaccesible
 265     5           Box has been removed
 266
 267 Only state 1 means box is capable of receiving messages.
 268
 269 Error codes:
 270     5001    Box does not exist
 271 Non-normative:
 272     2011    Box ID malformed