Migration from SOAP to REST

If your application already publishes messages to e-Box using the SOAP EBoxMessage web service, you are required to migrate to the REST e-Box publication web service. The EBoxMessage SOAP web service will no longer be supported soon. See the How to become a Document Sender page to start reading the technical documentation. You don't need to do an onboarding since you are already known as a Document Sender. However, we still need to do the OAuth configuration in order to provide needed scopes to your application.

You can reuse the certificates used for SOAP. If you want to reuse them, please send the public part of the certificate used in acceptance and production environment to eBoxIntegration@smals.be in order to perform the OAuth configuration. In the mail, please specify if you want to use the eboxPreferences/search functionality because it needs an additional OAuth scope.

If you want a new certificate, you will need a X.509 certificate. Any official issuer is acceptable for REST web service and self-signed certificates are accepted too. Please pay attention to respect the expected format. You can send your Certificate Signing Request to us for validation before the order. It’s also important to have a distinct certificate for each work environment (Acceptance, Production). Once you receive your order, send the public part of the certificate to eBoxIntegration.

REST counterpart to SOAP features

SOAP functionality	counterpart in REST
Publish messages	The ebox Message Registry is the new web service to use for message publication.
QualityCode	The recipient's quality or ebox type is replaced by the eboxType property in the EboxId object in the REST API for citizen and enterprise recipients. For other qualities, see the sections below.
Annexes	The annex feature is replaced by the mainContent feature. You can see in the Message Registry API that the attachments property is a list of documents to attach to the message. One of them has to have the mainContent boolean set to true. The other attachments must have the mainContent set to false and therefore, they are annexes. The difference between the main document and annexes is that the message is flagged as read if the main document is downloaded by the recipient.
Metadata	What is called metadata or Meta in SOAP request is called businessData in a REST publication request. Please refer to the Message Registry API to know how to put them in your request.
hasAnEbox	The eboxPreferences/search functionality in the e-Box Federation web service provides the same info given by the hasAnEbox SOAP feature. If you use it just to know if the recipient has consulted his e-Box, you can also refer to the code returned after a successful publication. See the NO_DIGITAL_USER code.
getMessageStatus	searchMessageStatus in the Message Registry API.
healthCheck	The healthCheck in REST does not require OAuth authentication. The URL is https://services-acpt.socialsecurity.be/REST/ebox/enterprise/messageRegistry/v2/api/healthCheck in Acceptance environment and https://services.socialsecurity.be/REST/ebox/enterprise/messageRegistry/v2/api/healthCheck in production.
getEboxInfo	There is no counterpart in REST.
CitizenProfile	The citizenEboxConsents/search functionality in the e-Box Federation web service
RegisteredMail	There is no counterpart in REST but RegisteredMail is not concerned by the migration. You can still use it.

REST e-Box publication for qualities

This section is only for senders in the Social Security domain as they may send messages to recipients with different qualities.

For employers and companies

The quality codes QUAL_EMP_NOSS, QUAL_EMP_NOSSPLA and QUAL_COMPANY are all enterprise quality codes. In a REST request to send a message to these qualities, you must put enterprise as value for the eboxType property. Example:

messageToPublish:{
     "sender":{
       "eboxType":"enterprise",
       "enterpriseNumber":"0123456789"
     },
     "recipient":{
       "eboxType":"enterprise",
       "enterpriseNumber":"0123456798"
     },
     "subject":{
       "fr":"Example request to publish for an enterprise"
     },
     "messageTypeId":"testMessageType",
     "senderApplicationId":"testApplicationId",
     "attachments":[
       {
         "httpPartName":"upfile1",
         "isMainContent":true,
         "isAttachmentSigned":false
       }
     ],
     "isReplyAuthorized":false
   }

For citizens

In a REST request to send a message to these qualities, you must put citizen as value for the eboxType property. Example:

messageToPublish:{
     "sender":{
       "eboxType":"enterprise",
       "enterpriseNumber":"0123456789"
     },
     "recipient":{
       "eboxType":"citizen",
       "ssin":"01234567890"
     },
     "subject":{
       "fr":"Example request to publish for a citizen"
     },
     "messageTypeId":"testMessageType",
     "senderApplicationId":"testApplicationId",
     "attachments":[
       {
         "httpPartName":"upfile1",
         "isMainContent":true,
         "isAttachmentSigned":false
       }
     ],
     "isReplyAuthorized":false
   }

Please note that only PDF files work properly for e-Box web application used by citizens.

For Professional personal

