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 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     EV11:   Primary user has logged into his box
 510     EV12:   Entrusted user havin permission to read this message has logged in
 511     EV13:   Application (not a human) has logged into box using `system'
 512             certificate
 513
 514
 515 GetSignedDeliveryInfo (+)
 516 =====================
 517
 518 Download info-sheet about incoming or outgoing message post and delivery or
 519 deliver impossibility as signed PKCS#7 structure. See GetDeliveryInfo for
 520 details about returned data.
 521
 522 The PKCS#7 structure carries digital signature made by ministry of interiors.
 523
 524 There is mangled namespace again: http://isds.czechpoint.cz/v20/ vs.
 525 http://isds.czechpoint.cz/v20/delivery:
 526
 527 <q:GetDeliveryInfoResponse xmlns:q="http://isds.czechpoint.cz/v20/delivery">
 528   <q:dmDelivery>
 529     <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
 530       <p:dmID>170272</p:dmID>
 531       ...
 532     </p:dmDm>
 533     <q:dmHash algorithm="SHA-1">...</q:dmHash>
 534     ...
 535     </q:dmEvents>...</q:dmEvents>
 536   </q:dmDelivery>
 537 </q:GetDeliveryInfoResponse>
 538
 539
 540 FindDataBox (*)
 541 ===========
 542
 543 Find boxes conforming to search criteria or exact ID and return corresponding
 544 (possibly truncated) list of boxes.
 545
 546 Returned boxes exist, but it does not mean they can receive messages. Use
 547 CheckDataBox to figure out.
 548
 549 There are three different search cases distinguished in this order:
 550
 551     – If dbID is filled in request, it will search for exact box only, other
 552     criteria will be ignored.
 553
 554     – If identifier and registryCode are filled, it will search for exact
 555     box only, other criteria will be ignored.
 556
 557     – Otherwise search against other criteria.
 558
 559 Returns list of boxes (possibly empty).
 560
 561 List can be truncated or search request refused because of not enough
 562 specific criteria to protect user privacy. There are following constrains
 563 differentiated by box type now:
 564
 565 Gross Box type  Constraints (required search criteria)
 566 ------------------------------------------------------
 567 FO              pnLastName
 568 PFO             ic or pnLastName
 569 PO              ic or prefix (at least 3 characters) of firmName
 570 OVM             ic or prefix of firmName
 571
 572 String search criteria are matched case insensitive (except dbID). Strings are
 573 compared to prefix. Except firmName, adCity, adStreet and biCity that are
 574 matched as substrings.
 575
 576 Search results depends or logged-in user type. Users of boxes with open
 577 addressing can search other open-addressing boxes, otherwise only OVM type
 578 boxes can be searched. Search based on exact box identifier finder unlimited.
 579
 580 Error codes:
 581     0002    No box suits to search request (by other criteria)
 582     0003    To much boxes suit to search request (by other criteria),
 583             response truncated. Returned list of boxes is still valid.
 584     1109    More than one box matches the search request
 585     5001    No such box exists (by box ID or registry identifier)
 586 Non-normative error codes:
 587     1101    Box type (dbType) must be specified
 588     2017    Syntax error in date (biDate)
 589
 590
 591 FindPersonalDataBox (*)
 592 ===================
 593
 594 Return list of active FO-type boxes matching given criteria.
 595
 596 Input is `dbOwnerInfo' element specifying search criteria for box owner by
 597 these children elements:
 598
 599 Element                 Type    At search   Meaning
 600 --------------------------------------------------------------------------------
 601 dbID                    String              Box ID
 602 aifoIsds                Boolean Ignored     Reference to citizen registry exists
 603 pnFirstName             String              Given name
 604 pnMiddleName            String              Middle name
 605 pnLastName              String              Surname
 606 biDate                  Date                Birth date
 607 biCity                  String              Birth place
 608 biCounty                String              Birth district (`okres' in Czech)
 609 biState                 String  Ignored     Birth state
 610 adCode                  Integer             RUIAN address code
 611 adCity                  String              Municipality name
 612 adDistrict              String  Ignored     Municipality part
 613 adStreet                String              Street
 614 adNumberInStreet        String              Entrance number
 615 adNumberInMunicipality  String              Building number
 616 adZipCode               String  Ignored     Post office code
 617 adState                 String              State
 618 nationality             String              State citizenship
 619
 620 Syntactically, all of the `dbOwnerInfo' children can be empty. Semantically,
 621 if `dbID' is specified, other criteria will be ignored. Otherwise `pnLastName'
 622 must be specified and it is matched as exact string. Values except `dbID' are
 623 matched case insensitively.
 624
 625 Output is list of `dbResults' and `dbStatus' elements. `dbResults' is optional
 626 and possibly empty list of `dbOwnerInfo' elements that have the same structure
 627 as the input `dbOwnerInfo' element.
 628
 629 The output differs from FindDataBox output. Here are `aifoIsds', `adCode', and
 630 `adDistrict' elements added. Some unused elements are missing.
 631
 632 This service can be used only by an user with PRIVIL_SEARCH_DB permisson to a
 633 gross OVM box type.
 634
 635 Error codes:
 636     0002    No box matches
 637     0003    Too many boxes match, result list is truncated but still valid
 638
 639
 640 CheckDataBox (*)
 641 ============
 642
 643 Return state of one box identified by dbID.
 644
 645 State of the box is stored in dbStatus element. Only state 1 means box is
 646 capable of receiving messages.
 647
 648 Error codes:
 649     5001    Box does not exist
 650     1007    Box ID malformed
 651     2011    Box ID malformed
 652
 653
 654 GetDataBoxList (*)
 655 ==============
 656
 657 Get comma-separate list of all boxes of given type.
 658
 659 Input is type of boxes of interrest (dblType element):
 660
 661 Value   Description             File name           Permission
 662 -------------------------------------------------------------------------------
 663 ALL     All active boxes        actdsYYYYMMDD.csv   OVM, OVM_EXEKUT,
 664                                                     OVM_NOTAR, OVM_REQ, or
 665                                                     upgraded OVM user
 666                                                     authenticated by commercial
 667                                                     certificate or user with
 668                                                     PRIVIL_BILLING permission
 669 UPG     Effectively OVM active  effovmYYYYMMDD.csv  Anybody
 670         boxes
 671 POA     Active boxes that       puboaYYYYMMDD.csv   Anybody
 672         allow to receive
 673         commerical messages
 674
 675 Non-normative: Following types are not documented anymore.
 676
 677 Value   Description             File name           Permission
 678 -------------------------------------------------------------------------------
 679 OVM     OVM gross type boxes    ovmYYYYMMDD.csv     PRIVIL_BILLING only
 680 OPN     Boxes that allow to     opendsYYYYMMDD.csv  PRIVIL_BILLING only
 681         receive commercial
 682         messages
 683
 684 Output is Base64-encoded ZIP file containing a file with name from the table.
 685 The Base64 string is stored in dblData element. The name of the file embeds
 686 date of list creation (Y is year digit, M is month, D is day).
 687
 688 The file is created daily and its format a comma-separate list with following
 689 columns.
 690
 691 Columns for ALL and UPG lists:
 692
 693 Key
 694 ----------------------
 695 dbID
 696 dbType
 697 pnFirstName
 698 pnMiddleName
 699 pnLastName
 700 biDate
 701 firmName
 702 ic
 703 adCity
 704 adStreet
 705 adNumberInStreet
 706 adNumberInMunicipality
 707 adZipCode
 708 adState
 709 nationality
 710 lastChangeDate
 711
 712 Columns for POA lists:
 713
 714 Key
 715 ----
 716 dbID
 717 ic
 718
 719 The inner file is encoded in UTF-8. First line of the file is a header. Each
 720 next line is a box. If a value is undefined, it will be empty. Values in
 721 a line are separated by a comma (`,'). If a value contains comma or quotation
 722 (`"'), the value will be enclosed into quotes (`"'). If value contains quotes,
 723 they will be escaped by a quotes (e.g. `"lazy, ""fox""' means `lazy, "fox"').
 724
 725 Error codes:
 726     1004    Operation not permitted
 727
 728
 729 PDZInfo
 730 =======
 731
 732 Return posibilities of sending commerical messages. Only if one of the
 733 possibility is the payer is the recipient (PDZType is `O'), then calling this
 734 service will cause marking messages as delivered.
 735
 736 Input is `PDZSender' element with a box ID as the only text node child.
 737
 738 Ouput is orderer list of rules for sending commercial messages wrapped in
 739 dbPDZRecords element. The list can be empty what means no permission is
 740 available. Each list item is a subtree:
 741
 742 dbPDZRecord
 743     + PDZType – rule type; see below for known values
 744     + PDZRecip – only this recipient box ID is possible. Empty value means no
 745     |   restriction on the recipient.
 746     + PDZPayer – the message is payed by this box ID owner
 747     + PDZExpire – expiration time of this rule. Empty value means no
 748     |   expiration.
 749     + PDZCnt – number of remaining commecrial messages that can be sent based
 750     |   on thid rule. Empty value means no limit.
 751     + ODZIdent – identifier referring to message enabling sending pre-paid
 752         answer. Must be added as dmRecipientRefNumber into sent message.
 753
 754 PDZType     Meaning
 755 -------------------------------------------------------------------------------
 756 D           Externally subsidized (undocumented)
 757 E           Commercial message pre-paid by the sender
 758 G           PDZPayer owner pays for all commercial messages
 759 K           Commercial message paid by sender based on an agreement with the
 760             Czech Post.
 761 O           Answer on a commercial message is pre-paid by PDZPayer. ODZIdent
 762             value must be added into an outgoing message to bind the message to
 763             the payer and requesting message.
 764 Z           Limitedly subsidized (undocumented)
 765
 766
 767 DataBoxCreditInfo (*)
 768 =================
 769
 770 Return current credit value and and history of credit changes for given box
 771 and time interval.
 772
 773 Input is `dbID' element with box ID whose credit you want to obtain and
 774 possibly empty elements `ciFromDate' and `ciTodate' carrying start and end
 775 date (inclusive) for history records to obtain.
 776
 777 Output is `currentCredit' element delivering current credit value,
 778 `notifEmail' element delivering e-mail address to send notifications
 779 about changes in the commercial services to, and `ciRecords' tree with history
 780 of changes that occurred in the given interval. All these elements are optional.
 781
 782 The `ciRecords' element contains possibly (if interval is not defined) empty
 783 time-sorted list of `ciRecord' trees:
 784
 785 ciRecord
 786     + ciEventTime – time of the change
 787     + ciEventType – type of the change expressed as an integer
 788     + ciCreditChange – value of the credit change
 789     + ciCreditAfter – value of the credit after the change
 790
 791 ciEventType     Meaning
 792 ------------------------------------------
 793 1               Charge credit
 794 2               Discharge credit
 795 3               Sending commercial message
 796 4               Setting long term storage
 797 5               Credit expiration
 798
 799 `ciRecord' contains other elements depending on `ciEventType':
 800
 801 Element         ciEventType     Meaning
 802 ------------------------------------------------------------------
 803 ciTransID       1, 2            String; not specified
 804 ciRecipientID   3               Recipient's box ID of the sent message
 805 ciPDZID         3               ID of the sent message
 806 ciNewCapacity   4               Integer; new capacity of storage in messages
 807 ciNewFrom       4               Date when the new capacity is effective
 808 ciNewTo         4               Date when the new capacity expires
 809 ciOldCapacity   4               Integer, optional; former capacity in messages
 810 ciOldFrom       4               Date, optional
 811 ciOldTo         4               Date, optional
 812 ciDoneBy        4               String, optional; Name of user who initiated
 813                                 the change
 814
 815 All credit values are integers in hundredths of Czech Crowns.
 816
 817 Output carries standard `dbStatus' tree with status code and status message.
 818
 819 Error codes (codes are not normative):
 820     1004    Insufficient priviledges for the box
 821     2011    The box does not exist
 822     1093    Date is too long (history is not available after 15 months)
 823     1137    Interval is too long (limit is 3 months)
 824     1058    Invalid date
 825
 826
 827 ISDSSearch2 (*)
 828 ===========
 829
 830 Return list of boxes matching a full text criteria.
 831
 832 The search is perfomed on an index cached each 3 hours.
 833
 834 The search phrase is splitted on word boundaries and the words are looked up
 835 in the index. Only whole words matches. All search phrase words must be found
 836 in the same box metadata (not necessarily in the same attribute and in the
 837 same order). Diacritics supplementing, case folding, and lemmatization is
 838 supported.
 839
 840 Non-OVM users still cannot see FO boxes which cannot receive commercial
 841 messages and whose owners forbade listing on a public index.
 842
 843 Input is this list of these elements:
 844
 845 Element         Type                    Details
 846 --------------------------------------------------------------------------------
 847 searchText      String                  Mandatory, non-empty
 848 searchType      Enumerated string       Mandatory, can be empty,
 849                                         defaults to GENERAL
 850 searchScope     Enumerated string       Mandatory, can be empty,
 851                                         defaults to ALL
 852 page            Non-negative integer    Mandatory, can be empty,
 853                                         defaults to 0, counts from 0
 854 pageSize        Non-negative integer    Mandatory, can be empty,
 855                                         defaults to 50, counts from 0,
 856                                         server clamps the value to 100
 857 highlighting    Boolean                 Optional, can be empty,
 858                                         defaults to false
 859
 860 Acceptable values for `searchType' element are:
 861
 862 Value       Meaning
 863 --------------------------------------------------------------------------
 864 GENERAL     Search a phrase in names, addresses, organization identifiers,
 865             and box IDs
 866 ADDRESS     Search a phrase in addresses only
 867 ICO         Search in organization identifiers only by equivalence
 868 DBID        Search in box IDs only by equivalence
 869
 870 If `searchType' is `ICO' or `DBID', `searchScope' restriction is ignored.
 871
 872 `searchScope' element restricts box types. See `Box types' section in `box'
 873 file for the semantics, acceptable values are:
 874
 875 Value       Meaning
 876 ------------------------------------------------------------------------
 877 ALL         Search over all box types
 878 OVM
 879 OVM_MAIN    Search over main (without suboridanated, with secondary) OVM
 880             box types only
 881 OVM_REQ
 882 OVM_FO
 883 OVM_PFO
 884 OVM_PO
 885 OVM_NOTAR
 886 OVM_EXEKUT
 887 PO
 888 PO_ZAK
 889 PO_REQ
 890 PFO
 891 PFO_ADVOK
 892 PFO_INSSPR
 893 PFO_DANPOR
 894 PFO_AUDITOR
 895 FO
 896
 897 Output is this list of these optional elements
 898
 899 Element         Type                    Meaning
 900 ------------------------------------------------------------------------
 901 totalCount      Non-negative integer    Number of matching boxes
 902 currentCount    Non-negative integer    Number of boxes in this response
 903 position        Non-negative integer    Ordinal number of first box in this
 904                                         response, counts from 0
 905 lastPage        Boolean                 True if no more boxes match
 906 dbResults       List of elements
 907
 908 Last mandatory element is the standard response status of the service call
 909 `dbStatus' element with status code and status message.
 910
 911 `dbResults' content is a possibly empty list of `dbResult' elements.
 912 The list is sorted according to a search relevance. The `dbResult' element
 913 consists of:
 914
 915 dbResult
 916     + dbID – box ID
 917     + dbType – box type
 918     + dbName – box name
 919     + dbAddress – residence address as one string
 920     + dbBiDate – can be empty, date of birth
 921     + dbICO – can be empty, identifier of an organization
 922     + dbEffectiveOVM – boolean, true for a box upgraded to an OVM role
 923     + dbSendOptions – enumerated string, capability to deliver different
 924         kinds of messages, it depends on querrier's box type and the found box
 925
 926 Acceptable values for `dbSendOptions' element are:
 927
 928 Value       Meaning
 929 -------------------
 930 DZ          Only noncommecrial messages can be sent
 931 ALL         Noncommercial and commercial messages can be sent
 932 PDZ         Only commercial messages can be sent
 933 NONE        No message can be sent
 934 DISABLED    The box is not active
 935
 936 If input `highlighting' is true, output `dbName' and `dbAddress' can contain
 937 delimeters highlighting the phrase found in the strings. The start of the
 938 phrase is marked by `|$*HL_START*$|' string, the end of the phrase is marked
 939 by `|$*HL_END*$|' string.
 940
 941 Error codes:
 942     1004    Not allowed to search
 943     1152    `searchText' is empty
 944     1153    Searched box ID is malformed
 945     1154    Searched organization ID is malformed
 946     1155    Invalid input
 947     1156    `pageSize' is too large
 948     9002    Search engine internal error
 949
 950
 951 GetDataBoxActivityStatus (*)
 952 ========================
 953
 954 Retrive box state changes in given history time frame.
 955
 956 Input is list of these elements:
 957
 958 Element Type    Mandatory   Meaning
 959 --------------------------------------------------------------------------
 960 dbID    String  Mandatory   Box ID
 961 baFrom  Time    Optional    Interval beginning, inclusive, second accuracy
 962                             defaults to box creation
 963 baTo    Time    Optional    Interval end, inclusive, second accuracy,
 964                             defaults to now
 965
 966 Non-normative: XML schema does not match textual documentation regarding
 967 obligatority of the elements and their values. The table conforms to the
 968 textual specification.
 969
 970 Output is list of optional `dbID', optional `Periods', and mandatory
 971 `dbStatus' elements. `Periods' element is possibly empty list of these
 972 `Period' elements:
 973
 974 Period
 975     + PeriodFrom – xs:dateTime
 976     + PeriodTo – xs:dateTime
 977     + DbState – non-negative integer
 978
 979 `DbState' is 1 for accessible state. Inaccessible state is signaled by 0 for
 980 OVM users authenticated by system certificate, by 2--6 as defined in box
 981 states for some internal priviledged users. Other users are not allowed to
 982 call this service.
 983