eInvoicing (Storecove) configuration

Link copied to clipboard

Preparation

Link copied to clipboard

Before you start, make sure you have:

  • PortaSwitch MR132-0 or later.
  • An active Storecove account with access to the Storecove portal. Complete the Storecove onboarding, including Peppol registration, for each country where you send eInvoices.
  • An Add-on Mart account with a trial or paid subscription to the eInvoicing (Storecove) module.
  • A public DNS name for the module instance that points to the Add-on Mart cluster where the instance is deployed. Create a CNAME record (or an A record) for this name as described in Add-on Mart addresses by region. Both PortaBilling and Storecove connect to the module over HTTPS using this name.

    TLS certificates for this domain can be generated automatically by PortaOne using Let’s Encrypt certification authority (CA). Optionally, you can contact your trusted CA to order a TLS certificate for your domain.

  • The Peppol ID (Peppol ID scheme and participant ID) of each customer who will receive eInvoices.

Configuration overview

Link copied to clipboard
  1. Set up the Storecove account
  2. Create a new API user in PortaBilling with an access token
  3. Configure and deploy the module in the Add-on Mart management portal
  4. Register the delivery callback in Storecove
  5. Enable eInvoicing on the Configuration server web interface
  6. Specify your company information in PortaBilling
  7. Create the ESPF event handler
  8. Enable eInvoicing for a customer class
  9. Configure a customer

When you finish, check that eInvoicing works with a test customer.

Step 1. Set up the Storecove account

Link copied to clipboard

Perform these steps in the Storecove portal. Save the API key and legal entity ID values you get here – you will need them to configure the module in step 3.

  1. Create an API key for the Access Point as a Service. Copy the key right away, as Storecove shows it only once.

    Create an API key

  2. Create a legal entity for your company that acts as the sender of eInvoices. Specify your company’s registered name and address and add your Peppol identifier(s), such as your GLN or national registration number. Note the numeric ID of the legal entity.

    Create a legal entity

  3. If your company is registered for VAT, mark the legal entity as tax registered and add your VAT number as a Peppol identifier. Select your country’s VAT scheme, for example, BE:VAT for Belgium, and enter your VAT number starting with the two-letter country code, for example, BE0123456749. You will enter the same VAT number as the Tax ID in PortaBilling in step 6. Storecove rejects eInvoices if the legal entity isn’t marked as tax registered or has no VAT number, or if the VAT numbers in Storecove and PortaBilling don’t match.

For detailed instructions, refer to the Storecove documentation.

Step 2. Create a new API user in PortaBilling with an access token

Link copied to clipboard

The module requires API user credentials to retrieve the data from PortaBilling via the API. Creating a dedicated admin user for this purpose is recommended.

To create a new user, log in to PortaBilling and perform the following steps:

  1. Navigate to My company > Access control > Users.
  2. Click +Add and fill in the user details:
    • Login – type the username that will be used by the module for connecting to the PortaBilling API;
    • Email – type in the email address of the admin (for receiving alerts or password recoveries for the user);
    • Password – type a long and strong password for this user;
    • Role – select a role for this user.

      Fill in the user details

      Ensure the selected role has no restrictions on the entities that require data access. It’s recommended to create a dedicated admin role with the following permissions:

      • Customer – “Read”
      • Company info – “Read”
      • Invoice – “Modify”
    • Click Save.
  3. Open the user record, navigate to the Web interface panel, enable the API token access, and generate an API token.

    Generate an API token

Copy the login and the API token. You will enter them in the module configuration in step 3.

Step 3. Configure and deploy the module in the Add-on Mart management portal

Link copied to clipboard

Log in to the Add-on Mart management portal, open My modules, locate your eInvoicing (Storecove) subscription, and click Configure.

Click Configure

On the Configuration page that opens, fill in the details:

General settings

Link copied to clipboard

Instance location – select the Add-on Mart cluster that the module domain points to (see Preparation).

Version to deploy – choose a module version. The following options are available:

  • Deploy the latest (recommended) – select if you want to deploy the latest version.
  • Select from the full list – select if you want to deploy another version.

