Using Hermes API¶

Introduction¶

Hermes has implemented web services to communicate with external applications. The main advantages of using web services are reducing the coupling between external applications and Hermes, and to allow external applications to integrate with Hermes seamlessly using any programming languages that support sending SOAP Messages with Attachments or calling REST APIs. This article helps developers writing a client which talks to Hermes via web services based on SOAP or REST APIs on HTTP.

For more information on the installation and partnerships of Hermes, please refer to Installing Hermes and The First Step respectively.

To choose whether to use SOAP or REST APIs in your application, you may refer to Understanding SOAP and REST Basics and Differences for guidance.

Overview¶

Here is a brief summary about the communication architecture between Hermes and external applications. The core of Hermes can run on any J2EE compliant web server as a servlet. The core itself provides neither any web services or HTTP listeners, nor any functionality related to messaging. All features in Hermes are derived from the core using SPA (Simple Plugin Architecture).

One of the core SPAs, called Main Plugin (shown below in the core SPA layer), provides an HTTP context listener that accepts HTTP requests at the specified context path (extension point) for external invocation. The protocol-specific SPA ebMS and AS2 plugins (shown below in the external SPA layer) make use of this listener to provide all SOAP and REST web services.

In the default Hermes installation, each of ebMS 2.0 and AS2 plugins supports the following registered web services in Hermes:

ebMS 2.0 Hermes API¶
Functionality	REST(ebMS) [1]	SOAP(ebMS)
Send message	POST:corvus/api/message/send/ebms	/corvus/httpd/ebms/sender
List received message ID	GET:/corvus/api/message/receive/ebms	/corvus/httpd/ebms/receiver_list
Download received message payload	POST:/corvus/api/message/receive/ebms	/corvus/httpd/ebms/receiver
Get message status	GET:/corvus/api/message/send/ebms	/corvus/httpd/ebms/status
Reset message status	POST:/corvus/api/message/redownload/ebms	/corvus/httpd/ebms/permitdl
Query message with parameters	GET:/corvus/api/message/history/ebms	/corvus/httpd/ebms/msg_history
Add partnership	POST:/corvus/api/partnership/ebms	NIL
Delete partnership	DELETE /corvus/api/partnership/ebms/{pid}	NIL
Update partnership	POST:/corvus/api/partnership/ebms	NIL
Get partnerships	GET:/corvus/api/partnership/ebms	NIL

AS2 Hermes API¶
Functionality	REST(AS2) [1]	SOAP(AS2)
Send Message	POST:/corvus/api/message/send/as2	/corvus/httpd/as2/sender
List received message ID	GET:/corvus/api/message/receive/as2	/corvus/httpd/as2/receiver_list
Download received message payload	POST:/corvus/api/message/receive/as2	/corvus/httpd/as2/receiver
Get message status	GET:/corvus/api/message/send/as2	/corvus/httpd/as2/status
Query message with parameters	GET:/corvus/api/message/history/as2	/corvus/httpd/as2/msg_history
Add partnership	POST:/corvus/api/partnership/as2	NIL
Delete partnership	DELETE /corvus/api/partnership/as2/{pid}	NIL
Update partnership	POST:/corvus/api/partnership/as2	NIL
Get partnerships	GET:/corvus/api/partnership/as2	NIL

Note

To make an REST API request, the simplest way is to use curl as a command line REST client, or Postman as a GUI based client.
To enhance the security of Hermes REST API, HTTP Basic Authenication is enabled for the Rest API. Please place the base64 encoded username:password in the HTTP Header as below : HTTP Header:Authorization = basic base64encode[username:pwd] where the username and pwd are defined in tomcat-users.xml mentioned in Tomcat installation.

ebMS 2.0 Web Service¶

Send message¶

This is a web service interface for external parties to request Hermes to send an ebMS message to another Hermes or an ebMS compliant messaging gateway. The service provides a message identifier to the sender for future reference. This is the main channel for external applications to deliver ebMS messages using Hermes.

SOAP¶

Service endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/sender

Request message

Instead composing the entire ebMS messages, the sender simply needs to send a web service request to Hermes with key parameters including CPA ID, Service and Action. These 3 key parameters identify the sending partnership in Hermes that will be used to configure the ebMS message.

