Skip to main content

Ebox Enterprise Federation Service

The Ebox Federation Service allows to

  • Know the activity and the preferences of a particular e-Box (enterprise)
  • Know the consent of a citizen to the e-Box Citizen terms and condition

Search Ebox Enterprise Preferences​

A POST /eboxPreferences/searchcall allows to know whether the enterprise has opt for receiving his messages exclusively in e-Box or when he visited his e-Box for the last time. The OAuth scope needed for this request is scope:documentmanagement:ebox:enterprise:federation-rest:preference. You can see bellow in this page more information about how to retrieve a token.

Example:​

Request: POST /eboxPreferences/search with json body

{
    "eboxType": "ENTERPRISE",
    "eboxIdType": "EnterpriseNumber",
    "eboxIdValueList": ["0474028805","0212148896","0800002352"]
}

The service returns a list of objects for each existing e-Box in the request. For example, if we send the request above and if the two first e-Box in the list exist, we can get :

[
    {
        "eboxId": {
            "eboxType": "enterprise",
            "eboxIdValue": "0474028805"
        },
        "exclusivelyEbox": false
    },
    {
        "eboxId": {
            "eboxType": "enterprise",
            "eboxIdValue": "0212148896"
        },
        "exclusivelyEbox": true,
        "lastConnectionDate": "2022-08-23T00:00:00+02:00"
    }
]

If none of the e-Box exist, the result is an empty list.

[]

What are e-Box enterprise preferences for?​

There are two use cases for e-Box enterprise preferences

1) You implement the /publishMessage endpoint of a Document Provider. In this case you should call e-Box Preferences in order to know whether the user already has an e-Box or not. If he does not have an e-Box, a special status code needs to be sent in the reply. 2) You want to know if someone is using his e-Box in order to decide on whether to send via messages via e-Box or via Paper. This use case mostly applies to Document senders sending messages to enterprises.

A POST /citizenEboxConsents/searchcall allows to know if a citizen accepted the terms and condition to use the e-Box Citizen service.

Example:​

For the following example, let's assume that the citizen with the SSIN 12345678901 accepted the terms and condition and the citizen with the SSIN 12345678902 never opened the e-Box or did not accepted the terms and condition or revoked the consent or does not exist. Then :

Request: POST /citizenEboxConsents/search with json body

{
  "ssins":["12345678901","12345678902"]
}

And the result is

[
    {
        "eboxId": {
            "eboxType": "citizen",
            "eboxIdValue": "12345678901"
        },
        "hasConsent": true
    },
    {
        "eboxId": {
            "eboxType": "citizen",
            "eboxIdValue": "12345678902"
        },
        "hasConsent": false
    }
]

Technical information​

How to get an OAuth token​

In order to be granted the needed scope, you need to contact eBoxIntegration@smals.be providing the public part of the certificates. The certificates must follow this structure and can be from any issuer, even self-signed. Once the onboarding is done in acceptance environment, you will receive the client-ID from eBoxIntegration and the scope scope:documentmanagement:ebox:enterprise:federation-rest:preference will be granted. eBoxIntegration will ask you to test in acceptance environment before doing the onboarding in production environment.

You have to request your AccessToken to the Authorization Server. The Cookbook OAuth V5 introduces OAuth and explains how a token can be retrieved. You can also see the get OAuth token example for a java example on how to retrieve an OAuth token. The GetAccessTokenV5.getAccessToken() method is the one responsible of getting the token. If you take this example, we advise you to add the scope scope:documentmanagement:ebox:enterprise:federation-rest:preference as parameter in the getAccessToken() call so if the onboarding was not done properly, you will receive an error message and know that the scope is not granted before sending the requests.

OAuth Authorization Server URL (ACC)https://services-acpt.socialsecurity.be/REST/oauth/v5/token
Audience (ACC)https://services-acpt.socialsecurity.be/REST/oauth/v5/token
OAuth Authorization Server URL (PRD)https://services.socialsecurity.be/REST/oauth/v5/token
Audience (PRD)https://services.socialsecurity.be/REST/oauth/v5/token