Publications happen through the
/publishMessage method of the e-Box RESTful API.
This method uses a multipart HTTP POST to send up to 6 documents attached to an e-Box Message.
The API fully supports end to end streaming.
Minimal publication example
Note: The examples in the documentation follows the API 2.6 but a new API 3.0 is available. We advise new clients to follow the 3.0 API.
The following is pretty much the simplest publication request that can be made. It is comprised of the following HTTP parts:
messageToPublish: This part contains the meta information of the message.
"fr": "Message example title"
upfile1: This part MUST contain the binary and basic meta information of the document. It is a standard HTTP binary file upload part which needs to specify the following information:
- data stream: the raw data of the content
- filename: the file name of the document
- Note: The filename must be encoded if it contains characters outside of the ISO-8859-1 charset (so french accents etc).
- Content-Type: the MIME type of the document
Content-Disposition: form-data; name="upfile1
upfile1 part and the extra meta information of the document are linked together through
"httpPartName": "upfile1" in the
Provided that the request is correct, one can expect a
201 status code to be issued with our without an additional information
code in the JSON response body.
NO_DIGITAL_USER response code
This code allows the Document Sender to know that the publication was to a recipient that never opened his e-Box. This is the preferred method for a Sender to determine if the User uses his e-Box or not. An alternative to this is to use the e-Box Federation WS but this requires to integrate with another web service and does not fit the "e-Box First" philosophy we are trying to push.
For the attention of
If the publication is for the attention of a particular person, a
ForTheAttentionOf object has to be added in the
"name": "John Doe"
type is used to determine if the attention is for a person or a group of people. For the moment, only
"person" is suported. The
id property is the National Register Number.
Minimal publication example for a citizen
If the recipient is a citizen, the example below shows a minimal publication.
"fr": "Message de test"
The difference is in the
recipient object. The
citizen and the
eboxIdValue is the recipient SSIN.
Also you cannot use a
messageTypeId and a
senderApplicationId that are configured only for enterprise-to-enterprise publications.
Please note that only PDF files work properly for e-Box web application used by citizens.
Getting an Oauth Token for publication
The Cookbook OAuth V5 introduces OAuth and explains how a token can be retrieved.
You can also see the oauth introspect example for a java example on how to retrieve an OAuth token.
You have to request your AccessToken to the Authorization Server.
GetAccessTokenV4.getAccessToken() method is the one responsible of getting the token.
The scope needed to publish message is
|OAuth Authorization Server URL (ACC)||https://services-acpt.socialsecurity.be/REST/oauth/v5/token|
|OAuth Authorization Server URL (PRD)||https://services.socialsecurity.be/REST/oauth/v5/token|
Getting a token requires having cleared the OAuth part of the onboarding. If it is not done yet, see the Document Sender onboarding process.
Once you have got your token, you can call a method using one of these endpoints:
|Environment||Endpoint e-Box enterprise|
End to end Streaming Considerations
The order of HTTP parts is arbitrary, each part being linked to its associated meta-data by the
httpPartName property of the publication payload. This allows for end to end streaming on the Document Sender side. See the Publication Profile Documentation for more information.
Examples with Postman
If you use Postman, you might be interested in a Postman publication examples collection. After importing that collection,
- Paste your token in the Authorization tab in the menu to edit the collection,
- Replace the
upfile6in the body of the requests with a file in your desktop,
messageTypeIdwith what you are authorized to use,
- Set the variable
EndpointEnterpriseMessageRegistryV2with the corresponding endpoint as value, terminating with a slash.
Our implementation choices
There are some restrictions in our implementation of the service:
- We do not support publication with several languages. Only one among
dehas to be selected in a publication request for the subject, attachment title, body content and business data values.
- We do not support the
attachmentTitleproperty in the
AttachmentToPublishobject. The attachment title will be the file name of the uploaded file.
/linkEboxMessagefeature is not implemented but the broadcast feature still available by asking the procedure to eBoxIntegration@smals.be.
- We do not support dynamic expiration date. That is to say, in the API about the
expirationDateproperty is ignored. The expiration date will be calculated from the current date plus the validity period defined for the message type. You can see the
validityPeriodby doing a GET on
- The business data put in a
messageToPublishcan only be those defined for the message type created during the Onboarding process.
messageToPublishobject is only supported in the case of a reply. The value to put is the ID of the message to reply.
- We do not accept null values. If a property has to be null, like
"registeredMail": null, the equivalent we accept is to not put that property.
- We do not support payment data.
- Only one main content is accepted. That is to say, either bodyMainContent is true or one (and only one) of the mainContent is true.
There is also a maximum length on some strings in a publication request:
subjectlength is 400 characters maximum.
- The file name of uploaded files are 255 characters maximum.
- The value given to business data are 256 characters maximum.
forTheAttentionOfobject is 100 characters maximum.