The quality code PROFESSIONAL means a professional quality identified by its SSIN number. To publish to a professional, the value for the eboxType property is citizen and the partition property must have the value QUAL_PROFESSIONAL. In this way, the message is not sent to a professional partition but is sent to the actual professional e-Box. It is not published to an enterprise e-Box. Request example :

messageToPublish:{
     "sender":{
       "eboxType":"enterprise",
       "enterpriseNumber":"0123456798"
     },
     "recipient":{
       "eboxType":"citizen",
       "ssin":"01234567890",
       "partition":"QUAL_PROFESSIONAL"
     },
     "subject":{
       "fr":"Example request to publish for PROFESSIONAL REST request"
     },
     "messageTypeId":"testMessageType",
     "senderApplicationId":"testApplicationId",
     "attachments":[
       {
         "httpPartName":"upfile1",
         "isMainContent":true,
         "isAttachmentSigned":false
       }
     ],
     "isReplyAuthorized":false
   }

If there are several attachments to the message, it is advised to put an attachmentTitle to attachments that are not main content. It will display a correct annex name in the GUI version used by professionals. You still have to not put an attachmentTitle for the main content.

For curator

The curator quality code is QUAL_CUR. The steps to publish to curators are the same as professional. See the subsection above. The value for the partition property is QUAL_CUR. Example :

messageToPublish:{
     "sender":{
       "eboxType":"enterprise",
       "enterpriseNumber":"0123456798"
     },
     "recipient":{
       "eboxType":"citizen",
       "ssin":"01234567890",
       "partition":"QUAL_CUR"
     },
     "subject":{
       "fr":"Example request to publish for QUAL_CUR REST request"
     },
     "messageTypeId":"testMessageType",
     "senderApplicationId":"testApplicationId",
     "attachments":[
       {
         "httpPartName":"upfile1",
         "isMainContent":true,
         "isAttachmentSigned":false
       }
     ],
     "isReplyAuthorized":false
   }

If there are several attachments to the message, it is advised to put an attachmentTitle to attachments that are not main content. It will display a correct annex name in the GUI version used by curators. You still have to not put an attachmentTitle for the main content.

For institution and mandataries

For mandataries quality code (QUAL_FSC, QUAL_SP_LEG, QUAL_SSC) and all other qualities like QUAL_SOC_ACTION, QUAL_COMP_PENSION, QUAL_NOTSOC, etc, the value for the eboxType property is enterprise and the partition property must have the same value as the quality code. In this way, the message is sent to the e-Box corresponding to the quality code. For mandatary recipient, a copy is also in the mandatary partition of the enterprise e-Box. Request example :

messageToPublish:{
  "sender":{
    "eboxType":"enterprise",
    "enterpriseNumber":"0123456798"
  },
  "recipient":{
    "eboxType":"enterprise",
    "enterpriseNumber":"0123456789",
    "partition":"QUAL_COMP_PENSION"
  },
  "subject":{
    "fr":"Example publish for QUAL_COMP_PENSION REST request"
  },
  "messageTypeId":"testMessageType",
  "senderApplicationId":"testApplicationId",
  "attachments":[
    {
      "httpPartName":"upfile1",
      "isMainContent":true,
      "isAttachmentSigned":false
    }
  ],
  "isReplyAuthorized":false
}

If there are several attachments to the message, it is advised to put an attachmentTitle to attachments that are not main content. It will display a correct annex name in the GUI version used by mandataries. You still have to not put an attachmentTitle for the main content.

For subdivisions

To publish to subdivisions/subentity, the value for the partition is QUAL_SUBDIVISION_ followed by the subdivision identifier. In this way, the message is sent to the e-Box corresponding to the subdivision. For example, to publish to the subdivision 6332007101 of the enterprise 0225205492 :

messageToPublish:{
  "sender":{
    "eboxType":"enterprise",
    "enterpriseNumber":"0123456798"
  },
  "recipient":{
    "eboxType":"enterprise",
    "enterpriseNumber":"0225205492",
    "partition":"QUAL_SUBDIVISION_6332007101"
  },
  "subject":{
    "fr":"Example publish for subdivision request"
  },
  "messageTypeId":"testMessageType",
  "senderApplicationId":"testApplicationId",
  "attachments":[
    {
      "httpPartName":"upfile1",
      "isMainContent":true,
      "isAttachmentSigned":false
    }
  ],
  "isReplyAuthorized":false
}

Currently in production, only the enterprise 0225205492 has subdivisions.