The elements in the SOAP body use the namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP request is shown below.

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
   <SOAP-ENV:Header/>
   <SOAP-ENV:Body>
       <tns:cpaId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[CPA_Id]</tns:cpaId>
       <tns:service xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Service]</tns:service>
       <tns:action xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Action]</tns:action>
       <tns:convId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Conversation_Id]</tns:convId>
       <tns:fromPartyId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[From_Party_Id]</tns:fromPartyId>
       <tns:fromPartyType xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[From_Party_Type]</tns:fromPartyType>
       <tns:toPartyId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[To_Party_Id]</tns:toPartyId>
       <tns:toPartyType xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[To_Party_Type]</tns:toPartyType>
       <tns:refToMessageId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Reference_Message_Id]</refToMessageId>
       <tns:serviceType xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Service_Type]</tns:serviceType>
   </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<!-- Attached payloads... -->

The descriptions of the elements in the SOAP body are as follows:

Element	Mandatory	Description
`<cpaId>`, `<service>`, `<action>`	Yes	They are the `CPA Id`, `Service` and `Action` elements in the ebMS messages sent by Hermes. These three fields are used to identify the partnership used to send and receive the ebMS messages by the sending and receiving parties respectively. These are required to identify a registered partnership in Hermes.
`<convId>`	Yes	This corresponds to the `conversation id` element in the ebMS messages sent by Hermes.
`<fromPartyId>`	Yes	This identifies the sender. [ebMS v2_0 3.1.1] It corresponds to the `PartyId` element in `From` element of ebMS messages sent by Hermes.
`<fromPartyType>`	Yes	This identifies the domain of the sender. It corresponds to the `type` attribute of `PartyId` in the `From` element of ebMS messages sent by Hermes.
`<toPartyId>`	Yes	This identifies the receiver. [ebMS v2_0 3.1.1] It corresponds to the `PartyId` element in `To` element of ebMS messages sent by Hermes.
`<toPartyType>`	Yes	This identifies the domain of the receiver. It corresponds to the `type` attribute of `PartyId` in the `From` element of ebMS messages sent by Hermes.
`<refToMessageId>`	No	This corresponds to the `RefToMessageId` of ebMS messages sent by Hermes.
`<serviceType>`	No	A type identifier for the ebXML service defined in the partnership.

Response message

The elements inside the SOAP body uses namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
        <SOAP-ENV:Body>
            <message_id xmlns="http://service.ebms.edi.cecid.hku.hk/">[newly_created_message_id]</message_id>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In the SOAP request message, the <message_id> element is the message identifier assigned by Hermes in the sending party. The sending application can use it for later reference and status tracking with Get message status web service.

REST [1]¶

Request message

$ curl -X POST --data '{"partnership_id":"<partnership_id>", "from_party_id":"<from>", "to_party_id":"<to>", "conversation_id":"<conv>", "payload":"<payload>"}' http://<HOST>:<PORT>/corvus/api/message/send/ebms

Response message

{
    "id": "<message_id>"
}

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

List received message ID¶

This web service is used by the application of the receiving party to retrieve message identifiers of received and processed ebMS messages that have not been downloaded. These message identifiers will be used to retrieve message payloads with Download received message payload web service.

SOAP¶

Service endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/receiver_list

Request message

The elements in the SOAP body use the namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP request is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <tns:cpaId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[CPA_Id]</tns:cpaId>
        <tns:service xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Service]</tns:service>
        <tns:action xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Action]</tns:action>
        <tns:convId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Conversation_Id]</tns:convId>
        <tns:fromPartyId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[From_Party_Id]</tns:fromPartyId>
        <tns:fromPartyType xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[From_Party_Type]</tns:fromPartyType>
        <tns:toPartyId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[To_Party_Id]</tns:toPartyId>
        <tns:toPartyType xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[To_Party_Type]</tns:toPartyType>
        <tns:numOfMessages xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Number_of_messages]</tns:numOfMessages>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The descriptions of the elements in the SOAP body are as follows:

Element	Mandatory	Description
`<cpaId>`, `<service>`, `<action>`	Yes	The `CPA Id`, `Service` and `Action` elements in ebMS messages sent by Hermes. These three fields identify the partnership used to send ebMS messages. These are required to query the list of available messages.
`<convId>`	No	Only the identifiers of messages with a matching `Conversation Id` will be retrieved.
`<fromPartyId>`	No	Only the identifiers of messages with a matching `From Party Id` will be retrieved.
`<fromPartyType>`	No	Only the identifiers of messages with a matching `From Party Type` will be retrieved.
`<toPartyId>`	No	Only the identifiers of messages with a matching `To Party Id` will be retrieved.
`<toPartyType>`	No	Only the identifiers of messages with a matching `To Party Type` will be retrieved.
`<numOfMessages>`	No	The maximum number of message identifiers retrieved by this request.

