doc/user_web_services

   1 User web services specification
   2 ===============================
   3
   4 Source: Provozní řád ISDS, version 2010-11-28, Pages 15–16
   5 Source: Webové služby ISDS pro manipulaci s datovými zprávami,
   6     version 2.23 (2011-11-24)
   7 Source: Webové služby ISDS pro vyhledávání datových schránek,
   8     version 2.23 (2011-11-15)
   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 GetMessageAuthor
  72     Get details about sender
  73 GetMessageStateChanges
  74     Download list of outgoing messages that changed state
  75
  76
  77 db_search.wsdl
  78 ==============
  79
  80 URL postfix: df
  81
  82 FindDataBox (*)
  83     Find boxes conforming to search criteria
  84 CheckDataBox (*)
  85     Return state of given box
  86 GetDataBoxList (*)
  87     Get list of all boxes
  88 PDZInfo
  89     Rules for sending commercial messages of given box
  90
  91
  92 CreateMessage (*)
  93 =============
  94
  95 Create and send a message.
  96
  97 Envelope of outgoing message must contain dbIDRecipient and dmAnnotation.
  98 Other elements are optional (dmRecipientOrgUnit, dmRecipientOrgUnitNum,
  99 dmSenderOrgUnit, dmSenderOrgUnitNum, dmToHands, dmPersonalDelivery,
 100 dmAllowSubstDelivery, dmRecipientRefNumber, dmRecipientIdent,
 101 dmSenderRefNumber, dmSenderIdent, dmLegalTitleLaw, dmLegalTitleYear,
 102 dmLegalTitleSect, dmLegalTitlePar, dmLegalTitlePoint, dmOVM, dmPublishOwnID).
 103
 104 Since 2010-05-20, outgoing message envelope can specify dmType. However it's
 105 currently ignored.
 106
 107 Constraints: Sender must have PRIVIL_CREATE_DM permission.
 108 Constraints: Exactly one document in message must be main type.
 109 Constraints: Total size of all documents must not be bigger than 10 MB.
 110
 111 Identifier of just sent message assigned by system is returned.
 112
 113 Error codes:
 114     0000    Message sent successfully
 115 Non-normative error codes:
 116     1214    Document description is not a file name with acceptable file name
 117             extension
 118     1214    Document description extension does not match document content
 119     1214    Provided MIME type does not match document
 120     2010    First document structure invalid
 121     2032    Message does not carry any document
 122     9005    Message not valid (probably)
 123
 124 In case of positive virus detection (processed after sending), infected
 125 document is removed, message state is set to value 3 (from point of view of
 126 recipient) and sender get new message originated by server.
 127
 128
 129 CreateMultipleMessage (*)
 130 =====================
 131
 132 Create and send a message to multiple recipients.
 133
 134 Input composes of nonempty list of recipients (maximal count is 50),
 135 one envelope (different from envelope for CreateMessage, misses elements from
 136 dmRecipient) and list of documents to send to all of them to each recipient.
 137
 138 Only dbIDRecipient and dmToHands are mandatory. Other dmRecipient children are
 139 optional.
 140
 141 Structure:
 142 CreateMultipleMessage
 143     + dmRecipients
 144     |   + dmRecipient
 145     |   |   + dbIDRecipient – recipient box ID
 146     |   |   + dmRecipientOrgUnit
 147     |   |   + dmRecipientOrgUnitNum
 148     |   |   + dmToHands – can be empty, but must not missing
 149     |   + dmRecipient
 150     |   ⋮
 151     + dmEnvelope
 152     |   + <other elements, usually empty>: dmSenderOrgUnit, dmSenderOrgUnitNum,
 153     |   |   dmAnnotation, dmRecipientRefNumber, dmSenderRefNumber,
 154     |   |   dmRecipientIdent, dmSenderIdent, dmLegalTitleLaw,
 155     |   |   dmLegalTitleYear, dmLegalTitleSect, dmLegalTitlePar,
 156     |   |   dmLegalTitlePoint, dmPersonalDelivery, dmAllowSubstDelivery
 157     |   + dmOVM – optional
 158     |   + dmPublishOwnID – optional
 159     + dmFiles
 160
 161 ISDS outputs list of assigned message IDs (each copy gets independent ID),
 162 list of sent status for each message ID and one cumulative status of
 163 whole CreateMultipleMessage operation.
 164
 165 If operation fails before replicating messages for each recipient
 166 (i.e. sending), global error code will be non-zero. If operation fails on some
 167 message copies (i.e. while sending) special global error code 0004 will be
 168 returned and erroneous recipients can be gather by recipient specific error
 169 code (failed ones will have non-zero code). If all messages are sent
 170 successfully, global error code will be 0000.
 171
 172 Structure:
 173 CreateMultipleMessageResponse
 174     + dmMultipleStatus
 175     |   + dmSingleStatus
 176     |   |   + dmID – assigned message ID, optional, missing if error occurred
 177     |   |   + dmStatus – message local error code and textual description
 178     |   + dmSingleStatus
 179     |   ⋮
 180     + dmStatus – global error code and textual description
 181
 182 Global error codes:
 183     0000    Messages sent successfully
 184     0004    Some message failed while sending
 185
 186
 187 MessageDownload
 188 ===============
 189
 190 Retrieve incoming message identified by message ID.
 191
 192 This service can return message without digital time-stamp (more precisely
 193 with empty dmQTimesamp element, see schema).
 194
 195 Commercial message must be accepted manually by ConfirmDelivery before.
 196 Commercial message has set dmReturnedMessage/@dmType="K".
 197
 198 Error codes:
 199     0000    Message sent successfully
 200 Non-normative error codes:
 201     1219    Message with ID does not exist in ISDS in current box.
 202
 203
 204 SignedMessageDownload
 205 =====================
 206
 207 Download incoming message with digital signature of ministry of interiors
 208 identified by message ID.
 209
 210 Return PKCS#7 structure containing data as defined in MessageDownload and
 211 digital signature of the message by ministry.
 212
 213 The data are XML document with mangled ISDS name space:
 214 http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/message:
 215
 216 <q:MessageDownloadResponse
 217      xmlns:q="http://isds.czechpoint.cz/v20/message">
 218   <q:dmReturnedMessage>
 219      <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 220          <p:dmID>151916</p:dmID>
 221          ...
 222      </p:dmDm>
 223      <q:dmHash algorithm="SHA-1">...</q:dmHash>
 224      ...
 225      <q:dmAttachmentSize>260</q:dmAttachmentSize>
 226   </q:dmReturnedMessage>
 227 </q:MessageDownloadResponse>
 228
 229 Commercial message must be accepted manually by ConfirmDelivery before.
 230
 231
 232 SignedSentMessageDownload
 233 =========================
 234
 235 Download outgoing message with digital signature of ministry of interiors
 236 identified by ID.
 237
 238 Return PKCS#7 structure containing data as defined in MessageDownload and
 239 digital signature of the message by ministry.
 240
 241 The data are XML document with mangled ISDS name space:
 242 http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/SentMessage:
 243
 244 <q:MessageDownloadResponse
 245      xmlns:q="http://isds.czechpoint.cz/v20/SentMessage">
 246   <q:dmReturnedMessage>
 247      <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 248          <p:dmID>151916</p:dmID>
 249          ...
 250      </p:dmDm>
 251      <q:dmHash algorithm="SHA-1">...</q:dmHash>
 252      ...
 253      <q:dmAttachmentSize>260</q:dmAttachmentSize>
 254   </q:dmReturnedMessage>
 255 </q:MessageDownloadResponse>
 256
 257
 258 GetListOfRecievedMessages
 259 =========================
 260
 261 Download list of incoming messages matching search criteria.
 262
 263 See GetListOfSentMessages for more details.
 264
 265
 266 GetListOfSentMessages
 267 =====================
 268
 269 Download list of outgoing messages matching search criteria.
 270
 271 Criteria are: delivery time not before, not after, organisation unit number of
 272 sender, message status filter, offset of first message in a list and limit on
 273 number of messages to get.
 274
 275 Message status filter is union of distinct message states expressed as
 276 exponents of 2. Effectively it's a polynom \sum_{x \in message_statux} 2^x.
 277 Special value -1 means all messages. Meaning for value 1 or 0 is undefined.
 278
 279 Messages are sorted in order of delivery time. Message type is stored in
 280 dmRecord/@dmType.
 281
 282 Offset starts on 1. Limit defaults to 1000.
 283
 284 Non-normative error codes:
 285     2017    Syntax error in date-time
 286
 287
 288 GetMessageAuthor
 289 ================
 290
 291 Get information about sender as un user of given message.
 292
 293 Input is mandatory message identifier. Output is optional userType and
 294 optional authorName.
 295
 296 userType (unknown and undefined for older messages) is type of user who has
 297 sent the message. Be ware there is special additional type `VIRTUAL'. Be ware
 298 the userType is a string unconstrained by XML schema:
 299
 300 Value               Description
 301 --------------------------------------------------------------------------
 302 PRIMARY_USER        The sender was a owner of the box
 303 ENTRUSTED_USER      The sender was an entrusted user associated to the box
 304 ADMINISTRATOR       The sender was administrator assiciated to the box
 305 OFFICIAL            The sender was ISDS (for system messages)
 306 VIRTUAL             The sender was an application authenticated by `system'
 307                     certificate
 308
 309 Non-normative: New user types OFFICIAL_CERT and LIQUIDATOR are not listed in
 310 official documentation for this service. However LIQUIDATOR is said to be
 311 equivalent to PRIMARY_USER and PRIMARY_USER can send messages, thus I conclude
 312 these two now user types can occur in output of this service.
 313
 314 authorName is a name of user logged into senders box (not a login name) if
 315 sender allowed to reveal his name explicitely.
 316
 317
 318 GetMessageStateChanges
 319 ======================
 320
 321 Download list of outgoing messages that changed state in given time range.
 322
 323 If a message changed state multiple times, it is listed more times. Only
 324 changes from state 2 to 4, from 4 to {5, 6, 8} are reported. Only recent
 325 changes (not older than 15 days currently) are reported.
 326
 327 This service is designed for polling state changes of sent messages.
 328
 329 Input are start (dmFromTime element) and end (dmToTime element) ISO times.
 330 Empty dmFromTime meands since last 15 days, empty dmToTime means till now.
 331
 332 Non-normative: Server does not report changes at recent more than one hour.
 333
 334 Output is list of records with message state changes. The order of records is
 335 undefined.
 336
 337 Structure:
 338 GetMessageStateChangesResponse
 339     + dmRecords – optional, possibly empty element
 340     |   + dmRecord – one state change
 341     |   |   + dmId – identifier of message that changed state
 342     |   |   + dmEventTime – ISO time of state change
 343     |   |   + dmMessageStatus – new message state in numeric notation
 344     |   + dmRecord
 345     |   ⋮
 346     + dmStatus – global error code and textual description
 347
 348
 349 AuthenticateMessage (+)
 350 ===================
 351
 352 Allows to verify message authenticity by providing copy to ISDS.
 353
 354 Only signed message encapsuleted into CMS structure with digital signature can
 355 be verified by this service. Client pass the raw message in Base64 encoding to
 356 ISDS, system performs checks and return boolean value: true if message has
 357 not been modified and has been delivered through ISDS, false if message
 358 has is unkown to ISDS. In both cases 0000 error code will be returned.
 359
 360 If message cannot be processed (e.g. broken CMS or XML syntax) or message
 361 contains has been signed by non-ISDS certificate or other error, non-zero
 362 error code will be returned.
 363
 364
 365 VerifyMessage (+)
 366 =============
 367
 368 Retrieve message hash (dmHash element) for given message from ISDS.
 369
 370 Works for not yet deleted messages only.
 371
 372 Only SHA-1 algorithm is in use currently. SHA-2 family is expected after
 373 2010 year beginning.
 374
 375 Hash input is isds:dmDM subtree processed as raw bit stream without XML
 376 canonicalization. Authoritative isds:dmDM element can be get via
 377 MessageDownload service. God bless ISDS developers to not change XML
 378 serialization.
 379
 380 Non-normative error codes:
 381     1219    Message with ID does not exist in ISDS.
 382
 383
 384 MessageEnvelopeDownload (+)
 385 =======================
 386
 387 Download envelope of incoming message. That is message without documents.
 388 Message type is stored in dmReturnedMessageEnvelope/@dmType.
 389
 390 Returned hash and time-stamp are computed from whole message. You must get
 391 complete message including documents to be able to verify them.
 392
 393
 394 MarkMessageAsDownloaded
 395 =======================
 396
 397 Change status of a message identified by its ID as read.
 398
 399 That means next GetListOfRecievedMessages service can exclude such message if
 400 only unread messages requested.
 401
 402
 403 ConfirmDelivery
 404 ===============
 405
 406 Mark commercial message as accepted by recipient.
 407
 408 Changes message state from delivered (4) to accepted (6). Applicable only to
 409 commercial messages. Messages from public offices (municipalities, government
 410 etc.) are accepted automatically by log-in on interactive web portal or by
 411 triggering most of SOAP operations.
 412
 413 Must be called before downloading (signed or unsigned) incoming message
 414 [Signed]MessageDownload.
 415
 416
 417 GetDeliveryInfo (+)
 418 ===============
 419
 420 Download info-sheet about incoming or outgoing message post and delivery or
 421 deliver impossibility. The message is specified by message ID.
 422
 423 It returns complete message envelope, hash, time-stamp. Delivery time and
 424 acceptance time only if message has been delivered to recipient box or
 425 accepted by recipient. Precise status of message is returned too.
 426
 427 In addition, non-empty list of events is attached. Each event compounds of
 428 ISO time and text description. The text description has well-known prefix to
 429 distinguish the event meaning. Following prefixes are defined:
 430
 431     Prefix  Meaning
 432     -----------------------------------------------------
 433     EV0:    Message enterend into ISDS
 434     EV1:    Message has been accepted by recipient action
 435     EV2:    Message has been delivered to box and is considered as accepted by
 436             no-user-action time out (through fiction)
 437     EV3:    Recipient box has been made inaccessible retrospectively
 438             (even after successful delivery or acceptance,
 439             this event is retroactive). In this case special system-generated
 440             message is sent to sender in addition.
 441     EV4:    Commercial message has been accepted by recipient confirmation
 442     EV5:    Message has been delivered into recipent box
 443     EV11:   Primary user has logged into his box
 444     EV12:   Entrusted user havin permission to read this message has logged in
 445     EV13:   Application (not a human) has logged into box using `system'
 446             certificate
 447
 448
 449 GetSignedDeliveryInfo (+)
 450 =====================
 451
 452 Download info-sheet about incoming or outgoing message post and delivery or
 453 deliver impossibility as signed PKCS#7 structure. See GetDeliveryInfo for
 454 details about returned data.
 455
 456 The PKCS#7 structure carries digital signature made by ministry of interiors.
 457
 458 There is mangled namespace again: http://isds.czechpoint.cz/v20/ vs.
 459 http://isds.czechpoint.cz/v20/delivery:
 460
 461 <q:GetDeliveryInfoResponse xmlns:q="http://isds.czechpoint.cz/v20/delivery">
 462   <q:dmDelivery>
 463     <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 464       <p:dmID>170272</p:dmID>
 465       ...
 466     </p:dmDm>
 467     <q:dmHash algorithm="SHA-1">...</q:dmHash>
 468     ...
 469     </q:dmEvents>...</q:dmEvents>
 470   </q:dmDelivery>
 471 </q:GetDeliveryInfoResponse>
 472
 473
 474 FindDataBox (*)
 475 ===========
 476
 477 Find boxes conforming to search criteria or exact ID and return corresponding
 478 (possibly truncated) list of boxes.
 479
 480 Returned boxes exist, but it does not mean they can receive messages. Use
 481 CheckDataBox to figure out.
 482
 483 There are three different search cases distinguished in this order:
 484
 485     – If dbID is filled in request, it will search for exact box only, other
 486     criteria will be ignored.
 487
 488     – If identifier and registryCode are filled, it will search for exact
 489     box only, other criteria will be ignored.
 490
 491     – Otherwise search against other criteria.
 492
 493 Returns list of boxes (possibly empty).
 494
 495 List can be truncated or search request refused because of not enough
 496 specific criteria to protect user privacy. There are following constrains
 497 differentiated by box type now:
 498
 499 Gross Box type  Constraints (required search criteria)
 500 ------------------------------------------------------
 501 FO              pnLastName or pnLastNameAtBirth
 502 PFO             ic or pnLastName or pnLastNameAtBirth
 503 PO              ic or prefix (at least 3 characters) of firmName
 504 OVM             ic or prefix of firmName
 505
 506 String search criteria are matched case insensitive (except dbID). Strings are
 507 compared to prefix. Except firmName, adCity, adStreet and biCity that are
 508 matched as substrings.
 509
 510 Search results depends or logged-in user type. Users of boxes with open
 511 addressing can search other open-addressing boxes, otherwise only OVM type
 512 boxes can be searched. Search based on exact box identifier finder unlimited.
 513
 514 Error codes:
 515     0002    No box suits to search request (by other criteria)
 516     0003    To much boxes suit to search request (by other criteria),
 517             response truncated. Returned list of boxes is still valid.
 518     5001    No such box exists (by box ID or registry identifier)
 519 Non-normative error codes:
 520     1101    Box type (dbType) must be specified
 521     2017    Syntax error in date (biDate)
 522
 523
 524 CheckDataBox (*)
 525 ============
 526
 527 Return state of one box identified by dbID.
 528
 529 State of the box is stored in dbStatus element. Only state 1 means box is
 530 capable of receiving messages.
 531
 532 Error codes:
 533     5001    Box does not exist
 534 Non-normative:
 535     2011    Box ID malformed
 536
 537
 538 GetDataBoxList (*)
 539 ==============
 540
 541 Get comma-separete list of all boxes of given type.
 542
 543 Input is type of boxes of interrest (dblType element):
 544
 545 Value   Description             File name           Permission
 546 -------------------------------------------------------------------------------
 547 ALL     All types of boxes      actdsYYYYMMDD.csv   OVM or OVM_REQ user
 548                                                     authenticated by commercial
 549                                                     certificate or user with
 550                                                     PRIVIL_BILLING permission
 551 UPG     Effectively OVM boxes   effovmYYYYMMDD.csv  Anybody
 552 OVM     OVM gross type boxes    ovmYYYYMMDD.csv     PRIVIL_BILLING only
 553 OPN     Boxes that allow to     opendsYYYYMMDD.csv  PRIVIL_BILLING only
 554         receive commercial
 555         messages
 556
 557 Output is Base64-encoded ZIP file containing a file with name from the table.
 558 The Base64 string is stored in dblData element. The name of the file embeds
 559 date of list creation (Y is year digit, M is month, D is day).
 560
 561 The file is created once per a day and its format is following comma-separate
 562 value table:
 563
 564 Key
 565 ----------------------
 566 dbID
 567 dbType
 568 pnFirstName
 569 pnMiddleName
 570 pnLastName
 571 pnLastNameAtBirth
 572 biDate
 573 firmName
 574 ic
 575 adCity
 576 adStreet
 577 adNumberInStreet
 578 adNumberInMunicipality
 579 adZipCode
 580 adState
 581 nationality
 582 lastChangeDate
 583
 584 The inner file is encoded in UTF-8. First line of the file is a header. Each
 585 next line is a box. If a value is undefined, it will be empty. Values in
 586 a line are separated by a comma (`,'). If a value contains comma or quotation
 587 (`"'), the value will be enclosed into quotes (`"'). If value contains quotes,
 588 they will be escaped by a quotes (e.g. `"lazy, ""fox""' means `lazy, "fox"').
 589
 590 Error codes:
 591     1004    Operation not permitted
 592
 593
 594 PDZInfo
 595 =======
 596
 597 Return posibilities of sending commerical messages. Only if one of the
 598 possibility is the payer is the recipient (PDZType is `O'), then calling this
 599 service will cause marking messages as delivered.
 600
 601 Input is a box ID.
 602
 603 Ouput is orderer list of rules for sending commercial messages wrapped in
 604 dbPDZRecords element. The list can be empty. Each list item is a subtree:
 605
 606 dbPDZRecord
 607     + PDZType – rule type; see below for known values
 608     + PDZRecip – only this recipient box ID is possible. Empty value means no
 609     |   restriction on the recipient.
 610     + PDZPayer – the message is payed by this box ID owner
 611     + PDZExpire – expiration time of this rule. Empty value means no
 612     |   expiration.
 613     + PDZCnt – number of remaining commecrial messages that can be sent based
 614     |   on thid rule. Empty value means no limit.
 615     + ODZIdent – identifier referring to message enabling sending pre-paid
 616         answer. Must be added as dmRecipientRefNumber into sent message.
 617
 618 Empty list means sending commerical messages is not restricted.
 619
 620 PDZType     Meaning
 621 -------------------------------------------------------------------------------
 622 E           Another pre-paid type not yet specified and in use
 623 G           PDZPayer owner pays for all commercial messages
 624 K           Commercial message paid by sender based on an agreement with the
 625             Czech Post.
 626 O           Answer on a commercial message is pre-paid by PDZPayer. ODZIdent
 627             value must be added into an outgoing message to bind the message to
 628             the payer and requesting message.
 629
 630 XXX: Documentation shows `xsi:nil="true"' text node under PDZRecip element
 631 instead of no element.