e-Boks channel

e-Boks

e-Boks is a secure digital mailbox which can be used by private individuals to receive electronic mail from private and public sector senders. 

There are a number of things that a sender must decide before being able to distribute documents to eBoks. These primarily relate to how the sender is presented in e-Boks and whether mandatory or user-managed (voluntary) registration for documents should be used. The Nets sales representative or the support team can help make a decision on which type of subscription in e-Boks is best for your company.

The functionalities available in e-Boks via Nets Share are described below.

​Addressing the recipient

There are two ways of addressing documents for distribution to e-Boks. Using either the personal identification number or an alias solution. 

Using the personal identification number requires the sender to follow current legal guidelines for the processing of personal information.

​​​Addressing documents using the personal identification number

Documents are addressed using a personal identification number and country code as address criteria in the shipment.xml.

Documents addressed from the sender will then be checked by Nets against a summary (subscription list) of users who have registered to receive documents in e-Boks. If the user cannot be found in the summary, the document will proceed to the next channel specified or in standard sequential order. Alternatively, the sender can send the document as "mandatory", which means it will be delivered in e-Boks regardless of the recipient having subscribed to the sender, or having logged into e-Boks yet.

Personal identification number supported formats:

The below format is the one to be used in the shipment.xml, if any other characters (e.g. a dash "-")  are added to the below, the shipment will be rejected due to incorrect formatting.

DK: DDMMYYXXXX
example: 0710881234
NO: DDMMYYXXXXX
example: 07108812345
SE: YYYYMMDDXXXX
example: 198810071234

​​Addressing documents using an alias solution

Senders who do not have the option of using a personal identification number for addressing in e-Boks may use an alias solution. This involves using two values (alias 1 and alias 2) which the recipient enters when registering for the document group. 

The sender decides which values to use as alias 1 and alias 2 based on the information held in the system. Registration requires both values while the shipment.xml itself will only use alias 1. Alias 1 is therefore an address key, which, in conjunction with the document type, must uniquely identify the e-Boks recipient.
The alias solution is described in detail further below. 

​Functionality for e-Boks distribution

A number of functions are available to the sender when distributing to e-Boks. Some of the functions may be managed in the shipment.xml. The available functions are:

• Publication date. Documents are made available to the recipient on a given date. Can be indicated in the XML.

• Document description. Free text element for further description of the document. Can be indicated in the XML.

• Pre-approval/Mandatory. The document recipient does not have e-Boks, or has not subscribed to the Sender, but has accepted distribution of given documents to e-Boks e.g. when accepting the terms and conditions of doing business with the sender. The document recipient must register for e-Boks to view the documents. This is agreed and configured in the system with a specific material ID.

• Attachments. Attachments which are to be included in the document must be referred in the shipment by using the correct tag. There is a limit of variations of attachments that can be predefinded in e-Boks. During distribution there can be maximum 8 attachments to one document that is distributed. ​

​e-Signing in e-Boks

 Description:

Through the channel e-Boks, a recipient can perform an electronic signing of a document, if the document is marked for it in Nets Share by the sender. It is possible to sign the document with a supported electronic signature in e-Boks (e.g. BankID or NemID).

It is determined if a document is distributed for signing by the "eboks:type". It is necessary to have setup an agreement with e-Boks regarding signing, determining which eboks:type's, and conditions you wish to use for signing, before sending the first document for signing.

Conditions of an eboks:type for signing can e.g. be 3 days time-out if not signed, meaning that the document in this example, is only available for signing for three days.

If the document is marked for signing e-Boks will start the e-Signing process for the document automatically upon receipt.

How to:

When a document is sent for signing and signed by the customer, you will receive a zipped return file in the Outbound SFTP mailbox containing the signed document as an SDO (Signed Digital Object) and a receipt. We send 1 zip file for each signed document where the name of the zip is: signed_documents_<date>_<messageid>.zip

