Maventa Peppol API

Maventa offers electronic invoicing and document exchange services for businesses and public organizations. It acts as a central hub connecting suppliers, buyers, and their systems. In addition to electronic invoicing and document exchange, Maventa provides various value-added services for invoicing and related financial processes.

This guide walks you through the integration process with the Maventa system for setting up the integration for sending and receiving invoices, with a primary focus on the Peppol network. Each stage highlights goals and outlines the necessary prerequisites before moving forward to ensure a smooth setup.

By following these steps, you’ll be well on your way to a smooth and efficient integration with Maventa.

The steps show how Maventa APIs are used directly. There are also reference implementations that show how the API can be access using C# and Java.

Step 1: Become a Maventa partner

Goals:

• Become a Maventa partner
• Get access to the API
• Have your Know Your Customer (KYC) process verified

1.1 Get access to API

Get access to the testing environment

To use Maventa APIs, you need access to API keys, which requires a partner company account in our testing environment. To obtain a partner company account, contact our integration care team at integrations@maventa.com.

Once you become a partner, you’ll receive credentials for our testing environment:

• client_id – Identifies the company (in this case your partner company account) (Company UUID).
• client_secret – Identifies the user of that company (User API key).
• vendor_api_key – Identifies you software (Vendor API key).

The Vendor API key is available in Maventa UI under Settings > Company settings > Software API keys. The User API key and Company UUID can be found in the Settings section.

Once you have these credentials, you can start making API calls to Maventa and building the integration.

Get access to the production environment

Before moving to the production environment, the integration must be thoroughly tested in our testing environment. Additionally, all integrators are required to complete and sign the Maventa Integration Agreement, which covers key aspects such as billing and support. This agreement will be provided by your integration contact point (sales or integration care).

Production API keys can be obtained by following the same process as in the testing environment.

1.2 Verify your KYC process

All Maventa customers need to be strongly authorized. The process ensures that a person with right to represent the company has confirmed and approved the registration for the Maventa service and has accepted Terms of Service. The process is crucial for preventing potential misuse of the service.

In testing environment your vendor will be automatically marked as trusted, so you can authorize the company accounts that you create. You can start implementing and testing without being trusted. Before going to production, your KYC process needs to be approved by Maventa.

Step 2: Register an account for a company

In the subsequent steps, you will create a new user and a new company account.

A company in Maventa is identified by a unique Business Identifier (BID), ensuring that only one company account exists per BID. There are two types of company accounts: user and partner. By default, a company is registered as a user account, which is a standard account used to send and receive electronic documents. A partner account is intended for software vendors or service providers who integrate their own software solutions with Maventa. Partner accounts can manage multiple software API keys (vendors), access additional integration tools, and support multiple clients or use cases under the same umbrella.

A user in Maventa is linked to a company through an email address, and the same user can be associated with multiple companies. Users can have different roles, such as user or admin, depending on their level of access and responsibilities.
There are also API users, which are typically created with non-personal or placeholder email addresses. These users are intended purely for integration purposes and do not require access to the Maventa UI.

2.1 Prepare data

To proceed, ensure the following:

• You have access to the API (see step 1)
• You have the necessary company registration information: a valid BID, name of the company and other relevant registration details (see step 2.3)

For creating Belgium account, you will need a valid CBE (Crossroads Bank for Enterprises) organization number

2.2 Create a user

Start by first creating a new user by making an unauthenticated API call to the POST /v1/users endpoint.

{
  “vendor_api_key”: “string”,
  “email”: “string”, // Can be an email address of a real user or API user
  “first_name”: “string”,
  “last_name”: “string”
}

{
  “user_api_key”: “string”
}

This returns a user_api_key. At this point, the user is not yet associated with any company account.

2.3 Create a company

Make an unauthenticated call to the POST /v1/companies endpoint to set up the company. The user created in the previous step will be associated with this new company.

