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 rozhraní ISDS pro manipulaci s datovými zprávami,
   6     version 2.32 (2012-10-05)
   7 Source: Webové služby ISDS pro vyhledávání datových schránek,
   8     version 2.41 (2014-12-08)
   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 DO NOT MARK incoming
  22 messages as delivered. Those marked with plus has access to envelopes of
  23 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 Re-signISDSDocument (*)
  45     Replace CMS signature of old message signed without time stamp
  46 DummyOperation
  47     Void operation used to log in and to keep connection alive
  48
  49
  50 dm_info.wsdl
  51 ============
  52
  53 URL postfix: dx
  54 Constraints: Client must be authenticated in Access Manager
  55
  56 VerifyMessage (*+)
  57     Verify local copy of message with remote original stored in ISDS
  58 MessageEnvelopeDownload (+)
  59     Download envelope of incoming message
  60 MarkMessageAsDownloaded (*)
  61     Mark message as read
  62 ConfirmDelivery
  63     Mark commercial message as accepted by recipient
  64 EraseMessage (*)
  65     Remove message from long term storage
  66 GetDeliveryInfo (+)
  67     Download info-sheet about message post and delivery
  68 GetSignedDeliveryInfo (+)
  69     Download info-sheet about message post and delivery with signature of
  70     ministry of interiors
  71 GetListOfRecievedMessages
  72     Download list of incoming messages
  73 GetListOfSentMessages
  74     Download list of outgoing messages
  75 GetMessageAuthor
  76     Get details about sender
  77 GetMessageStateChanges
  78     Download list of outgoing messages that changed state
  79
  80
  81 db_search.wsdl
  82 ==============
  83
  84 URL postfix: df
  85
  86 FindDataBox (*)
  87     Find boxes conforming to search criteria
  88 CheckDataBox (*)
  89     Return state of given box
  90 GetDataBoxList (*)
  91     Get list of all boxes
  92 PDZInfo
  93     Get rules for sending commercial messages from given box
  94 DataBoxCreditInfo (*)
  95     Get details about credit for comercial services
  96 ISDSSearch2 (*)
  97     Search for boxes conforming to full text criteria
  98
  99
 100 CreateMessage (*)
 101 =============
 102
 103 Create and send a message.
 104
 105 Envelope of outgoing message must contain dbIDRecipient and dmAnnotation.
 106 Other elements are optional (dmRecipientOrgUnit, dmRecipientOrgUnitNum,
 107 dmSenderOrgUnit, dmSenderOrgUnitNum, dmToHands, dmPersonalDelivery,
 108 dmAllowSubstDelivery, dmRecipientRefNumber, dmRecipientIdent,
 109 dmSenderRefNumber, dmSenderIdent, dmLegalTitleLaw, dmLegalTitleYear,
 110 dmLegalTitleSect, dmLegalTitlePar, dmLegalTitlePoint, dmOVM, dmPublishOwnID).
 111
 112 Outgoing message envelope can specify dmType to declare subtype of commercial
 113 message. If dmType is `I', then dmSenderRefNumber must be defined. If dmType
 114 is `O', then dmRecipientRefNumber must be defined.
 115
 116 Constraints: Sender must have PRIVIL_CREATE_DM permission.
 117 Constraints: Exactly one document in message must be main type.
 118 Constraints: Total size of all documents must not be bigger than 10 MB.
 119
 120 Identifier of just sent message assigned by system is returned.
 121
 122 Error codes:
 123     0000    Message sent successfully
 124 Non-normative error codes:
 125     1214    Document description is not a file name with acceptable file name
 126             extension
 127     1214    Document description extension does not match document content
 128     1214    Provided MIME type does not match document
 129     2010    First document structure invalid
 130     2032    Message does not carry any document
 131     9005    Message not valid (probably)
 132
 133 In case of positive virus detection (processed after sending), infected
 134 document is removed, message state is set to value 3 (from point of view of
 135 recipient) and sender get new message originated by server.
 136
 137
 138 CreateMultipleMessage (*)
 139 =====================
 140
 141 Create and send a message to multiple recipients.
 142
 143 Input composes of nonempty list of recipients (maximal count is 50),
 144 one envelope (different from envelope for CreateMessage, misses elements from
 145 dmRecipient) and list of documents to send to all of them to each recipient.
 146
 147 Only dbIDRecipient and dmToHands are mandatory. Other dmRecipient children are
 148 optional.
 149
 150 Structure:
 151 CreateMultipleMessage
 152     + dmRecipients
 153     |   + dmRecipient
 154     |   |   + dbIDRecipient – recipient box ID
 155     |   |   + dmRecipientOrgUnit
 156     |   |   + dmRecipientOrgUnitNum
 157     |   |   + dmToHands – can be empty, but must not missing
 158     |   + dmRecipient
 159     |   ⋮
 160     + dmEnvelope
 161     |   + <other elements, usually empty>: dmSenderOrgUnit, dmSenderOrgUnitNum,
 162     |   |   dmAnnotation, dmRecipientRefNumber, dmSenderRefNumber,
 163     |   |   dmRecipientIdent, dmSenderIdent, dmLegalTitleLaw,
 164     |   |   dmLegalTitleYear, dmLegalTitleSect, dmLegalTitlePar,
 165     |   |   dmLegalTitlePoint, dmPersonalDelivery, dmAllowSubstDelivery
 166     |   + dmOVM – optional
 167     |   + dmPublishOwnID – optional
 168     + dmFiles
 169
 170 It's not possible to send commercial message to multiple recipients. Though the
 171 dmEnvelope has @dmType attribute, so it should be possible to send a commercial
 172 message to one recient using CreateMultipleMessage service.
 173
 174 ISDS outputs list of assigned message IDs (each copy gets independent ID),
 175 list of sent status for each message ID and one cumulative status of
 176 whole CreateMultipleMessage operation.
 177
 178 If operation fails before replicating messages for each recipient
 179 (i.e. sending), global error code will be non-zero. If operation fails on some
 180 message copies (i.e. while sending) special global error code 0004 will be
 181 returned and erroneous recipients can be gather by recipient specific error
 182 code (failed ones will have non-zero code). If all messages are sent
 183 successfully, global error code will be 0000.
 184
 185 Structure:
 186 CreateMultipleMessageResponse
 187     + dmMultipleStatus
 188     |   + dmSingleStatus
 189     |   |   + dmID – assigned message ID, optional, missing if error occurred
 190     |   |   + dmStatus – message local error code and textual description
 191     |   + dmSingleStatus
 192     |   ⋮
 193     + dmStatus – global error code and textual description
 194
 195 Global error codes:
 196     0000    Messages sent successfully
 197     0004    Some message failed while sending
 198
 199
 200 MessageDownload
 201 ===============
 202
 203 Retrieve incoming message identified by message ID.
 204
 205 This service can return message without digital time-stamp (more precisely
 206 with empty dmQTimesamp element, see schema).
 207
 208 Commercial message has set dmReturnedMessage/@dmType="K".
 209
 210 Error codes:
 211     0000    Message sent successfully
 212 Non-normative error codes:
 213     1219    Message with ID does not exist in ISDS in current box.
 214
 215
 216 SignedMessageDownload
 217 =====================
 218
 219 Download incoming message with digital signature of ministry of interiors
 220 identified by message ID.
 221
 222 Return PKCS#7 structure containing data as defined in MessageDownload and
 223 digital signature of the message by ministry.
 224
 225 The data are XML document with mangled ISDS name space:
 226 http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/message:
 227
 228 <q:MessageDownloadResponse
 229      xmlns:q="http://isds.czechpoint.cz/v20/message">
 230   <q:dmReturnedMessage>
 231      <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 232          <p:dmID>151916</p:dmID>
 233          ...
 234      </p:dmDm>
 235      <q:dmHash algorithm="SHA-1">...</q:dmHash>
 236      ...
 237      <q:dmAttachmentSize>260</q:dmAttachmentSize>
 238   </q:dmReturnedMessage>
 239 </q:MessageDownloadResponse>
 240
 241
 242 SignedSentMessageDownload
 243 =========================
 244
 245 Download outgoing message with digital signature of ministry of interiors
 246 identified by ID.
 247
 248 Return PKCS#7 structure containing data as defined in MessageDownload and
 249 digital signature of the message by ministry.
 250
 251 The data are XML document with mangled ISDS name space:
 252 http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/SentMessage:
 253
 254 <q:MessageDownloadResponse
 255      xmlns:q="http://isds.czechpoint.cz/v20/SentMessage">
 256   <q:dmReturnedMessage>
 257      <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 258          <p:dmID>151916</p:dmID>
 259          ...
 260      </p:dmDm>
 261      <q:dmHash algorithm="SHA-1">...</q:dmHash>
 262      ...
 263      <q:dmAttachmentSize>260</q:dmAttachmentSize>
 264   </q:dmReturnedMessage>
 265 </q:MessageDownloadResponse>
 266
 267
 268 GetListOfRecievedMessages
 269 =========================
 270
 271 Download list of incoming messages matching search criteria.
 272
 273 See GetListOfSentMessages for more details.
 274
 275
 276 GetListOfSentMessages
 277 =====================
 278
 279 Download list of outgoing messages matching search criteria.
 280
 281 Criteria are: delivery time not before, not after, organisation unit number of
 282 sender, message status filter, offset of first message in a list and limit on
 283 number of messages to get.
 284
 285 Message status filter is union of distinct message states expressed as
 286 exponents of 2. Effectively it's a polynom \sum_{x \in message_statux} 2^x.
 287 Special value -1 means all messages. Meaning for value 1 or 0 is undefined.
 288
 289 Messages are sorted in order of delivery time. Message type is stored in
 290 dmRecord/@dmType.
 291
 292 Offset starts on 1. Limit defaults to 1000.
 293
 294 Non-normative error codes:
 295     2017    Syntax error in date-time
 296
 297
 298 GetMessageAuthor
 299 ================
 300
 301 Get information about sender as un user of given message.
 302
 303 Input is mandatory message identifier. Output is optional userType and
 304 optional authorName.
 305
 306 userType (unknown and undefined for older messages) is type of user who has
 307 sent the message. Be ware there is special additional type `VIRTUAL'. Be ware
 308 the userType is a string unconstrained by XML schema:
 309
 310 Value               Description
 311 --------------------------------------------------------------------------
 312 PRIMARY_USER        The sender was a owner of the box
 313 ENTRUSTED_USER      The sender was an entrusted user associated to the box
 314 ADMINISTRATOR       The sender was administrator assiciated to the box
 315 OFFICIAL            The sender was ISDS (for system messages)
 316 VIRTUAL             The sender was an application authenticated by `system'
 317                     certificate
 318
 319 Non-normative: New user types OFFICIAL_CERT and LIQUIDATOR are not listed in
 320 official documentation for this service. However LIQUIDATOR is said to be
 321 equivalent to PRIMARY_USER and PRIMARY_USER can send messages, thus I conclude
 322 these two now user types can occur in output of this service.
 323
 324 authorName is a name of user logged into senders box (not a login name) if
 325 sender allowed to reveal his name explicitely.
 326
 327
 328 GetMessageStateChanges
 329 ======================
 330
 331 Download list of outgoing messages that changed state in given time range.
 332
 333 If a message changed state multiple times, it is listed more times. Only
 334 changes from state 2 to 4, from 4 to {5, 6, 8} are reported. Only recent
 335 changes (not older than 15 days currently) are reported.
 336
 337 This service is designed for polling state changes of sent messages.
 338
 339 Input are start (dmFromTime element) and end (dmToTime element) ISO times.
 340 Empty dmFromTime meands since last 15 days, empty dmToTime means till now.
 341
 342 Non-normative: Server does not report changes recent more than one hour.
 343
 344 Output is list of records with message state changes. The order of records is
 345 undefined.
 346
 347 Structure:
 348 GetMessageStateChangesResponse
 349     + dmRecords – optional, possibly empty element
 350     |   + dmRecord – one state change
 351     |   |   + dmId – identifier of message that changed state
 352     |   |   + dmEventTime – ISO time of state change
 353     |   |   + dmMessageStatus – new message state in numeric notation
 354     |   + dmRecord
 355     |   ⋮
 356     + dmStatus – global error code and textual description
 357
 358
 359 AuthenticateMessage (*+)
 360 ===================
 361
 362 Allows to verify message authenticity by providing copy to ISDS.
 363
 364 Only signed message encapsuleted into CMS structure with digital signature can
 365 be verified by this service. Client pass the raw message in Base64 encoding to
 366 ISDS, system performs checks and return boolean value: true if message has
 367 not been modified and has been delivered through ISDS, false if message
 368 has is unkown to ISDS. In both cases 0000 error code will be returned.
 369
 370 If message cannot be processed (e.g. broken CMS or XML syntax) or message
 371 contains has been signed by non-ISDS certificate or other error, non-zero
 372 error code will be returned.
 373
 374
 375 Re-signISDSDocument (*)
 376 ===================
 377
 378 Re-sign old message or delivery info that has been generated with CMS without
 379 time stamp. These messages have been produced before 2011-04-16.
 380
 381 Input is dmDoc element carrying Base64-encoded original signed message or
 382 delivery info in text node.
 383
 384 Output is dmResultDoc element with Base64-encoded re-signed message or
 385 delivery info supplied in request, optional dmValidTo element of xs:date type,
 386 and dmStatus of tStatus type. dmValidTo advertises end of validity of
 387 time stamp added into CMS.
 388
 389 Error codes:
 390     0000    Message has been re-signed and returned in CadES-T CMS format
 391     2200    Input message is bad
 392     2201    Input message is not original (see AuthenticateMessage service)
 393     2204    Input message already contains time stamp in CAdES-EPES or CAdES-T
 394             CMS envelope
 395     2207    Time stamp could not been generated in time
 396
 397
 398 VerifyMessage (*+)
 399 =============
 400
 401 Retrieve message hash (dmHash element) for given message from ISDS.
 402
 403 Works for not yet deleted messages only.
 404
 405 Only SHA-1 algorithm is in use currently. SHA-2 family is expected after
 406 2010 year beginning.
 407
 408 Hash input is isds:dmDM subtree processed as raw bit stream without XML
 409 canonicalization. Authoritative isds:dmDM element can be get via
 410 MessageDownload service. God bless ISDS developers to not change XML
 411 serialization.
 412
 413 Non-normative error codes:
 414     1219    Message with ID does not exist in ISDS.
 415
 416
 417 MessageEnvelopeDownload (+)
 418 =======================
 419
 420 Download envelope of incoming message. That is message without documents.
 421 Message type is stored in dmReturnedMessageEnvelope/@dmType.
 422
 423 Returned hash and time-stamp are computed from whole message. You must get
 424 complete message including documents to be able to verify them.
 425
 426
 427 MarkMessageAsDownloaded (*)
 428 =======================
 429
 430 Change status of a message identified by its ID as read.
 431
 432 That means next GetListOfRecievedMessages service can exclude such message if
 433 only unread messages requested.
 434
 435
 436 ConfirmDelivery
 437 ===============
 438
 439 Mark commercial message as accepted by recipient.
 440
 441 XXX: This service has been removed from ISDS because commercial messages get
 442 accepted by logging-in (since 2011-11).
 443
 444 Changes message state from delivered (4) to accepted (6). Applicable only to
 445 commercial messages. Messages from public offices (municipalities, government
 446 etc.) are accepted automatically by log-in on interactive web portal or by
 447 triggering most of SOAP operations.
 448
 449 Must be called before downloading (signed or unsigned) incoming message
 450 [Signed]MessageDownload.
 451
 452
 453 EraseMessage (*)
 454 ============
 455
 456 Delete a message from long term storage (know as data safe formerly).
 457
 458 Input is message ID in `dmID' element and boolean in `dmIncoming' element
 459 (true for incoming message, false for outgoing mesage).
 460
 461 Output is standard `dmStatus' subtree.
 462
 463 Only message in long term storage can be removed on user request through
 464 this service. Other message cannot be removed on request, they get removed
 465 automatically after 90-days period.
 466
 467 Error codes:
 468     1211    The message belongs to other (= not currently logged-in user) box
 469     1218    Insufficient permissions (PRIVIL_ERASE_VAULT) to remove the message
 470     1219    The message is not in long term storage or is not incoming or
 471             outgoing as requested.
 472
 473
 474 GetDeliveryInfo (+)
 475 ===============
 476
 477 Download info-sheet about incoming or outgoing message post and delivery or
 478 deliver impossibility. The message is specified by message ID.
 479
 480 It returns complete message envelope, hash, time-stamp. Delivery time and
 481 acceptance time only if message has been delivered to recipient box or
 482 accepted by recipient. Precise status of message is returned too.
 483
 484 In addition, non-empty list of events is attached. Each event compounds of
 485 ISO time and text description. The text description has well-known prefix to
 486 distinguish the event meaning. Following prefixes are defined:
 487
 488     Prefix  Meaning
 489     -----------------------------------------------------
 490     EV0:    Message enterend into ISDS
 491     EV1:    Message has been accepted by recipient action
 492     EV2:    Message has been delivered to box and is considered as accepted by
 493             no-user-action time out (through fiction)
 494     EV3:    Recipient box has been made inaccessible retrospectively
 495             (even after successful delivery or acceptance,
 496             this event is retroactive). In this case special system-generated
 497             message is sent to sender in addition.
 498     EV4:    Commercial message has been accepted by recipient confirmation
 499     EV5:    Message has been delivered into recipent box
 500     EV11:   Primary user has logged into his box
 501     EV12:   Entrusted user havin permission to read this message has logged in
 502     EV13:   Application (not a human) has logged into box using `system'
 503             certificate
 504
 505
 506 GetSignedDeliveryInfo (+)
 507 =====================
 508
 509 Download info-sheet about incoming or outgoing message post and delivery or
 510 deliver impossibility as signed PKCS#7 structure. See GetDeliveryInfo for
 511 details about returned data.
 512
 513 The PKCS#7 structure carries digital signature made by ministry of interiors.
 514
 515 There is mangled namespace again: http://isds.czechpoint.cz/v20/ vs.
 516 http://isds.czechpoint.cz/v20/delivery:
 517
 518 <q:GetDeliveryInfoResponse xmlns:q="http://isds.czechpoint.cz/v20/delivery">
 519   <q:dmDelivery>
 520     <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 521       <p:dmID>170272</p:dmID>
 522       ...
 523     </p:dmDm>
 524     <q:dmHash algorithm="SHA-1">...</q:dmHash>
 525     ...
 526     </q:dmEvents>...</q:dmEvents>
 527   </q:dmDelivery>
 528 </q:GetDeliveryInfoResponse>
 529
 530
 531 FindDataBox (*)
 532 ===========
 533
 534 Find boxes conforming to search criteria or exact ID and return corresponding
 535 (possibly truncated) list of boxes.
 536
 537 Returned boxes exist, but it does not mean they can receive messages. Use
 538 CheckDataBox to figure out.
 539
 540 There are three different search cases distinguished in this order:
 541
 542     – If dbID is filled in request, it will search for exact box only, other
 543     criteria will be ignored.
 544
 545     – If identifier and registryCode are filled, it will search for exact
 546     box only, other criteria will be ignored.
 547
 548     – Otherwise search against other criteria.
 549
 550 Returns list of boxes (possibly empty).
 551
 552 List can be truncated or search request refused because of not enough
 553 specific criteria to protect user privacy. There are following constrains
 554 differentiated by box type now:
 555
 556 Gross Box type  Constraints (required search criteria)
 557 ------------------------------------------------------
 558 FO              pnLastName or pnLastNameAtBirth
 559 PFO             ic or pnLastName or pnLastNameAtBirth
 560 PO              ic or prefix (at least 3 characters) of firmName
 561 OVM             ic or prefix of firmName
 562
 563 String search criteria are matched case insensitive (except dbID). Strings are
 564 compared to prefix. Except firmName, adCity, adStreet and biCity that are
 565 matched as substrings.
 566
 567 Search results depends or logged-in user type. Users of boxes with open
 568 addressing can search other open-addressing boxes, otherwise only OVM type
 569 boxes can be searched. Search based on exact box identifier finder unlimited.
 570
 571 Error codes:
 572     0002    No box suits to search request (by other criteria)
 573     0003    To much boxes suit to search request (by other criteria),
 574             response truncated. Returned list of boxes is still valid.
 575     1109    More than one box matches the search request
 576     5001    No such box exists (by box ID or registry identifier)
 577 Non-normative error codes:
 578     1101    Box type (dbType) must be specified
 579     2017    Syntax error in date (biDate)
 580
 581
 582 CheckDataBox (*)
 583 ============
 584
 585 Return state of one box identified by dbID.
 586
 587 State of the box is stored in dbStatus element. Only state 1 means box is
 588 capable of receiving messages.
 589
 590 Error codes:
 591     5001    Box does not exist
 592     1007    Box ID malformed
 593     2011    Box ID malformed
 594
 595
 596 GetDataBoxList (*)
 597 ==============
 598
 599 Get comma-separate list of all boxes of given type.
 600
 601 Input is type of boxes of interrest (dblType element):
 602
 603 Value   Description             File name           Permission
 604 -------------------------------------------------------------------------------
 605 ALL     All active boxes        actdsYYYYMMDD.csv   OVM or OVM_REQ user
 606                                                     authenticated by commercial
 607                                                     certificate or user with
 608                                                     PRIVIL_BILLING permission
 609 UPG     Effectively OVM active  effovmYYYYMMDD.csv  Anybody
 610         boxes
 611
 612 Non-normative: Following types are not documented anymore.
 613
 614 Value   Description             File name           Permission
 615 -------------------------------------------------------------------------------
 616 OVM     OVM gross type boxes    ovmYYYYMMDD.csv     PRIVIL_BILLING only
 617 OPN     Boxes that allow to     opendsYYYYMMDD.csv  PRIVIL_BILLING only
 618         receive commercial
 619         messages
 620
 621 Output is Base64-encoded ZIP file containing a file with name from the table.
 622 The Base64 string is stored in dblData element. The name of the file embeds
 623 date of list creation (Y is year digit, M is month, D is day).
 624
 625 The file is created once per a day and its format is following comma-separate
 626 value table:
 627
 628 Key
 629 ----------------------
 630 dbID
 631 dbType
 632 pnFirstName
 633 pnMiddleName
 634 pnLastName
 635 pnLastNameAtBirth
 636 biDate
 637 firmName
 638 ic
 639 adCity
 640 adStreet
 641 adNumberInStreet
 642 adNumberInMunicipality
 643 adZipCode
 644 adState
 645 nationality
 646 lastChangeDate
 647
 648 The inner file is encoded in UTF-8. First line of the file is a header. Each
 649 next line is a box. If a value is undefined, it will be empty. Values in
 650 a line are separated by a comma (`,'). If a value contains comma or quotation
 651 (`"'), the value will be enclosed into quotes (`"'). If value contains quotes,
 652 they will be escaped by a quotes (e.g. `"lazy, ""fox""' means `lazy, "fox"').
 653
 654 Error codes:
 655     1004    Operation not permitted
 656
 657
 658 PDZInfo
 659 =======
 660
 661 Return posibilities of sending commerical messages. Only if one of the
 662 possibility is the payer is the recipient (PDZType is `O'), then calling this
 663 service will cause marking messages as delivered.
 664
 665 Input is `PDZSender' element with a box ID as the only text node child.
 666
 667 Ouput is orderer list of rules for sending commercial messages wrapped in
 668 dbPDZRecords element. The list can be empty what means no permission is
 669 available. Each list item is a subtree:
 670
 671 dbPDZRecord
 672     + PDZType – rule type; see below for known values
 673     + PDZRecip – only this recipient box ID is possible. Empty value means no
 674     |   restriction on the recipient.
 675     + PDZPayer – the message is payed by this box ID owner
 676     + PDZExpire – expiration time of this rule. Empty value means no
 677     |   expiration.
 678     + PDZCnt – number of remaining commecrial messages that can be sent based
 679     |   on thid rule. Empty value means no limit.
 680     + ODZIdent – identifier referring to message enabling sending pre-paid
 681         answer. Must be added as dmRecipientRefNumber into sent message.
 682
 683 PDZType     Meaning
 684 -------------------------------------------------------------------------------
 685 D           Externally subsidized (undocumented)
 686 E           Commercial message pre-paid by the sender
 687 G           PDZPayer owner pays for all commercial messages
 688 K           Commercial message paid by sender based on an agreement with the
 689             Czech Post.
 690 O           Answer on a commercial message is pre-paid by PDZPayer. ODZIdent
 691             value must be added into an outgoing message to bind the message to
 692             the payer and requesting message.
 693 Z           Limitedly subsidized (undocumented)
 694
 695
 696 DataBoxCreditInfo
 697 =================
 698
 699 Return current credit value and and history of credit changes for given box
 700 and time interval.
 701
 702 Input is `dbID' element with box ID whose credit you want to obtain and
 703 possibly empty elements `ciFromDate' and `ciTodate' carrying start and end
 704 date (inclusive) for history records to obtain.
 705
 706 Output is `currentCredit' element delivering current credit value,
 707 `notifEmail' element delivering e-mail address to send notifications
 708 about changes in the commercial services to, and `ciRecords' tree with history
 709 of changes that occurred in the given interval. All these elements are optional.
 710
 711 The `ciRecords' element contains possibly (if interval is not defined) empty
 712 time-sorted list of `ciRecord' trees:
 713
 714 ciRecord
 715     + ciEventTime – time of the change
 716     + ciEventType – type of the change expressed as an integer
 717     + ciCreditChange – value of the credit change
 718     + ciCreditAfter – value of the credit after the change
 719
 720 ciEventType     Meaning
 721 ------------------------------------------
 722 1               Charge credit
 723 2               Discharge credit
 724 3               Sending commercial message
 725 4               Setting long term storage
 726 5               Credit expiration
 727
 728 `ciRecord' contains other elements depending on `ciEventType':
 729
 730 Element         ciEventType     Meaning
 731 ------------------------------------------------------------------
 732 ciTransID       1, 2            String; not specified
 733 ciRecipientID   3               Recipient's box ID of the sent message
 734 ciPDZID         3               ID of the sent message
 735 ciNewCapacity   4               Integer; new capacity of storage in messages
 736 ciNewFrom       4               Date when the new capacity is effective
 737 ciNewTo         4               Date when the new capacity expires
 738 ciOldCapacity   4               Integer, optional; former capacity in messages
 739 ciOldFrom       4               Date, optional
 740 ciOldTo         4               Date, optional
 741 ciDoneBy        4               String, optional; Name of user who initiated
 742                                 the change
 743
 744 All credit values are integers in hundredths of Czech Crowns.
 745
 746 Output carries standard `dbStatus' tree with status code and status message.
 747
 748 Error codes (codes are not normative):
 749     1004    Insufficient priviledges for the box
 750     2011    The box does not exist
 751     1093    Date is too long (history is not available after 15 months)
 752     1137    Interval is too long (limit is 3 months)
 753     1058    Invalid date
 754
 755
 756 ISDSSearch2
 757 ===========
 758
 759 Return list of boxes matching a full text criteria.
 760
 761 The search is perfomed on an index cached each 3 hours.
 762
 763 The search phrase is splitted on word boundaries and the words are looked up
 764 in the index. Only whole words matches. All search phrase words must be found
 765 in the same box metadata (not necessarily in the same attribute and in the
 766 same order). Diacritics supplementing, case folding, and lemmatization is
 767 supported.
 768
 769 Non-OVM users still cannot see FO boxes which cannot receive commercial
 770 messages and whose owners forbade listing on a public index.
 771
 772 Input is this list of these elements:
 773
 774 Element         Type                    Details
 775 --------------------------------------------------------------------------------
 776 searchText      String                  Mandatory, non-empty
 777 searchType      Enumerated string       Mandatory, can be empty,
 778                                         defaults to GENERAL
 779 searchScope     Enumerated string       Mandatory, can be empty,
 780                                         defaults to ALL
 781 page            Non-negative integer    Mandatory, can be empty,
 782                                         defaults to 0, counts from 0
 783 pageSize        Non-negative integer    Mandatory, can be empty,
 784                                         defaults to 50, counts from 0,
 785                                         server clamps the value to 100
 786 highlighting    Boolean                 Optional, can be empty,
 787                                         defaults to false
 788
 789 Acceptable values for `searchType' element are:
 790
 791 Value       Meaning
 792 --------------------------------------------------------------------------
 793 GENERAL     Search a phrase in names, addresses, organization identifiers,
 794             and box IDs
 795 ADDRESS     Search a phrase in addresses only
 796 ICO         Search in organization identifiers only by equivalence
 797 DBID        Search in box IDs only by equivalence
 798
 799 If `searchType' is `ICO' or `DBID', `searchScope' restriction is ignored.
 800
 801 `searchScope' element restricts box types. See `Box types' section in `box'
 802 file for the semantics, acceptable values are:
 803
 804 Value       Meaning
 805 -------------------------------------
 806 ALL         Search over all box types
 807 OVM
 808 OVM_REQ
 809 OVM_NOTAR
 810 OVM_EXEKUT
 811 PO
 812 PO_ZAK
 813 PO_REQ
 814 PFO
 815 PFO_ADVOK
 816 PFO_INSSPR
 817 PFO_DANPOR
 818 FO
 819
 820 Output is this list of these optional elements
 821
 822 Element         Type                    Meaning
 823 ------------------------------------------------------------------------
 824 totalCount      Non-negative integer    Number of matching boxes
 825 currentCount    Non-negative integer    Number of boxes in this response
 826 position        Non-negative integer    Ordinal number of first box in this
 827                                         response, counts from 0
 828 lastPage        Boolean                 True if no more boxes match
 829 dbResults       List of elements
 830
 831 Last mandatory element is the standard response status of the service call
 832 `dbStatus' element with status code and status message.
 833
 834 `dbResults' content is a possibly empty list of `dbResult' elements.
 835 The list is sorted according to a search relevance. The `dbResult' element
 836 consists of:
 837
 838 dbResult
 839     + dbID – box ID
 840     + dbType – box type
 841     + dbName – box name
 842     + dbAddress – residence address as one string
 843     + dbBiDate – can be empty, date of birth
 844     + dbICO – can be empty, identifier of an organization
 845     + dbEffectiveOVM – boolean, true for a box upgraded to an OVM role
 846     + dbSendOptions – enumerated string, capability to deliver different
 847         kinds of messages, it depends on querrier's box type and the found box
 848
 849 Acceptable values for `dbSendOptions' element are:
 850
 851 Value       Meaning
 852 -------------------
 853 DZ          Only noncommecrial messages can be sent
 854 ALL         Noncommercial and commercial messages can be sent
 855 PDZ         Only commercial messages can be sent
 856 NONE        No message can be sent
 857 DISABLED    The box is not active
 858
 859 If input `highlighting' is true, output `dbName' and `dbAddress' can contain
 860 delimeters highlighting the phrase found in the strings. The start of the
 861 phrase is marked by `|$*HL_START*$|' string, the end of the phrase is marked
 862 by `|$*HL_END*$|' string.
 863
 864 Error codes:
 865     1004    Not allowed to search
 866     1152    `searchText' is empty
 867     1153    Searched box ID is malformed
 868     1154    Searched organization ID is malformed
 869     1155    Invalid input
 870     1156    `pageSize' is too large
 871     9002    Search engine internal error