Using Hermes API

Introduction

Hermes has implemented web services to communicate with external applications. The main advantages of using web services are to reduce coupling between external applications and Hermes, and to allow external applications to integrate Hermes seamlessly using any programming languages that support sending SOAP Messages with Attachments or calling RESTful APIs. This article helps developers write a client talking to Hermes using web services based on SOAP or RESTful APIs.

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

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.

_images/h2o-ws-pl-free.png

Overview

Here is a brief summary about the communication architecture between Hermes and external applications. The core of Hermes can attach to 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.

_images/ws-archtecture.png

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 is a useful tool too.
  • 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

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.

_images/h2o-ws-sender-ebms.png

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 details 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 details 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.

_images/h2o-ws-recv.png

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 details 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 details 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 details 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.

_images/MessageHistory.png

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 details 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.

_images/h2o-ws-sender-as2.png

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 details 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 details 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.

_images/h2o-ws-recv.png

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 details 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 details 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.

_images/MessageHistory.png

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 details 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