{
  “vendor_api_key”: “string”,
  “user_api_key”: “string”, // API key of the user created in the previous step
  “name”: “string”,
  “bid”: “string”, // Refer to the table above for the correct BID type
  “no_vat”: “boolean”, // Set to true if the BID is not a VAT number
  “address1”: “string”,
  “post_code”: “string”,
  “post_office”: “string”,
  “city”: “string”,
  “country”: “string”,
  “email”: “string” // This is the company’s email address
}

{
  “id”: “string”
}

This returns a new company identifier often referred as company_id.

Note: Maventa doesn’t recommend using the same user for every company you create. Even when using API users, it’s better to have a unique user for each company.

2.4 Conclusion

You should now have:

• company_id, also known as client_id in the token creation
• user_api_key, also known as client_secret in the token creation
• vendor_api_key

These are needed when making an OAuth2 token to call the other endpoints.

Step 3: Authenticate

Prerequisites

In order to authorize the company in production in Step 3.2, you must have an approved KYC process, as detailed in 1.2 Verify your KYC process.

3.1 API authorization

From this point onward, this guide includes setting company settings, registering profiles to Peppol, sending invoices to Peppol and other routes, and fetching received invoices. The scopes you need are company lookup invoice:send invoice:receive.

Make a call to POST /oauth2/token endpoint giving grant_type, client_id, client_secret, vendor_api_key, and scope to get an OAuth2 (Open Authorization) token.
It returns an access_token with token_type being Bearer, which is valid for 60 minutes.

As client_id and client_secret, use the ones received in steps 2.2 and 2.3. Do not use the credentials you have for your partner company.

{
  "grant_type": "client_credentials",
  "client_id": "string", // Use the company_id from step 2.2
  "client_secret": "string", // Use the user_api_key from step 2.3
  "scope": "string",
  "vendor_api_key": "string"
}

After you have successfully received a token, try calling the GET /oauth2/current endpoint, providing the bearer token as the authentication header, for example Bearer eyJ0eXAiOiJKV1QiLCJraWQi...., to fetch information about the authenticated user and company.

You can now also try calling GET /v1/invoices endpoint to list sent or received invoices. The response should be an empty list, as the company has no invoices.

3.2 Authorize the company

Reuse the token created in the previous step or create a new token with the scope being company. Make a call to the POST /v1/company/authorization endpoint with:

{
  "auth_email": "the-email-of-the-user", // Can be an email address of a real user or API user
  "locale": "EN",
  "options": "{\"authorization_method\": \"this needs to be something unique per company\"}"
}

You must provide an identifier in authorization_method unique to each company to link to the authorization event (e.g., contract number, signing eventID). This will be determined in the approved KYC process, so you should already know what to put here.

After a successful authorization call, make another call to GET /v1/company/authorization to confirm it returns company_state = verified.

Conclusion

You now have:

• Knowledge on how to create an OAuth2 token and perform authenticated API calls
• A customer company that has one user and has been authorized

Now you can move on to using the account for receiving and sending documents.

Step 4: Sending invoices

With Maventa, invoices can be sent as e-invoices through various networks, including Peppol, or through alternative fallback delivery routes like email and print. Learn more about email invoicing and sending invoices through our printing service. You can either send the invoice to Maventa and let the system automatically determine the best delivery route based on the recipient’s business ID, or you can force the invoice to a specific route, such as email.

In Belgium, the primary delivery route for sending e-invoices is the Peppol network.

Goals

• Enable seamless e-invoice sending
• Ensure efficient monitoring of sent invoices
• Quickly identify and address any errors that may occur

Prerequisites

• An authorized company
• You can generate a valid PeppolBIS 3.0 XML file (or other supported format)

4.1 Prepare your invoice

As the sender, you need to generate and prepare the invoice along with any necessary attachments in your system and send them to Maventa via the API.

Create the XML file

You need to create a Peppol BIS 3.0 (or other supported format). This means mapping data from your system into an XML file. Read more about XML formats and conversions.