Configure General settings

Choose domain configuration

Link copied to clipboard
  • Module domain – specify the public DNS name of the module instance (see Preparation).
  • Generate certificates – select this checkbox so that the Add-on Mart issues the TLS certificate for the module domain automatically. Alternatively, clear the checkbox and upload your custom certificate and the private RSA key for your domain.

Choose domain configuration

PortaBilling

Link copied to clipboard

Fill in the parameters that the module needs to connect to the PortaBilling API:

  • PortaBilling API URL – specify the URL of the PortaBilling REST API, e.g., https://<pb-web-host>/rest. Use the same host as the PortaBilling admin web interface. Add the :8443 port only if the API is available on that port.
  • API user login – specify the login of the API user created in step 2.
  • API user token – specify the API token generated in step 2.

Fill in the PortaBilling parameters

ESPF webhook

Link copied to clipboard

Fill in the credentials that PortaBilling uses to send invoice events to the module. The module rejects events without these credentials.

  • Webhook username – specify any username. You will enter the same value in the BasicAuth.User field of the event handler in step 7.
  • Webhook password – specify a strong password. You will enter the same value in the BasicAuth.Key field of the event handler in step 7.

Fill in the credentials

Storecove

Link copied to clipboard
  • API key – specify the Storecove API key from step 1.
  • Legal entity ID – specify the ID of the sender legal entity from step 1.
  • Delivery callback token – specify a secret value that is hard to guess, as you would for a strong password. Storecove sends this value with every delivery result, so the module can verify that the result really comes from Storecove. You will enter the same value as the x-callback-token header value of the Storecove webhook in step 4.

Fill in the Storecove credentials

eInvoicing

Link copied to clipboard

Specify why your VAT-exempt invoices don’t include VAT. The module adds this reason only to VAT-exempt invoices (category E). If you issue only standard VAT invoices, leave both fields empty.

  • Tax exemption reason code – specify the VATEX code of the exemption, e.g., VATEX-EU-132 for exemptions under Article 132 of Directive 2006/112/EC. See the full list of codes in the Peppol VATEX code list. Specify only a code that describes an exemption. If you specify a code of another kind (e.g., VATEX-EU-AE), the exempt invoices fail.
  • Tax exemption reason text – specify the description of the exemption, e.g., “Exempt from VAT (Article 132 of Directive 2006/112/EC)”.

The EN 16931 standard accepts either the code or the text. We recommend that you specify both: the code is used for automatic validation and the text is for the person who reads the invoice.

Reverse charge invoices always carry the VATEX-EU-AE code with the “Reverse charge” text, so no configuration is required.

Specify VAT-exemption details

Deployment

Link copied to clipboard

Click Deploy (or Save for later to deploy it later) and wait until the deployment status is Success.

