doc/user_web_services

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