Version 2.01
1 Introduction
1.1 Scope
The present document specifies the protocols and interfaces in order submit SMS and Emails between Government departments and the Notification Gateway.
1.2 Target Audience
The intended audience for this document are:
- Software Designers;
- Software Developers;
- API Developers.
1.3 Structure of this document
The document is organized as follows:
- Chapter 1 – Introduction presents the scope and the terminology used in the document;
- Chapter 2 – Describes the Message Specifications for the Notification Gateway;
2 Notification Gateway Message Specifications
2.1 Supported Message Patterns
The Notification Gateway supports only Synchronous exchange:
– In the synchronous exchange, the consuming client/service waits for a business response message from the Provider service.
2.2 Supported Message Types
The Notification Gateway supports the following message type:
- Simple Message: The e-Service should provide the submitted text
- Template Message: The e-Service should provide tokens and values that will be replaced in a pre-defined template configured in the Notification Gateway.
2.3 Message Specifications
2.3.1 Base URL
All REST API’s are served over HTTPS. To ensure data privacy, unencrypted HTTP is not supported.
All URLs referenced in the API documentation have the following base:
- https://{FQDN}/DITS.CeGG.DIS.Notifications/api/v1.0
The Production FQDN is: https://dis.gateway.local
The Test FQDN is: https://dis.dev.gateway.local
FQDN: A fully qualified domain name (FQDN) that identifies the connector host.
2.3.2 Swagger Specifications
Swagger specifications can be found in the following url:
- https://{FQDN}/swagger
2.3.3 Submit Simple Message
2.3.3.1 HTTP Request
To send a new simple message, make an HTTP POST to the following resource URL. Resource: https://{Base URL}/notification/simple-message
2.3.3.1.1 Authentication
HTTP request to REST API are protected with Basic authentication. In short, you will use your department notification account provided by the Gateway Team.
2.3.3.1.2 Payload
The payload must be a valid JSON object of type «Simple Message» as specified at section 2.4.1
2.3.3.2 HTTP Response
2.3.3.2.1 HTTP Headers
2.3.3.2.2 X-RequestID
The HTTP header is always returned. Contains the Message ID generated by the API. You may use this for troubleshooting.
2.3.3.2.3 Possible HTTP status Codes
HTTP Status | Description |
---|---|
200 OK | The request was successful. |
401 UNAUTHORIZED | The supplied credentials, if any, are not sufficient to access the resource. |
400 BAD REQUEST | Empty request body or not valid message or not valid JSON object. |
404 NOT FOUND | The server cannot find the requested resource. |
500 INTERNAL SERVER ERROR | Indicates that the server encountered an unexpected condition that prevented from fulfilling the request. |
2.3.3.2.4 Successful Response Format
When the HTTP Status Code is 200 ?? then the response body is a JSON object of
«SendMessageResponse» (see section 2.4).
2.3.3.2.5 Error Response Format
The REST API will return an «ErrorResponse» JSON object in the HTTP response body when something goes wrong.
2.3.4 Submit Template Message
2.3.4.1 HTTP Request
2.3.4.1.1 Authentication
HTTP request to this endpoint is protected with Basic authentication. In short, you will use your department notification account provided by the Gateway Team.
2.3.4.1.2 Payload
The payload must be a valid JSON object of type «Template Message» as specified at section 2.4.2
2.3.4.2 HTTP Response
2.3.4.2.1 HTTP Headers
2.3.4.2.2 X-RequestID
The HTTP header is always returned. Contains the Message ID generated by the API. You may use this for troubleshooting.
2.3.4.2.3 Possible HTTP status Codes
HTTP Status | Description |
---|---|
200 ?? | The request was successful. |
401 UNAUTHORIZED | The supplied credentials, if any, are not sufficient to access the resource. |
400 BAD REQUEST | Empty request body or not valid message or not valid JSON. |
404 NOT FOUND | The server cannot find the requested resource. |
500 INTERNAL SERVER ERROR | Indicates that the server encountered an unexpected condition that prevented from fulfilling the request. |
2.3.4.2.4 Successful Response Format
When the HTTP Status Code is 200 ?? then the response body is a JSON object of
«SendMessageResponse» (see section 2.4).
2.3.4.2.5 Error Response Format
The REST API will return an «ErrorResponse» JSON object in the HTTP response body when something goes wrong.
2.4 Message Data Structures
2.4.1 Simple Message
Element Name | Cardinality | Description | Type | Values |
---|---|---|---|---|
Subject | 0..1 | The subject of the message | an..500 | |
Body | 1..1 | The body of the message | an..4000 | |
Channel | 1..1 | Channel to use | Possible values: eMailSMS | |
Recipients | 1..n | List of recipients (email or phone numbers | string | |
Origin | 0..1 | The [from] address to use in case more than one is configured for your account (email or SMS Sender Id) | an..20 | |
Attachments | 0..n | List of email attachments | Attachment |
Note 1: The element «Subject» should not be set in case the message «channel» is
«SMS».
Note 2: The e-Service developer should consider the following for the body:
- One SMS message is 160 Latin characters.
- One SMS message is 70 Greek characters
Note 3: Attachments are only allowed in case the message channel» is «eMail».
2.4.2 Template Message
Element Name | Cardinality | Description | Type | Values |
---|---|---|---|---|
TemplateCode | 1..1 | Template code of the template to use | ||
TemplateLanguage | 1..1 | Language code of the template | Possible Values: ENEL | |
Tokens | 0..n | List of template parameters | ||
Channel | 1..1 | Channel to use | Possible Values: eMailSMS | |
Recipients | 1..n | List of recipients (emails or phone numbers) | string | |
Origin | 0..1 | The [from] address to use in case more than one is configured for your account (email or SMS Sender Id) | an..20 | |
Attachments | 0..n | List of email attachments | Attachment |
2.4.3 Attachment
Element Name | Cardinality | Description | Type | Values |
---|---|---|---|---|
Name | 1..1 | Name of the Attachment | an..100 | |
Content | 1..1 | Base-64 encoded string of the content types | an |
2.4.4 Message Token
Element Name | Cardinality | Description | Type | Values |
---|---|---|---|---|
Name | 1..1 | The Name of the template parameter | an..20 | |
Value | 1..1 | The Value of the template parameter | an..250 |
2.4.5 SendMessageResponse
Element Name | Cardinality | Description | Type | Values |
---|---|---|---|---|
MessageId | 0..1 | Response message id | an..20 |
2.4.6 ErrorResponse
Element Name | Cardinality | Description | Type | Values |
---|---|---|---|---|
Description | 1..1 | The Error Message | an..250 | |
Number | 1..1 | The Error Code | n..10 |