Then open the deployment details and copy the two URLs listed under Post-deployment artifacts:

  • ESPF webhook URL (https://<module-domain>/webhooks/invoice) – you will need it in step 7.
  • Delivery callback URL (https://<module-domain>/webhooks/delivery_status) – you will need it in step 4.

Copy the URLs under Post-deployment artifacts

Step 4. Register the delivery callback in Storecove

Link copied to clipboard

Storecove reports the delivery result to the module using a webhook. If you don’t set it up, eInvoices stay in the Submitted status even after Storecove delivers them and are marked as failed when the delivery timeout expires.

In the Storecove portal, create and enable a webhook with the following settings:

  • Event to notify – select Document sending result (document_submission).
  • Webhook mode – select Push and enable the webhook.
  • URL – enter the delivery callback URL from step 3 (in the format https://<module-domain>/webhooks/delivery_status).
  • Authentication – select HTTP Header, specify x-callback-token as the header name, and enter the Delivery callback token from step 3 as the header value.

Create and enable a webhook

Created Webhook

Step 5. Enable eInvoicing on the Configuration server web interface

Link copied to clipboard

Log in to the Configuration server web interface and perform the following steps:

  1. Navigate to Web Cluster > Global > EInvoice and set Enabled to Yes.
  2. Optionally, adjust DeliveryTimeoutHours (48 by default). This is how long an eInvoice can remain in the Submitted status before it is marked as Delivery failed and the administrator is notified.

    Enable eInvoicing

  3. Verify and apply the configuration.

Step 6. Specify your company information in PortaBilling

Link copied to clipboard

Log in to the PortaBilling web interface, open My company > Company info, and perform the following steps:

  1. Go to the Address information panel and make sure your company name, country, address, city, and postal code are specified. The country is the seller country on the eInvoice. It also determines which VAT rates Storecove accepts on the eInvoice.

    Fill in the Address information

  2. If your company is registered for VAT, go to the Invoicing and taxation panel and make sure your VAT number with the country prefix is specified in the Tax ID field (e.g., BE0123456789). This must be the same VAT number that you added to the Storecove legal entity in step 1.

    Specified the Tax ID

  3. If this is the first Add-on Mart module you set up, go to the Add-on Mart panel and enter the PortaSwitch Credentials from the Add-on Mart management portal. For details, see Connect PortaSwitch to Add-on Mart. Skip this step if you have already done this for another module.

    Enter the PortaSwitch Credentials for Add-on Mart

  4. Click Save.

Step 7. Create the ESPF event handler

Link copied to clipboard

PortaBilling notifies the module about new, changed, and voided invoices via the External System Provisioning Framework (ESPF). To send these events to the module, create an EventSender handler.

  1. In PortaBilling, navigate to Infrastructure > Event handlers and add click + Event handler.
  2. Fill in the handler details:
    • Name – type a descriptive name for the handler.
    • Type – select EventSender.
    • Enabled – leave the checkbox selected so that the handler starts sending events once it’s configured.
    • Events version – select Events v.1. The module doesn’t accept v.2 events.
    • AuthMethod – select Basic.
    • BasicAuth.Key – enter the Webhook password from the module configuration in step 3 – ESPF webhook.
    • BasicAuth.User – enter the Webhook username from the module configuration in step 3 – ESPF webhook.
    • URL – enter the ESPF webhook URL from the deployment details in step 3 – Deployment (e.g., https://<module-domain>/webhooks/invoice).
    • Leave the other parameters at their default values.

      Fill in the handler details

  3. On the Event subscriptions tab, enable these four events:
    • Invoice/New
    • Invoice/Status/Changed
    • Invoice/Voided
    • Invoice/EInvoice/RetryRequested

      Enable events

  4. Click Save.

Step 8. Enable eInvoicing for a customer class

Link copied to clipboard

You can enable eInvoicing for a customer class or for an individual customer. If you enable it for a customer class, it applies to all customers in that class whose eInvoicing setting is As defined by the customer class, which is the default. To make an exception, change the setting for a specific customer in step 9. For example, you can enable eInvoicing for a single customer whose class doesn’t use it, or disable it for a customer in a class that does.

  1. Open the customer class and go to Finances > Regular invoices.
  2. Make sure an invoice template is selected in the Invoice template field. PortaBilling doesn’t generate invoices without a template, even for customers who receive only eInvoices. The template defines only the PDF invoice layout; the module builds the eInvoice from the invoice data.
  3. Turn on Generate an eInvoice. If the option is unavailable and has an orange Add-on Mart icon next to it, PortaBilling can’t connect to the module. Check the Add-on Mart credentials from step 6.
  4. Optionally, set Send the PDF invoice via email. When eInvoicing is enabled, this option works as follows:
    • Never – the customer receives an email with the eInvoice XML file only.
    • Automatically or After review and approval by admin – the customer receives an email with both the PDF invoice and the eInvoice XML file.

      Whichever option you select, PortaBilling sends the email only after the eInvoice is delivered, so the customer receives the final document.

      Configure invoicing

  5. Click Save.

Step 9. Configure a customer

Link copied to clipboard

For each customer who receives eInvoices, you need to specify their own Peppol ID and a complete company address. If your company is registered for VAT, the customer also needs VAT taxation settings.

Open a specific customer and configure the following:

  1. Go to General info > Basic info and specify the customer’s company name, street, city, postal code, and country. These fields are mandatory – Storecove rejects eInvoices without a complete buyer address.

    Fill in the address info

  2. Go to the Finances > Financial info tab:
    • Generate an eInvoice – select Enabled or As defined by the customer class to use the setting from step 8.
    • The Peppol ID scheme – select the type of identifier under which the customer is registered on Peppol (e.g., BE:EN for a Belgian enterprise number or BE:VAT for a Belgian VAT number).
    • The Peppol participant ID – specify the customer’s identifier in the selected scheme.
  3. If your company is registered for VAT, configure taxation for the customer in the Taxation section on the same tab:
    • Taxation plug-in – select the taxation plug-in (e.g., Fixed VAT Rate).
    • Tax ID – specify the customer’s VAT number with the country prefix.
    • Taxes included into rates/fees – make sure this option is turned off. eInvoicing doesn’t support tax-inclusive prices.
    • Exempt from – select Default to use the customer class setting, No if the customer pays VAT, or Yes if the customer is exempt from VAT. For exempt customers, the eInvoice includes the tax exemption reason from step 3 – eInvoicing.
    • VAT % – specify the VAT rate you charge the customer.
  4. Click Save.

    Configure invoicing and taxation

Check that eInvoicing works

Link copied to clipboard
  1. Open a test customer configured as described in step 9 and add a manual charge (Balance adjustments > Manual charge).
  2. Wait about 30 seconds for PortaBilling to calculate taxes for the charge, then generate an invoice on demand.
  3. On the Issued invoices tab, check the invoice’s eInvoice status. Within a minute, the status changes from Pending to Submitted and then to Delivered once Storecove has delivered it over Peppol.
    The eInvoice column is hidden by default – to display it, click Settings on the title bar, click Customize columns, and select the eInvoice checkbox.
  4. Once the eInvoice is delivered, use the Download the eInvoice action to get the final XML document.

Download the eInvoice

In the Storecove portal, the eInvoice appears in Invoices Sent with a delivery mark, and Settings > Webhook History shows the callback to the module with the 200 OK response.

eInvoice statuses

Link copied to clipboard

To see the status details, such as the time of the last status change and the reason for a failure, hover over the status icon in the eInvoice column.

Status Meaning What to do
Not applicable eInvoicing isn’t enabled for the customer. –
Pending The module has received the event and is creating the eInvoice. Wait. If the status doesn’t change, the event didn’t reach the module. Check that the event handler from step 7 is enabled, subscribed to the four events, and uses the URL and credentials from step 3.
Submitted Storecove has accepted the eInvoice and is delivering it. Wait for the delivery result. If the status doesn’t change, check the webhook history in the Storecove portal: the webhook from step 4 must be enabled, and the module must respond with 200 OK.
Delivered The eInvoice has been delivered. The XML file is available for download. –
Generation failed The eInvoice couldn’t be created or was rejected by Storecove. Correct the data mentioned in the failure reason (e.g., add a postal code to the customer’s address) and use the Retry the eInvoice generation action.

If the reason is BR-O-02, the customer has no taxation plug-in enabled while your company has a Tax ID: select a VAT taxation plug-in for the customer, e.g., Fixed VAT Rate.

Delivery failed Storecove reported a delivery failure or didn’t report the delivery result within the delivery timeout (48 hours by default). Check the customer’s Peppol ID and the Storecove webhook, then use the Retry the eInvoice generation action.
Cancelled The invoice was voided before its eInvoice was successfully sent, so no eInvoice was delivered to the customer. –
Voided The invoice was voided after the eInvoice had been submitted. Agree with the customer on how to handle the original eInvoice: it can’t be withdrawn. If PortaBilling generates a replacement invoice, it’s sent as a separate eInvoice.

On this page

Docs for
What's new
Admin manuals
Handbooks
UI help
Developers documentation
  • Loading…