Response message

The elements inside the SOAP body use the namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <messageIds xmlns="http://service.ebms.edi.cecid.hku.hk/">
            <messageId>[downloadable_message_id]</messageId>
            <messageId>[downloadable_message_id]</messageId>
        </messageIds>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Each element in the messageIds represents the message identifier of an ebMS message received by Hermes.

Please note that a message is considered to be downloaded only when the message body has been downloaded by Download received message payload SOAP web service. If your application never calls Download received message payload SOAP web service to download the messages, the same set of message identifiers will always be retrieved.

REST [1]¶

Request message

$ curl -X GET http://<HOST>:<PORT>/corvus/api/message/receive/ebms?partnership_id=<partnership_id>

REST reponse message

{
    "message_ids": [
        {
            "id": "<message_id>",
            "timestamp": 1234567890,
            "status": "<status>"
        }
    ]
}

Please note that a message is considered to be downloaded when the message id is returned by this REST API call.

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

Download received message payload¶

This web service is used by the application of the receiving party to retrieve message payloads of received ebMS messages. After the message payloads have been downloaded, the message will be marked as received, and its message identifier will no longer be retrieved by List received message ID web service.

SOAP¶

Service endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/receiver

Request message

The elements in the SOAP body use the namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP request is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <tns:messageId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[id_of_message_to_download]</tns:messageId>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The <messageId> element contains a message identifier which obtained from List received message ID web service.

Response message

The element inside the SOAP body is using namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <hasMessage xmlns="http://service.ebms.edi.cecid.hku.hk/">[true_if_payload_in_message]</hasMessage>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<!--
    Attached payloads...
-->

If a payload is associated with the message identifier, the <hasMessage> element will have the value true. If the received ebMS message has payloads, the response message will have one or more SOAP attachments. Each SOAP attachment has a content type, which is set by the sending application.

Please note that a message is considered to be downloaded when the message is returned by this SOAP request.

REST [1]¶

Request message

$ curl -X POST --data '{"message_id":"<message_id"}' http://<HOST>:<PORT>/corvus/api/message/receive/ebms

Response message

{
    "id": "<message_id>",
    "cpa_id": "<cpa>",
    "service": "<service>",
    "action": "<action>",
    "from_party_id": "<from>",
    "to_party_id": "<to>",
    "conversation_id": "<conv>",
    "timestamp": 1234567890,
    "status": "<status>",
    "payloads": [
        {
            "payload": "<content>"
        }
    ]
}

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

Get message status¶

This web service is used by the application of the sending party to retrieve the status of a delivered ebMS message.

The message status is a two-character code indicating the progress of an ebMS message. It provides a tracking service to monitor ebMS messages requested from Hermes.

SOAP¶

Service endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/status

Request message

The elements in the SOAP body use the namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP request is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <tns:messageId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[id_of_message_to_download]</tns:messageId>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The <messageId> element contains a message identifier obtained from Send message web service response or List received message ID web service.

Response message

The element inside the SOAP body is using namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <messageInfo xmlns="http://service.ebms.edi.cecid.hku.hk/">
            <status>[status]</status>
            <statusDescription>[statusDescription]</statusDescription>
            <ackMessageId>[ackMessageId]</ackMessageId>
            <ackStatus>[ackStatus]</ackStatus>
            <ackStatusDescription>[ackStatusDescription]</ackStatusDescription>
        </messageInfo>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The descriptions of the elements in the SOAP body are as follows:

Element	Description
`<status>`	The current status of the ebMS message.
`<statusDescription>`	A text description of the current status.
`<ackMessageId>`	The message identifier of the associated acknowledgment (if any).
`<ackStatus>`	The current status of the associated acknowledgment (if any).
`<ackStatusDescription>`	A text description of the associated acknowledgment (if any).

REST [1]¶

Request message

$ curl -X GET http://<HOST>:<PORT>/corvus/api/message/send/ebms?id=<message_id>

Response message

{
    "message_id": "<message_id>",
    "status": "<status>"
}

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

Reset message status¶

This web service is used by the application of the receiving party to reset the status of a downloaded ebMS message from DL (delivered) to PS (processed), so that it can be redownloaded again.

SOAP¶

Service endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/permitdl

