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.11 (2010-05-20)
   7 Source: Webové služby ISDS pro vyhledávání datových schránek,
   8     version 2.11 (2010-05-19)
   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. Those marked with plus has
  23 access to envelopes of deleted messages.
  24
  25
  26 dm_operations.wsdl
  27 ==================
  28
  29 URL postfix: dz
  30 Constraints: Client must be authenticated 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 ministry of interiors
  40 SignedSentMessageDownload
  41     Download outgoing message with digital signature of ministry of interiors
  42 AuthenticateMessage (+)
  43     Submit local message copy to ISDS to confirm message authenticity
  44 DummyOperation
  45     Void operation used to log in and to keep connection alive
  46
  47
  48 dm_info.wsdl
  49 ============
  50
  51 URL postfix: dx
  52 Constraints: Client must be authenticated in Access Manager
  53
  54 VerifyMessage (+)
  55     Verify local copy of message with remote original stored in ISDS
  56 MessageEnvelopeDownload (+)
  57     Download envelope of incoming message
  58 MarkMessageAsDownloaded
  59     Mark message as read
  60 ConfirmDelivery
  61     Mark commercial message as accepted by recipient
  62 GetDeliveryInfo (+)
  63     Download info-sheet about message post and delivery
  64 GetSignedDeliveryInfo (+)
  65     Download info-sheet about message post and delivery with signature of
  66     ministry of interiors
  67 GetListOfRecievedMessages
  68     Download list of incoming messages
  69 GetListOfSentMessages
  70     Download list of outgoing messages
  71
  72
  73 db_search.wsdl
  74 ==============
  75
  76 URL postfix: df
  77
  78 FindDataBox (*)
  79     Find boxes conforming to search criteria
  80 CheckDataBox (*)
  81     Return state of given box
  82
  83
  84 CreateMessage (*)
  85 =============
  86
  87 Create and send a message.
  88
  89 Envelope of outgoing message must contain dbIDRecipient and dmAnnotation.
  90 Other elements are optional (dmRecipientOrgUnit, dmRecipientOrgUnitNum,
  91 dmSenderOrgUnit, dmSenderOrgUnitNum, dmToHands, dmPersonalDelivery,
  92 dmAllowSubstDelivery, dmRecipientRefNumber, dmRecipientIdent,
  93 dmSenderRefNumber, dmSenderIdent, dmLegalTitleLaw, dmLegalTitleYear,
  94 dmLegalTitleSect, dmLegalTitlePar, dmLegalTitlePoint, dmOVM).
  95
  96 Since 2010-05-20, outgoing message envelope can specify dmType. However it's
  97 currently ignored.
  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 description is not a file name 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 dbIDRecipient and dmToHands are mandatory. Other dmRecipient children are
 131 optional.
 132
 133 Structure:
 134 CreateMultipleMessage
 135     + dmRecipients
 136     |   + dmRecipient
 137     |   |   + dbIDRecipient – recipient box ID
 138     |   |   + dmRecipientOrgUnit
 139     |   |   + dmRecipientOrgUnitNum
 140     |   |   + dmToHands – can be empty, but must not missing
 141     |   + dmRecipient
 142     |   ⋮
 143     + dmEnvelope
 144     |   + <other elements, usually empty>: dmSenderOrgUnit, dmSenderOrgUnitNum,
 145     |   |   dmAnnotation, dmRecipientRefNumber, dmSenderRefNumber,
 146     |   |   dmRecipientIdent, dmSenderIdent, dmLegalTitleLaw,
 147     |   |   dmLegalTitleYear, dmLegalTitleSect, dmLegalTitlePar,
 148     |   |   dmLegalTitlePoint, dmPersonalDelivery, dmAllowSubstDelivery
 149     |   + dmOVM – optional
 150     + dmFiles
 151
 152 ISDS outputs list of assigned message IDs (each copy gets independent ID),
 153 list of sent status for each message ID and one cumulative status of
 154 whole CreateMultipleMessage operation.
 155
 156 If operation fails before replicating messages for each recipient
 157 (i.e. sending), global error code will be non-zero. If operation fails on some
 158 message copies (i.e. while sending) special global error code 0004 will be
 159 returned and erroneous recipients can be gather by recipient specific error
 160 code (failed ones will have non-zero code). If all messages are sent
 161 successfully, global error code will be 0000.
 162
 163 Structure:
 164 CreateMultipleMessageResponse
 165     + dmMultipleStatus
 166     |   + dmSingleStatus
 167     |   |   + dmID – assigned message ID, optional, missing if error occurred
 168     |   |   + dmStatus – message local error code and textual description
 169     |   + dmSingleStatus
 170     |   ⋮
 171     + dmStatus – global error code and textual description
 172
 173 Global error codes:
 174     0000    Messages sent successfully
 175     0004    Some message failed while sending
 176
 177
 178 MessageDownload
 179 ===============
 180
 181 Retrieve incoming message identified by message ID.
 182
 183 This service can return message without digital time-stamp (more precisely
 184 with empty dmQTimesamp element, see schema).
 185
 186 Commercial message must be accepted manually by ConfirmDelivery before.
 187 Commercial message has set dmReturnedMessage/@dmType="K".
 188
 189 Error codes:
 190     0000    Message sent successfully
 191 Non-normative error codes:
 192     1219    Message with ID does not exist in ISDS in current box.
 193
 194
 195 SignedMessageDownload
 196 =====================
 197
 198 Download incoming message with digital signature of ministry of interiors
 199 identified by message ID.
 200
 201 Return PKCS#7 structure containing data as defined in MessageDownload and
 202 digital signature of the message by ministry.
 203
 204 The data are XML document with mangled ISDS name space:
 205 http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/message:
 206
 207 <q:MessageDownloadResponse
 208      xmlns:q="http://isds.czechpoint.cz/v20/message">
 209   <q:dmReturnedMessage>
 210      <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 211          <p:dmID>151916</p:dmID>
 212          ...
 213      </p:dmDm>
 214      <q:dmHash algorithm="SHA-1">...</q:dmHash>
 215      ...
 216      <q:dmAttachmentSize>260</q:dmAttachmentSize>
 217   </q:dmReturnedMessage>
 218 </q:MessageDownloadResponse>
 219
 220 Commercial message must be accepted manually by ConfirmDelivery before.
 221
 222
 223 SignedSentMessageDownload
 224 =========================
 225
 226 Download outgoing message with digital signature of ministry of interiors
 227 identified by ID.
 228
 229 Return PKCS#7 structure containing data as defined in MessageDownload and
 230 digital signature of the message by ministry.
 231
 232 The data are XML document with mangled ISDS name space:
 233 http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/SentMessage:
 234
 235 <q:MessageDownloadResponse
 236      xmlns:q="http://isds.czechpoint.cz/v20/SentMessage">
 237   <q:dmReturnedMessage>
 238      <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 239          <p:dmID>151916</p:dmID>
 240          ...
 241      </p:dmDm>
 242      <q:dmHash algorithm="SHA-1">...</q:dmHash>
 243      ...
 244      <q:dmAttachmentSize>260</q:dmAttachmentSize>
 245   </q:dmReturnedMessage>
 246 </q:MessageDownloadResponse>
 247
 248
 249 GetListOfRecievedMessages
 250 =========================
 251
 252 Download list of incoming messages matching search criteria.
 253
 254 See GetListOfSentMessages for more details.
 255
 256
 257 GetListOfSentMessages
 258 =====================
 259
 260 Download list of outgoing messages matching search criteria.
 261
 262 Criteria are: delivery time not before, not after, organisation unit number of
 263 sender, message status filter, offset of first message in a list and limit on
 264 number of messages to get.
 265
 266 Message status filter is union of distinct message states expressed as
 267 exponents of 2. Effectively it's a polynom \sum_{x \in message_statux} 2^x.
 268 Special value -1 means all messages. Meaning for value 1 or 0 is undefined.
 269
 270 Messages are sorted in order of delivery time. Message type is stored in
 271 dmRecord/@dmType.
 272
 273 Offset starts on 1. Limit defaults to 1000.
 274
 275 Non-normative error codes:
 276     2017    Syntax error in date-time
 277
 278
 279 AuthenticateMessage (+)
 280 ===================
 281
 282 Allows to verify message authenticity by providing copy to ISDS.
 283
 284 Only signed message encapsuleted into CMS structure with digital signature can
 285 be verified by this service. Client pass the raw message in Base64 encoding to
 286 ISDS, system performs checks and return boolean value: true if message has
 287 not been modified and has been delivered through ISDS, false if message
 288 has is unkown to ISDS. In both cases 0000 error code will be returned.
 289
 290 If message cannot be processed (e.g. broken CMS or XML syntax) or message
 291 contains has been signed by non-ISDS certificate or other error, non-zero
 292 error code will be returned.
 293
 294
 295 VerifyMessage (+)
 296 =============
 297
 298 Retrieve message hash (dmHash element) for given message from ISDS.
 299
 300 Works for not yet deleted messages only.
 301
 302 Only SHA-1 algorithm is in use currently. SHA-2 family is expected after
 303 2010 year beginning.
 304
 305 Hash input is isds:dmDM subtree processed as raw bit stream without XML
 306 canonicalization. Authoritative isds:dmDM element can be get via
 307 MessageDownload service. God bless ISDS developers to not change XML
 308 serialization.
 309
 310 Non-normative error codes:
 311     1219    Message with ID does not exist in ISDS.
 312
 313
 314 MessageEnvelopeDownload (+)
 315 =======================
 316
 317 Download envelope of incoming message. That is message without documents.
 318 Message type is stored in dmReturnedMessageEnvelope/@dmType.
 319
 320 Returned hash and time-stamp are computed from whole message. You must get
 321 complete message including documents to be able to verify them.
 322
 323
 324 MarkMessageAsDownloaded
 325 =======================
 326
 327 Change status of a message identified by its ID as read.
 328
 329 That means next GetListOfRecievedMessages service can exclude such message if
 330 only unread messages requested.
 331
 332
 333 ConfirmDelivery
 334 ===============
 335
 336 Mark commercial message as accepted by recipient.
 337
 338 Changes message state from delivered (4) to accepted (6). Applicable only to
 339 commercial messages. Messages from public offices (municipalities, government
 340 etc.) are accepted automatically by log-in on interactive web portal or by
 341 triggering most of SOAP operations.
 342
 343 Must be called before downloading (signed or unsigned) incoming message
 344 [Signed]MessageDownload.
 345
 346
 347 GetDeliveryInfo (+)
 348 ===============
 349
 350 Download info-sheet about incoming or outgoing message post and delivery or
 351 deliver impossibility. The message is specified by message ID.
 352
 353 It returns complete message envelope, hash, time-stamp. Delivery time and
 354 acceptance time only if message has been delivered to recipient box or
 355 accepted by recipient. Precise status of message is returned too.
 356
 357 In addition, non-empty list of events is attached. Each event compounds of
 358 ISO time and text description. The text description has well-known prefix to
 359 distinguish the event meaning. Following prefixes are defined:
 360
 361     Prefix  Meaning
 362     -----------------------------------------------------
 363     EV1:    Message has been accepted by recipient action
 364     EV2:    Message has been delivered to box and is considered as accepted by
 365             no-user-action time out (through fiction)
 366     EV3:    Recipient box has been made inaccessible retrospectively
 367             (even after successful delivery or acceptance,
 368             this event is retroactive). In this case special system-generated
 369             message is sent to sender in addition.
 370     EV4:    Commercial message has been accepted by recipient confirmation
 371
 372
 373 GetSignedDeliveryInfo (+)
 374 =====================
 375
 376 Download info-sheet about incoming or outgoing message post and delivery or
 377 deliver impossibility as signed PKCS#7 structure. See GetDeliveryInfo for
 378 details about returned data.
 379
 380 The PKCS#7 structure carries digital signature made by ministry of interiors.
 381
 382 There is mangled namespace again: http://isds.czechpoint.cz/v20/ vs.
 383 http://isds.czechpoint.cz/v20/delivery:
 384
 385 <q:GetDeliveryInfoResponse xmlns:q="http://isds.czechpoint.cz/v20/delivery">
 386   <q:dmDelivery>
 387     <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 388       <p:dmID>170272</p:dmID>
 389       ...
 390     </p:dmDm>
 391     <q:dmHash algorithm="SHA-1">...</q:dmHash>
 392     ...
 393     </q:dmEvents>...</q:dmEvents>
 394   </q:dmDelivery>
 395 </q:GetDeliveryInfoResponse>
 396
 397
 398 FindDataBox (*)
 399 ===========
 400
 401 Find boxes conforming to search criteria or exact ID and return corresponding
 402 (possibly truncated) list of boxes.
 403
 404 Returned boxes exist, but it does not mean they can receive messages. Use
 405 CheckDataBox to figure out.
 406
 407 There are three different search cases distinguished in this order:
 408
 409     – If dbID is filled in request, it will search for exact box only, other
 410     criteria will be ignored.
 411
 412     – If identifier and registryCode are filled, it will search for exact
 413     box only, other criteria will be ignored.
 414
 415     – Otherwise search against other criteria.
 416
 417 Returns list of boxes (possibly empty).
 418
 419 List can be truncated or search request refused because of not enough
 420 specific criteria to protect user privacy. There are following constrains
 421 differentiated by box type now:
 422
 423 Gross Box type  Constraints (required search criteria)
 424 ------------------------------------------------------
 425 FO              pnLastName or pnLastNameAtBirth
 426 PFO             ic or pnLastName or pnLastNameAtBirth
 427 PO              ic or prefix (at least 3 characters) of firmName
 428 OVM             ic or prefix of firmName
 429
 430 String search criteria are matched case insensitive (except dbID). Strings are
 431 compared to prefix. Except firmName, adCity, adStreet and biCity that are
 432 matched as substrings.
 433
 434 Search results depends or logged-in user type. Users of boxes with open
 435 addressing can search other open-addressing boxes, otherwise only OVM type
 436 boxes can be searched. Search based on exact box identifier finder unlimited.
 437
 438 Error codes:
 439     0002    No box suits to search request (by other criteria)
 440     0003    To much boxes suit to search request (by other criteria),
 441             response truncated. Returned list of boxes is still valid.
 442     5001    No such box exists (by box ID or registry identifier)
 443 Non-normative error codes:
 444     1101    Box type (dbType) must be specified
 445     2017    Syntax error in date (biDate)
 446
 447
 448 CheckDataBox (*)
 449 ============
 450
 451 Return state of one box identified by dbID.
 452
 453 State of the box is stored in dbStatus element. Only state 1 means box is
 454 capable of receiving messages.
 455
 456 Error codes:
 457     5001    Box does not exist
 458 Non-normative:
 459     2011    Box ID malformed