User web services specification
===============================

Source: Provozní řád ISDS, version 2010-11-28, Pages 15–16
Source: Webové služby rozhraní ISDS pro manipulaci s datovými zprávami,
    version 2.32 (2012-10-05)
Source: Webové služby ISDS pro vyhledávání datových schránek,
    version 2.37 (2014-01-14)


These services are intended for working with messages inside a box by
a regular user.

SOAP web services defined in: dm_operations.wsdl, dm_info.wsdl, db_search.wsdl
(Appendix 2 of Provozní řád ISDS)

Data types: dmBaseTypes.xsd (Appendix 1)

Documentation: DataMessage_ws.pdf, DBSearch_ws.pdf (Appendix 2)

List of SOAP requests follows. Those marked with asterisk DO NOT MARK incoming
messages as delivered. Those marked with plus has access to envelopes of
deleted messages.


dm_operations.wsdl
==================

URL postfix: dz
Constraints: Client must be authenticated in Access Manager

CreateMessage (*)
    Create and send a message
CreateMultipleMessage (*)
    Create and send a message to multiple recipients
MessageDownload
    Download incoming message
SignedMessageDownload
    Download incoming message with digital signature of ministry of interiors
SignedSentMessageDownload
    Download outgoing message with digital signature of ministry of interiors
AuthenticateMessage (*+)
    Submit local message copy to ISDS to confirm message authenticity
Re-signISDSDocument (*)
    Replace CMS signature of old message signed without time stamp
DummyOperation
    Void operation used to log in and to keep connection alive


dm_info.wsdl
============

URL postfix: dx
Constraints: Client must be authenticated in Access Manager

VerifyMessage (*+)
    Verify local copy of message with remote original stored in ISDS
MessageEnvelopeDownload (+)
    Download envelope of incoming message
MarkMessageAsDownloaded (*)
    Mark message as read
ConfirmDelivery
    Mark commercial message as accepted by recipient
EraseMessage (*)
    Remove message from long term storage
GetDeliveryInfo (+)
    Download info-sheet about message post and delivery
GetSignedDeliveryInfo (+)
    Download info-sheet about message post and delivery with signature of
    ministry of interiors
GetListOfRecievedMessages
    Download list of incoming messages
GetListOfSentMessages
    Download list of outgoing messages
GetMessageAuthor
    Get details about sender
GetMessageStateChanges
    Download list of outgoing messages that changed state


db_search.wsdl
==============

URL postfix: df

FindDataBox (*)
    Find boxes conforming to search criteria
CheckDataBox (*)
    Return state of given box
GetDataBoxList (*)
    Get list of all boxes
PDZInfo
    Get rules for sending commercial messages from given box
DataBoxCreditInfo (*)
    Get details about credit for comercial services


CreateMessage (*)
=============

Create and send a message.

Envelope of outgoing message must contain dbIDRecipient and dmAnnotation.
Other elements are optional (dmRecipientOrgUnit, dmRecipientOrgUnitNum,
dmSenderOrgUnit, dmSenderOrgUnitNum, dmToHands, dmPersonalDelivery,
dmAllowSubstDelivery, dmRecipientRefNumber, dmRecipientIdent,
dmSenderRefNumber, dmSenderIdent, dmLegalTitleLaw, dmLegalTitleYear,
dmLegalTitleSect, dmLegalTitlePar, dmLegalTitlePoint, dmOVM, dmPublishOwnID).

Outgoing message envelope can specify dmType to declare subtype of commercial
message. If dmType is `I', then dmSenderRefNumber must be defined. If dmType
is `O', then dmRecipientRefNumber must be defined.

Constraints: Sender must have PRIVIL_CREATE_DM permission.
Constraints: Exactly one document in message must be main type.
Constraints: Total size of all documents must not be bigger than 10 MB.

Identifier of just sent message assigned by system is returned.

Error codes:
    0000    Message sent successfully