Request message

The elements in the SOAP body use the namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP request is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <tns:messageId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">
            [The_message_id_you_want_to_redownload]
        </tns:messageId>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The <messageId> element contains a message identifier obtained from the ebMS sender web service response or the ebMS receiver list web service.

Response message

The element inside the SOAP body is using namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <message_id xmlns="http://service.ebms.edi.cecid.hku.hk/">[newly_created_message_id]</message_id>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

In the SOAP request message, the <message_id> element is the message identifier where they are the same if reset status successfully.

REST [1]¶

Request message

$ curl -X POST --data '{"message_id":"<message_id>"}' http://<HOST>:<PORT>/corvus/api/message/redownload/ebms

Response message

{
    "id": "<message_id>"
}

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

Query message with parameters¶

This web service is used by the application of the sending or receiving party to query messages according to specific parameters.

SOAP¶

Service endpoint: http://<HOST>:<PORT>/corvus/httpd/ebms/msg_history

Request message

The elements in the SOAP body use the namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP request is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:messageBox xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Message_Box]</tns:messageBox>
<tns:status xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Message_Status]</tns:status>
<tns:messageId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Message_Id]</tns:messageId>
<tns:conversationId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Conversation_Id]</tns:conversationId>
<tns:cpaId xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[CPA_Id]</tns:cpaId>
<tns:service xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Defined_Service_with_trading_party]</tns:service>
<tns:action xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[Action]</tns:action>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Response message

The element <messageList> inside the SOAP body uses the namespace URI http://service.ebms.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <messageList xmlns="http://service.ebms.edi.cecid.hku.hk/">
            <messageElement>
                <messageId>[message_id]</messageId>
                <messageBox>[message_box_containing_this_message]</messageBox>
            </messageElement>
            <messageElement>
                <messageId>[message_id]</messageId>
                <messageBox>[message_box_containing_this_message]</messageBox>
            </messageElement>
            <messageElement>...</messageElement>
            <messageElement>...</messageElement>
        </messageList>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The descriptions of the elements in the SOAP body are as follows:

Element	Description
`<messageList>`	A list of retrieved message elements (if any).
`<messageElement>`	A complex element containing `messageId` and `messageBox` values of a retrieved message.
`<messageId>`	The message identifier of a retrieved message.
`<messageBox>`	The message box of a retrieved message.

REST [1]¶

Request message

$ curl -X GET http://<HOST>:<PORT>/corvus/api/message/history/ebms?message_id=<message_id>&message_box=<message_box>&conversation_id=<cid>&cpa_id=<cpa_id>&service=<service>&action=<action>&status=<status>&limit=<limit>

Response message

{
    "message_ids": [
        {
            "id": "<id>",
            "cpa_id": "<cpa_id>",
            "service": "<service>",
            "action": "<action>",
            "conversation_id": "<conversation_id>",
            "message_box": "<message_box>",
            "timestamp": "<timestamp>",
            "status": "<status>"
        }
    ]
}

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

Add partnership¶

The ebMS Add Partnership web service is used by the application of the sending and receiving party to create partnership. For further details about ebMS partnership, please refer to Setting Up ebMS 2.0 Partnerships.

REST [1]¶

Request message

$ curl -X POST -- data '{"id":"<partnership_id>", "cpa_id":"<cpa>", "service":"<service>", "action":"<action>", "transport-endpoint":"http://<RECEIVER HOST>:<RECEIVER PORT>/corvus/httpd/ebms/inbound"}' \
http://<SENDER_HOST>:<SENDER_PORT>/corvus/api/partnership/ebms

Response message

{
    "id" : "<partnership_id>"
}

Delete partnership¶

The ebMS delete Partnership web service is used by the application of the sending and receiving party to delete partnership.

REST [1]¶

Request message

$ curl -X DELETE http://<HOST>:<PORT>/corvus/api/partnership/ebms/<partnership_id>

Response message

{
    "id": "<partnership_id>",
    "success": true
}

Update partnership¶

The ebMS update Partnership web service is used by the application of the sending and receiving party to update partnership. For further details about ebMS partnership, please refer to Setting Up ebMS 2.0 Partnerships.

REST [1]¶

Request message

$ curl -X POST -- data '{"id":"<partnership_id>", "cpa_id":"<cpa>", "service":"<service>", "action":"<action>", "transport-endpoint":"http://<RECEIVER HOST>:<RECEIVER PORT>/corvus/httpd/ebms/inbound"}' \
http://<SENDER_HOST>:<SENDER_PORT>/corvus/api/partnership/ebms

