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