Recipient lookup and routing

To ensure your invoice is sent as an e-invoice, you can perform a lookup before sending. This confirms whether the recipient can receive e-invoices, and if not, you can decide if you want to still send it using fallback delivery routes (e.g., email or print). You can either manage this lookup yourself or rely on Maventa to handle it for you. When sending invoices through Maventa, the system will perform a recipient lookup and determine the most suitable delivery route. There is specific delivery route order the system uses and it depends on the sender’s country. In Belgium, the priority order is Maventa’s internal network first, followed by Peppol, and then fallback routes, with email as the first option and print as the last. You can influence this routing by specifying which delivery routes are allowed or restricted either directly in the XML file or through API metadata (read more about controlling delivery routes).

Automatic lookup and routing

• Matching based on e-invoice address:

  If you provide a valid e-invoice address, such as a Peppol ID (e.g., 9925:be000000000b21) or another supported identifier, Maventa will use it to look up the recipient in e-invoice address registries and attempt direct delivery through the identified route. Adding an operator code (e.g., PEPPOL) alongside the e-invoice address forces delivery through that specific route, disabling fallback options even if delivery fails. The operator code can be specified in the API metadata or the invoice XML, depending on the format (note: Peppol BIS 3.0 does not support an operator code field).

• Recipient’s business ID based lookup:

  If you don’t know the recipient’s e-invoice address, Maventa will attempt to find an e-invoice address using the recipient’s business ID from the invoice data (e.g., VAT number or national business registry number). If a matching e-invoice address is found Maventa will attempt delivery through the identified route.

• Alternative fallback delivery routes:

  If no e-invoice address is found, or if sending to the identified e-invoice address fails for any reason, Maventa can still deliver the invoice through other available routes, such as email or print. This is determined based on your account configurations, metadata given in the sending method, or data on the invoice.

Manual lookup

To perform the lookup yourself before sending, use the GET /v1/lookup/receivers method. You can search using identifiers like the company name, business ID (VAT number or national business registry number), or e-invoice address (e.g., EDI, OVT, EAN, GLN).

For the API call, use the following values:

• Network = PEPPOL The primary route for sending invoices to recipients in Belgium is through the Peppol network. (If you want to include recipients from Maventa’s internal network, you can add INTERNAL as an additional network in the search)
• If you have the recipient’s full EIA, enter it in the eia field. If you only have the recipient’s business ID, enter it in the bid field.

The purpose of the lookup is to identify the Peppol participant identifier (in the format 9925:be000000000b21), confirming that the recipient can receive e-invoices. Or alternative Maventa’s internal address if the recipient is also using Maventa as their e-invoicing operator.

How to use the recipient data

Recipient information can be provided in two ways when sending an invoice through Maventa:

• Embedded in the XML file (recommended for Peppol BIS 3.0)
• As parameters in the API call (takes precedence over XML if both are provided)

If both a business ID and an endpoint ID are present in the XML, the Endpoint ID takes priority for routing the invoice.

Example: Including Recipient Business ID in XML

To enable automatic recipient lookup via business ID (e.g. VAT number or organization number), include the following in your Peppol BIS 3.0 XML:

<cac:Party>
  <cac:PartyIdentification>
    <cbc:ID schemeID="9925">BE000000000B21</cbc:ID>
  </cac:PartyIdentification>
</cac:Party>

Example: Including E-Invoice Address (Endpoint ID)

If you know the recipient’s Peppol endpoint ID, include it like this:

<cac:Party>
  <cac:EndpointID schemeID="9930">0216:123456789</cac:EndpointID>
</cac:Party>

Invoice image and attachments

The way invoice images (like PDFs) and other attachments are included depends on the format of the invoice you are sending. They can either be embedded within the XML (e.g. Peppol BIS 3.0) or included as separate files in a ZIP package alongside the XML (e.g. Finvoice 3.0).

