doc/user_web_services

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