Response message

{
    "id": "<partnership_id>"
}

Get partnerships¶

The ebMS get Partnership web service is used by the application of the sending and receiving party to get all partnership details.

REST [1]¶

Request message

$ curl -X GET http://<HOST>:<PORT>/corvus/api/partnership/ebms

Response message

{
    "partnerships": [
        {
            "id": "<partership_id>",
            "cpa_id": "<cpa>",
            "service": "<service>",
            "action": "<action>",
            "disabled": false,
            "transport_endpoint": "http://<HOST>:<PORT>/corvus/httpd/ebms/inbound",
            "ack_requested": null,
            "signed_ack_requested": null,
            "duplicate_elimination": null,
            "message_order": null,
            "retries": 0,
            "retry_interval": 0,
            "sign_requested": false,
            "sign_certicate": null
        }
    ]
}

AS2 Web Service¶

Send Message¶

This web service is used by the application of the sending party to request Hermes to send an AS2 message to another Hermes or a compatible messaging gateway. The service returns a message identifier to the application for future reference.

SOAP¶

Service endpoint: http://<HOST>:<PORT>/corvus/httpd/as2/sender

Request message

The elements in the SOAP body use the namespace URI http://service.as2.edi.cecid.hku.hk/.

A sample SOAP request is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <tns:as2_from xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[as2_from]</tns:as2_from>
        <tns:as2_to xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[as2_to]</tns:as2_to>
        <tns:type xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[type]</tns:type>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>
<!-- Attached payloads... -->

The descriptions of the elements in the SOAP body are as follows:

Element Mandatory Description

<as2_from>, <as2_to>

Yes

The values of the From and To fields in AS2 messages sent through the partnership by Hermes. These fields are used to identify the sending partnership.

These are required to identify the message destination.

<type>

Yes

A three-character code indicating the content type of the sent payload. The available codes are:

edi, for the content type application/EDIFACT.

x12, for the content type application/EDI-X12.

eco, for the content type application/edi-consent.

xml, for the content type application/XML.

bin, for the content type application/ octet-stream.

For other values, Hermes will assume the content type of the payload is application/deflate, which means that the payload is compressed by Zip.

Response message

The elements inside the SOAP body use the namespace URI http://service.as2.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <message_id xmlns="http://service.as2.edi.cecid.hku.hk/">[newly_created_message_Id]</message_id>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The <message_id> element is the identifier of the sent message that can be used for later reference and status tracking with Get message status web service.

REST [1]¶

Request message

$ curl -X POST --data '{  "as2_from": <as2_from>, "as2_to": <as2_to>, "type": <type>, "payload": <payload>}' http://<HOST>:<PORT>/corvus/api/message/send/as2

Response message

{
    "id": "<message_id>"
}

Note

To try the REST API, the simplest way is to use curl as a command line REST client, or Postman as a GUI based client is a useful tool too.

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

List received message ID¶

This web service is used by the application of the receiving party to retrieve message identifiers of received AS2 messages which have not been downloaded by the application. The message identifiers will be used to retrieve message payloads using Download received message payload web service.

SOAP¶

Service endpoint: http://<HERMES_HOST>:<HERMES_PORT>/corvus/httpd/as2/receiver_list

Request message

The elements in the SOAP body use the namespace URI http://service.as2.edi.cecid.hku.hk/.

A sample SOAP request is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <tns:as2_from xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[as2_from]</tns:as2_from>
        <tns:as2_to xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[as2_to]</tns:as2_to>
        <tns:numOfMessages xmlns:tns="http://service.ebms.edi.cecid.hku.hk/">[numOfMessages]</tns:numOfMessages>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The descriptions of the elements in the SOAP body are as follows:

Element Mandatory Description

<as2_from>, <as2_to>, <as2_to>

Yes

The values of the From and To fields in AS2 messages sent through the partnership by Hermes. These fields are used to identify the sending partnership.

These are required to query messages associated with the specified partnership.

<numOfMessages> No The maximum number of message identifiers retrieved by this request.

Response message

The elements inside the SOAP body use the namespace URI http://service.as2.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <messageIds xmlns="http://service.as2.edi.cecid.hku.hk/">
            <messageId>[downloadable_message_id]</messageId>
            <messageId>[downloadable_message_id]</messageId>
        </messageIds>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Each <downloadable_message_id> element in the response message represents the identifier of an AS2 message received by Hermes.