It is important to follow the specific requirements of each format to ensure successful processing by Maventa and proper delivery via the Peppol network. Keep in mind that not all recipients in Peppol support or display attachments — some may ignore them entirely. While including a PDF can be helpful, it is optional; the XML must always be complete and valid on its own to ensure proper processing.

Embedding in Peppol BIS 3.0 and other UBL-based formats

In the Peppol BIS 3.0 format (commonly used in Belgium), attachments must be embedded within the XML file as defined in the specification. Sending Peppol BIS 3.0, attachments placed outside the XML (e.g., in the ZIP file) will be ignored.

ZIP Packaging for other formats

If you are using a format that does not support embedded attachments, you may include attachments within the same ZIP file as the XML. To ensure proper recognition of the invoice image by Maventa, the XML and the invoice image must have the same file name, e.g., 12345.xml and 12345.pdf. Other attachments do not need to match the XML filename.

Fallback for missing invoice image

If no invoice image is included and the chosen delivery route requires one (e.g., print), Maventa will automatically generate a visual invoice image from the provided XML data. Peppol route does not require one.

File size limits

To ensure reliable delivery and avoid processing issues, follow these size guidelines:

• Maximum size per attachment: 10 MB
• Maximum total package size: 100 MB

Best practice: Keep attachments as small as possible. The smaller, the better for performance and delivery success.

Validate before sending

Validating your invoice XML before sending is optional, but it is required for all invoices sent to Peppol. If you have your own validation process or are confident that your XML invoice is valid, you can skip this step. Maventa will perform validation during the sending process, but doing a pre-send validation can help you catch any issues earlier.

Call the POST /v1/validate

4.2 Send the invoice

All Maventa company accounts have invoice sending enabled by default — you’re ready to go from day one. Before sending, make sure your invoice is properly constructed and, ideally, validated.

To send an invoice through Maventa, send the XML file along with required parameters using the following API:

POST /v1/invoices.

After successful sent, Maventa reponds with a UUID (invoice ID), which should be saved in your system to track delivery status and updates.

Key API parameters

• Recipient’s e-invoicing address (recipient_eia) and operator PEPPOL (recipient_operator) can be provided to force routing through Peppol. Note: If recipient details are provided both in the API request and in the XML file, the API parameters will override the values in the XML.
• Recipient’s email address can also be given for email delivery fallback in the API request

Controlling delivery routes

If you want to restrict certain delivery routes, use the disabled_routes parameter. This gives you control over which route (einvoice, email, print) are allowed or blocked for each invoice. Adding an operator code (e.g., PEPPOL) alongside the e-invoice address forces delivery through that specific network, disabling fallback options even if they would not be disabled separately. Read more about recipient lookup and routing.

Few important things to remember:

• Adding an operator code (e.g., PEPPOL) alongside the e-invoice address forces delivery through that specific network, disabling fallback options even if delivery fails
• If recipient details are provided both in the API request and in the XML file, the API parameters will override the values in the XML
• Remember to store the invoice ID for tracking purposes

4.3 Follow up and handle errors

After sending the invoice and securely storing its UUID, it’s important to monitor its progress. We recommend using webhooks for real-time tracking. As a backup, you can also use polling to check the invoice status.

Register for webhook notifications for sent invoices

Use the following API to register webhook for sent invoice events: POST /v1/company/notifications:

Example registering for DELIVERED, DELIVERY_CONFIRMED and FAILED events for invoices:

{
  “destination_type”: “WEBHOOK”,
  “destination”: “https://your.example/endpoint”,
  “events”: [
    “DOCUMENTS.INVOICE.DELIVERED”,
    “DOCUMENTS.INVOICE.DELIVERY_CONFIRMED”,
    “DOCUMENTS.INVOICE.FAILED”
  ]
}

