To boost generalization of e-invoicing in Belgium, the Government decided to set up Hermes (hrms), an xml to pdf gateway that brings Belgian enterprises not yet equipped with inbound e-invoicing tools within the reach of Peppol BIS invoice senders.
\nA key component of hrms is HermeSMP (hsmp): this smp is dedicated to store only hrms receivers, ie all Belgian enterprises as long as they have not found a suitable Peppol Access Provider.
\nThis API provides a 'machine friendly exit' for participant by providing Peppol access point to get the necessary migration key to start the standard SMP migration process, as defined in Peppol specifications.
\nNote that beside this API, there is also the possibility for an enterprise representative manually collects the migration key using a webform exposed by the Government. TODO : @Arnaud could you provide the url of the IWF
\nThis documentation describes the REST interface for the exchanges between the HSMP and a client wishing to retrieve a migration key in order to take over a Peppol participant.
\nThis process is part of the
\n\n. But the actual exchange of the migration key part is left to specific implementation, as described in this extract of the SML specification:
\n_Another set of steps relating to SMPs and the SML relates to the migration of the metadata about a participant from one SMP to another SMP (for example, the participant decides to change suppliers for this function). There are interfaces to the SML to support migrations of this kind, which imply following a sequence of steps along the lines shown in figure 4.__In this sequence, the original SMP receives a request from a participant to migrate its metadata to a new SMP (a step that is done out-of-band: there are no interfaces defined in these specifications for this).The SMP generates a Migration Key which is a unique string containing characters and numbers only, with a maximum length of 24 characters.The original SMP invokes the PrepareToMigrate operation of the SML and then passes the migration key to the new SMP (the key passing is an out-of-band step not defined in these specifications).__When the new SMP has created the relevant metadata for the participant, it signals that it is taking over by invoking the Migrate operation of the SML, which then causes the DNS record(s) for that participant ID to be updated to point at the new SMP._Once this switch is complete, the original SMP can remove the metadata which it holds for the participant.
\nIn order to call the API, the access point must use a valid Peppol certificate to perform a mutual TLS authentication:
\nProduction Access point certificate can be used for PROD and TEST Participants (SML and SMK)
\nTest Access Point Certificate can only be used for TEST Participants (SMK)
\nSwagger is not able to specify security based on mutual TLS authentication, therefore the security part is left empty in the endpoint documentation.
\nHSMP allows a maximum of 1000 queries per day coming from a single certificate. If the limit is reached, the certificate is permanently baned. Access point may send a email request to BOSA support in order to to unblock the certificate.
\nThe DNS entries are done for the following domains:
\n91.198.243.18
\n91.198.243.19
\n91.198.243.20
\n91.198.243.21
\nThe first release was done as parto f the initial development of the HSMP. Its purpose was to enable the BOSA intelligent web form to gather and distribute the migration key.
\nFollowing up on Access Points feedback, BOSA decided to provide a public API for Access Point to automate Participant migration.
\nHere is the list of changes:
\nThe name of the API was changed to a more 'REST' friendly resource like name
\nThe xml elements names were adapted to be closer to the one used in the SML documentation
\nThe xml structure of the API request and response have been adapted in order to be fit in the capabilities of the swagger definition file.
\nAuthentication was change to leverage the Peppol PKI
\nError code were added. Note that due to swagger documentation, the error code are documented as x-000-HSMP-000. The API will respond a standard response code corresponding to the first 3 digits. The body of the response will contain the error code and message.
\nAs part of the development few consistency changes were made.
\nHere is the list of changes:
\nChange prefix to URL : /hermes-rw/migrationKey
\nFew error codes (002 -> 012, 003 -> 013, 004 -> 811) were changed to insure consistency with the former SMP.Belgium.be
\nIn order to be able to perform this test, you need to add you Peppol access point to the Postman:
\n(Required) 1 participant ID
\n","type":"text/plain"},"key":"participant","value":"0211487714"}],"variable":[]}},"response":[{"id":"06bb7f6f-f096-4489-af40-be01c1f4cfbb","name":"Ok","originalRequest":{"method":"GET","header":[],"url":{"raw":"smp.acc-hermes-belgium.be/migrationKey?participant=HSMP-999HSMP-004HSMP-001HSMP-802Get the service group for a valid participant
\n","urlObject":{"protocol":"http","path":["iso6523-actorid-upis%3A%3A0208%3A0211487714"],"host":["smp.acc-hermes-belgium.be"],"query":[],"variable":[]}},"response":[],"_postman_id":"8e06d72c-d663-4961-92ab-259fb93fcb2b"},{"name":"Case 2.2. Get Service Group for non 0208 participant","id":"4435e4cb-5805-4a6f-9745-23a42fef515f","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://smp.acc-hermes-belgium.be/iso6523-actorid-upis%3A%3A9956%3A00000","description":"Get the service group for a non 0208 participant
\n","urlObject":{"protocol":"http","path":["iso6523-actorid-upis%3A%3A9956%3A00000"],"host":["smp.acc-hermes-belgium.be"],"query":[],"variable":[]}},"response":[],"_postman_id":"4435e4cb-5805-4a6f-9745-23a42fef515f"},{"name":"Case 2.3. Get Service Group for syntactically invalid CBE","id":"a483b419-287c-4624-a1b7-835b7c99c1c5","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://smp.acc-hermes-belgium.be/iso6523-actorid-upis%3A%3A0208%3A1111","description":"Get the service group for a syntactically invalid CDE number
\n","urlObject":{"protocol":"http","path":["iso6523-actorid-upis%3A%3A0208%3A1111"],"host":["smp.acc-hermes-belgium.be"],"query":[],"variable":[]}},"response":[],"_postman_id":"a483b419-287c-4624-a1b7-835b7c99c1c5"},{"name":"Case 2.4. Get Service Metadata for active participant","id":"8a08011c-6660-45b9-a2bb-90b315ea93e8","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://smp.acc-hermes-belgium.be/iso6523-actorid-upis%3A%3A0208%3A0211487714/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1","description":"Get the service metadata for a valid participant
\n","urlObject":{"protocol":"http","path":["iso6523-actorid-upis%3A%3A0208%3A0211487714","services","busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1"],"host":["smp.acc-hermes-belgium.be"],"query":[],"variable":[]}},"response":[],"_postman_id":"8a08011c-6660-45b9-a2bb-90b315ea93e8"},{"name":"Case 2.5. Get Service Metadata for invalid participant","id":"af731773-1d0f-41f8-a53d-2e379388314c","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://smp.acc-hermes-belgium.be/iso6523-actorid-upis%3A%3A0208%3A1111/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1","description":"Get the service group for a invalid participant. This number was never known as a valid Belgian BCE number.
\n","urlObject":{"protocol":"http","path":["iso6523-actorid-upis%3A%3A0208%3A1111","services","busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1"],"host":["smp.acc-hermes-belgium.be"],"query":[],"variable":[]}},"response":[],"_postman_id":"af731773-1d0f-41f8-a53d-2e379388314c"},{"name":"Case 2.6. Get Service Metadata for migrated participant","id":"f1e5c8a5-0e35-4064-8080-e4f5dd5e1707","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://smp.acc-hermes-belgium.be/iso6523-actorid-upis%3A%3A0208%3A0211276292/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1","description":"Get the service group for a migrated participant.
\n","urlObject":{"protocol":"http","path":["iso6523-actorid-upis%3A%3A0208%3A0211276292","services","busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1"],"host":["smp.acc-hermes-belgium.be"],"query":[],"variable":[]}},"response":[],"_postman_id":"f1e5c8a5-0e35-4064-8080-e4f5dd5e1707"},{"name":"Case 2.7. Get Service Metadata for deleted participant","id":"91bd0c85-83f1-411f-b7d7-f1fb492a3563","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://smp.acc-hermes-belgium.be/iso6523-actorid-upis%3A%3A0208%3A0458625502/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1","description":"Get the service group for a deleted participant.
\n","urlObject":{"protocol":"http","path":["iso6523-actorid-upis%3A%3A0208%3A0458625502","services","busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.1"],"host":["smp.acc-hermes-belgium.be"],"query":[],"variable":[]}},"response":[],"_postman_id":"91bd0c85-83f1-411f-b7d7-f1fb492a3563"},{"name":"Case 2.8. Get Service Metadata for invalid document","id":"1fa90c06-6683-4197-997e-551ba6578465","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"method":"GET","header":[],"url":"http://smp.acc-hermes-belgium.be/iso6523-actorid-upis%3A%3A0208%3A0211487714/services/busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.4","description":"Get the service group for a invalid document.
\n","urlObject":{"protocol":"http","path":["iso6523-actorid-upis%3A%3A0208%3A0211487714","services","busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3ACreditNote-2%3A%3ACreditNote%23%23urn%3Acen.eu%3Aen16931%3A2017%23compliant%23urn%3Afdc%3Apeppol.eu%3A2017%3Apoacc%3Abilling%3A3.0%3A%3A2.4"],"host":["smp.acc-hermes-belgium.be"],"query":[],"variable":[]}},"response":[],"_postman_id":"1fa90c06-6683-4197-997e-551ba6578465"}],"id":"355f18d3-6771-431f-8223-b04823c571e6","_postman_id":"355f18d3-6771-431f-8223-b04823c571e6","description":""},{"name":"3. migrationKey test cases","item":[{"name":"Case 3.1. Get Migration Key for active participant","id":"c230ac33-03f2-4e96-a19a-3657925a2cf9","protocolProfileBehavior":{"disableBodyPruning":true},"request":{"auth":{"type":"noauth","isInherited":false},"method":"GET","header":[],"url":"https://smp.acc-hermes-belgium.be/hermes-rw/migrationKey?participant=0211487714","description":"In order to be able to perform this test, you need to add you Peppol access point to the Postman:
\nOpen Postman.
\nGo to “Preferences” in the main navigation
\nIn \"General\", disable SSL certificate verification
\nIn \"Certificates\" tab, click “Add Certificates”. Choose the following values:
\nCRT: your_peppol_ap_cert.crt (Public certificate)
\nKey: your_peppol_ap_cert.pem (private key)
\n(Required) 1 participant ID
\n","type":"text/plain"},"key":"participant","value":"0211487714"}],"variable":[]}},"response":[{"id":"3df4877d-e0d9-49d7-9103-d53f39780f1a","name":"Ok","originalRequest":{"method":"GET","header":[],"url":{"raw":"smp.acc-hermes-belgium.be/hermes-rw/migrationKey?participant=HSMP-001HSMP-802HSMP-999HSMP-004In order to be able to perform this test, you need to add you Peppol access point to the Postman:
\n(Required) 1 participant ID
\n","type":"text/plain"},"key":"participant","value":"1111"}],"variable":[]}},"response":[{"id":"4b6c620f-d627-46fe-83b7-2c2a7dd39e99","name":"#### Error Code:\n* HSMP-004 : Blacklisted. Please contact BOSA\n","originalRequest":{"method":"GET","header":[],"url":{"raw":"smp.acc-hermes-belgium.be/hermes-rw/migrationKey?participant=HSMP-004HSMP-802HSMP-001HSMP-999In order to be able to perform this test, you need to add you Peppol access point to the Postman:
\n(Required) 1 participant ID
\n","type":"text/plain"},"key":"participant","value":"0211276292"}],"variable":[]}},"response":[{"id":"0a95c7b4-6da5-4440-b247-d2f77c5079c9","name":"#### Error Code:\n* HSMP-004 : Blacklisted. Please contact BOSA\n","originalRequest":{"method":"GET","header":[],"url":{"raw":"smp.acc-hermes-belgium.be/hermes-rw/migrationKey?participant=HSMP-004HSMP-802HSMP-001HSMP-999In order to be able to perform this test, you need to add you Peppol access point to the Postman:
\n(Required) 1 participant ID
\n","type":"text/plain"},"key":"participant","value":"0458625502"}],"variable":[]}},"response":[{"id":"1ebc1ab4-ddfd-4dbd-aea0-4a1ed2fcde03","name":"#### Error Code:\n* HSMP-999: The service encountered an internal error\n","originalRequest":{"method":"GET","header":[],"url":{"raw":"smp.acc-hermes-belgium.be/hermes-rw/migrationKey?participant=HSMP-999HSMP-001HSMP-004HSMP-802In order to be able to perform this test, you need to add you Peppol access point to the Postman:
\n(Required) 1 participant ID
\n","type":"text/plain"},"key":"participant","value":"0211487714"}],"variable":[]}},"response":[{"id":"47240390-8242-4591-a438-db16b7a18159","name":"#### Error Code:\n* HSMP-001 : Invalid or non-existing enterprise number + id\n* HSMP-002 : Inactive enterprise number + id\n* HSMP-003 : Already migrated + id\n","originalRequest":{"method":"GET","header":[],"url":{"raw":"smp.acc-hermes-belgium.be/hermes-rw/migrationKey?participant=HSMP-001HSMP-004HSMP-999HSMP-802