Get notifications and events

The notification service provides methods for retrieving information about asynchronous events related to your documents.

Important:

This service is currently available only in Italy.

The notification service lets you query and retrieve events that occur asynchronously during document processing. These events are organized into categories and subcategories.

Event categories

The only supported category is SdiEvent.

For the SdiEvent category, the supported subcategories are the following:

FailedDeliveryNotice
RejectionNotice
OutcomeNotice
DeliveryReceipt
FailedDeliveryAttestation
InvoiceReceipt
DeadlinePassedNotice
InvoiceUnwrapped

How it works

The workflow for working with events has two steps:

Query the notification service to search for events that match your criteria. The query returns a list of matching results, each with metadata and a link.
Use the link returned in each result to retrieve the full event details in JSON format.

Inbound and outbound workflows

Event queries behave differently depending on the workflow:

For inbound workflows, use RecipientId to filter results by the recipient associated with the transaction.
For outbound workflows, don't provide a RecipientId. Providing one returns an empty result set.

Service operation and authentication

Operation: The notification service exposes a single port: NotificationServicePort. This port uses text encoding, so the Message Transmission Optimization Mechanism (MTOM) is not used. The operation address is provided during onboarding.
Authentication: All requests to the notification service require Transport Layer Security (TLS) client certificate authentication. Use the same certificate that has access to the storage area used for the Query call. This requirement applies to both the Query operation and to the HTTPS GET request used to retrieve event details from the URL returned in each QueryResult.
Encoding: The notification service uses text encoding for all messages. Don't enable MTOM for requests to this port.

Query events through the API

You must have a valid client certificate and access to the NotificationServicePort operation. The operation's address is provided during onboarding.

The Query operation searches for events that match the criteria you specify. Each result includes metadata and a link you can use to retrieve the full event details.

Build a QueryRequest with the following elements:

Request type tns:QueryRequest extends tac:TrustArchiveRequest


Parameter	Type	Cardinality	Description
Category	xs:string	1	The category of the events. The only currently supported value is `SdiEvent`.
SubCategories	tns:SubCategories	1	One or more subcategories for filtering purposes. The set of possible values depends on the category. See Notifications and events for the list of supported subcategories.
SubCategory	xs:string	0..n	Each individual subcategory to include in the query.
NotBefore	xs:dateTime	1	Exclusive lower bound of the event time range.
NotAfter	xs:dateTime	1	Inclusive upper bound of the event time range.
IncludeRetrieved	xs:Boolean	1	Use `true` to include both retrieved and non-retrieved events. Use `false` to return only non-retrieved events.
RecipientId	xs:string	1	The recipient ID associated with the transaction. Applicable only for inbound workflows. For outbound workflows, providing this value returns an empty result set.

Send the request to the NotificationServicePort operation.
Example request:
XML
<?xml version="1.0" encoding="utf-8"?> <QueryRequest xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1" xmlns:i="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://www.trustweaver.com/trustarchive/notification/v1"> <tac:TransactionId>abae2...</tac:TransactionId> <Category>SdiEvent</Category> <SubCategories> <SubCategory>InvoiceReceipt</SubCategory> </SubCategories> <NotBefore>2018-05-21T13:10:32.1299777+02:00</NotBefore> <NotAfter>2019-07-20T13:10:32.126985+02:00</NotAfter> </QueryRequest>
```
<?xml version="1.0" encoding="utf-8"?>
<QueryRequest
  xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1"
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://www.trustweaver.com/trustarchive/notification/v1">
  <tac:TransactionId>abae2...</tac:TransactionId>
  <Category>SdiEvent</Category>
  <SubCategories>
    <SubCategory>InvoiceReceipt</SubCategory>
  </SubCategories>
  <NotBefore>2018-05-21T13:10:32.1299777+02:00</NotBefore>
  <NotAfter>2019-07-20T13:10:32.126985+02:00</NotAfter>
</QueryRequest>
```
Process the QueryResults response.

The response contains zero or more QueryResult elements. Each element includes a Metadata field and a Url you can use to retrieve full event details.

See Retrieve event details for instructions on using the returned link.

The service returns a QueryResults collection. If no events match the criteria, the collection is empty.

Retrieve event details

Query output structure

Each QueryResult returned by the Query operation contains the following elements:

Result type: tns:QueryResults


Element	Type	Cardinality	Description
QueryResults	tns:QueryResults	1	A collection of `QueryResult` elements.
QueryResult	tns:QueryResult	0..n	Each individual result that matches the query criteria, or an empty collection if there are no matches.
SubCategory	xs:string	1	The subcategory for this result. Always one of the subcategories specified in the Query request.
Metadata	xs:string	1	Event metadata in JSON format. The exact format depends on the category and subcategory.
Url	xs:string	1	A link for retrieving the complete event data in JSON format. Requires Transport Layer Security (TLS) client certificate authentication using a certificate that has access to the same area as the one used for the Query call.

Metadata format for SdiEvent

For the SdiEvent category, the Metadata JSON object contains the following keys:

SdiId
FileName
MetadataFileName
NotificationTime

Retrieve event data

To retrieve the complete event data, send an HTTPS GET request to the Url returned in the QueryResult. Authenticate using TLS client certificate authentication with a certificate that has access to the same storage area used for the Query call.

The response is a JSON document. The format of the JSON depends on the event category and subcategory.

Example query response

XML

<?xml version="1.0" encoding="utf-8"?>
<QueryResults
  xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1"
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://www.trustweaver.com/trustarchive/notification/v1">
  <QueryResult>
    <SubCategory>InvoiceReceipt</SubCategory>
    <Metadata>
      {"SdiId":"202","FileName":"filename_00002.xml",
      "MetadataFileName":"filename_00002_MT_001.xml",
      "NotificationTime":"2019-05-21T11:13:41.85941"}
    </Metadata>
    <Url>https://localhost/ta_hubservices/SdiEvent.ashx?Id=1</Url>
  </QueryResult>
</QueryResults>

<?xml version="1.0" encoding="utf-8"?>
<QueryResults
  xmlns:tac="http://www.trustweaver.com/trustarchive/common/v1"
  xmlns:i="http://www.w3.org/2001/XMLSchema-instance"
  xmlns="http://www.trustweaver.com/trustarchive/notification/v1">
  <QueryResult>
    <SubCategory>InvoiceReceipt</SubCategory>
    <Metadata>
      {"SdiId":"202","FileName":"filename_00002.xml",
      "MetadataFileName":"filename_00002_MT_001.xml",
      "NotificationTime":"2019-05-21T11:13:41.85941"}
    </Metadata>
    <Url>https://localhost/ta_hubservices/SdiEvent.ashx?Id=1</Url>
  </QueryResult>
</QueryResults>

e-invoicing