{
  “id”: “d726d240-4631-483e-a4e3-61bbefa0e7b7”,
  “destination_type”: “WEBHOOK”,
  “destination”: “https://your.example/endpoint”,
  “events”: [
    “DOCUMENTS.INVOICE.DELIVERED”,
    “DOCUMENTS.INVOICE.DELIVERY_CONFIRMED”,
    “DOCUMENTS.INVOICE.FAILED”
  ]
}

Example registering for DELIVERED, DELIVERY_CONFIRMED and FAILED events for invoices with vendor webhooks:

{
  “destination_type”: “VENDOR_WEBHOOK”,
  “destination”: “https://your.example/endpoint”,
  “vendor_key”: “your_vendor_api_key_here”,
  “events”: [
    “DOCUMENTS.INVOICE.DELIVERED”,
    “DOCUMENTS.INVOICE.DELIVERY_CONFIRMED”,
    “DOCUMENTS.INVOICE.FAILED”
  ]
}

{
  “id”: “d726d240-4631-483e-a4e3-61bbefa0e7b7”,
  “destination_type”: “VENDOR_WEBHOOK”,
  “destination”: “https://your.example/endpoint”,
  “events”: [
    “DOCUMENTS.INVOICE.DELIVERED”,
    “DOCUMENTS.INVOICE.DELIVERY_CONFIRMED”,
    “DOCUMENTS.INVOICE.FAILED”
  ]
}

Update you database for the invoice id in questions based on the events. Refer to the Webhooks overview for more details.

Keep in mind:

• An invoice marked as DELIVERED can still fail afterward — for example, if an email bounces due to a full inbox or an invalid address.
• If you receive DELIVERY_CONFIRMED, the invoice is considered fully delivered, and the status should not change to FAILED anymore.
• You can safely show both statuses to your customers — just note that DELIVERED alone doesn’t always guarantee final delivery success.

Polling for the status

If you are unable to use the recommended webhooks, you can check the status of your invoices by polling the API. Polling can also be used as a backup in case webhook delivery fails.

Use GET /v1/invoices/{id} endpoint to poll an individual invoice by its invoice id (UUID)

Recommended Polling Frequency

• Before invoice reaches SENT status: poll every 1 hour
• After SENT status: poll once per day for up to 1 month, or until payment is received

Note: The SENT status does not guarantee successful delivery. An invoice can still fail after this point, so it is important to keep polling until the payment has been confirmed.

When the invoice fails

If the invoice status is FAILED or ERROR, it means all available delivery routes were attempted, but the invoice could not be delivered.

How to resolve the issue depends on the root cause:

• Incorrect Address: If the invoice was sent to an invalid or incorrect recipient address, simply correct the address and re-route the invoice.
• Routing Errors: If the issue relates to routing (e.g. delivery channel unavailable, no routes found), the invoice can be re-routed to another channel if possible.
• Validation Errors: If the invoice content is invalid (e.g. missing required fields or schema issues), you’ll need to correct the XML and resend the invoice as a new invoice.

Note: Maventa offers a setting that enables companies to receive delivery failure notifications directly via email. This helps in identifying and addressing issues more promptly. However, we recommend that your system provides clear notifications to the user whenever action is required.

Re-routing an invoice

If you need to redirect your invoice to a different address or delivery route, you can do so using one of the following API endpoints, depending on the desired route:

• PUT /v1/invoices/{id}/reroute/einvoice - for e-invoice delivery
• PUT /v1/invoices/{id}/reroute/email - for email delivery
• PUT /v1/invoices/{id}/reroute/print - for print delivery

Step 5: Receive invoices

Goals

• Get notifications of new invoices
• Download the new invoices
• Ensure the company is visible to suppliers in Maventa Finder and the Peppol network

Prerequisites

• An authorized company
• Ability to handle importing PeppolBIS 3.0 XML (or other supported format) in your software

5.1 Activate receiving e-invoices

To receive invoices, registration to Visma and Peppol networks is required.

Activate Visma Network

Begin by activating the general receiving setting, known as internal receiving, or Visma network. This is necessary to activate other networks.