Non-normative error codes:
    1214    Document description is not a file name with acceptable file name
            extension
    1214    Document description extension does not match document content
    1214    Provided MIME type does not match document
    2010    First document structure invalid
    2032    Message does not carry any document
    9005    Message not valid (probably)

In case of positive virus detection (processed after sending), infected
document is removed, message state is set to value 3 (from point of view of
recipient) and sender get new message originated by server.


CreateMultipleMessage (*)
=====================

Create and send a message to multiple recipients.

Input composes of nonempty list of recipients (maximal count is 50),
one envelope (different from envelope for CreateMessage, misses elements from
dmRecipient) and list of documents to send to all of them to each recipient.

Only dbIDRecipient and dmToHands are mandatory. Other dmRecipient children are
optional.

Structure:
CreateMultipleMessage
    + dmRecipients
    |   + dmRecipient
    |   |   + dbIDRecipient – recipient box ID
    |   |   + dmRecipientOrgUnit
    |   |   + dmRecipientOrgUnitNum
    |   |   + dmToHands – can be empty, but must not missing
    |   + dmRecipient
    |   ⋮ 
    + dmEnvelope
    |   + <other elements, usually empty>: dmSenderOrgUnit, dmSenderOrgUnitNum,
    |   |   dmAnnotation, dmRecipientRefNumber, dmSenderRefNumber,
    |   |   dmRecipientIdent, dmSenderIdent, dmLegalTitleLaw,
    |   |   dmLegalTitleYear, dmLegalTitleSect, dmLegalTitlePar,
    |   |   dmLegalTitlePoint, dmPersonalDelivery, dmAllowSubstDelivery
    |   + dmOVM – optional
    |   + dmPublishOwnID – optional
    + dmFiles

It's not possible to send commercial message to multiple recipients. Though the
dmEnvelope has @dmType attribute, so it should be possible to send a commercial
message to one recient using CreateMultipleMessage service.

ISDS outputs list of assigned message IDs (each copy gets independent ID),
list of sent status for each message ID and one cumulative status of
whole CreateMultipleMessage operation.

If operation fails before replicating messages for each recipient
(i.e. sending), global error code will be non-zero. If operation fails on some
message copies (i.e. while sending) special global error code 0004 will be
returned and erroneous recipients can be gather by recipient specific error
code (failed ones will have non-zero code). If all messages are sent
successfully, global error code will be 0000.

Structure:
CreateMultipleMessageResponse
    + dmMultipleStatus
    |   + dmSingleStatus
    |   |   + dmID – assigned message ID, optional, missing if error occurred
    |   |   + dmStatus – message local error code and textual description
    |   + dmSingleStatus
    |   ⋮
    + dmStatus – global error code and textual description

Global error codes:
    0000    Messages sent successfully
    0004    Some message failed while sending


MessageDownload
===============

Retrieve incoming message identified by message ID.

This service can return message without digital time-stamp (more precisely
with empty dmQTimesamp element, see schema). 

Commercial message has set dmReturnedMessage/@dmType="K".

Error codes:
    0000    Message sent successfully
Non-normative error codes:
    1219    Message with ID does not exist in ISDS in current box.


SignedMessageDownload
=====================

Download incoming message with digital signature of ministry of interiors
identified by message ID.

Return PKCS#7 structure containing data as defined in MessageDownload and
digital signature of the message by ministry.

The data are XML document with mangled ISDS name space:
http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/message:

<q:MessageDownloadResponse
     xmlns:q="http://isds.czechpoint.cz/v20/message">
  <q:dmReturnedMessage>
     <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
         <p:dmID>151916</p:dmID>
         ...
     </p:dmDm>
     <q:dmHash algorithm="SHA-1">...</q:dmHash>
     ...
     <q:dmAttachmentSize>260</q:dmAttachmentSize>
  </q:dmReturnedMessage>
</q:MessageDownloadResponse>


SignedSentMessageDownload
=========================

Download outgoing message with digital signature of ministry of interiors
identified by ID.

Return PKCS#7 structure containing data as defined in MessageDownload and
digital signature of the message by ministry.