e-Boks sends the return "retursvar" file once a day and Nets-share processes the return file and sends the zip file back the customer straight away.

Sample files for reference can be found in the Example package​ or in Get Started – Step 1

There are 2 types of reject reasons:

• ​REJECTED_BY_SIGNER 
  If the document is rejected by the signer, the receipt can include a reason text in the tag <reasonText/>
  
  
• PASSED_DEADLINE 
  In case the receiver has not signed the document within the given deadline of the eboks:type. 
  If the signing is rejected due to passed deadline, then the <responseDate> is the date where Nets-share processed the return file from e-Boks (we do not receive a date from e-Boks in this case)
  

See examples of the above under Get Started Step 1

Conditions: 

The PDF must follow the whitelist guideline from NemID regarding layout, documentation and validation test program can be provided upon request.

The main condition is that the maximum size of a document for digital signing is kept within the below limits, and fonts not supported must be embedded in the PDF, along with no active links; mailto, url's or alike.
We recomment that all fonts are subset embedded to support all current and future channels.

​Multi signing in e-Boks

It is possible for a sender to require multiple signees on the same document distributed in e-Boks. It can be used in the case of a contract or similar, where more than one signature is required. The document will only be valid returned if all the required signees have signed within the preagreed timeframe in the <documentType>. (The timeframe for signing is setup uppon the senders request by e-Boks when creating a new documentType and can only be altered via the support team at Nets)

When the document for multiple singing has been created, all recipients will be able to sign it via their eBoks independently. It has therefore no significance which order they have been placed in the shipment. Please note that the signees will individually not be able to see who else has or is supposed to sign the document, but only that they can sign it or already have done so.

How to:

A document distributed for multiple signing must use a <documentType> set up for signing by e-Boks.

If the document needs to be signed by more than one person, this should be addressed in the shipment.xml. The extra users besides the one mentioned in <eboks:receiver> must be placed in the (<eboks:config<eboks:signers<eboks:danishSigner) – one signer for each extra receiver who is required to sign the document.

It is a prerequisite that all signees of the documents must have agreed in advance to accept documents in e-Boks from the given sender, or the sender has to send the document as Mandatory. In case the sender is not using mandatory delivery the shipment is validated against the "subscription list" (tilmeldingsliste).  All signees must sign the document before it is automatically returned to the sender. If one signee rejects or does not sign within the time limit or for other reasons reject the document, the signing process is rejected. Nets-share sends the result of the signing process back to the sender/customer in a zip file to the same mailbox, as described in Signing in e-Boks. The only difference with multiple signing is that in a completed signing the returned SDO will include the extra number of signatures instead of only one.

Sample of adding extra signers to the document is viewable in the example package. 

Conditions:

• Same conditions as single signing

• Each signee must be registered to receive digital documents from the given sender in e-Boks unless the document is sent as Mandatory

• There is a maximum of 9 signees in multiple signing.

​Attention format (P-nummer)

Description:

Attention is the possibility to distribute a message to a particular department, production site (P-nummer) etc. within an organization, hence an attention will always follow a CVR/Org. number.

Attention is here referred to as "Production unit identifier".

How to:

Nets-share does not validate these types within e-Boks. The values are only validated against the XSD. If e-Boks is unable to distribute to these "attentions" the message is sent to main mailbox of the CVR/Org. number of the receiver.

Use of Attention-format is therefore often a bilateral agreement between sender and receiver.

The receiver must contact e-Boks for support regarding setup of various sub- catalogues on e.g. P numbers within a shared CVR e-Boks.

Below is a sample of the xml from the example package:

    <!-- message to eBoks, cvr + attention pNumber -->
    <message id="1">
      <sender>
        <eboks:eboksId>15723</eboks:eboksId>
      </sender>
      <eboks:receiver>
        <eboks:danishOrganisation cvr="12345678">
          <eboks:productionUnitIdentifier>1234567890</eboks:productionUnitIdentifier>
        </eboks:danishOrganisation>
        <eboks:country>DK</eboks:country>
      </eboks:receiver>
      <document>
