Initial setup
The client library is available as a nuget package. The client library (and associated nuget package) is updated regularly as new functionality is added.
To install the nuget package, follow these steps in Visual Studio:
- Select TOOLS -> nuget Package Manager -> Manage nuget Packages Solution…
- Search for “digipost-api-client”
- If you would like pre-releases og this package, make sure it says Include Prerelease in the drop-down menu above the search results (where it by default says Stable Only).
- Select digipost-api-client and click Install.
Install business certificate in certificate store
SSL Certificates are small data files that digitally bind a cryptographic key to an organization's details. When installed on a web server, it activates the padlock and the https protocol (over port 443) and allows secure connections from a web server to a browser.
To communicate over HTTPS you need to sign your request with a business certificate. The following steps will install the certificate in the your certificate store. This should be done on the server where your application will run.
- Double-click on the actual certificate file (CertificateName.p12)
- Save the sertificate in Current User and click Next
- USe the suggested filename. Click Next
- Enter password for private key and select Mark this key as exportable … Click Next
- Select Automatically select the certificate store based on the type of certificate
- Click Next and Finish
- Accept the certificate if prompted.
- When prompted that the import was successful, click Ok.
Use business certificate thumbprint
- Start mmc.exe (Click windowsbutton and type mmc.exe)
- Choose File -> Add/Remove Snap-in…(Ctrl + M)
- Mark certificate and click Add >
- Choose ‘My user account’ followed by Finish, then ‘OK’.
- Double-click on ‘Certificates’
- Double-click on the installed certificate
- Go to the ‘Details’ tab
- Scroll down to ‘Thumbprint’
- Copy the thumbprint.
Client configuration
ClientConfig is a container for all the connection specific paramters that you can set. All attributes, except TechnicalSenderID, have default values. The technical sender id is a required parameter to contstruct the class.
Use cases
Send one letter to recipient via personal identification number
Send one letter to recipient via name and address
Send one letter with multiple attachments
Send letter with SMS notification
Send letter with fallback to print
In cases where the recipient is not a Digipost user, it is also possible to use the recipient’s name and address for physical mail delivery.
Send letter with higher security level
Identify user by personal identification number
Send letter through Norsk Helsenett
The Digipost API is accessible from both internet and Norsk Helsenett (NHN). Both entry points use the same API, the only difference is the base URL.
Handling responses
The client library will return the most important status codes and the raw xml response.
- StatusMessage is the status of the messages.
- DeliveryTime is the time the digital mail was delivered. This will be set with 01/01/0001 00:00:00) if the message had errors.
- DelimeryMethod is the channel through which the message was delivered. This is either DIGIPOST for digital mail or PRINT for physical mail.
- ErrorCode is populated if relevant.
- ErrorType is the type of error.
- ResponseMessage is the the raw XML of the respnse.
Example of a response where the recipient is not a Digipost user:
Response objects
The client library returns appropiate response objects for relevant methods.
Identify response
IdentificationResult.cs is populated by three properties:
- IdentificationResultCode , wich describes if the recipient is either identified, unidentified, invalid or an digipost-customer.
- IdentificationType is in wich type Digipost will return the identification.
- IdentificationValue is the value of the IdentificationType.
An example of response could be:
IdentificationResultCode = Digipost
IdentificationType = Digipostaddress
IdentificationValue = johnny.test#1234
Example of a response where the letter has been delivered as digital mail:
Send message response
MessageDeliveryResult.cs is populated by six properties:
- Deliverymethod is either digital or physical, where Print is physical and Digipost is digital.
- Status is the status of the message in the delivery prosess. See MessageStatus.cs for more information.
- Deliverytime is the time the message was delivered to the recipient.
- Primarydocument is a copy of the document that was sent in, except for the actual byte content.
- Attachment is an list of the attachments that was sent inn, except for the actual byte content.
- Link is possible links/actions from here. In idempotent methods, this will return blank.
An example of response could be:
Logging
The need for application logging varies from project to project. The client library exposes the ability to set a separate log function on the ClientConfig object. ClientConfig.Logger
can be set to a Action<TraceEventType, Guid?, String, String>
, where TraceEventType
is the type of log message is and Guid
is Id of the message. The penultimate parameter is the method in which was logged, and the final parameter is the actual message.
Following is an example:
The following will log all messages sent an received.
Error Handling
Synchronous error handling
If you are communicating synchronously, the errors will be wrapped in an AggregateException
. This is because a set of errors may have occured before the result is received. You can handle each exception within the aggregate by sending in an anonymous function to AggregateException.Handle()
:
Asynchronous error handling
If you are using methods in the client library that has async
in the name, it means that you are communicating asynchronously.
To correctly identify errors that might happen, for example during sending a message, you can catch errors like you normally would in an application:
Asynchronous communication with Digipost using the client library involves using methods with async in method name, like IdentifyAsync.