The data are XML document with mangled ISDS name space:
http://isds.czechpoint.cz/v20/ vs. http://isds.czechpoint.cz/v20/SentMessage:

<q:MessageDownloadResponse
     xmlns:q="http://isds.czechpoint.cz/v20/SentMessage">
  <q:dmReturnedMessage>
     <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
         <p:dmID>151916</p:dmID>
         ...
     </p:dmDm>
     <q:dmHash algorithm="SHA-1">...</q:dmHash>
     ...
     <q:dmAttachmentSize>260</q:dmAttachmentSize>
  </q:dmReturnedMessage>
</q:MessageDownloadResponse>


GetListOfRecievedMessages
=========================

Download list of incoming messages matching search criteria.

See GetListOfSentMessages for more details.


GetListOfSentMessages
=====================

Download list of outgoing messages matching search criteria.

Criteria are: delivery time not before, not after, organisation unit number of
sender, message status filter, offset of first message in a list and limit on 
number of messages to get.

Message status filter is union of distinct message states expressed as
exponents of 2. Effectively it's a polynom \sum_{x \in message_statux} 2^x.
Special value -1 means all messages. Meaning for value 1 or 0 is undefined.

Messages are sorted in order of delivery time. Message type is stored in
dmRecord/@dmType.

Offset starts on 1. Limit defaults to 1000.

Non-normative error codes:
    2017    Syntax error in date-time


GetMessageAuthor
================

Get information about sender as un user of given message.

Input is mandatory message identifier. Output is optional userType and
optional authorName.

userType (unknown and undefined for older messages) is type of user who has
sent the message. Be ware there is special additional type `VIRTUAL'. Be ware
the userType is a string unconstrained by XML schema:

Value               Description
--------------------------------------------------------------------------
PRIMARY_USER        The sender was a owner of the box
ENTRUSTED_USER      The sender was an entrusted user associated to the box
ADMINISTRATOR       The sender was administrator assiciated to the box
OFFICIAL            The sender was ISDS (for system messages)
VIRTUAL             The sender was an application authenticated by `system'
                    certificate

Non-normative: New user types OFFICIAL_CERT and LIQUIDATOR are not listed in
official documentation for this service. However LIQUIDATOR is said to be
equivalent to PRIMARY_USER and PRIMARY_USER can send messages, thus I conclude
these two now user types can occur in output of this service.

authorName is a name of user logged into senders box (not a login name) if
sender allowed to reveal his name explicitely.


GetMessageStateChanges
======================

Download list of outgoing messages that changed state in given time range.

If a message changed state multiple times, it is listed more times. Only
changes from state 2 to 4, from 4 to {5, 6, 8} are reported. Only recent
changes (not older than 15 days currently) are reported.

This service is designed for polling state changes of sent messages.

Input are start (dmFromTime element) and end (dmToTime element) ISO times.
Empty dmFromTime meands since last 15 days, empty dmToTime means till now.

Non-normative: Server does not report changes recent more than one hour.

Output is list of records with message state changes. The order of records is
undefined.

Structure:
GetMessageStateChangesResponse
    + dmRecords – optional, possibly empty element
    |   + dmRecord – one state change
    |   |   + dmId – identifier of message that changed state
    |   |   + dmEventTime – ISO time of state change
    |   |   + dmMessageStatus – new message state in numeric notation
    |   + dmRecord
    |   ⋮
    + dmStatus – global error code and textual description


AuthenticateMessage (*+)
===================

Allows to verify message authenticity by providing copy to ISDS.

Only signed message encapsuleted into CMS structure with digital signature can
be verified by this service. Client pass the raw message in Base64 encoding to
ISDS, system performs checks and return boolean value: true if message has
not been modified and has been delivered through ISDS, false if message
has is unkown to ISDS. In both cases 0000 error code will be returned.

If message cannot be processed (e.g. broken CMS or XML syntax) or message
contains has been signed by non-ISDS certificate or other error, non-zero
error code will be returned.


Re-signISDSDocument (*)
===================