<documentType>162812</documentType>
        <filepath>document1.pdf</filepath>
        <attachment path="attachment_002.pdf">
<eboks:attachmentDescription>folgebrev2</eboks:attachmentDescription>
</attachment>
      </document>
    </message>

​​​​«message to eBoks, cvr + attention P number»

​​Subscription lists

Nets offers senders the option of receiving lists of recipients registered in their registration groups in eBoks. Via the Subscription list, the sender is able to see which of their customers are already available on the e-Boks channel. 

If this functionality is required, a complete list containing all subscriptions (for the sender) is made available in the mailbox at 2 p.m. daily. The file will be uploaded to the Outbound directory with a filename in the following format: 

[ORG]eboks_subscribers[DATE]_[running number].xml 

11223344556_eboks_subscribers_2016-05-05_1.xml

The file contains information about:

• The recipient's personal identification number or alias number

• Registered document type (6 digit number)

• Whether it is Norwegian, Swedish or Danish e-Boks

• The e-Boks id (customer number) the subscription list applies to. (5 digit number)
  
  See Get Started - Step 1 for an example of a subscription list, and below for the A​lias​ solution. ​

Alias sol​​ution for dispatch addressing

Senders who do not have the option of using a personal identification number for addressing in e-Boks may use an alias solution. This involves using two values (alias 1 and alias 2) which the recipient enters when registering for the document group. 

The sender decides which values to use as alias 1 and alias 2 based on the information held in the system. Registration requires both values while the dispatch itself will only use alias 1. Alias 1 is therefore an address key, which, in conjunction with the document type, must uniquely identify the e-Boks recipient.

General process

The recipient wishes to register for a document group using an alias solution. The recipient then receives a message to enter two information fields in e-Boks (see below).

As can be seen from the solution outline below, alias 1 and alias 2 are sent to Nets, which then calls a sender web service. The web service states whether the combination the user has entered is valid.

«Aliases in e-Boks (In this case alias1 is customer number and alias2 in a electricity ​meter related number)»​

If the combination is valid, the user will be registered in the document group. The sender will receive a message stating that the recipient is available as a recipient via standard registration lists. If the combination is not valid, the recipient will be informed of this.

Choosing alias keys

When choosing the alias solutions, the following is important:

• Alias1, is used for address purposes. This must be unique to each recipient (typically customer number) and cannot be changed even if the customer moves, changes subscription etc.

• Alias2 is used for registering a new customer to verify that the user has been approved to receive messages. No one should be able to guess the combination of alias 1 and alias 2. Alias 2 should therefore be something more 'secret' than alias 1, e.g. a code or information that can be found on a paper invoice or similar.
  
  Both alias 1 and alias 2 should be terms known to the message recipient.
  
  The alias 1 and alias 2 fields are limited to 1 to 50 characters which must be alphanumeric.

​The sender must implement web service to query alias parameter

The solution works as follows: every time an e-Boks recipient registers for a document type which is addressed using an alias, a web service is called (in real-time), which indicates whether the information entered is a valid alias. 

This requires that the sender has provided a web service that Nets Share can query for validation of the values. So to use alias integration with e-Boks via Nets Share, the document sender must implement a web service that Nets Share can query using SSL for every alias registration.

Request

Nets sends the following query to the client web service: ([…]replace with customer-specific information) https://HOST/RESOURCE?document_group=[group]&field1_id=[name1]&field_value=[value1]&field2_id=[ name2]&field2_value=[value2]

Where HOST is replaced by a customer-specific host and RESOURCE is an optional name for the service. The query parameters are described in Table 1.​

Table 1. Key to query parameters

Response

As a response, an http response code is expected = '200' and one of the return values from table (below) as the only body content.

Table 2. Response from the client web service which is forwarded to the e-Boks user.

Security

To ensure security, communication must take place over SSL with both valid server and client certificates.