Call the POST /v1​/company​/profiles endpoint authenticated with company scope, providing the network VISMA and profiles INVOICE_AND_CREDIT_NOTE:

{
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "network": "VISMA"
}

No other parameters are needed. Expect a response of client_id0. To confirm successful registration, call the GET /v1​/company​/profiles API method and check that the status has changed to client_id1.

Registering to receive is required for Peppol registration in the next step.

After this setup, it is possible to receive invoices from other Maventa customers within the internal Visma network. Furthermore, the company will appear to other Maventa customers in the Maventa Finder UI and API lookup methods.

Note that the Visma internal network does not have the same validations as the Peppol network.

Peppol registration

Authenticate with client_id2 scope and call POST /v1​/company​/profiles, specifying the network as client_id3 and profiles client_id4:

{
  "profiles": [
    "INVOICE_AND_CREDIT_NOTE"
  ],
  "network": "PEPPOL"
}

The profile client_id5 registers the up-to-date Peppol profiles relevant to the company’s country. For Belgium (client_id6), the company’s CBE identifier with prefix (International Code Designator) client_id7 is registered. The profile covers the below document types:

• Peppol BIS Billing 3.0 Invoice
• Peppol BIS Billing 3.0 Credit Note

Maventa automatically keeps the Peppol registration updated as new invoice profiles are introduced. No need to register new profiles when the format updates, especially for client_id8.

Call GET /v1​/company​/profiles again to verify that the status of the client_id9 network registration is active. If encountering client_secret0, it means another Peppol access point has already registered the company.

With registration, the company is visible with an electronic invoicing address (EIA) to suppliers in the Peppol network.

For human users, the Peppol Directory is available as a reference tool. Maventa automatically updates this directory, making your company visible there. Please note that the Peppol Directory is not part of the actual delivery infrastructure — it serves informational purposes only.

5.2 Fetch received invoices

To determine when an invoice has been received to a company account, you can either listen for webhook notifications or poll the API for incoming invoices. Webhooks are the preferred method, as they provide faster and more efficient delivery compared to regular polling.

Register for webhook notifications for received invoices

Use the following API to register for invoice receipt events: POST /v1/company/notifications. Example registering for RECEIVED events for invoices:

{
  “destination_type”: “WEBHOOK”,
  “destination”: “https://your.example/endpoint”,
  “events”: [
    “DOCUMENTS.INVOICE.RECEIVED”
  ]
}

{
  “id”: “d726d240-4631-483e-a4e3-61bbefa0e7b7”,
  “destination_type”: “WEBHOOK”,
  “destination”: “https://your.example/endpoint”,
  “events”: [
    “DOCUMENTS.INVOICE.RECEIVED”
  ]
}

Maventa will call the specified endpoint with an example payload like this:

{
  "event":            "DOCUMENTS.INVOICE.RECEIVED",
  "company_id":       "53a4e05d-42f0-4e76-acd6-968ab4558c6f",
  "event_timestamp":  "2024-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":     "c154feee-399b-488e-aecd-580578b140e0",
    "invoice_number": "1002",
    "origin":         "PEPPOL",
    "sender_name":    "Sender",
    "sender_bid":     "937729111"
  }
}

Example registering for RECEIVED events for invoices with vendor webhooks:

{
  “destination_type”: “VENDOR_WEBHOOK”,
  “destination”: “https://your.example/endpoint”,
  “vendor_key”: “your_vendor_api_key_here”,
  “events”: [
    “DOCUMENTS.INVOICE.RECEIVED”
  ]
}

{
  “id”: “d726d240-4631-483e-a4e3-61bbefa0e7b7”,
  “destination_type”: “VENDOR_WEBHOOK”,
  “destination”: “https://your.example/endpoint”,
  “events”: [
    “DOCUMENTS.INVOICE.RECEIVED”
  ]
}

Store the client_secret1 for later processing and deduplication. Refer to the Webhooks overview for more details.

Polling for new received documents