Re-sign old message or delivery info that has been generated with CMS without
time stamp. These messages have been produced before 2011-04-16.

Input is dmDoc element carrying Base64-encoded original signed message or
delivery info in text node.

Output is dmResultDoc element with Base64-encoded re-signed message or
delivery info supplied in request, optional dmValidTo element of xs:date type,
and dmStatus of tStatus type. dmValidTo advertises end of validity of
time stamp added into CMS.

Error codes:
    0000    Message has been re-signed and returned in CadES-T CMS format
    2200    Input message is bad
    2201    Input message is not original (see AuthenticateMessage service)
    2204    Input message already contains time stamp in CAdES-EPES or CAdES-T
            CMS envelope
    2207    Time stamp could not been generated in time


VerifyMessage (*+)
=============

Retrieve message hash (dmHash element) for given message from ISDS.

Works for not yet deleted messages only.

Only SHA-1 algorithm is in use currently. SHA-2 family is expected after
2010 year beginning.

Hash input is isds:dmDM subtree processed as raw bit stream without XML
canonicalization. Authoritative isds:dmDM element can be get via
MessageDownload service. God bless ISDS developers to not change XML
serialization.

Non-normative error codes:
    1219    Message with ID does not exist in ISDS.


MessageEnvelopeDownload (+)
=======================

Download envelope of incoming message. That is message without documents.
Message type is stored in dmReturnedMessageEnvelope/@dmType.

Returned hash and time-stamp are computed from whole message. You must get
complete message including documents to be able to verify them.


MarkMessageAsDownloaded (*)
=======================

Change status of a message identified by its ID as read.

That means next GetListOfRecievedMessages service can exclude such message if
only unread messages requested.


ConfirmDelivery
===============

Mark commercial message as accepted by recipient.

XXX: This service has been removed from ISDS because commercial messages get
accepted by logging-in (since 2011-11).

Changes message state from delivered (4) to accepted (6). Applicable only to
commercial messages. Messages from public offices (municipalities, government
etc.) are accepted automatically by log-in on interactive web portal or by
triggering most of SOAP operations.

Must be called before downloading (signed or unsigned) incoming message
[Signed]MessageDownload.


EraseMessage (*)
============

Delete a message from long term storage (know as data safe formerly).

Input is message ID in `dmID' element and boolean in `dmIncoming' element
(true for incoming message, false for outgoing mesage).

Output is standard `dmStatus' subtree.

Only message in long term storage can be removed on user request through
this service. Other message cannot be removed on request, they get removed
automatically after 90-days period.

Error codes:
    1211    The message belongs to other (= not currently logged-in user) box
    1218    Insufficient permissions (PRIVIL_ERASE_VAULT) to remove the message
    1219    The message is not in long term storage or is not incoming or
            outgoing as requested.


GetDeliveryInfo (+)
===============

Download info-sheet about incoming or outgoing message post and delivery or
deliver impossibility. The message is specified by message ID.

It returns complete message envelope, hash, time-stamp. Delivery time and
acceptance time only if message has been delivered to recipient box or
accepted by recipient. Precise status of message is returned too.

In addition, non-empty list of events is attached. Each event compounds of
ISO time and text description. The text description has well-known prefix to
distinguish the event meaning. Following prefixes are defined:

    Prefix  Meaning
    -----------------------------------------------------
    EV0:    Message enterend into ISDS
    EV1:    Message has been accepted by recipient action
    EV2:    Message has been delivered to box and is considered as accepted by
            no-user-action time out (through fiction)
    EV3:    Recipient box has been made inaccessible retrospectively
            (even after successful delivery or acceptance,
            this event is retroactive). In this case special system-generated
            message is sent to sender in addition.
    EV4:    Commercial message has been accepted by recipient confirmation
    EV5:    Message has been delivered into recipent box
    EV11:   Primary user has logged into his box
    EV12:   Entrusted user havin permission to read this message has logged in
    EV13:   Application (not a human) has logged into box using `system'
            certificate 


GetSignedDeliveryInfo (+)
=====================

