doc/user_web_services

   1 User web services specification
   2 ===============================
   3
   4 Source: Provozní řád ISDS, version 2009-10-30, Pages 13–14
   5 Source: Webové služby ISDS pro manipulaci s datovými zprávami,
   6     version 2.1 (2009-10-30)
   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, DBSearch_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 CreateMultipleMessage (*)
  35     Create and send a message to multiple recipients
  36 MessageDownload
  37     Download incoming message
  38 SignedMessageDownload
  39     Download incoming message with digital signature of ministery of interiors
  40 SignedSentMessageDownload
  41     Download outgoing message with digital signature of ministery of interiors
  42 DummyOperation
  43     Void operation used to log in and to keep connection alive
  44
  45
  46 dm_info.wsdl
  47 ============
  48
  49 URL postfix: dx
  50 Constraints: Client must be autenticated in Access Manager
  51
  52 VerifyMessage
  53     Verify local copy of message with remote original stored in ISDS
  54 MessageEnvelopeDownload
  55     Download envelope of incoming message
  56 MarkMessageAsDownloaded
  57     Mark message as read
  58 GetDeliveryInfo
  59     Download infosheet about message post and delivery
  60 GetSignedDeliveryInfo
  61     Download infosheet about message post and delivery with signature of
  62     ministery of interiors
  63 GetListOfRecievedMessages
  64     Download list of incoming messages
  65 GetListOfSentMessages
  66     Download list of outgoing messages
  67
  68
  69 db_search.wsdl
  70 ==============
  71
  72 URL postfix: df
  73
  74 FindDataBox (*)
  75     Find boxes conforming to serch criteria
  76 CheckDataBox (*)
  77     Return state of given box
  78
  79
  80 Unsorted operations
  81 ===================
  82
  83 ConfirmDelivery
  84     Mark commercial message as accepted by recipient
  85
  86
  87 CreateMessage (*)
  88 =============
  89
  90 Create and send a message.
  91
  92 Envelope of outgoing message must contain dbIDRecipient and dmAnnotation.
  93 Other elements are optional (dmRecipientOrgUnit, dmRecipientOrgUnitNum,
  94 dmSenderOrgUnit, dmSenderOrgUnitNum, dmToHands, dmPersonalDelivery,
  95 dmAllowSubstDelivery, dmRecipientRefNumber, dmRecipientIdent,
  96 dmSenderRefNumber, dmSenderIdent, dmLegalTitleLaw, dmLegalTitleYear,
  97 dmLegalTitleSect, dmLegalTitlePar, dmLegalTitlePoint, dmOVM).
  98
  99 Constraints: Sender must have PRIVIL_CREATE_DM permission.
 100 Constraints: Exactly one document in message must be main type.
 101 Constraints: Total size of all documents must not be bigger than 10 MB.
 102
 103 Identifier of just sent message assigned by system is returned.
 104
 105 Error codes:
 106     0000    Message sent successfully
 107 Non-normative error codes:
 108     1214    Document desciption is not a filename with acceptable file name
 109             extension
 110     1214    Document description extension does not match document content
 111     1214    Provided MIME type does not match document
 112     2010    First document structure invalid
 113     2032    Message does not carry any document
 114     9005    Message not valid (probably)
 115
 116 In case of positive virus detection (processed after sending), infected
 117 document is removed, message state is set to value 3 (from point of view of
 118 recipient) and sender get new message originated by server.
 119
 120
 121 CreateMultipleMessage (*)
 122 =====================
 123
 124 Create and send a message to multiple recipients.
 125
 126 Input composes of nonempty list of recipients (maximal count is 50),
 127 one envelope (different from envelope for CreateMessage, misses elements from
 128 dmRecipient) and list of documents to send to all of them to each recipient.
 129
 130 Only dmRecipient and dmToHands are mandatory. Other dmRecipient childs are
 131 optional.
 132
 133 Structure:
 134 CreateMultipleMessage
 135     + dmRecipients
 136     |   + dmRecipient
 137     |   |   + dbIDRecipient – recipient box ID
 138     |   |   + dmRecipientOrgUnit
 139     |   |   + dmRecipientOrgUnitNum
 140     |   |   + dmRecipientOrgUnitNum
 141     |   |   + dmToHands – can be empty, but must not missing
 142     |   + dmRecipient
 143     |   ⋮
 144     + dmEnvelope
 145     |   + <other elements, usually empty>: dmSenderOrgUnit, dmSenderOrgUnitNum,
 146     |   |   dmAnnotation, dmRecipientRefNumber, dmSenderRefNumber,
 147     |   |   dmRecipientIdent, dmSenderIdent, dmLegalTitleLaw,
 148     |   |   dmLegalTitleYear, dmLegalTitleSect, dmLegalTitlePar,
 149     |   |   dmLegalTitlePoint, dmPersonalDelivery, dmAllowSubstDelivery
 150     |   + dmOVM – optional
 151     + dmFiles
 152
 153 ISDS outputs list of assigned message IDs (each copy gets independent ID),
 154 list of sent status for each message ID and one cumulative status of
 155 whole CreateMultipleMessage operation.
 156
 157 If operation failes before replicating messages for each recipient
 158 (i.e. sending), global error code will be non-zero. If operation fails on some
 159 message copies (i.e. while sending) special global error code 0004 will be
 160 returned and errornous recipients can be gather by recipient specific error
 161 code (failed ones will have non-zero code). If all messages are sent
 162 successfully, global error code will be 0000.
 163
 164 Structure:
 165 CreateMultipleMessageResponse
 166     + dmMultipleStatus
 167     |   + dmSingleStatus
 168     |   |   + dmID – assigned message ID, optional, missing if error occured
 169     |   |   + dmStatus – message local error code and textual desciption
 170     |   + dmSingleStatus
 171     |   ⋮
 172     + dmStatus – global error code and textual description
 173
 174 Global error codes:
 175     0000    Messages sent successfully
 176     0004    Some message failed while sending
 177
 178
 179 MessageDownload
 180 ===============
 181
 182 Retrieve incoming message identified by message ID.
 183
 184 Commercial message must be accepted manually by ConfirmDelivery before.
 185
 186 Error codes:
 187     0000    Message sent successfully
 188 Non-normative error codes:
 189     1219    Message with ID does not exist in ISDS in current box.
 190
 191
 192 SignedMessageDownload
 193 =====================
 194
 195 Download incoming message with digital signature of ministery of interiors
 196 identified by message ID.
 197
 198 Return PKCS#7 structure containing data as defined in MessageDownload and
 199 digital signature of the message by ministery.
 200
 201 The data are XML document with mangled ISDS name space:
 202 http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/message:
 203
 204 <q:MessageDownloadResponse
 205      xmlns:q="http://isds.czechpoint.cz/v20/message">
 206   <q:dmReturnedMessage>
 207      <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 208          <p:dmID>151916</p:dmID>
 209          ...
 210      </p:dmDm>
 211      <q:dmHash algorithm="SHA-1">...</q:dmHash>
 212      ...
 213      <q:dmAttachmentSize>260</q:dmAttachmentSize>
 214   </q:dmReturnedMessage>
 215 </q:MessageDownloadResponse>
 216
 217 Commercial message must be accepted manually by ConfirmDelivery before.
 218
 219
 220 SignedSentMessageDownload
 221 =========================
 222
 223 Download outgoing message with digital signature of ministery of interiors
 224 identified by ID.
 225
 226 Return PKCS#7 structure containing data as defined in MessageDownload and
 227 digital signature of the message by ministery.
 228
 229 The data are XML document with mangled ISDS name space:
 230 http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/SentMessage:
 231
 232 <q:MessageDownloadResponse
 233      xmlns:q="http://isds.czechpoint.cz/v20/SentMessage">
 234   <q:dmReturnedMessage>
 235      <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 236          <p:dmID>151916</p:dmID>
 237          ...
 238      </p:dmDm>
 239      <q:dmHash algorithm="SHA-1">...</q:dmHash>
 240      ...
 241      <q:dmAttachmentSize>260</q:dmAttachmentSize>
 242   </q:dmReturnedMessage>
 243 </q:MessageDownloadResponse>
 244
 245
 246 GetListOfRecievedMessages
 247 =========================
 248
 249 Download list of incoming messages matching search criteria.
 250
 251 See GetListOfSentMessages for more details.
 252
 253
 254 GetListOfSentMessages
 255 =====================
 256
 257 Download list of outgoing messages matching search criteria.
 258
 259 Non-normative error codes:
 260     2017    Syntax error in date-time
 261
 262
 263 VerifyMessage
 264 =============
 265
 266 Retrieve message hash (dmHash element) for given message from ISDS.
 267
 268 Works for not yet deleted messages only.
 269
 270 Only SHA-1 algorithm is in use currently. SHA-2 family is expected after
 271 2010 year begining.
 272
 273 Hash input is isds:dmDM subtree procesed as raw bit stream without XML
 274 canonicalization. Authoritative isds:dmDM element can be get via
 275 MessageDownload service. God bless ISDS developers to not change XML
 276 serialization.
 277
 278 Non-normative error codes:
 279     1219    Message with ID does not exist in ISDS.
 280
 281
 282 MessageEnvelopeDownload
 283 =======================
 284
 285 Download envelope of incoming message. That is message without documents.
 286
 287 Returend hash and timestamp are computed from whole message. You must get
 288 complete message inluding documents to be able to verify them.
 289
 290
 291 MarkMessageAsDownloaded
 292 =======================
 293
 294 Change status of a message identidied by its ID as read.
 295
 296 That means next GetListOfRecievedMessages service can exclude such message if
 297 only unread messages requested.
 298
 299
 300 GetDeliveryInfo
 301 ===============
 302
 303 Download infosheet about incoming or outgoing message post and delivery or
 304 deliver impossibility. The message is specified by message ID.
 305
 306 It returns complete message envelope, hash, timestamp. Delivery time and
 307 acceptance time only if message has been delivered to recipient box or
 308 accepted by recipient. Precise status of message is returned too.
 309
 310 In addition, non-empty list of events is attached. Each event compounds of
 311 ISO time and text description. The text description has well-known prefix to
 312 distinguishe the event meaning. Following prefixes are defined:
 313
 314     Prefix  Meaning
 315     -----------------------------------------------------
 316     EV1:    Message has been accepted by recipient action
 317     EV2:    Message has been delivered to box and is considered as accepted by
 318             no-user-action time out (through fiction)
 319     EV3:    Recipient box has been made unaccessible retrospectively
 320             (even after successful delivery or acceptance,
 321             this event is retroactive). In this case special system-generated
 322             message is sent to sender in addition.
 323
 324
 325 GetSignedDeliveryInfo
 326 =====================
 327
 328 Download infosheet about incoming or outgoing message post and delivery or
 329 deliver impossibility as signed PKCS#7 structure. See GetDeliveryInfo for
 330 details about returned data.
 331
 332 The PKCS#7 structure carries digital signature made by ministery of interiours.
 333
 334 There is mangled namespace again: http://isds.czechpoint.cz/v20/ vs.
 335 http://isds.czechpoint.cz/v20/delivery:
 336
 337 <q:GetDeliveryInfoResponse xmlns:q="http://isds.czechpoint.cz/v20/delivery">
 338   <q:dmDelivery>
 339     <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 340       <p:dmID>170272</p:dmID>
 341       ...
 342     </p:dmDm>
 343     <q:dmHash algorithm="SHA-1">...</q:dmHash>
 344     ...
 345     </q:dmEvents>...</q:dmEvents>
 346   </q:dmDelivery>
 347 </q:GetDeliveryInfoResponse>
 348
 349
 350 FindDataBox (*)
 351 ===========
 352
 353 Find boxes conforming to serch criteria or exact ID and returns corresponding
 354 (possibly truncated) list of boxes.
 355
 356 Returned boxes exist, but it does not mean they can recieve messages. Use
 357 CheckDataBox to figure out.
 358
 359 If dbID filled in request, search only to exact box.
 360 If identifier and registryCode filled, search only to exact box.
 361 Otherwise search against other criteria.
 362
 363 Returns list of boxes (possibly empty).
 364
 365 Error codes:
 366     0002    No box suits to search request (by other criteria)
 367     0003    To much boxes suit to search request (by other criteria),
 368             response truncated. Returned list of boxes is still valid.
 369     5001    No such box exists (by box ID or registry identifier)
 370 Non-normative error codes:
 371     1101    Box type (dbType) must be specified
 372     2017    Syntax error in date (biDate)
 373
 374
 375 CheckDataBox (*)
 376 ============
 377
 378 Return state of one box identified by dbID.
 379
 380 State of the box is stored in dbStatus element:
 381     0 or empty  Error occurred
 382     1           Box is accessible.
 383     2           Temporarily unaccesible
 384     3           Not yet active
 385     4           Permanently unaccesible
 386     5           Box has been removed
 387
 388 Only state 1 means box is capable of receiving messages.
 389
 390 Error codes:
 391     5001    Box does not exist
 392 Non-normative:
 393     2011    Box ID malformed
 394
 395
 396 ConfirmDelivery
 397 ===============
 398
 399 Mark commercial message as accepted by recipient.
 400
 401 Changes message state from delivered (4) to accepted (6). Appliable only to
 402 commercial messages. Messages from public offices (municipalities, government
 403 etc.) are accepted automatically by login on interactive web portal or by
 404 triggering most of SOAP operations.
 405
 406 Must be called before downloading (signed or unsigned) incoming message
 407 [Signed]MessageDownload.