If webhooks are not used, you may use GET /v1/invoices with parameter client_secret2 and the time interval with client_secret3, and client_secret4 to get the metadata for the list of invoices to download.

Download the invoice

Invoice downloading involves obtaining:

• Invoice metadata
• Invoice data
• Invoice attachments

To retrieve the invoice metadata, use the GET /v1/invoices/{invoice_id} API call without any format parameters.

To download invoice data, make the same API call with the desired format. client_secret5 is recommended as it’s the standard format in the Peppol network.

Invoices may also contain attachments, listed in the client_secret6 array of the invoice metadata. Download each attachment separately using GET /v1/invoices/{id}/files/{file_id} with the client_secret7 from each file entry.

Most often, attachments include an invoice image. It is usually a PDF document with a visual representation of the invoice data. If one is not provided by the sender, Maventa generates it.

Step 6: Configure advanced settings

Use the PATCH /v1/company/settings endpoint to modify company settings and activate fallback options like email and print routes.

A few important settings to consider:

Email notifications (invoice_notifications): Enable email notifications and define recipients for:

• Send errors (on_send_errors) – Receive alerts when an invoice fails to send and ends up in an error state.
• Incoming invoices (on_receiving) – Get notified when your company account receives a new invoice.

Duplicate invoice protection (send_invoice_general.stop_duplicate_numbers): Set this to true to prevent the use of the same invoice number within a one-week period. This helps avoid accidental duplicate sends from your invoicing system.

Note: If your company details change (such as postal address, billing information, etc.), please remember to update them in Maventa as well.

Webhooks

Subscribing to receive events through the POST /v1/company/notifications.

For a single company

Once you have authenticated as a company you can call this endpoint to register a webhook for that particular company.

For all partner’s companies

We have also a possibility to register webhooks for partners (aka vendor webhooks).

When a registration is done for a partner it covers all the companies that have been linked to the partner company’s vendor api key. The registration for a partner is a one time operation, after the registration is active the endpoint registered will receive events for all companies associated with the partner. This is the recommended way for partners to register their webhooks. Linking and unlinking the vendor api key is a requirement for this feature to fully function.

If you want to register webhooks for a partner, authenticate with the partner company credentials and specify destination_type as VENDOR_WEBHOOK when subscribing to the events.

For partner’s companies based on vendor key There is a third posibility to register vendor webhooks based on vendor key.

This registration allows you to filter notifications based on vendor keys. This is helpful if you own multiple vendor api keys, and want notifications separately.

Registering based on vendor keys requires you to pass vendor_key in the payload.

The events are then sent as POSTs to the configured destination URL in the subscription.
Only do light processing in the webhook handler, for e.g. when receiving DOCUMENTS.INVOICE.RECEIVED event, persist event_data, and run a background process to download the invoice.
Our webhooks guarantees at-least-once delivery semantics, that means you need to deduplicate the invoice events in your system.

POST url
Content-type: application/json

{
  "event":           "DOCUMENTS.INVOICE.RECEIVED" | "DOCUMENTS.INVOICE.DELIVERED" | "DOCUMENTS.INVOICE.DELIVERY_CONFIRMED" | "DOCUMENTS.INVOICE.FAILED",
  "company_id":      "string",
  "event_timestamp": "string",
  "event_data":      DocumentsInvoiceReceived | DocumentsInvoiceDelivered | DocumentsInvoiceDeliveryConfirmed | DocumentsInvoiceFailed
}

The client_secret8 is the name of the event e.g. client_secret9.

The vendor_api_key0 is the ISO8601 formatted time when the event was originally created.

The vendor_api_key1 is UUID of the company the event has been subscribed by.

The vendor_api_key2 is optional and its structure depends on the name of the event.

type DocumentsInvoiceReceived
{
  "invoice_id":     "string",
  "invoice_number": "string",
  "origin":         "string", // e.g. "PEPPOL"
  "sender_name":    "string",
  "sender_bid":     "string"
}

