Receive e-invoices

The sequence diagram below, illustrates the overall principle of setting up child customers for reception, and then receiving documents on behalf of them, using the Sproom API.

Below we will go through the calls from the API integrator (you) to the Sproom API, and explain in short what they do.

To create a webhook so you will get notified about incoming documents, use POST /api/webhooks

The type should of webhook should be: documentReceived (more information here: https://sproom.net/api/documentation/Webhooks.html)

This will allow Sproom to notify you about a new invoice that is ready to be downloaded.

The webhook will work for your own incoming documents, as well as for the documents received by all your child companies. The Webhook will contain the CompanyID of the recipient, either it is your main company or one of your child companies.

Note that if you want to register for Peppol reception, you first need to have the child company go through the Peppol participant verification process, by issuing a POST /api/peppol-participant-verifications request - we will not go further in to that process here, please read the API documentation for this. NemHandel does currently not require extra participant verification.

Register the child company for reception on NemHandel using POST /api/registrations/nemhandel

Register the child company for reception on PEPPOL using POST /api/registrations/peppol

You can register any number of identifiers that you have for the company (like CVR, GLN, SE etc.)

If the API request went OK, it will return a 200 response that includes a NetworkID.
This networkID is to be saved and used for updates to the registration. That could be to delete it in the future, or change it to support other profiles, such as orders.

Now the child company can receive documents on the registered endpoint id's

When you or your child receives say an invoice, we push a Webhook your way.

That will look like so:

{
         "webhookType": "documentReceived",
         "companyId": "fet23-9002-4ffc-b647-7c1f10e4385a",
         "documentId": "6d2244b2c1-a7cf-4d10-a835-ad19863f67ff",
         "documentType": "Invoice",
         "hasRelatedDocuments": false
     }

The "companyId" will match either your own, or the Id of one of your created child companies.
The "documentId" is needed to download the specific invoice from Sproom.

To download the invoice you will need to GET /api/documents/{documentId}/{format}

Note: You can choose which format you want to download the invoice in, either OIOUBL or Peppol BIS 3

This will return a code 200 which includes the invoice in the requested format, as the body of the response.

When the end user has either accepted the document, or for some reason chosen to reject it (maybe the invoice wasn't correct), you should set the corresponding document response, using POST https://sproom.net/api/documents/{documentId}/responses

When setting the document response, Sproom will, behind the scenes, look at the document and send back a response to the original sender of the document as required by the OIOUBL standard. Specifically, in case of a rejection, a response will be sent if the profile of the document supports it, in case of accepting the document, a response will be sent if the profile requires it.

The reason you give when setting the response, will be included in the response to the supplier, so preferably the end user should be able to supply this for rejects.

If you prefer to create and send your own ApplicationResponse documents, you can do so, sending it like any other business document, and the state of the corresponding document will be updated. We do however recommend using the responses endpoint, so you won't have to bother with document profiles and generation of response documents.