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