Download info-sheet about incoming or outgoing message post and delivery or
deliver impossibility as signed PKCS#7 structure. See GetDeliveryInfo for
details about returned data.

The PKCS#7 structure carries digital signature made by ministry of interiors.

There is mangled namespace again: http://isds.czechpoint.cz/v20/ vs.
http://isds.czechpoint.cz/v20/delivery:

<q:GetDeliveryInfoResponse xmlns:q="http://isds.czechpoint.cz/v20/delivery">
  <q:dmDelivery>
    <p:dmDm xmlns:p="http://isds.czechpoint.cz/v20">
      <p:dmID>170272</p:dmID>
      ...
    </p:dmDm>
    <q:dmHash algorithm="SHA-1">...</q:dmHash>
    ...
    </q:dmEvents>...</q:dmEvents>
  </q:dmDelivery>
</q:GetDeliveryInfoResponse>
             

FindDataBox (*)
===========

Find boxes conforming to search criteria or exact ID and return corresponding
(possibly truncated) list of boxes.

Returned boxes exist, but it does not mean they can receive messages. Use
CheckDataBox to figure out.

There are three different search cases distinguished in this order:

    – If dbID is filled in request, it will search for exact box only, other
    criteria will be ignored.

    – If identifier and registryCode are filled, it will search for exact
    box only, other criteria will be ignored.

    – Otherwise search against other criteria.

Returns list of boxes (possibly empty).

List can be truncated or search request refused because of not enough
specific criteria to protect user privacy. There are following constrains
differentiated by box type now:

Gross Box type  Constraints (required search criteria)
------------------------------------------------------
FO              pnLastName or pnLastNameAtBirth
PFO             ic or pnLastName or pnLastNameAtBirth
PO              ic or prefix (at least 3 characters) of firmName
OVM             ic or prefix of firmName

String search criteria are matched case insensitive (except dbID). Strings are
compared to prefix. Except firmName, adCity, adStreet and biCity that are
matched as substrings.

Search results depends or logged-in user type. Users of boxes with open
addressing can search other open-addressing boxes, otherwise only OVM type
boxes can be searched. Search based on exact box identifier finder unlimited.

Error codes:
    0002    No box suits to search request (by other criteria)
    0003    To much boxes suit to search request (by other criteria),
            response truncated. Returned list of boxes is still valid.
    1109    More than one box matches the search request
    5001    No such box exists (by box ID or registry identifier)
Non-normative error codes:
    1101    Box type (dbType) must be specified
    2017    Syntax error in date (biDate)


CheckDataBox (*)
============

Return state of one box identified by dbID.

State of the box is stored in dbStatus element. Only state 1 means box is
capable of receiving messages.

Error codes:
    5001    Box does not exist
    1007    Box ID malformed
    2011    Box ID malformed


GetDataBoxList (*)
==============

Get comma-separate list of all boxes of given type.

Input is type of boxes of interrest (dblType element):

Value   Description             File name           Permission
-------------------------------------------------------------------------------
ALL     All active boxes        actdsYYYYMMDD.csv   OVM or OVM_REQ user
                                                    authenticated by commercial
                                                    certificate or user with
                                                    PRIVIL_BILLING permission
UPG     Effectively OVM active  effovmYYYYMMDD.csv  Anybody
        boxes

Non-normative: Following types are not documented anymore.

Value   Description             File name           Permission
-------------------------------------------------------------------------------
OVM     OVM gross type boxes    ovmYYYYMMDD.csv     PRIVIL_BILLING only
OPN     Boxes that allow to     opendsYYYYMMDD.csv  PRIVIL_BILLING only
        receive commercial
        messages

Output is Base64-encoded ZIP file containing a file with name from the table.
The Base64 string is stored in dblData element. The name of the file embeds
date of list creation (Y is year digit, M is month, D is day).

The file is created once per a day and its format is following comma-separate
value table:

Key 
----------------------
dbID
dbType
pnFirstName
pnMiddleName
pnLastName
pnLastNameAtBirth
biDate
firmName
ic
adCity
adStreet
adNumberInStreet
adNumberInMunicipality
adZipCode
adState
nationality
lastChangeDate

The inner file is encoded in UTF-8. First line of the file is a header. Each
next line is a box. If a value is undefined, it will be empty. Values in
a line are separated by a comma (`,'). If a value contains comma or quotation
(`"'), the value will be enclosed into quotes (`"'). If value contains quotes,
they will be escaped by a quotes (e.g. `"lazy, ""fox""' means `lazy, "fox"').

Error codes:
    1004    Operation not permitted


PDZInfo
=======

Return posibilities of sending commerical messages. Only if one of the
possibility is the payer is the recipient (PDZType is `O'), then calling this
service will cause marking messages as delivered.

Input is `PDZSender' element with a box ID as the only text node child.

Ouput is orderer list of rules for sending commercial messages wrapped in
dbPDZRecords element. The list can be empty what means no permission is
available. Each list item is a subtree:

dbPDZRecord
    + PDZType – rule type; see below for known values
    + PDZRecip – only this recipient box ID is possible. Empty value means no
    |   restriction on the recipient.
    + PDZPayer – the message is payed by this box ID owner
    + PDZExpire – expiration time of this rule. Empty value means no
    |   expiration.
    + PDZCnt – number of remaining commecrial messages that can be sent based
    |   on thid rule. Empty value means no limit.
    + ODZIdent – identifier referring to message enabling sending pre-paid
        answer. Must be added as dmRecipientRefNumber into sent message.

PDZType     Meaning
-------------------------------------------------------------------------------
D           Externally subsidized (undocumented)
E           Commercial message pre-paid by the sender
G           PDZPayer owner pays for all commercial messages
K           Commercial message paid by sender based on an agreement with the
            Czech Post.
O           Answer on a commercial message is pre-paid by PDZPayer. ODZIdent
            value must be added into an outgoing message to bind the message to
            the payer and requesting message.
Z           Limitedly subsidized (undocumented)


DataBoxCreditInfo
=================

Return current credit value and and history of credit changes for given box
and time interval.

Input is `dbID' element with box ID whose credit you want to obtain and
possibly empty elements `ciFromDate' and `ciTodate' carrying start and end
date (inclusive) for history records to obtain.

Output is `currentCredit' element delivering current credit value,
`notifEmail' element delivering e-mail address to send notifications
about changes in the commercial services to, and `ciRecords' tree with history
of changes that occurred in the given interval. All these elements are optional.

The `ciRecords' element contains possibly (if interval is not defined) empty
time-sorted list of `ciRecord' trees:

ciRecord
    + ciEventTime – time of the change
    + ciEventType – type of the change expressed as an integer
    + ciCreditChange – value of the credit change
    + ciCreditAfter – value of the credit after the change

ciEventType     Meaning                 
------------------------------------------
1               Charge credit
2               Discharge credit
3               Sending commercial message
4               Setting long term storage
5               Credit expiration

`ciRecord' contains other elements depending on `ciEventType':

Element         ciEventType     Meaning
------------------------------------------------------------------
ciTransID       1, 2            String; not specified
ciRecipientID   3               Recipient's box ID of the sent message
ciPDZID         3               ID of the sent message
ciNewCapacity   4               Integer; new capacity of storage in messages
ciNewFrom       4               Date when the new capacity is effective
ciNewTo         4               Date when the new capacity expires
ciOldCapacity   4               Integer, optional; former capacity in messages
ciOldFrom       4               Date, optional
ciOldTo         4               Date, optional
ciDoneBy        4               String, optional; Name of user who initiated
                                the change

All credit values are integers in hundredths of Czech Crowns.

Output carries standard `dbStatus' tree with status code and status message.

Error codes (codes are not normative):
    1004    Insufficient priviledges for the box
    2011    The box does not exist
    1093    Date is too long (history is not available after 15 months)
    1137    Interval is too long (limit is 3 months)
    1058    Invalid date