Please note that a message is considered to be downloaded only when the message body has been downloaded by Download received message payload SOAP web service. If your application never calls Download received message payload SOAP web service to download the messages, the same set of message identifiers will always be retrieved.

REST [1]¶

Request message

$ curl -X GET http://<HOST>:<PORT>/corvus/api/message/receive/as2?partnership_id=<partnership_id>

REST reponse message

{
    "message_ids": [
        {
            "id": "<message_id>",
            "timestamp": 1234567890,
            "status": "<status>"
        }
    ]
}

Please note that a message is considered to be downloaded when the message id is returned by this REST API call.

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

Download received message payload¶

This web service is used by the application of the receiving party to retrieve the message payloads of received AS2 messages. After the payloads have been downloaded, the message will be marked as received, and the message identifier of the message will no longer be retrieved by the AS2 receiver list service.

SOAP¶

Service endpoint: http://<HOST>:<PORT>/corvus/httpd/as2/receiver.

Request message

The elements in the SOAP body use the namespace URI http://service.as2.edi.cecid.hku.hk/.

A sample SOAP request is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <tns:messageId xmlns:tns="http://service.as2.edi.cecid.hku.hk/">[id_of_message_to_download]</tns:messageId>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Response message

The element inside the SOAP body is using namespace URI http://service.as2.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
     <SOAP-ENV:Header/>
     <SOAP-ENV:Body>
         <hasMessage xmlns="http://service.as2.edi.cecid.hku.hk/">[true_if_payload_in_message]</hasMessage>
     </SOAP-ENV:Body>
 </SOAP-ENV:Envelope>
.<!-- Attached payloads... -->

If a payload is associated with the message identifier, then <hasMessage> will have the value true. If the received AS2 message has payloads, the response message will have one or more SOAP attachments. Each SOAP attachment has a content type, which is set by the sender application.

Please note that a message is considered to be downloaded when the message is returned by this SOAP request.

REST [1]¶

Request message

$ curl -X POST --data '{"id":"<message_id"}' http://<HOST>:<PORT>/corvus/api/message/receive/as2

Response message

{
    "id": "<id>",
    "as2_from": "<as2_from>",
    "as2_to": "<as2_to>",
    "timestamp": 1234567890,
    "status": "<status>",
    "payloads": [
        {
            "payload": "<payload>"
        }
    ]
}

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

Get message status¶

This web service is used by the application of the sending party to retrieve the message status of a sent or received AS2 message respectively.

SOAP¶

Service endpoint: http://<HOST>:<PORT>/corvus/httpd/as2/status.

Request message

The elements in the SOAP body use the namespace URI http://service.as2.edi.cecid.hku.hk/.

A sample SOAP request is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <tns:messageId xmlns:tns="http://service.as2.edi.cecid.hku.hk/">[id_of_message_to_download]</tns:messageId>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Response message

The element <messageInfo> inside the SOAP body is using the namespace URI http://service.as2.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
    <SOAP-ENV:Header/>
    <SOAP-ENV:Body>
        <messageInfo xmlns="http://service.as2.edi.cecid.hku.hk/">
            <status>[status]</status>
            <statusDescription>[statusDescription]</statusDescription>
            <mdnMessageId>[mdnMessageId]</mdnMessageId>
            <mdnStatus>[mdnStatus]</mdnStatus>
            <mdnStatusDescription>[mdnStatusDescription]</mdnStatusDescription>
        </messageInfo>
    </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The descriptions of the elements in the SOAP body are as follows:

Element	Description
`<status>`	The current status of the AS2 message.
`<statusDescription>`	A text description of the current status.
`<mdnMessageId>`	The message identifier of the associated receipt (if any).
`<mdnStatus>`	The current status of the associated receipt.
`<mdnStatusDescription>`	A text description of the associated receipt.

REST [1]¶

Request message

$ curl -X GET http://<HOST>:<PORT>/corvus/api/message/send/as2?id=<message_id>

Response message

{
    "message_id": "<message_id>",
    "status": "<status>"
}

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

Query message with parameters¶

This web service is used by the application of the sending or receiving party to query messages according to specific parameters.

SOAP¶

Service endpoint: http://<HOST>:<PORT>/corvus/httpd/as2/msg_history

Request message

The elements in the SOAP body use the namespace URI http://service.as2.edi.cecid.hku.hk/.

A sample SOAP request is shown below:

<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
<SOAP-ENV:Header/>
<SOAP-ENV:Body>
<tns:messageBox xmlns:tns="http://service.as2.edi.cecid.hku.hk/">[Message_Box]</tns:messageBox>
<tns:status xmlns:tns="http://service.as2.edi.cecid.hku.hk/">[Message_Status]</tns:status>
<tns:messageId xmlns:tns="http://service.as2.edi.cecid.hku.hk/">[Message_Id]</tns:messageId>
<tns:as2From xmlns:tns="http://service.as2.edi.cecid.hku.hk/">[AS2_From_Party]</tns:as2From>
<tns:as2To xmlns:tns="http://service.as2.edi.cecid.hku.hk/">[AS2_To_Party]</tns:as2To>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Response message

The element <messageList> in the SOAP body uses the namespace URI http://service.as2.edi.cecid.hku.hk/.

A sample SOAP response is shown below:

 <SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">
     <SOAP-ENV:Header/>
     <SOAP-ENV:Body>
         <messageList xmlns="http://service.as2.edi.cecid.hku.hk/">
             <messageElement>
                 <messageId>[message_id]</messageId>
                 <messageBox>[message_box_containing_this_message] </messageBox>
             </messageElement>
             <messageElement>
                 <messageId>[message_id]</messageId>
                 <messageBox>[message_box_containing_this_message]</messageBox>
             </messageElement>
             <messageElement>...</messageElement>
             <messageElement>...</messageElement>
         </messageList>
     </SOAP-ENV:Body>
</SOAP-ENV:Envelope>

The descriptions of the elements in the SOAP body are as follows:

Element	Description
`<messageList>`	The list of retrieved message elements.
`<messageElement>`	A complex element containing the `messageId` and `messageBox` values of the retrieved message.
`<messageId>`	The message identifier of the retrieved message.
`<messageBox>`	The message box of the retrieved message.

REST [1]¶

Request message

$ curl -X GET http://<HOST>:<PORT>/corvus/api/message/history/as2?message_id=<message_id>&message_box=<message_box>&as2_from=<as2_from>&as2_to=<as2_to>&status=<status>&limit=<limit>

Response message

{
    "message_ids": [
        {
            "id": "<message_Id>",
            "as2_from": "<as2_from>",
            "as2_to": "<as2_to>",
            "message_box": "<message_box>",
            "timestamp": 1234567890,
            "status": "<status>"
        }
    ]
}

For the detailed specification of this REST API, please refer to HERMES RESTful OpenAPI Specification.

Add partnership¶

The AS2 Add Partnership web service is used by the application of the sending and receiving party to create partnership. For further details about AS2 partnership, please refer to Setting Up AS2 Partnerships.

REST [1]¶

Request message

$ curl -X POST -- data '{"id":"<partnership_id>", "as2_from":"<as2_from>", "as2_to":"<as2_to>", "disabled":<true/false>, "sync_reply": "string", "subject": <subject>, "recipient_address": <recipient_address>, "hostname_verified": <Yes/No>, "receipt_address": <receipt_address>, "receipt_requested": <Yes/No>, "outbound_sign_required": <Yes/No>, "outbound_encrypt_required": <Yes/No>,\
                         "outbound_compress_required": <Yes/No>, "receipt_sign_required": <Yes/No>, "inbound_sign_required": <Yes/No>, "inbound_encrypt_required": <Yes/No>, "retries": <no_of_retries>, "retry_interval": <retry_interval>, "sign_algorithm": <sha1/md5>, "encrypt_algorithm": <3des/rc2>, "mic_algorithm": <sha1/md5>, "encrypt_certicate": <cert_path>, "verify_certicate": <cert_path> }' \
  http://<SENDER_HOST>:<SENDER_PORT>/corvus/api/partnership/as2

Response message

{
    "id": "<partnership_id>"
}

Delete partnership¶

The AS2 delete Partnership web service is used by the application of the sending and receiving party to delete partnership.

REST [1]¶

Request message

$ curl -X DELETE http://<HOST>:<PORT>/corvus/api/partnership/as2/<partnership_id>

Response message

{
    "id": "<partnership_id>",
    "success": true
}

Update partnership¶

The ebMS update Partnership web service is used by the application of the sending and receiving party to update partnership. For further details about AS2 partnership, please refer to Setting Up AS2 Partnerships.

REST [1]¶

Request message

