doc/user_web_services

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