doc/user_web_services

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