User web services specification
===============================
Source: Provoznà Åád ISDS, version 2010-01-22, Pages 14â15
Source: Webové služby ISDS pro manipulaci s datovými zprávami,
version 2.11 (2010-05-20)
Source: Webové služby ISDS pro vyhledávánà datových schránek,
version 2.11 (2010-05-19)
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 DOES NOT MARK
noncommercial 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
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
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
db_search.wsdl
==============
URL postfix: df
FindDataBox (*)
Find boxes conforming to search criteria
CheckDataBox (*)
Return state of given box
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).
Since 2010-05-20, outgoing message envelope can specify dmType. However it's
currently ignored.
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
+ dmFiles
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 must be accepted manually by ConfirmDelivery before.
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>
Commercial message must be accepted manually by ConfirmDelivery before.
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
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.
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.
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.
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
-----------------------------------------------------
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
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.
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
Non-normative:
2011 Box ID malformed