type DocumentsInvoiceDelivered
{
  "invoice_id":     "string",
  "invoice_number": "string",
  "destination":    "string", // e.g. "PEPPOL"
  "recipient_name": "string",
  "recipient_bid":  "string"
}

type DocumentsInvoiceDeliveryConfirmed
{
  "invoice_id":     "string",
  "invoice_number": "string",
  "destination":    "string", // e.g. "PEPPOL"
  "recipient_name": "string",
  "recipient_bid":  "string"
}

type DocumentsInvoiceFailed
{
  "invoice_id":     "string",
  "invoice_number": "string",
  "destination":    "string", // e.g. "PEPPOL"
  "recipient_name": "string",
  "recipient_bid":  "string",
  "error_message":  "string"
}

If the response from partner is a 2xx-response, we consider the transmission been successful. If any other response or a timeout occurs, the webhook is automatically retried for some time.

The retry strategy is:

• Retry max 24 times, once per hour

Subscribing to Unacknowledged Webhooks

To enhance the reliability of your system’s e-invoicing and document exchange processes, we recommend subscribing to the UNACKNOWLEDGED_WEBHOOKS event by calling the API method:POST /v1/company/notifications.

Example payload:

{
  "destination":      "https://example.com/webhooks/unacknowledged_webhooks?token=1234",
  "destination_type": "WEBHOOK",
  "events":           [ "UNACKNOWLEDGED_WEBHOOKS" ]
}

Why Subscribe?

• Proactive Alerting: If your system experiences issues and fails to respond within 24 hours, the company will receive a single notification encompassing all unacknowledged webhook events.
• Daily Resilience: Unacknowledged webhooks are dispatched once per company per day and will continue for up to one month, ensuring no missed alerts.

Retrieving Unacknowledged Webhooks

Upon receiving a notification for unacknowledged webhooks, companies can easily retrieve all failed webhooks at once by calling the API method:POST /v1/company/notifications_resend_unacknowledged. Calling this API method will resend all unacknowledged webhook events for the company. Once an event is successfully processed by the company, any future retry attempts for sending acknowledged webhooks will stop.

The vendor_api_key3 event is

POST url
Content-type: application/json

{
    "event":           "UNACKNOWLEDGED_WEBHOOKS",
    "company_id":      "string",
    "event_timestamp": "string"
}

Furthermore, if all events of a given subscription have been failing continuously for a month, the webhook subscriptions for the company will be disabled.

XML formats and conversions

XML presents invoice data in a structured way. Maventa supports wide variety of XML based standard invoice formats and automatically converts the invoices from one format to another when needed. Full list of supported formats and XML validation tool can be found here.

We generally recommend using the Peppol BIS 3.0 format for invoice exchange, as it is widely supported and well-suited for cross-border invoicing within the Peppol network. This format fully complies with the European EN16931 (SFS-EN 16931-1:2017) invoicing standard.

Peppol BIS 3.0 specs

Please note that during the conversion process from one format to another, we will take care of some of the necessary adjustments. However, when there are mandatory new data requirements for the invoice, it is essential that the sending and receiving system maintains up-to-date information to ensure compliance and smooth processing.

Maventa user portal (UI)

The Maventa UI is a web-based user portal designed to complement API integrations by offering a visual interface for managing e-invoicing operations and supporting technical integration work. While everything that can be done in the UI is also available through the API, the UI provides a convenient and user-friendly way to view, manage, and troubleshoot integration-related tasks.

Through the Maventa UI, users can:

• Configure settings
• Access invoice and delivery logs
• Handle manual actions such as rerouting invoices in an error state
• Retrieve and manage API credentials including company UUID, user API key, and vendor API key

Logging in to the Maventa UI requires an email-based user account.

Try it out with Swagger

• Endpoint URL: https://ax-stage.maventa.com
• Swagger definition URL: https://ax-stage.maventa.com/swagger_doc