$ curl -X POST -- data '{"id":"<partnership_id>", "as2_from":"<as2_from>", "as2_to":"<as2_to>", "disabled":<true/false>, "sync_reply": "string", "subject": <subject>, "recipient_address": <recipient_address>, "hostname_verified": <Yes/No>, "receipt_address": <receipt_address>, "receipt_requested": <Yes/No>, "outbound_sign_required": <Yes/No>, "outbound_encrypt_required": <Yes/No>,\
                         "outbound_compress_required": <Yes/No>, "receipt_sign_required": <Yes/No>, "inbound_sign_required": <Yes/No>, "inbound_encrypt_required": <Yes/No>, "retries": <no_of_retries>, "retry_interval": <retry_interval>, "sign_algorithm": <sha1/md5>, "encrypt_algorithm": <3des/rc2>, "mic_algorithm": <sha1/md5>, "encrypt_certicate": <cert_path>, "verify_certicate": <cert_path> }' \
  http://<SENDER_HOST>:<SENDER_PORT>/corvus/api/partnership/as2

Response message

{
    "id": "<partnership_id>"
}

Get partnerships¶

The AS2 get Partnership web service is used by the application of the sending and receiving party to get all partnership details.

REST [1]¶

Request message

$ curl -X GET http://<HOST>:<PORT>/corvus/api/partnership/as2

Response message

{
    "partnerships": [
        {
            "id": "<partnership_id>",
            "as2_from": "<as2_from>",
            "as2_to": "<as2_to>",
            "disabled": true,
            "sync_reply": "<sync_reply>",
            "subject": "<subject>",
            "recipient_address": "<recipient_address>",
            "hostname_verified": "<yes_or_no>",
            "receipt_address": "<receipt_address>",
            "receipt_requested": "<yes_or_no>",
            "outbound_sign_required": "<yes_or_no>",
            "outbound_encrypt_required": "<yes_or_no>",
            "outbound_compress_required": "<yes_or_no>",
            "receipt_sign_required": "<yes_or_no>",
            "inbound_sign_required": "<yes_or_no>",
            "inbound_encrypt_required": "<yes_or_no>",
            "retries": 2,
            "retry_interval": 10,
            "sign_algorithm": "<sha1_or_md5>",
            "encrypt_algorithm": "<3des_or_rc2>",
            "mic_algorithm": "<sha1_or_md5>",
            "encrypt_certicate": "<cert_path>",
            "verify_certicate": "<cert_path>"
        }
    ]
}

[1]	(1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21)

Note

If error occurs when processing REST API request, it will return an error JSON response.
```
{
    "code": "<error code>",
    "message": "<error description>"
}
```

Error code and message¶

Error code Error Message

10000 ERROR_UNKNOWN

10001 ERROR_MISSING_REQUIRED_PARAMETER

10002 ERROR_PROTOCOL_UNSUPPORTED

10003 ERROR_READING_DATABASE

10004 ERROR_WRITING_DATABASE

10005 ERROR_READING_REQUEST

10006 ERROR_PARSING_REQUEST

10007 ERROR_RECORD_ALREADY_EXIST

10008 ERROR_DATA_NOT_FOUND

10009 ERROR_WRITING_MESSAGE

10010 ERROR_SENDING_MESSAGE

10011 ERROR_EXTRACTING_PAYLOAD_FROM_MESSAGE

10012 ERROR_UNKNOWN_ACTION

Using Hermes API¶

Introduction¶

Overview¶

ebMS 2.0 Web Service¶

Send message¶

SOAP¶

REST [1]¶

List received message ID¶

SOAP¶

REST [1]¶

Download received message payload¶

SOAP¶

REST [1]¶

Get message status¶

SOAP¶

REST [1]¶

Reset message status¶

SOAP¶

REST [1]¶

Query message with parameters¶

SOAP¶

REST [1]¶

Add partnership¶

REST [1]¶

Delete partnership¶

REST [1]¶

Update partnership¶

REST [1]¶

Get partnerships¶

REST [1]¶

AS2 Web Service¶

Send Message¶

SOAP¶

REST [1]¶

List received message ID¶

SOAP¶

REST [1]¶

Download received message payload¶

SOAP¶

REST [1]¶

Get message status¶

SOAP¶

REST [1]¶

Query message with parameters¶

SOAP¶

REST [1]¶

Add partnership¶

REST [1]¶

Delete partnership¶

REST [1]¶

Update partnership¶

REST [1]¶

Get partnerships¶

REST [1]¶

See also¶