# Maventa documentation — full content

> Maventa documentation
>
> This file is the full canonical documentation concatenated into one
> document. **Changelog entries are not included here** because individual
> changelog entries can reference deprecated APIs, renamed products, and
> outdated activation steps; mixed into a single bundle that context is
> easily lost. For historical changelog content, fetch individual entries
> under `https://documentation.maventa.com/changelogs/developer-changelog/<slug>.md` and
> `https://documentation.maventa.com/changelogs/product-changelog/<slug>.md`, or see the index at
> `https://documentation.maventa.com/llms.txt`.
>
> Generated 2026-05-05. Always prefer the live site for the
> most current information.


# Integration Guide

## Getting Started
Source: https://documentation.maventa.com/integration-guide/getting-started/

This guide shows how Maventa enables seamless e-invoicing and document exchange through your financial system. It explains the available APIs, key capabilities, and market-specific requirements, helping you understand what is needed to start sending invoices, support consumer invoicing, or serve customers across different countries, whatever your business needs across e-invoicing and digital document exchange.

The Maventa APIs support a wide range of business use cases, including electronic invoicing for **B2B,** (Business-to-Business — commercial transactions between companies) **B2G** (Business-to-Government — invoicing directed at public sector entities) scenarios, consumer invoicing to bank networks and mobile applications, electronic ordering and other business document exchange, access to value-added services supporting purchase-to-pay and order-to-cash processes, as well as custom applications and import tools. Availability of specific features may vary depending on the country or market, so not all functionality is supported in every region.

## APIs available for integration

Maventa provides two APIs for integration: REST and SOAP. Both can be used, but not all functionality is available via the SOAP API. Going forward, new features and improvements will be delivered exclusively through the REST API.

### REST API

The REST API provides access to account management and e-invoicing services, as well as other business document flows such as order exchange. It also enables integration with advanced services supporting **P2P** (Purchase-to-Pay — the full cycle from purchasing goods to making payment) and **O2C** (Order-to-Cash — the full cycle from receiving an order to collecting payment) processes.

[View REST API docs](/api-specification/rest-api/getting-started/)

### SOAP API

The SOAP API provides access to account management and e-invoicing services, but is considered legacy and does not support all available features.

[View SOAP API docs](/api-specification/soap-api/getting-started/)

## Choosing the right integration approach

There are multiple ways to integrate with Maventa, depending on the services you want to offer and the level of automation you require. The following sections help you define the scope and depth of your integration.

### Integration scope - what you want to support

The integration scope defines which Maventa services you connect to and what functionality your users will have. When defining the scope, consider whether you need to support sending invoices and documents, receiving invoices and documents, or all. You should also determine whether your customers require B2B, B2G, or B2C invoicing, as consumer invoicing options vary by market and delivery channel.

In addition, consider which optional services your customers may need. Maventa offers services such as printing, scanning, receivables management, and supplier activation to support and enhance the invoicing flow.

### Integration level - how deeply you want to integrate

The development effort required for a Maventa integration can range from using a small set of API endpoints to building a fully automated, end-to-end solution. Higher integration levels provide richer functionality but require more development work. For example, you can choose whether users interact with the Maventa UI or whether all actions are handled entirely within your ERP system.

<!-- Level 1 – Low Effort -->
<section class="mx-auto max-w-5xl px-4 py-6">
  <header class="mb-4 text-center">
    <div class="text-2xl font-bold text-gray-900 dark:text-gray-100">
      Level 1 – Low Effort 
      <wa-icon name="rocket" class="ml-2 text-blue-600 dark:text-blue-400"></wa-icon>
    </div>
    <p class="text-sm text-gray-600 dark:text-gray-400">Basic value • Minimal automation</p>
  </header>

  <!-- Grid ensures each pillar = 1/3 width; items-end aligns bottoms -->
  <div class="h-auto md:h-72 grid grid-cols-1 md:grid-cols-3 gap-3 md:gap-6 items-end">
    <!-- API -->
    <div class="h-48 md:h-5/6 rounded-xl bg-emerald-600/95 dark:bg-emerald-700/95 text-emerald-50 shadow-md flex flex-col relative overflow-hidden">
      <div class="py-3 text-base font-bold uppercase text-center">API</div>
      <ul class="px-6 pb-3 text-sm space-y-1.5">
        <li>Sending invoices</li>
        <li>Receiving invoices</li>
      </ul>
      <wa-icon name="code" class="text-5xl absolute bottom-3 right-3 text-emerald-900/20 dark:text-emerald-950/30"></wa-icon>
    </div>

    <!-- Web UI -->
    <div class="h-48 md:h-5/6 rounded-xl bg-sky-600/95 dark:bg-sky-700/95 text-sky-50 shadow-md flex flex-col relative overflow-hidden">
      <div class="py-3 text-base font-bold uppercase text-center">Web UI</div>
      <ul class="px-6 pb-3 text-sm space-y-1.5">
        <li>Companies &amp; Settings</li>
        <li>Monitoring invoices</li>
      </ul>
      <wa-icon name="browser" class="text-5xl absolute bottom-3 right-3 text-sky-900/20 dark:text-sky-950/30"></wa-icon>
    </div>

    <!-- Email -->
    <div class="h-40 md:h-2/3 rounded-xl bg-amber-600/95 dark:bg-amber-700/95 text-amber-50 shadow-md flex flex-col relative overflow-hidden">
      <div class="py-3 text-base font-bold uppercase text-center">Email</div>
      <ul class="px-6 pb-3 text-sm space-y-1.5">
        <li>Handling errors</li>
      </ul>
      <wa-icon name="envelope" class="text-5xl absolute bottom-3 right-3 text-amber-900/20 dark:text-amber-950/30"></wa-icon>
    </div>
  </div>

  <p class="mt-4 text-sm font-medium text-gray-700 dark:text-gray-300 text-center bg-gray-100 dark:bg-gray-800 rounded-lg py-3 px-4">
    <wa-icon name="arrow-right" class="mr-2 text-blue-600 dark:text-blue-400"></wa-icon>
    Suitable for quick start. Mix of API + UI + Email.
  </p>
</section>

<!-- Level 2 – Medium Effort -->
<section class="mx-auto max-w-5xl px-4 py-6">
  <header class="mb-4 text-center">
    <div class="text-2xl font-bold text-gray-900 dark:text-gray-100">
      Level 2 – Medium Effort 
      <wa-icon name="balance-scale" class="ml-2 text-purple-600 dark:text-purple-400"></wa-icon>
    </div>
    <p class="text-sm text-gray-600 dark:text-gray-400">High value • More automation</p>
  </header>

  <div class="h-auto md:h-72 grid grid-cols-1 md:grid-cols-3 gap-3 md:gap-6 items-end">
    <!-- API -->
    <div class="h-40 md:h-2/3 rounded-xl bg-emerald-600/95 dark:bg-emerald-700/95 text-emerald-50 shadow-md flex flex-col relative overflow-hidden">
      <div class="py-3 text-base font-bold uppercase text-center">API</div>
      <ul class="px-6 pb-3 text-sm space-y-1.5">
        <li>Sending invoices</li>
        <li>Receiving invoices</li>
      </ul>
      <wa-icon name="code" class="text-5xl absolute bottom-3 right-3 text-emerald-900/20 dark:text-emerald-950/30"></wa-icon>
    </div>

    <!-- Web UI (taller) -->
    <div class="h-52 md:h-full rounded-xl bg-sky-600/95 dark:bg-sky-700/95 text-sky-50 shadow-md flex flex-col relative overflow-hidden">
      <div class="py-3 text-base font-bold uppercase text-center">Web UI</div>
      <ul class="px-6 pb-3 text-sm space-y-1.5">
        <li>Companies &amp; Settings</li>
        <li>Monitoring invoices</li>
        <li>Handling errors</li>
      </ul>
      <wa-icon name="browser" class="text-5xl absolute bottom-3 right-3 text-sky-900/20 dark:text-sky-950/30"></wa-icon>
    </div>

    <!-- Email (empty, faded) -->
    <div class="h-32 md:h-1/4 rounded-xl bg-amber-600/70 dark:bg-amber-700/70 text-amber-50 shadow-md flex flex-col relative overflow-hidden">
      <div class="py-3 text-base font-bold uppercase text-center opacity-60">Email</div>
      <ul class="px-6 pb-12 text-sm space-y-1.5 opacity-60">
      </ul>
      <wa-icon name="envelope" class="text-4xl absolute bottom-2 right-2 text-amber-900/15 dark:text-amber-950/20 opacity-60"></wa-icon>
    </div>
  </div>

  <p class="mt-4 text-sm font-medium text-gray-700 dark:text-gray-300 text-center bg-gray-100 dark:bg-gray-800 rounded-lg py-3 px-4">
    <wa-icon name="arrow-right" class="mr-2 text-blue-600 dark:text-blue-400"></wa-icon>
    More automation than Level 1, but still partly dependent on Web UI.
  </p>
</section>

<!-- Level 3 – High Effort -->
<section class="mx-auto max-w-5xl px-4 py-6">
  <header class="mb-4 text-center">
    <div class="text-2xl font-bold text-gray-900 dark:text-gray-100">
      Level 3 – High Effort 
      <wa-icon name="gem" class="ml-2 text-indigo-600 dark:text-indigo-400"></wa-icon>
    </div>
    <p class="text-sm text-gray-600 dark:text-gray-400">Maximum value • Full automation</p>
  </header>

  <div class="h-auto md:h-72 grid grid-cols-1 md:grid-cols-3 gap-3 md:gap-6 items-end">
    <!-- API (tallest) -->
    <div class="h-56 md:h-full rounded-xl bg-emerald-600/95 dark:bg-emerald-700/95 text-emerald-50 shadow-md flex flex-col relative overflow-hidden">
      <div class="py-3 text-base font-bold uppercase text-center">API</div>
      <ul class="px-6 pb-3 text-sm space-y-1.5">
        <li>Sending invoices</li>
        <li>Receiving invoices</li>
        <li>Handling errors</li>
        <li>Companies &amp; Settings</li>
        <li>Monitoring invoices</li>
      </ul>
      <wa-icon name="code" class="text-5xl absolute bottom-3 right-3 text-emerald-900/20 dark:text-emerald-950/30"></wa-icon>
    </div>

    <!-- Web UI (short, empty, faded) -->
    <div class="h-32 md:h-1/3 rounded-xl bg-sky-600/70 dark:bg-sky-700/70 text-sky-50 shadow-md flex flex-col relative overflow-hidden">
      <div class="py-3 text-base font-bold uppercase text-center opacity-60">Web UI</div>
      <ul class="px-6 pb-12 text-sm space-y-1.5 opacity-60">
      </ul>
      <wa-icon name="browser" class="text-4xl absolute bottom-2 right-2 text-sky-900/15 dark:text-sky-950/20 opacity-60"></wa-icon>
    </div>

    <!-- Email (short, empty, faded) -->
    <div class="h-32 md:h-1/3 rounded-xl bg-amber-600/70 dark:bg-amber-700/70 text-amber-50 shadow-md flex flex-col relative overflow-hidden">
      <div class="py-3 text-base font-bold uppercase text-center opacity-60">Email</div>
      <ul class="px-6 pb-12 text-sm space-y-1.5 opacity-60">
      </ul>
      <wa-icon name="envelope" class="text-4xl absolute bottom-2 right-2 text-amber-900/15 dark:text-amber-950/20 opacity-60"></wa-icon>
    </div>
  </div>

  <p class="mt-4 text-sm font-medium text-gray-700 dark:text-gray-300 text-center bg-gray-100 dark:bg-gray-800 rounded-lg py-3 px-4">
    <wa-icon name="arrow-right" class="mr-2 text-blue-600 dark:text-blue-400"></wa-icon>
    Full automation. Everything handled via API. No UI or Email.
  </p>
</section>


The appropriate integration level depends on your automation needs. It is also possible to start with a simpler integration and extend it over time.

## Integration process overview - from setup to production

Integrating with Maventa typically involves setting up the connection, validating it in the testing environment, and enabling it in production. Before accessing the production environment, all integrators must complete and sign the Maventa Integration Agreement, which defines key aspects such as billing and support. This agreement is provided by your integration contact.

Instructions for obtaining API keys for testing and production are described below.

> [!NOTE]
> **Contact us before you start building**
>
> Before you start building the integration, we recommend reaching out to our [sales team](https://maventa.com/contact#sales). They will introduce you to the service, assess your business needs, and connect you with our integration care team. Our integration care team will then provide all the necessary technical support to help you build and refine your integration. Depending on your needs, we may also arrange an integration kick-off meeting or additional training to ensure a successful implementation.

### Integration setup

#### 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](https://testing.maventa.com/registrations?lang=en). To obtain a partner company account, contact our integration care team at <integrations@maventa.com>.  

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

> [!IMPORTANT]
> **`client_id`** – Identifies the company (in this case your partner company account) (Company UUID).

> [!IMPORTANT]
> **`client_secret`** – Identifies the user of that company (User API key).

> [!IMPORTANT]
> **`vendor_api_key`** – Identifies your 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.

<details>
<summary>**Question:** What is a vendor?</summary>

In Maventa, a **vendor** refers to the software that is integrated with the service. A **partner account** can have one or more vendors, each represented by a **software API key** (vendor API key). This key is used to authenticate the software when connecting to Maventa via the API.

- The **vendor API key** uniquely identifies the software connecting to Maventa.  
- A single partner account can manage multiple vendor API keys — for example, to support different software products or operations in different countries.  
- All vendor API keys are managed under the same partner account, which is the entity that owns and oversees these integrations.
</details>

#### Get access to the production environment

Before moving to the production environment, the integration must be thoroughly tested in the Maventa testing environment. This includes verifying that the core integration flows work as expected: invoices are routed to the correct destinations with accurate data, sending via the Peppol network functions correctly for applicable countries, consumer invoicing is properly configured when in use, received invoices are downloaded in the correct format, webhooks are delivered and processed successfully, and polling intervals are set to reasonable values and so on.

In addition, all integrators are required to complete and sign the Maventa Integration Agreement, which defines key topics such as billing, responsibilities, and support. The agreement will be provided by your integration contact person, either from sales or integration care.

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

> [!NOTE]
> Note that the testing and production endpoints of the API use different API keys. API keys from testing will not work on production and vice versa. Errors like *USER NOT FOUND* mean that the `user_api_key` is wrong for that environment. Please, make sure you are using the correct API endpoint for your API key.

## Testing environment

The Maventa testing environment allows you to simulate most invoice sending and document exchange processes before moving to production. However, the behavior depends on the route:

### Real Sends

- Internal sends between Maventa customers function the same as in production.
- Peppol sends are processed as real transactions within the Peppol test network.

### Simulated Sends

- External operator routes in Finland and Sweden
- Consumer routes
- Email and print deliveries

Simulated sends are not actually delivered, they are marked as SENT in Maventa to mimic real processing.

> [!NOTE]
> Important Notes
>
> - All notification emails related to account management and error handling are sent to the actual recipients. Only use email addresses you have access to, avoid using addresses like `test@test.com` or your customers’ real addresses.
> - If you need to test sending invoices via email to a real recipient, please contact [support.maventa@visma.com](mailto:support.maventa@visma.com) to enable this for your account.
> - The testing environment is also used for internal testing, so it may differ from production. It can be temporarily unavailable, and the database may be cleared without notice. For privacy reasons, do not use real production data in the testing environment.

## 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 most functionality available in the UI is also accessible 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.

---

## Invoice sending
Source: https://documentation.maventa.com/integration-guide/invoice-sending/invoice-sending/

Maventa delivers invoices as e-invoices through multiple networks — country-specific networks, Peppol, or fallback methods like email and print. Send the invoice to Maventa and let it automatically choose the best delivery route based on the recipient’s data, or specify a route manually — for example, email.

For details on available delivery channels in each market, see the country-specific guides. For more information about Peppol, see the [Peppol network page](/integration-guide/peppol/peppol-network/).

> [!NOTE]
> This guide assumes you have API credentials and can authenticate with the Maventa REST API. If you haven’t set up your integration yet, start with the [getting started guide](/integration-guide/getting-started/) to obtain your API keys and learn about authentication. For detailed authentication instructions, see the [REST API getting started page](/api-specification/rest-api/getting-started/).

To send an invoice, you need:

* **Sender company account**: A company account in Maventa. Invoice sending is enabled by default, but additional services like the print service must be activated separately.
* **Invoice XML**: An invoice XML file from your system in a supported e-invoice format. Attachments or a custom invoice image can also be included.
* **Recipient information**: An electronic invoicing address, business ID, email, or postal address for the recipient.

## Step 1: Prepare your invoice

Generate and prepare the invoice along with any necessary attachments in your system, then send them to Maventa via the API.

### Create the XML file

Create a valid XML file by mapping data from your system into the required XML structure.

XML structures invoice data in a standardised way. Maventa supports a wide range of XML formats and automatically converts invoices between them when needed. See the full list of [supported formats](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Validator+API) and more information about [invoicing formats](/integration-guide/invoicing-formats/invoicing-formats/).

Maventa recommends Peppol BIS 3.0, as it is widely supported and well suited for cross-border invoicing. This format fully complies with the European EN16931 (SFS-EN 16931-1:2017) standard. In some cases, it may be more practical to choose a format based on the countries your companies operate in and the type of invoicing you need. For example, in Finland and for B2C invoicing, Finvoice is the recommended format.

The specific format typically does not make a significant difference, as most formats are compatible in terms of core content. Any missing data can be provided as API parameters.

> [!WARNING]
> The maximum invoice number length is 20 characters. If the invoice number exceeds this limit, it will be automatically truncated to 20 characters.

### Recipient lookup and routing

To confirm that a recipient can receive e-invoices, perform a lookup before sending. If the recipient cannot receive e-invoices, the invoice can be sent via fallback delivery routes such as email or print. You can handle this lookup yourself or let Maventa do it automatically.

Maventa follows a predefined delivery route order based on the sender’s country. Generally, Maventa first tries delivery through its internal network, then through Peppol or country-specific e-invoicing networks (order varies by country), and finally through fallback routes — email first, then print as the last resort.

You can influence this routing by defining which delivery routes are allowed or restricted, either directly in the XML file or via API metadata.

#### Automatic lookup and routing

* Matching based on e-invoice address:

If you provide a valid e-invoice address, such as a **Peppol ID** (A Peppol participant identifier consisting of a scheme prefix and company identifier, used to route documents within the Peppol network) (e.g., `9925:be000000000b21`) or another supported identifier, Maventa looks up the recipient in e-invoice address registries and attempts 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 attempts to find one 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 attempts delivery through the identified route.

> [!NOTE]
> Automatic lookup of the recipient’s e-invoicing address using just the business ID works only in the following situations:
>
> * Internal Maventa recipients
> * Finnish recipients via Finnish operator and bank networks
> * Swedish recipients via the Swedish operator network or Peppol
> * Norwegian recipients via Peppol
> * Dutch recipients via Peppol
>
> For recipients from all other countries, the full e-invoicing address must always be provided, including the scheme ID from [the eDec list](https://docs.peppol.eu/edelivery/codelists/) followed by the correct recipient ID.

* Alternative fallback delivery routes:

If no e-invoice address is found, or if delivery to the identified address fails, Maventa can still deliver the invoice through other routes — such as email or print. This is determined by your account configuration, metadata provided in the sending method, or data on the invoice.

<details>
<summary>E-invoicing address registries used by Maventa</summary>

Maventa performs recipient lookups using multiple e-invoicing registries to find the correct e-invoice address for delivery:

* [Peppol directory](https://directory.peppol.eu/public) – If the recipient is registered in the Peppol network, Maventa retrieves their Peppol ID and supported document types.
* Maventa’s own registry – Maventa maintains an internal registry of companies using its service, allowing invoices to be routed efficiently within its network.
* [Finnish TIEKE registry](https://verkkolaskuosoite.fi/client/) – For companies in Finland, Maventa checks the TIEKE e-invoice address registry, which contains Finnish business e-invoicing details.
* [Swedish NEA registry](https://eregister.nea.nu/nea/) – Used for finding e-invoice addresses of companies in Sweden.
</details>

<details>
<summary>How to use email and print as fallback routes</summary>

* To use the email route, email sending must be enabled on your company account. It is enabled by default but can be toggled in the company settings. Include the recipient’s email address either in the invoice XML or as a parameter (`recipient_email`) in the API metadata. Also make sure the email route is not disabled in the sending configuration (`disabled_routes`). For more details, see the [email invoicing guide](/integration-guide/invoice-sending/email-invoicing/).

* To use the print route, the print service must be enabled on your company account. The recipient’s full postal address should be included in the invoice XML. Also make sure the print route is not disabled in the sending configuration (`disabled_routes`). For more details, see the [printing guide](/integration-guide/invoice-sending/printing/).
</details>

#### Manual lookup

To perform the lookup yourself before sending, use the [GET /v1/lookup/receivers](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/lookup/getV1LookupReceivers) method. You can search by company name, business ID (VAT number or national business registry number), or e-invoice address (e.g., **OVT** (Finnish e-invoice address identifier, created by combining prefix '0037' with the Business ID without hyphen), **GLN** (Global Location Number — an international identifier for business locations, using Peppol scheme '0088')).

API parameters:

* `network` — `PEPPOL` for recipients in the Peppol network, `INTERNAL` for recipients within Maventa’s internal network, `EXTERNAL` for recipients in external registries (e.g., Finnish or Swedish operator networks), `SPROOM` for recipients behind Sproom and Nemhandel
* `eia` — the recipient’s full **e-invoice address (EIA)** (Electronic Invoicing Address — the unique identifier used to route e-invoices to the correct recipient, such as an OVT number or Peppol ID), if known
* `bid` — the recipient’s business ID, if the e-invoice address is not known
* `name` — the recipient’s name, if no other identifier is available
* `country` — the recipient’s ISO country code, to narrow down results

> [!WARNING]
> When searching for recipients in the Peppol network, there is a known limitation with this API. To perform a Peppol Directory lookup, you must use the name field for either the recipient’s name or business ID. The bid field does not currently work for Peppol lookups. This behaviour will be corrected in a future version of the lookup API, but for now, please keep this in mind when performing searches.

The lookup determines whether the recipient can receive electronic invoices and through which delivery route. It also returns the recipient’s e-invoicing address (e.g., a Peppol participant identifier such as `9925:be000000000b21`) and which Peppol document types the recipient supports (`INVOICE` or `CREDIT_NOTE`).

### Request URL

```json
https://ax.maventa.com/v1/lookup/receivers?network=PEPPOL,INTERNAL,EXTERNAL&name=3478209-8&country=FI&page=1&per_page=100
```

### Response

```json
[
  {
    "eia": "0216:003734782098",
    "network": "PEPPOL",
    "operator": "PEPPOL",
    "document_types": [
      {
        "document_type": "CREDIT_NOTE",
        "document_identifier": "urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
        "process_identifier": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
      },
      {
        "document_type": "INVOICE",
        "document_identifier": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
        "process_identifier": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
      }
    ],
    "participant": {
      "name": "Maventa Oy",
      "country": "FI"
    }
  }
]
```

#### How to use recipient data on the invoice

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

* In the XML file – depending on the format, this may even be mandatory (e.g., Peppol BIS 3.0).
* As parameters in the API call – if both XML and API parameters are provided, the API parameters take precedence.

If both a business ID and an Endpoint ID are included in the XML, the Endpoint ID will take priority for routing the invoice. Note that automatic lookup by business ID alone is only supported for certain countries — see [automatic lookup and routing](#automatic-lookup-and-routing) for details.

Example: Including e-invoice address (EndpointID) for Peppol BIS 3.0:

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

> [!WARNING]
> The EndpointID is mandatory in Peppol BIS 3.0 and must always be included.

> [!NOTE]
> When using Peppol BIS 3.0, the operator ID cannot be included in the XML. If an invoice needs to be routed via Peppol, the Peppol operator can be specified in the API metadata. Note that providing only the operator code in the metadata will work exclusively for routing through the Peppol network.

### Invoice image and attachments

How invoice images (such as PDFs) and other attachments are included depends on the invoice format. 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).

Follow the specific requirements of each format to ensure successful processing and delivery. Keep in mind that not all recipients 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.

Supported file types: pdf (recommended), tif, tiff, jpg, jpeg, png, gif, txt, xml, xls, xsl, xlsx, html, htm, aix, doc, docx, ods, csv.

> [!NOTE]
> Only the following [MIME types](https://docs.peppol.eu/poacc/billing/3.0/codelist/MimeCode/) are supported in Peppol.

> [!WARNING]
> PDF attachments must be provided without encryption or any form of security restriction. Files that are password-protected or have restricted permissions (e.g., preventing printing or content extraction) cannot be processed by the printing service. Such files may also cause issues for email delivery and for some receiving operators.

#### Embedding in Peppol BIS 3.0 and other UBL-based formats

In Peppol BIS 3.0, attachments must be embedded within the XML file as defined in the specification. Attachments placed outside the XML (e.g., in the ZIP file) are ignored.

#### ZIP Packaging for other formats

If you are using a format that does not support embedded attachments, include attachments within the same ZIP file as the XML. To ensure Maventa correctly recognises the invoice image, 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 delivery route requires one (e.g., print), Maventa automatically generates a visual invoice image from the XML data. The Peppol route does not require an invoice image.

* [Example of invoice image (Finland)](/assets/pages/01-integration-guide/01-invoice-sending/01-invoice-sending/example_for_country_fi_in_language_en.approved.pdf)
* [Example of invoice image (Sweden)](/assets/pages/01-integration-guide/01-invoice-sending/01-invoice-sending/example_for_country_se_in_language_en.approved.pdf)

#### 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 for better performance and delivery success.

#### Filenaming requirements

All files sent through the service must follow these naming rules:

* File names may only include letters (A–Z), numbers (0–9), periods (.) and underscores (_)
* Special characters are not allowed
* The file name must not exceed 50 characters in length

### Validate before sending

Validating your invoice XML before sending is optional. Maventa validates all invoices automatically during the sending process. If you already have a validation process or are confident your XML is valid, skip this step. Pre-send validation simply helps catch issues earlier.

Call [POST /v1/validate](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Validator+API#/validation/post_v1_validate) to validate your invoice XML. Read more about [validation](/integration-guide/invoicing-formats/validation/).

## Step 2: Send your invoice

All Maventa company accounts have invoice sending enabled by default. Before sending, make sure your invoice is properly constructed and, ideally, validated.

> [!WARNING]
> Sending or receiving invoices is not allowed if `company_state` is unverified (-1) — the API returns the error message “Unauthorized”. Invoices can be sent after authorisation is complete.

To send an invoice through Maventa, send the XML file along with required parameters using [POST /v1/invoices](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/postV1Invoices).

### Request

```json
{
  "format": "PEPPOLBIS3",
  "recipient_eia": "0216:003734782098",
  "recipient_operator": "PEPPOL",
  "recipient_email": "fallback@example.com",
  "disabled_routes": ["print"],
  "file": "<base64-encoded invoice XML>"
}
```

### Response

```json
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "PROCESSING",
  "number": "INV-2026-001",
  "recipient": {
    "name": "Maventa Oy",
    "bid": "3478209-8",
    "eia": "0216:003734782098"
  },
  "destination": "PEPPOL"
}
```

The `file` parameter contains the base64-encoded invoice XML. If you are sending a ZIP package (XML with attachments), base64-encode the entire ZIP file. After a successful send, Maventa responds with a UUID (invoice ID), which should be saved in your system to track delivery status and updates.

### Key API parameters

* **Recipient details** — Provide the recipient’s e-invoicing address (`recipient_eia`) and/or operator (`recipient_operator`).
* **Email fallback** — Add the recipient’s email address using the `recipient_email` parameter for fallback delivery if e-invoicing is not possible.
* **Country-specific invoicing fields** — Some parameters are specific to certain countries, for example fields required for B2C invoicing in Finland or Norway.
* **Print settings** — Define invoice-specific print preferences that override the company-level defaults. Read more about [print service](/integration-guide/invoice-sending/printing/).
* **Language settings** — Use the `lang` parameter to define the language of the generated PDF and email content. Supported languages: FI, SE, NO, NL, DK, and EN.
* **Custom invoice ID** — Use the `uuid` parameter to specify your own invoice ID for tracking purposes. The value must be a valid UUID. If not provided, Maventa generates one automatically. Store this ID in your system to monitor delivery status and updates.
* **Prevent routing** — The `prevent_routing` setting marks an invoice as SENT without actually delivering it. This is typically used to manually create an assignment for Maventa’s reminder or debt collection services without sending the invoice itself.
* **Email settings** — Use `email_settings[xml_format]` to force email delivery and include the XML attachment in the specified format. Read more about [email invoicing](/integration-guide/invoice-sending/email-invoicing/).

### Controlling delivery routes

To block certain delivery routes, use the `disabled_routes` parameter. This gives you control over which routes (einvoice, email, print) are allowed or blocked for each invoice.

Keep in mind:

* 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 override the values in the XML.
* Store the invoice ID for tracking purposes.

### Preventing duplicate invoices

Maventa offers two mechanisms to prevent sending the same invoice twice:

* **Custom UUID** — Use the `uuid` parameter in [POST /v1/invoices](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/postV1Invoices) to assign your own invoice ID. If an invoice with the same UUID already exists, the API rejects the duplicate.

* **Duplicate invoice number prevention** — Enable the `stop_duplicate_numbers` setting using [PATCH /v1/company/settings](https://swagger.maventa.com/#/company/patchV1CompanySettings) (set `stop_duplicate_numbers` to `true`). When enabled, Maventa rejects any invoice with the same invoice number that was sent within the past 7 days. The API returns a `DUPLICATE INVOICE NUMBER` error in this case. After 7 days, the same invoice number can be used again.

### Cancelling a sent invoice

A sent or delivered invoice cannot be cancelled through Maventa. Once an invoice has been sent, it has already been handed over to the recipient's operator or delivery channel.

If you need to cancel an invoice after it has been sent, the correct approach is to send a credit note to the recipient. This is the standard and officially recognised way to reverse an invoice. Alternatively, the sender can contact the recipient directly to arrange cancellation outside the invoicing system.

## Step 3: Follow up and handle errors

After sending the invoice and storing its invoice ID, monitor its delivery progress. Maventa recommends webhooks for real-time tracking. As a backup, you can also poll the API to check invoice status.

### Register for webhook notifications for sent invoices

Register a webhook for sent invoice events using [POST /v1/company/notifications](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/company/postV1CompanyNotifications):

<details>
<summary>Example registering for DELIVERED, DELIVERY_CONFIRMED and FAILED events for invoices</summary>

Request

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

Response

```json
{
  "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"
  ]
}
```
</details>

Maventa calls the specified endpoint with a payload like this when an invoice is delivered:

```json
{
  "event":"DOCUMENTS.INVOICE.DELIVERED",
  "company_id":"xxxxe05d-42f0-4e76-acd6-968ab455xxxx",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"xxxx8354-5998-495b-8675-67bf05dexxxx",
    "invoice_number":"1003",
    "destination":"PEPPOL",
    "recipient_name":"Recipient",
    "recipient_bid":"933640000"
  }
}
```

Maventa calls the specified endpoint with a payload like this when invoice sending fails:

```json
{
  "event":"DOCUMENTS.INVOICE.FAILED",
  "company_id":"xxxxe05d-42f0-4e76-acd6-968ab455xxxx",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"xxxx8354-5998-495b-8675-67bf05dexxxx",
    "invoice_number":"1001",
    "destination":"PEPPOL",
    "recipient_name":"Recipient",
    "recipient_bid":"933640000",
    "error_message": "Error that happened"
  }
}
```

Update your database for the invoice ID in question based on the `event`. Refer to the [webhook doc](/integration-guide/integration-tools/webhooks/) for more details.

<details>
<summary>Difference between DELIVERED and DELIVERY_CONFIRMED events</summary>

DELIVERED means the invoice has been successfully handed over to the chosen delivery channel (e.g., Peppol, email, print).

DELIVERY_CONFIRMED means the delivery channel has acknowledged receipt or completion of delivery. Not all routes support this extra confirmation.
</details>

Keep in mind:

* An invoice marked as DELIVERED can still fail afterwards — 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.
* You can safely show both statuses to your customers — just note that DELIVERED alone does not always guarantee final delivery success.
* Not all routes support DELIVERY_CONFIRMED.

### Polling for the status

If webhooks are not an option, check invoice status by polling the API. Polling can also serve as a backup in case webhook delivery fails.

Use [GET /v1/invoices/{id}](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/getV1InvoicesId) to poll an individual invoice by its invoice ID (UUID).

Recommended polling frequency:

* While the invoice is still PENDING: poll every 1 hour.
* After the invoice reaches SENT or DELIVERED status: poll once per day for up to 1 month, or until payment is received.
* As a backup for webhooks: poll once a day or a few times per week.

The SENT status does not guarantee successful delivery. An invoice can still fail after this point, so keep polling until the final status is confirmed.

### Delivery times

Invoices are usually sent within about 10 minutes, moving from pending to sent/delivered state. At the turn of the month or during high-traffic periods, queues can be longer and delivery may take up to a few hours.

In some cases, especially with Peppol invoices, temporary issues caused by other access points can delay delivery. When this happens, the invoice may remain in pending while Maventa checks, resends, or takes other steps to ensure successful delivery.

Invoices do not remain stuck in pending without notice. Maventa's internal alerting system monitors all pending invoices, so everything is eventually processed — sometimes with a short delay if manual action or coordination with the receiving access point is needed.

#### Invoice statuses

The REST API uses the following statuses when filtering invoices with [GET /v1/invoices](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/getV1Invoices):

* **PENDING** — The invoice is queued and waiting to be sent.
* **DELIVERED** — The invoice has been successfully handed over to the recipient's delivery channel.
* **FAILED** — All available delivery routes were attempted, but the invoice could not be delivered.

> [!NOTE]
> SENT and DELIVERED refer to the same state — the invoice has been handed over to the delivery channel. The REST API uses DELIVERED, while SENT may appear in other contexts (e.g., the SOAP API or UI). In the REST API, use DELIVERED.

The invoice lifecycle also includes these additional statuses:

* **DELIVERY_CONFIRMED** — The delivery channel has confirmed receipt or completion of delivery. Not all routes support this.
* **ERROR** — Same as FAILED. The invoice could not be delivered.

### When the invoice fails

If the invoice status is FAILED (or ERROR), 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** — Correct the address and re-route the invoice.
* **Routing errors** — If the issue relates to routing (e.g., delivery channel unavailable, no routes found), re-route the invoice to another channel if possible.
* **Validation errors** — If the invoice content is invalid (e.g., missing required fields or schema issues), correct the XML and resend the invoice as a new invoice.

Maventa offers a setting that enables companies to receive delivery failure notifications via email. This helps identify and address issues promptly. Maventa recommends that your system notifies the user whenever action is required.

#### Re-routing an invoice

To redirect an invoice to a different address or delivery route, use one of these API endpoints:

* [PUT /v1/invoices/{id}/reroute/einvoice](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/putV1InvoicesIdRerouteEinvoice) - for e-invoice delivery
* [PUT /v1/invoices/{id}/reroute/email](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/putV1InvoicesIdRerouteEmail) - for email delivery
* [PUT /v1/invoices/{id}/reroute/print](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/putV1InvoicesIdReroutePrint) - for print delivery

## Testing invoice sending

Before going to production, test your invoice sending integration in the Maventa testing environment. For general setup instructions, API keys, and environment details, see the [getting started guide](/integration-guide/getting-started/).

To test internal sending between Maventa accounts, create two company accounts in the testing environment and send invoices from one to the other. Internal sends between Maventa accounts work the same way in testing as in production.

To test sending via Peppol, the testing environment is connected to the Peppol test network. You can register one of your test accounts as a Peppol receiver — the registration is created in the Peppol test environment. Then send an invoice to that account from another test account to verify the full Peppol flow end to end. You can also use [Peppol's public test endpoints](https://peppol.helger.com/public/locale-en_US/menuitem-tools-test-endpoints) to send test invoices without needing a real recipient.

> [!NOTE]
> External operator routes (Finland, Sweden), consumer routes, email, and print deliveries are simulated in the testing environment. Invoices are marked as SENT but not actually delivered. To test real email delivery, contact [support.maventa@visma.com](mailto:support.maventa@visma.com).

---

## Consumer Invoicing
Source: https://documentation.maventa.com/integration-guide/invoice-sending/consumer-invoicing/

Maventa enables businesses to send invoices directly to consumers (B2C) through a range of electronic channels — including netbanks, digital mailboxes, direct debit, email, and print. The available channels and activation steps vary by country, so select your market below for detailed instructions.

<div class="flex flex-wrap gap-4 mt-6 not-prose justify-center">


</div>


## How it works

Consumer invoices are sent through the same [POST /v1/invoices](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/postV1Invoices) endpoint used for B2B invoices. Maventa's routing logic automatically determines the best delivery channel based on the recipient's registrations, the sender's active agreements, and any route preferences specified in the API call.

If the primary electronic channel is unavailable — for example, the consumer has not registered for e-invoicing — the invoice falls through to the next channel in the routing order, such as email or print.

## Supported channels by country

### Finland

- **E-invoices and direct payments** to consumer netbanks via the Finnish banking network. Requires SI/RI message exchange to establish agreements with banks and consumers.
- **Kivra** — digital mailbox delivery, with automatic consumer lookup based on invoice data.
- **OmaPosti** — digital letter delivery through the print route. Consumers with an active OmaPosti account receive the invoice digitally instead of on paper.
- **Email and print** as fallback channels.

### Sweden

- **E-invoices to consumer netbanks** via InConx AB (Certified Technical Distributor), covering all major Swedish banks through BGC, Nordea, and Swedbank connections.
- **Kivra and Billo** — digital mailbox services. If no bank agreement (FMI) exists for the consumer, Maventa attempts delivery to Billo first, then Kivra.
- **Email and print** as fallback channels.

### Norway

- **eFaktura** to consumer netbanks and Vipps, using the Yes to All (JTTA) registry for automatic consumer matching.
- **AvtaleGiro** — direct debit with automatic deduction file creation. Maventa handles both the payment and the consumer notification.
- **Digital Postkasse Innbygger (DPI)** — for municipalities sending digital post to consumers.
- **Email and print** as fallback channels.

## Consumer invoicing in other markets

Maventa's consumer invoicing solution is currently available in Finland, Sweden, and Norway. If you need to send consumer invoices in other markets, [contact Maventa](https://maventa.com/contact/) to discuss the available options.

---

## Printing
Source: https://documentation.maventa.com/integration-guide/invoice-sending/printing/

Print can be used as a delivery method when an invoice cannot be sent as an e-invoice or via email.

Requirements for print delivery:

* The sender company has the print service activated
* The full postal address of the receiver is included on the invoice
* The invoice image meets the technical restrictions

## Activating the printing service

To use print as a delivery option, the printing service must be activated separately for the company account. Activation can be done through the API or UI.

* Enable the print service using [PATCH ​/v1​/company​/setting](https://swagger.maventa.com/#/company/patchV1CompanySettings). Under the `send_invoice_print` block, set the parameter `enabled` to `true`.
* To disable the printing service, set the `enabled` parameter to `false`.
* To check the status, use [GET ​/v1​/company​/settings](https://swagger.maventa.com/#/company/getV1CompanySettings). The `enabled` parameter under `send_invoice_print` indicates whether the service is active (true) or disabled (false).

## Template

By default, invoices sent through the print service use a Maventa-generated invoice template. This template is optimised for efficient processing, complies with all technical requirements, and is designed to fit the envelopes used by the printing service provider in each country. Customers can personalise this template by adding their company logo (via UI or API).

Examples of Maventa templates for each country are available on the country-specific rules and settings page.

As an alternative, customers may use their own invoice image for all printed invoices or on a per-invoice basis (via UI or API). When using a custom image, Maventa automatically adds a cover sheet with the recipient’s address details. This ensures proper alignment with the envelope window. The cover sheet is counted as an extra page and billed accordingly.

Prints are always double-sided if there is more than one page.

* To add a logo to a Maventa-generated invoice image template, use the [PATCH ​/v1​/company​/setting](https://swagger.maventa.com/#/company/patchV1CompanySettings) method with the parameter logos. Note: Most image formats are supported except PDF. JPEG or PNG is recommended. PNG files with transparency are not supported.
* To remove an uploaded logo, use the same method as above.
* If you want to use your own invoice image for all prints, use [PATCH ​/v1​/company​/setting](https://swagger.maventa.com/#/company/patchV1CompanySettings) and set the parameter `send_invoice_print.use_own_pdf` to `true`. To disable it, set the parameter back to `false`.
* If you want to control the use of your own invoice image per invoice, you can do so when sending invoices with the [POST ​/v1​/invoices](https://swagger.maventa.com/#/invoices/postV1Invoices) method. Inside `print_settings`, use the parameter `print_own_image` (true or false). This setting will override the company-level configuration.

When using your own invoice image, make sure it meets the technical restrictions below.

### Technical restrictions of the PDF

All files must be in PDF format and fully self-contained — no dynamic components, and all fonts, images, and other resources must be embedded. All new customers should test their PDF files (all variants of fonts, images, etc.) to verify that the PDFs can be processed. If the PDF contains graphics such as logos, charts, or other images, they must be of good quality.

* Keep the top and right margins empty
* Do not send any invoice image or attachment with black/dark background  
* No transparencies  
* All fonts must be embedded (subset or complete)  
* All images must be in 250-300dpi. Higher resolution produces little or no quality gain. Lower resolution gives poor quality.
* Text should be stored as text (not bitmap)
* Recommended size per page is 1024kB, smaller the better
* Black / White print: 2bit colors (black and white only), not grayscale.
* Colour print: Black text should be in black, not 4-colour
* Colour print: All colours must be CMYK
* PDF page size needs to be A4 (210 x 297 millimeters)

> [!WARNING]
> PDF attachments must be provided without encryption or any form of security restriction. Password-protected files or files with restricted permissions (e.g., preventing printing or content extraction) cannot be processed by the printing service.

## Attachment handling

When sending separate PDF attachments for print, the following rules apply:

* Up to 3 separate attachments are allowed (maximum of 4 files including the invoice image).
* Only PDF format is allowed.
* Maximum size per attachment: 50 MB.
* Total maximum number of pages: 110.

If these limits are exceeded, all attachments will be discarded. The sender will be notified by email, but the invoice image itself will still be printed.

> [!NOTE]
> There is an extra charge per page printed.

Default setting: For Finnish companies, attachment printing is disabled by default. For all other countries, it is enabled. This setting can be adjusted via the API or UI.

Use the [PATCH ​/v1​/company​/setting](https://swagger.maventa.com/#/company/patchV1CompanySettings) to change the setting. Under the `send_invoice_print` block, set the parameter `attachment_print` to `true` to enable attachment printing, or `false` to disable it.

## Error handling

If an invoice cannot be delivered due to an outdated or invalid address, it is returned to the sender’s address. The sender’s address is always included on the Maventa-generated invoice image and on the cover sheet. The return address is taken from the invoice data.

The exception is Norway, where Maventa offers an automated return post handling feature. Invoices are not returned to the sender’s address in this case. Read more on the Norway-specific page.

Maventa validates that a recipient address is provided and all required address fields are present, but does not validate the format or correctness of the address content.

## Country specific rules and settings

Some aspects of the printing service vary by country:

* Templates
* Colour printing option
* Attachment handling
* Envelope sizes
* Delivery schedules
* Digital delivery channels for prints and other extra services
* Automatic return post handling

Take a look at the country specific instructions:

<div class="flex flex-wrap gap-4 mt-6 not-prose justify-center">


</div>

---

## Email invoicing
Source: https://documentation.maventa.com/integration-guide/invoice-sending/email-invoicing/

Email is the primary fallback delivery method when an invoice cannot be sent as an e-invoice. Maventa evaluates delivery options in the following order:

1. E-invoice
2. Email
3. Print service

To force email delivery, disable all other routes in the invoice sending API. Email delivery is enabled by default for all company accounts but can be disabled in company settings or per invoice.

To send an invoice by email, include the recipient's email address either in the XML or as metadata in the invoice sending API.

## Sending an invoice via email

To send an invoice via email, use the [POST /v1/invoices](https://swagger.maventa.com/#/invoices/postV1Invoices) method and include the recipient's email address. To force email delivery, disable the other delivery routes using the `disabled_routes` parameter.

### Request

```json
{
  "format": "PEPPOLBIS3",
  "recipient_email": "recipient@example.com",
  "disabled_routes": ["einvoice", "print"],
  "file": "<base64-encoded invoice XML>"
}
```

### Response

```json
{
  "id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "status": "PROCESSING",
  "number": "INV-2026-001",
  "recipient": {
    "name": "Example Company",
    "bid": "1234567-8",
    "email": "recipient@example.com"
  },
  "destination": "EMAIL"
}
```

The `file` parameter contains the base64-encoded invoice XML. If a `recipient_email` is provided in the metadata, it overrides any email address specified in the XML. Store the returned `id` to track delivery status.

## Forced email route

You can also force email delivery without explicitly disabling routes. The following XML formats support this natively:

* **S-EDI**: Set OutputMedia to "PDF" to enable only the email route.
* **Finvoice**: In the SOAP header, use the following:

```xml
<eb:To>
  <eb:PartyId>EMAIL</eb:PartyId>
  <eb:Role>Receiver</eb:Role>
</eb:To>
```

If a SOAP header is not an option, use this instead:

```xml
<ToIdentifier SchemeID="0037">EMAIL</ToIdentifier>
<ToIntermediator>EMAIL</ToIntermediator>
```

* **TEAPPS**:

```xml
<NET_SERVICE_ID>EMAIL</NET_SERVICE_ID>
```

## Email sending settings

Senders can choose from four options for how invoice emails are delivered. These settings can be modified through the UI or using [`PATCH /v1/company/settings`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/patchV1CompanySettings).

### Send all invoice emails with a download link

The invoice email includes a link to download the invoice from Maventa. A passcode is included in the email, which the recipient must enter to access the invoice. When the recipient opens the invoice via the link, the sender receives a notification email (if notifications are enabled).

> [!NOTE]
> The download link is valid for 90 days after the invoice due date. After this period, the recipient needs to contact the sender for a copy of the invoice.

### Send all invoice emails with attachments

Invoice emails include the PDF image and other files as attachments. If the total size exceeds 5 MB, a download link is included instead. In Finland, a virtual barcode is included in the email body.

> [!WARNING]
> The sender does not receive a delivery confirmation or notification if email sending fails.

### Send all invoice emails with merged PDF attachments

All PDF attachments and the PDF image are combined into a single PDF file. If the total size exceeds 5 MB, the email includes a download link instead. In Finland, a virtual barcode is added to the email body.

> [!WARNING]
> Sending with merged PDF attachments is not compatible with digitally signed PDF invoices.

### Send all invoice emails with invoice objections

Recipients must accept the invoice before accessing payment information. They can also decline the invoice and optionally provide a reason. When an invoice is accepted or declined, the sender receives a notification, and the invoice status is updated in Maventa.

> [!NOTE]
> The link to the hosting service is valid for 90 days after the invoice due date.

## Invoice XML as email attachment

You can attach an invoice XML file to email invoices. This allows the recipient to receive structured XML data instead of a PDF, making it easier to import the invoice directly into their invoicing system.

This feature was originally developed for the Netherlands, where Peppol does not support departmental divisions due to the lack of separate Peppol IDs. By attaching the XML to the email, departments can still receive structured invoice data and import it manually. The functionality is available for all countries.

To enable XML attachment, use the `email_settings[xml_format]` parameter in the [POST /v1/invoices](https://swagger.maventa.com/#/invoices/postV1Invoices) request and specify the desired XML format (see the Swagger documentation for available formats).

> [!WARNING]
> When this parameter is provided, the invoice is sent **only** via email. The email route is forced, and no other delivery channels are attempted even if the email sending fails.

* If an XML file is attached to the email, a separate PDF is not attached.
* Exception: if the selected XML format supports embedding a PDF (e.g., UBL-based formats), the PDF image is included inside the XML file.
* If the sender's email setting uses a download link, the PDF is still available from the link even if it is not attached to the email.
* The maximum allowed email size is 5 MB. If the total size exceeds this limit, invoice sending fails with an error message.

The cost of sending an email with an XML attachment is the same as sending an e-invoice in the respective country.

## Header image

You can customise the invoice email by adding a header image that appears at the top of the email body. A header image helps recipients identify the sender at a glance.

Add a header image through the API using [`PATCH /v1/company/settings`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/patchV1CompanySettings), or through the UI from invoice settings.

### Header image requirements

* Only PNG format is allowed
* Maventa recommends a width of 650–700 pixels and a height of 90–200 pixels

Once added, the header image appears in the next invoice sent via email. The header image only affects invoice emails — other email types, such as notifications, are not affected.

## Payment links

You can add a payment link to the email invoice display page, allowing recipients to access a payment service directly. Maventa requires prior approval of the link's domain and validates the link before displaying it.

> [!NOTE]
> To use payment links in invoice emails, contact Maventa support to request activation.

Provide the link in an `AdditionalDocumentReference` element in UBL-based formats (Peppol BIS 3.0, SiUBL 2.0) by setting the ID to "68" and DocumentDescription to "Payment link". The link itself goes in the URI field.

```xml
<cac:AdditionalDocumentReference>
    <cbc:ID>68</cbc:ID>
    <cbc:DocumentDescription>Payment Link</cbc:DocumentDescription>
    <cac:Attachment>
      <cac:ExternalReference>
        <cbc:URI>http://pay.your.com/p/xxxxxxxxxxxxx</cbc:URI>
      </cac:ExternalReference>
    </cac:Attachment>
</cac:AdditionalDocumentReference>
```

## Message to the email recipient

You can define a message and contact details that appear in the email body. Add these through the UI or using [`PATCH /v1/company/settings`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/patchV1CompanySettings).

> [!NOTE]
> A confirmation message is sent to any defined contact email, and the address must be confirmed before it appears in invoice emails.

## Language of the email

The email language is determined by the input XML format and the language setting within it. Supported languages: FI, EN, SE, NO, DK, NL.

| Format | Language field | Fallback |
|--------|---------------|----------|
| Finvoice | `InvoiceRecipientLanguageCode` | FI |
| EHF/Peppol BIS | `AccountingCustomerParty/Party/PostalAddress/Country/IdentificationCode`, then sender's Maventa account country code | EN |
| LiinosXML | `Data/Parties/Party[Type="IV"]/Language` | EN |
| TEAPPSXML | `RECEIVER/CUSTOMER_INFORMATION/LANGUAGE_CODE` | EN |
| SEDI | `/Invoice/Header/PrintInfo/Layout/@Language` | EN |
| VismaXML 6.0 | `PrintInfo/Layout["Language"]` | EN |
| E2B | `Invoice@language` | EN |
| `invoice_create` API | `:lang`, then `:customer[:lang]` | EN |

> [!NOTE]
> Finvoice also supports SV (Swedish) because Finvoice uses ISO 639 language codes. Both SV and SE result in Swedish.

> [!NOTE]
> EHF/Peppol BIS and E2B only detect language from the country code when the value is FI, SE, NO, DK, or NL. All other country codes fall back to EN.

## Email reminders

You can configure reminder email frequency for invoices that have not been opened, accepted, or declined. This does not apply to invoices sent as attachments.

Configure reminders through the UI or using [`PATCH /v1/company/settings`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/patchV1CompanySettings) with the `reminder_frequency` parameter.

## Sender email address and reply-to address

All invoice emails are sent from `noreply@mail.maventa.com`. This address is fixed and cannot be customised.

The reply-to address is determined in the following order:

1. The contact email address, if defined
2. The API user's email address
3. The company email address

## Tracking email delivery

Email invoices use the same webhook events and polling methods as all other delivery routes. There are no email-specific events — Maventa treats email as one of the possible destinations and reports status through the standard invoice events.

Register for the `DOCUMENTS.INVOICE.DELIVERED`, `DOCUMENTS.INVOICE.DELIVERY_CONFIRMED`, and `DOCUMENTS.INVOICE.FAILED` events to track delivery. When an invoice is delivered via email, the webhook payload includes `"destination": "EMAIL"` in the event data, so you can identify the delivery channel.

For invoices sent with the download link or invoice objections setting, a `DELIVERY_CONFIRMED` event is triggered when the recipient opens the invoice via the link. For invoices sent as attachments, only `DELIVERED` is triggered — there is no way to confirm the recipient actually opened the email.

If an email bounces, a `FAILED` event is triggered with an error message describing the reason.

For more details on webhook registration and payload structure, see the [webhooks documentation](/integration-guide/integration-tools/webhooks/). For polling as a backup, see the status tracking section on the [invoice sending page](/integration-guide/invoice-sending/invoice-sending/).

## Error handling

If an email bounces due to a non-existent address, the invoice enters an error state and the sender is notified (unless notifications are disabled). The error is returned via the API.

> [!NOTE]
> Invoices do not enter an error state if the recipient's mailbox is full or if the email goes to spam. For large attachments, verify that the recipient actually received the invoice.

> [!WARNING]
> PDF attachments must be provided without encryption or security restrictions. Password-protected files or PDFs with limited permissions (such as disabled printing or content extraction) can cause delivery issues, particularly when merging multiple PDF files.

---

## Invoice receiving
Source: https://documentation.maventa.com/integration-guide/invoice-receiving/

Maventa makes it easy to receive invoices from multiple sources, including country-specific e-invoicing networks, Peppol, and PDF scanning services. Once activated, Maventa registers your company in the relevant electronic address directories and assigns you an electronic invoice address (EIA) that senders can use to deliver invoices directly to you.

All invoices first arrive in your Maventa account, where they can be downloaded or fetched via API into your system. You can also use webhooks to create a smooth, automated receiving flow and integrate the [Detect](/integration-guide/invoice-receiving/detect/) service for validation and fraud detection. For extra protection, the fraud reporting feature allows you to flag suspicious senders and help prevent invoice fraud across the network.

> [!NOTE]
> This guide covers the REST API. If you are using the SOAP API, see the [SOAP invoice receiving API methods](/api-specification/soap-api/invoice-receiving-api-methods/) instead. For authentication setup, see [Getting started with the REST API](/api-specification/rest-api/getting-started/).

## Typical receiving flow

The following steps describe the recommended flow for receiving invoices:

1. **Activate** — Enable VISMA Network and Peppol receiving for the company.
2. **Listen** — Register a webhook for `DOCUMENTS.INVOICE.RECEIVED` events.
3. **Download** — When a webhook fires, fetch the invoice XML, image, and attachments by ID.
4. **Validate** — If Detect is enabled, fetch fraud and validation check results.
5. **Back up** — Poll `GET /v1/invoices` once a day to catch any invoices missed by webhooks.

### Prerequisites

To start receiving invoices, make sure you have:

* **Company account enabled for receiving**: Your company must have an active Maventa account with invoice receiving enabled.
* **Invoice XML handling capabilities**: During download, you select which XML format to use. Maventa supports a variety of international and national formats. See the full list of [supported formats](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Validator+API) and more information about [invoicing formats](/integration-guide/invoicing-formats/invoicing-formats/).

## Step 1: Activate invoice receiving

To start receiving invoices, enable the VISMA Network setting. This is the main control for receiving e-invoices in Maventa. It allows the company to receive invoices from other Maventa users and, depending on the country, also from other operators or banks.

Once VISMA Network is turned on, additional networks such as Peppol or scanning can be enabled separately. Maventa recommends enabling Peppol for all customers to ensure the widest possible reach for receiving invoices.

After activation, the company is automatically registered in the relevant electronic address directories (depending on the country) and assigned an electronic invoice address (EIA) that senders can use to deliver invoices directly. The company also becomes visible as an invoice recipient in Maventa Finder and via the [lookup method](/integration-guide/invoice-sending/invoice-sending/#manual-lookup).

You can check which address registries are used in each country, as well as whether the country supports operator or bank networks, in the [country-specific guides](/services-and-reach/overview/). Typically, receiving is activated at the same time the account is registered, but it can also be enabled later if needed.

### Activate VISMA Network

Call the [POST /v1​/company​/profiles](#operations-company-postV1CompanyProfiles) endpoint authenticated with `company` scope, providing the network `VISMA` and profiles `INVOICE_AND_CREDIT_NOTE`:

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

No other parameters are needed. Expect the `status` field in the response to be `pending`. To confirm successful registration, call the [GET /v1​/company​/profiles](#operations-company-getV1CompanyProfiles) endpoint and check that the status has changed to `active`.

### Register company as Peppol receiver

When activating the electronic receiving setting, Maventa recommends that all customers are also registered to receive electronic invoices in the international [Peppol network](/integration-guide/peppol/peppol-network/). When a company is registered, its information is added to the [Peppol Directory](https://directory.peppol.eu/public).

Authenticate with `company` scope and call [POST /v1​/company​/profiles](#operations-company-postV1CompanyProfiles), specifying the network as `PEPPOL` and profiles `INVOICE_AND_CREDIT_NOTE`:

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

The profile `INVOICE_AND_CREDIT_NOTE` automatically registers both document types for Peppol BIS Billing 3.0. Some countries also include additional, country-specific profiles automatically. Maventa automatically keeps the Peppol registration updated as new invoice profiles are introduced. There is no need to register new profiles when the format updates.

<details>
<summary>Peppol BIS Billing UBL Invoice V3</summary>

**Peppol document identifier:**

- `urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**Process identifier:** `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing UBL Credit Note V3</summary>

**Peppol document identifier:**

- `urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**Process identifier:** `urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

Call [GET /v1​/company​/profiles](#operations-company-getV1CompanyProfiles) again to verify that the status of the `PEPPOL` network registration is active. If the response contains the error code `PROFILE_ALREADY_REGISTERED`, the company is already registered with another Peppol access point. The current access point must deregister the company before Maventa can complete the registration.

> [!WARNING]
> Switching Peppol access points requires coordination with the current provider. Contact the existing access point and ask them to deregister the company. Once deregistered, repeat the registration call above. The process typically takes a few business days.

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

The [Peppol Directory](https://directory.peppol.eu/public) is available as a reference tool for looking up registered companies. Maventa automatically updates this directory, making your company visible there. Note that the Peppol Directory is not part of the actual delivery infrastructure — it serves informational purposes only.

### Deactivate invoice receiving

To stop receiving invoices on a specific network, delete the corresponding network registration. This removes the company from the associated electronic address directories, and senders can no longer deliver invoices to the company through that network.

First, retrieve the profile ID by calling [GET /v1​/company​/profiles](#operations-company-getV1CompanyProfiles) with `company` scope. Filter by network if needed — for example, `?network=VISMA` or `?network=PEPPOL`. The response includes the `id` for each active registration.

Then, call [DELETE /v1​/company​/profiles/{id}](#operations-company-deleteV1CompanyProfilesId) with the profile `id` to delete the registration.

> [!WARNING]
> The VISMA Network registration cannot be deleted while Peppol or scanning registrations are still active. Deactivate those registrations first before removing the VISMA Network profile.

> [!NOTE]
> Not all profiles can be deleted. If deletion is not allowed for a specific profile, the endpoint returns a `409 Conflict` response.

To deregister from Peppol specifically, use the same approach: find the Peppol profile ID from the list and delete it. The company is then removed from the Peppol network and the [Peppol Directory](https://directory.peppol.eu/public). Senders looking up the company through Peppol will no longer find a registered e-invoicing address.

Each network registration can be deactivated independently. For example, deleting the Peppol registration does not affect the VISMA Network registration, and vice versa.

#### Receiving invoice extensions

To enable receiving of invoice extensions, call [PUT /v1/company/profiles/{id}/extensions](https://swagger.maventa.com/#/company/putV1CompanyProfilesIdExtensions).

Example request:

```json
{
  "profile_name": "INVOICE_AND_CREDIT_NOTE",
  "extensions": ["GACCOUNT10"]
}
```

Currently, Maventa supports only the GACCOUNT10 extension for the Netherlands.

To view the active extensions, call [GET /v1/company/profiles/{id}](https://swagger.maventa.com/#/company/getV1CompanyProfilesId).

```json
{
  // ...
  "profiles_with_extensions": [
    {
      "profile_name": "INVOICE_AND_CREDIT_NOTE",
      "extensions": ["GACCOUNT10"]
    }
  ]
}
```

To disable receiving of invoice extensions, call [PUT /v1/company/profiles/{id}/extensions](https://swagger.maventa.com/#/company/putV1CompanyProfilesIdExtensions) with an empty extensions array:

```json
{
  "profile_name": "INVOICE_AND_CREDIT_NOTE",
  "extensions": []
}
```

## Step 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.

### Webhooks

Webhooks notify your system immediately when a new invoice arrives, enabling a seamless automated receiving flow. As a backup routine, Maventa recommends polling for invoices once a day.

#### Register for webhook notifications for received invoices

Register for invoice receipt events by calling [POST /v1/company/notifications](#operations-company-postV1CompanyNotifications).

Example registering for RECEIVED events for invoices:

### Request

```json
{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.RECEIVED"
  ]
}
```

### Response

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

Maventa calls the specified endpoint with a payload like this:

```json
{
  "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:

### Request

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

### Response

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

Store the `event_data.invoice_id` for later processing and deduplication. Maventa may deliver the same webhook event more than once (for example, if your endpoint is temporarily unreachable), so always check whether an invoice ID has already been processed before downloading it again.

Your endpoint should return an HTTP `200` status code to acknowledge receipt. If Maventa does not receive a `200` response, the webhook is retried. Refer to the [Webhooks guide](/integration-guide/integration-tools/webhooks/) for full details on retry behaviour, payload signatures, and configuration.

### Polling

If you do not use webhooks, you can poll the API to list new invoices and then download them with their attachments. Maventa recommends polling no more than once or twice per day. Even when using webhooks, poll once a day as a backup to catch any missed deliveries.

#### List new received invoices

Use [GET /v1/invoices](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/getV1Invoices) with parameters `direction=RECEIVED`, `received_at_start`, and `received_at_end` to get a list of invoices to download. This method is called per company, so it is only possible to list invoices from one company at a time.

The timestamp parameters use ISO 8601 format, for example:

```http
GET /v1/invoices?direction=RECEIVED&received_at_start=2025-01-15T08:00:00%2B02:00&received_at_end=2025-01-15T20:00:00%2B02:00
```

The response is paginated. Use the `page` and `per_page` parameters to iterate through results. Check the response headers or result count to determine whether more pages are available.

> [!NOTE]
> * Call the method starting with the latest fetch timestamp and ending with the current timestamp.
> * If the API returns an error, do not update the stored timestamp. Retry the listing later.
> * Save the returned invoice IDs locally with a status such as "pending download".
> * The server timestamp is GMT+2. Differences between client-side and server-side clocks can create gaps. Add a buffer of about 1 minute before and after the timestamps to avoid missing invoices.

### Download invoice based on ID

After you have saved the new incoming invoice IDs, download the invoice files and attachments into your system.

Invoice downloading involves obtaining:

* Invoice metadata
* Invoice data
* Invoice attachments

Use [GET /v1/invoices/{id}](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/getV1InvoicesId) to download the invoice XML file in the specified format, or to download the invoice image. Set the `return_format` parameter to the desired format.

Common `return_format` values for XML download:

| Value | Format |
|-------|--------|
| `PEPPOLBIS30` | Peppol BIS Billing 3.0 (recommended) |
| `FINVOICE30` | Finvoice 3.0 |
| `TEAPPSXML30` | TEAPPSXML 3.0 |
| `UBL20` | UBL 2.0 |
| `SIUBL` | Visma SI-UBL |

For the full list of supported formats, see the [Validator API specification](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Validator+API) and the [invoicing formats](/integration-guide/invoicing-formats/invoicing-formats/) page.

> [!NOTE]
> * Mark an invoice as successfully retrieved only after it has actually been downloaded. If the download fails, log the error and retry later.
> * Use the locally stored invoice ID list to ensure the same invoice is not downloaded twice.

#### Download invoice image and attachments

To download the invoice image, use the `return_format` parameter:

* `ORIGINAL_OR_GENERATED_IMAGE` — returns the original image if one exists, otherwise Maventa generates one
* `ORIGINAL_IMAGE` — returns an image only if the original exists
* `GENERATED_IMAGE` — returns an image generated by Maventa

##### Example: Original format Peppol BIS3

If the invoice's original format is Peppol BIS3 and you download it as Peppol BIS3, you only need the XML file as it has all original attachments embedded.

> [!WARNING]
> When downloading in a different format than the original, Maventa converts the XML but does not embed separate attachments into the converted file. Download attachments separately using the files endpoint described below.

##### Example: Original format TEAPPSXML 3.0 downloaded as Finvoice 3.0

If the invoice's original format is TEAPPSXML 3.0 and it includes an invoice image and extra attachments:

* Download the invoice as Finvoice 3.0 with [GET /v1/invoices/{id}](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/getV1InvoicesId) by setting `return_format` to `FINVOICE30`.
* Then download the invoice image or other attachments using the same endpoint with `return_format` set to one of the image options described above.

Invoices may also contain attachments, listed in the `files` array of the invoice metadata. Download each attachment separately using [GET /v1/invoices/{id}/files/{file_id}](#operations-invoices-getV1InvoicesIdFilesFileId) with the `id` from each file entry.

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

#### Invoice origin and origin_type details

In the invoice details, the `origin` field indicates the source of the received invoice — for example, `PEPPOL`, `VISMA`, or `SCAN`. If the `origin` is `SCAN`, the `origin_type` field provides additional detail about the scanning method:

| `origin_type` | Description |
|----------------|-------------|
| `SCAN_PDF` | Scanned from a PDF file |
| `SCAN_PAPER` | Scanned from a paper invoice |
| `AUTOSCAN` | Automatically scanned from a PDF file (ML-based) |
| `SCAN` | Scanned from non-invoice material |

> [!NOTE]
> Scanned invoices may have lower data accuracy than electronic invoices, depending on the quality of the source document. Consider adding extra validation for scanned invoices in your integration, especially for key fields like amounts and bank account numbers. For more information about scanning services, see [Scanning](/integration-guide/invoice-receiving/scanning/).

## Error handling

When building your receiving integration, handle API errors gracefully so that temporary issues do not cause missed invoices or data loss. The Maventa REST API returns errors in a consistent JSON format:

```json
{
  "code": "not_found",
  "message": "Requested resource not found or you don't have access to it",
  "details": null
}
```

### HTTP status codes for receiving endpoints

The invoice listing and download endpoints can return the following status codes:

| Status | Code | Description | Action |
|--------|------|-------------|--------|
| `200` | — | Success | Process the response normally. |
| `400` | `invalid_parameters` | Request parameters are invalid — for example, an unsupported date format or missing required parameter. | Fix the request parameters. Do not retry with the same values. |
| `400` | `invalid_format` | The requested `return_format` is not supported. | Check the list of [supported formats](/integration-guide/invoicing-formats/invoicing-formats/) and correct the `return_format` value. |
| `400` | `invoice_download_api_error` | An error occurred while downloading the invoice — for example, the format conversion failed. | Log the error. If the issue is format-related, try downloading in the original format or as `PEPPOLBIS30`. |
| `401` | `auth_unauthorized` | Authentication token is missing, expired, or invalid. | Request a new OAuth2 token and retry. If the error persists, verify your credentials. |
| `403` | `forbidden` | Your account does not have permission to access this resource. | Verify that the authenticated company owns the invoice. Do not retry — this is a permanent error. |
| `403` | `vendor_api_key_missing` | The request is missing a valid vendor API key. | Include a valid `vendor_api_key` in your authentication. |
| `404` | `not_found` | The invoice or file ID does not exist, or you do not have access to it. | Verify the ID. If polling, the invoice may have been deleted or may belong to another company. Do not retry. |
| `429` | `too_many_requests` | You are sending requests too frequently. | Back off and retry after a delay. See [Retry strategy](#retry-strategy) below. |
| `500` | `internal_server_error` | An unexpected server error occurred. | Retry with exponential backoff. If the error persists, contact Maventa support. |
| `503` | `service_unavailable` | The service is temporarily unavailable due to maintenance or high load. | Retry with exponential backoff. |

### Retryable vs non-retryable errors

> [!NOTE]
> **Retryable** (use exponential backoff): `429`, `500`, `503`, and network timeouts or connection errors.
>
> **Non-retryable** (fix the request or configuration): `400`, `403`, `404`.
>
> **Special case**: `401` — retry once with a fresh token. If it fails again, the issue is with your credentials, not a transient problem.

### Retry strategy

When a retryable error occurs, use exponential backoff to avoid overloading the API:

1. **First retry** — wait 1 minute
2. **Second retry** — wait 5 minutes
3. **Third retry** — wait 30 minutes
4. **After three failures** — mark the invoice as failed and alert your operations team

Keep the invoice ID in your local list with a "pending download" status throughout the retry cycle. Do not remove it until the download succeeds or you decide to skip it.

> [!WARNING]
> Never retry `400` or `404` errors with the same parameters — these indicate a problem with the request itself, not a temporary issue. Retrying them wastes API calls and may trigger rate limiting.

### Common failure scenarios

| Scenario | Recommended approach |
|----------|---------------------|
| Download fails mid-process (XML succeeds, attachment fails) | Keep the invoice as "partially downloaded". Retry only the failed file downloads using `GET /v1/invoices/{id}/files/{file_id}`. |
| Webhook endpoint is temporarily down | Maventa retries webhook delivery once per hour for up to 24 attempts. Poll once a day as a backup to catch any gaps. See the [Webhooks guide](/integration-guide/integration-tools/webhooks/) for details. |
| Duplicate invoice ID received | Check your local ID list before processing. Duplicates can occur from webhook retries or overlapping polling windows. |
| Format conversion fails (`invoice_download_api_error`) | Try downloading in the invoice's original format, or use `PEPPOLBIS30` as a fallback. Download attachments separately if needed. |
| Polling returns an error | Do not update the stored timestamp. Retry with the same time window on the next polling cycle. |

## Step 3: Fetch Detect results

If the [Detect](/integration-guide/invoice-receiving/detect/) service is enabled for the company, fetch the validation and fraud check results for each received invoice.

Use [GET /v1/invoices/{id}/detect_results](https://swagger.maventa.com/#/invoices/getV1InvoicesIdDetectResults) to download the check results based on invoice ID.

The response includes results from checks such as VAT register verification, bank account change detection, and warning list cross-referencing. Use these results to flag invoices that require manual review before approval.

For more information, see the [Detect](/integration-guide/invoice-receiving/detect/) service documentation and [Fraud reporting](/integration-guide/invoice-receiving/fraud-reporting/).

---

## Scanning
Source: https://documentation.maventa.com/integration-guide/invoice-receiving/scanning/

When e-invoicing is not an option, scanning solutions help automate invoice delivery and processing.

With Maventa's scanning solutions, all invoices can be received through a single pipeline. Additional features such as [Detect](/integration-guide/invoice-receiving/detect/) fraud checks and reports that identify suppliers who could send e-invoices can also be enabled.

> [!NOTE]
> Invoice receiving must be enabled before activating any scanning service.

## Choosing a scanning solution

Maventa offers several scanning solutions for data interpretation, each with different strengths. The right choice depends on the balance between data accuracy, processing speed, and cost. Scan Network and AutoScan can also be used at the same time, as each service has its own dedicated email address that can be shared with suppliers.


### AutoScan

Maventa's recommended scanning solution. Powered by Smartscan machine learning technology, AutoScan delivers fast, fully automated invoice processing with continuously improving accuracy — no manual steps needed.

Available in all supported markets except Finland, where it will be available in spring 2026.

[Read more](#autoscan)

### Scan Network

Traditional scanning service that combines OCR technology with manual validation. Includes quality control — if the system finds any deviation, invoices are manually checked again.

Available in Finland, Sweden, Norway, Denmark, the Netherlands, and Belgium.

[Read more](#scan-network)

### Visma Scanner & DocScan

Visma Scanner (mobile app) and DocScan (web app) for scanning and forwarding invoices using machine learning-based interpretation (Smartscan). Can be integrated directly with ERPs or accounting systems, or through Maventa.

Visma Scanner will be deprecated by the end of 2026.

[Read more](#visma-scanner-and-docscan)


> [!NOTE]
> Regardless of the solution used, the recipient should always verify the accuracy of scanned invoices.

## Scanning features by country

| Feature | FI | NO | SE | DK | NL | BE | Other countries |
|---|---|---|---|---|---|---|---|
| Scan Network |  |  |  |  |  |  |  |
| AutoScan | Spring 2026 |  |  |  |  |  |  |
| Line scanning |  AutoScan (Pilot) |  AutoScan (Pilot) |  AutoScan (Pilot) |  AutoScan (Pilot) |  AutoScan (Pilot) | Late 2026 | Late 2026 |
| PO number |  |  |  |  |  Scan Network |  Scan Network |  |
| Paper scan |  Scan Network |  |  Scan Network |  |  |  |  |
| Non-invoice material return email (Scan Network) |  |  |  |  |  |  |  |
| Non-invoice material return email (AutoScan) |  |  |  |  |  |  |  |
| Grace period after service closure (60 days of invoice forwarding to return email) |  Scan Network |  Scan Network |  Scan Network |  Scan Network |  |  |  |

## How scanning works

1. The recipient company enables invoice receiving.
2. The recipient company activates the desired scanning service.
3. Once the service is activated, the recipient company receives a dedicated scan email address. A scan postal address is only provided for Scan Network in Finland and Sweden.
4. The supplier sends invoices to the scanning service by email (or post).
5. The scan service receives the invoices, processes them, and delivers the interpreted invoice file along with the PDF to Maventa.
6. Maventa delivers the file to the recipient's Maventa account.

Scanned invoices are treated as incoming e-invoices. The integrator fetches them the same way as any other received invoice and can request the invoice in the desired format — Maventa handles the conversion regardless of the original format. Webhooks for received invoices also apply to scanned invoices.

> [!WARNING]
> Sending test invoices to the scanning service is not supported in the testing environment. The scanning service can be activated in testing, but the full pipeline can only be tested in production — for example, by sending a test invoice to your own scan address.

## Invoice fields from Scan Network and AutoScan

| Invoice field                | Scan Network                                                                                                                  | AutoScan                                                                                          |
|------------------------------|-------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------|
| Invoice number               |                                                                                                                              |                                                                                                  |
| Invoice date                 |                                                                                                                              |                                                                                                  |
| Invoice due date             |                                                                                                                              |                                                                                                  |
| Document type                |                                                                                                                              |  Support for invoice, receipt, credit note, and debit note                                       |
| Currency                     |                                                                                                                              |  Three-letter currency code                                                                      |
| Supplier organisation number |  **Varies by country** (NO: Organisation number (for foreign suppliers, VAT number is used in the OrgNumber field).\nSE: Organisation number.\nNL: KvK number.\nDK: CVR number.\nFI: Organisation number (y-tunnus)) |  **Varies by country** (NO/SE: Organisation number.\nDK: CVR.\nNL: KvK) |
| Supplier VAT number          |                                                                                                                              |                                                                                                  |
| Supplier name                |  **Matched by organisation number** (Searched from a list by organisation number.\nNot found the first time an invoice is passed; automatic from the second time.\nIf the company name cannot be found, the organisation number is shown as the name.\nIf the organisation number cannot be interpreted, the supplier name is set to UNKNOWN_VENDOR.) |  Searched from known supplier list |
| Supplier address             |  Available for NL/BE only                                                                                                   |  Not available                                                                                   |
| Supplier country code        |  Available for NL/BE only                                                                                                   |  Two-letter country code                                                                         |
| Buyer organisation number    |  Interpreted by Scan Network or extracted from the scan email address                                                        |  Recipient organisation number is determined from email routing                                  |
| Gross amount (incl. VAT)     |                                                                                                                              |                                                                                                  |
| Net amount (excl. VAT)       |  Calculated: Gross amount − VAT amount                                                                                      |                                                                                                  |
| Total VAT amount             |                                                                                                                              |                                                                                                  |
| VAT percentage               |  **Calculated from gross and VAT amounts** (Delivered without decimals.\nIf products have different VAT percentages, the calculated percentage falls between the actual percentages.\nRounding amounts are not taken into account.\nFor NL/BE, the VAT percentage is provided by Scan Network.) |  Scanned or calculated when there is no detailed VAT information |
| VAT distribution             |  Available for NL/BE                                                                                                        |                                                                                                  |
| IBAN or account number       |  **Format varies by country** (NO: Account number (for foreign suppliers, IBAN is used in the AccountNumber field).\nSE: BankGiro and PostGiro (for foreign suppliers, IBAN).\nDK: FIK.\nFI: IBAN or account number.\nNL/BE: IBAN) |  **Format varies by country** (SE: BankGiro, PlusGiro.\nDK: FIK.\nOther countries: IBAN) |
| Payment reference            |  **Varies by country** (NO: KID.\nSE: OCR.\nDK: FIK code.\nFI: Viitenumero.\nNL/BE: not available) |  |
| Reference name/number        |  **Varies by country** (DK: Their reference and order number.\nFI: Text in "Viitteenne" field.\nSE: Reference name/number.\nNO, NL, BE: not available) |  Not available |
| PO number                    |  Available for NL/BE only                                                                                                   |  Not available                                                                                   |

## Scan Network

### How Scan Network works

Scan Network receives invoices either as PDF (by email) or as paper invoices, which are scanned into PDF. An Optical Character Recognition (OCR) system interprets keywords from the invoices.

After OCR interpretation and validation, all invoices go through an extra quality control. If the system finds any deviation, the invoices are manually checked again.

The interpreted invoice file, along with the original or flattened PDF, is delivered to the recipient's Maventa account, where the recipient's ERP can fetch them. In Finland, flattened PDFs are used by default, with the option to use the original PDF based on the vendor key.

Interpretation typically takes from a few business hours to a few days, depending on weekends, holidays, and volumes.

### Opening Scan Network

The scan account can be opened through the API or the UI invoice receiving page.

REST API: [POST /v1/services/scan](https://swagger.maventa.com/#/services/postV1ServicesScan)

Before opening the scan account, make sure the company has invoice receiving enabled and has completed the customer authentication process.

When opening the scanning service, the customer provides a return email address where all non-invoice materials are delivered by the scanning service. The return email address is available in Finland, Sweden, Norway, and Denmark, but not in the Netherlands or Belgium.

To check whether Scan Network is active for an account, use [GET /v1/services/scan](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/getV1ServicesScan).

### Updating Scan Network

The scan account can be updated through the API or the UI invoice receiving page. Currently, the only settings that can be updated are the return addresses for non-invoice materials — the return email address and, for Finland and Sweden where postal scanning is available, the return postal address.

REST API: [PUT /v1/services/scan](https://swagger.maventa.com/#/services/putV1ServicesScan)

### Closing Scan Network

The scan service can be closed through the API or the UI invoice receiving page.

REST API: [DELETE /v1/services/scan](https://swagger.maventa.com/#/services/deleteV1ServicesScan)

For customers in Finland, Norway, Sweden, and Denmark, when a scan account is disabled, it enters a 60-day grace period. During this time:

* PDF invoices are forwarded to the customer's return email address.
* Paper invoices are scanned and then sent to the return email address.

After the 60-day grace period:

* The scan email address stops working.
* PDF invoices sent to the scan email address bounce.
* Paper mail is ignored without notifying the sender.

The company is responsible for informing suppliers about alternative methods for sending invoices when closing the scan account.

For customers in the Netherlands and Belgium, there is no grace period or return email functionality.

### How suppliers send invoices to the scan service

The company informs its suppliers about the scan address provided when the service is activated. The scan address contains the company's scan ID number, which is used to identify the recipient.

Suppliers can send invoices to the scanning service in two ways: by email or by post.

#### By email

Requirements for sending:

* Invoices must be attached to the email.
* One invoice per PDF file, containing all pages and attachments. The invoice image should appear first, followed by attachments in order.
* Multiple invoices can be sent in one email, but all invoices must have the same recipient. Each file must have a unique name. There is no limit on the number of PDF attachments, but the total email size must not exceed 40 MB.
* Each individual PDF attachment must not exceed 10 MB.
* The scan ID number does not need to be on the invoice image itself — the email address containing the scan ID is enough to identify the recipient.
* PDF files must be real PDF documents, version 1.3 or newer.
* PDF files must not be locked or password protected. For example, invoices sent via secure mail are not scanned.
* The document's maximum exterior size is 210 x 297 mm.
* Attachment names may only contain standard characters: a–z, A–Z, 0–9. Underscores, hyphens, and spaces are also allowed.
* After sending the email, the sender receives a notification email confirming the email was sent (the notification is an automatic reply from the email service).
* If the email cannot be handled, the address is not found, or there are no PDF attachments, the sender receives an additional error notification after the first notification.

#### By post

##### Finland

The scan service identifies the recipient using the following information from the invoice image when the invoice is sent by post:

* Organisation number
* Company name
* Company OVT code

##### Sweden

The scan service identifies the recipient using the FeAddress (postal scan address) and company name on the envelope.

### Scan ID and scan addresses

| Country     | Scan ID                  | Email scan address                                                                                                               | Postal scan address                                                                                            |
|-------------|--------------------------|----------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------|
| Finland     | Company business ID      | `invoice-BID@kollektor.fi` — email address without "-" in business identity code (e.g. `invoice-12345678@kollektor.fi`)          | Company name, Scan ID, PL 100, 80020 Kollektor                                                                |
| Sweden      | Company business ID      | `BID@autoinvoice.se`                                                                                                             | Company name, AISEXXXX Scancloud, SE-831 90 ÖSTERSUND, Sweden (XXXX = customer number assigned to the company) |
| Norway      | Company business ID      | `BID@autoinvoice.no`                                                                                                             | −                                                                                                              |
| Denmark     | CVR number               | `CVRnumber@autoinvoice.dk`                                                                                                       | −                                                                                                              |
| Netherlands | VAT number or KvK number | `KvKnumber@autoinvoice.nl` or `VATnumber@autoinvoice.nl` — depending on which was used when the company was registered in Maventa | −                                                                                                              |
| Belgium     | Company business ID      | `BE-ENnumber@scan.maventa.com`                                                                                                   | −                                                                                                              |

#### Delivery of materials

The scan service delivers only invoices and credit notes electronically. When a customer opens the scan service, they specify a scan return address for non-invoice materials. Marketing materials are not delivered.

**Delivered as e-invoices:**

* Invoices
* Credit notes

**Delivered by email:**

* Reminders
* Agreements
* Invoices and credit notes that are missing mandatory information

**Delivered by post:**

* Materials that do not fit in the scanner

**Discarded:**

* Marketing materials such as ads, catalogues, and brochures

Refer to your pricing agreement for delivery costs.

### Error handling

End users can report interpretation errors by contacting the Maventa support team. Support contacts the validation teams at the scan service provider to use the auto-learning process, where interpretation is manually corrected so that invoices are correctly interpreted the next time.

If there are problems with an invoice, users can also request rescanning.

## AutoScan

AutoScan is Maventa's recommended scanning solution for receiving PDF invoices. Powered by Smartscan machine learning technology, it interprets invoice data accurately and near-instantly — delivering results in seconds rather than hours or days. Built-in automated quality checks (VERIFIED) cross-validate key fields like amounts and VAT, so manual verification steps are not needed. The result is a fast, cost-effective scanning pipeline with continuously improving accuracy.

AutoScan is available in all supported markets except Finland, where it is expected to launch in spring 2026.

### Smartscan tiers

AutoScan currently uses the **Smartscan Premium** tier, which includes the VERIFIED feature — a layer of automated checks that cross-validates key invoice fields to ensure they are mathematically consistent. This means fewer errors, fewer manual corrections, and smoother automated processing.

VERIFIED performs consistency checks and cross-validation across key fields on the document, such as amounts, lines, and VAT information. It checks relationships such as:

* Header totals vs. line totals
* VAT amounts vs. base amounts and VAT percentages
* Line-level totals vs. VAT amounts

If everything matches, the data is marked as verified. If discrepancies are found, Smartscan can sometimes correct values automatically based on the cross-validation.

#### Supported fields for VERIFIED

VERIFIED currently covers the following fields:

**Header-level fields**

* `totalInclVat`
* `totalExclVat`
* `totalVat`

**VAT distribution fields**

* `percentage`
* `amount`
* `inclVat`
* `exclVat`

**Purchase line fields**

* `totalInclVat`
* `totalExclVat`
* `totalAmount`
* `totalVat`
* `percentageVat`

#### Smartscan ULTRA (coming later in 2026)

Later this year, Maventa plans to introduce **Smartscan ULTRA** as an optional higher tier. ULTRA builds on everything in Smartscan Premium and adds multiple machine learning models combined with generative AI to verify and improve data quality. Processing may take slightly longer — up to an hour — but the accuracy improvements are significant.

Smartscan ULTRA will be available as an option at an additional cost. More details will follow later in 2026.

### VAT handling

AutoScan supports extracting multiple VAT levels from a document. Smartscan reads the first and last page of the document and extracts VAT information as stated on the invoice — Smartscan itself does not calculate or derive VAT values. When the extracted information is incomplete, AutoScan attempts to calculate the missing values based on the available data and national VAT rules.

If Smartscan determines that no relevant VAT information is present on the document, no VAT output is generated.

How VAT appears in the output depends on the content of the invoice:

**Invoices without line items:**

* If the PDF contains a VAT breakdown that Smartscan can extract, that breakdown is added to the scanned invoice. Each VAT category is listed as its own item, showing the VAT percentage and the amount of VAT paid under that percentage.
* If the invoice does not contain a VAT breakdown, AutoScan estimates the VAT percentage based on the tax information on the invoice and national VAT brackets. The estimate is calculated from total sums and the VAT amount.
* If there are different VAT categories on the invoice, the estimate will be a point estimate somewhere between those categories.
* For Swedish invoices, if AutoScan's estimate is close enough to an existing Swedish VAT category, that category is assigned to the whole invoice. Otherwise, the original estimate is used.

**Invoices with line items:**

* VAT is listed on each line item separately.

#### VAT distribution fields

| Field | Type | Description | Example |
|-------|------|-------------|---------|
| `percentage` | string | VAT level percentage. The decimal delimiter is always a dot. | `"25.0"` |
| `amount` | string | The amount the percentage represents, rounded to two decimal points. | `"585.45"` |
| `inclVat` | string | Amount including VAT for this VAT percentage. | `"2926.25"` |
| `exclVat` | string | The base amount VAT is based on. | `"2341.80"` |

### Opening AutoScan

Before opening AutoScan, make sure the company has invoice receiving enabled. AutoScan can be opened using the REST API method [PUT /v1/services/autoscan](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/putV1ServicesAutoscan) or the user interface. The endpoint activates the service and returns the scan email address.

To check whether AutoScan is active for an account, use [GET /v1/services/autoscan](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/getV1ServicesAutoscan).

The following optional parameters can be included in the request body:

| Parameter | Description |
|-----------|-------------|
| `return_email_address` | Email address where non-invoice materials are forwarded. Not yet mandatory in the API, but highly recommended to include from the start. Becomes mandatory on 17 August 2026. See [return email handling](#return-email-handling) for details. |
| `features.line_scanning` | Set to `true` to enable line scanning. Currently in pilot mode — contact Maventa support to activate. |

Example request:

```json
{
  "return_email_address": "returns@company.com",
  "features": {
    "line_scanning": true
  }
}
```

Example response:

```json
{
  "status": "active",
  "scan_email_address": "NO-987654321@autoscan.maventa.com",
  "return_email_address": "returns@company.com",
  "features": {
    "line_scanning": true
  }
}
```

Once AutoScan is successfully opened, the customer receives an AutoScan email address.

Format: `countrycode-BID@autoscan.maventa.com`
Example: `NO-987654321@autoscan.maventa.com`

### Updating AutoScan

You can update an existing AutoScan account using the REST API method [PUT /v1/services/autoscan](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/putV1ServicesAutoscan) or the user interface. The following settings can be updated:

- **Return email address** — Add or change the return email address for non-invoice materials.
- **Line scanning** — Enable or disable line scanning. Line scanning is in pilot mode and cannot be toggled automatically — contact Maventa support to make changes.

### Closing AutoScan

To disable AutoScan, use the REST API method [DELETE /v1/services/autoscan](https://swagger.maventa.com/#/services/deleteV1ServicesAutoscan) or the user interface.

### Sending invoices to AutoScan

To ensure successful delivery, the supplier should make sure:

* The email contains only one PDF attachment.
* The attached PDF is a recognisable invoice or credit note.
* The PDF file size does not exceed 5 MB.
* The recipient's email address is active.

If processing fails, an error email is sent to the sender. Non-PDF emails and emails containing viruses are automatically discarded.

### Return email handling

AutoScan supports forwarding non-invoice materials to a return email address — similar to how Scan Network handles non-invoice material delivery.

#### How it works

When a PDF sent to a company's AutoScan email address cannot be recognised and processed as an invoice, Maventa forwards it to the company's return email address. Maventa creates a new email with the original PDF as an attachment and includes the original sender's email address in the email body for identification. The original email is not forwarded as is.

Forwarded emails also include a security notice advising recipients that while attachments have been scanned for viruses and spam, they may still carry risk. Recipients are advised to verify the original sender and contact their IT or security team if the message appears suspicious.

Non-invoice materials are only forwarded when the AutoScan service is active for the company. When the service is closed, the sender receives a reply that the email address no longer exists.

As a reminder, AutoScan only accepts PDF attachments. Emails containing other attachment types are rejected and not processed further. Only PDFs are forwarded to the return email address.

> [!WARNING]
> All forwarded emails are scanned for viruses and spam. However, as with any email forwarding, Maventa cannot guarantee that forwarded content is entirely free of risk.

#### Return email parameter timeline

- The `return_email_address` parameter is available as an optional field in the API. New activations through the UI require a return email address.
- **17 August 2026** — The `return_email_address` parameter becomes mandatory in the API. The AutoScan service will be closed for existing users who have not provided a return email address by this date.

> [!NOTE]
> Existing AutoScan users are not required to add a return email address immediately, but we highly recommend providing one as soon as possible. Until one is configured, the previous behaviour of sending an error email to the sender continues. The return email address must be in place by 17 August 2026 to avoid service disruption.

#### Cost

Each non-invoice email forwarded to the return email address is billed at the same rate as a scanned invoice through AutoScan.

### Error handling

To report interpretation errors, contact the Maventa support team.

### AutoScan invoice line scanning

AutoScan also provides a feature to interpret invoice line-level data. Line scanning currently processes only the first 5 pages of the invoice. This feature is in pilot mode — contact Maventa support to enable it.

Interpreted line fields:

* Item number
* Line description
* Product code
* Quantity
* Unit
* Unit price
* Total incl. VAT
* Total excl. VAT
* Total VAT
* VAT %
* Discounts (coming soon)

Later in 2026, an enhanced line scanning option will be available that scans all pages of the invoice without the 5-page limitation. This will be available at an additional cost.

## Visma Scanner and DocScan

Visma Scanner (mobile app) and DocScan (web app from Visma Home) can be used to scan and forward invoices and vouchers. Both use Smartscan machine learning technology for data interpretation.

> [!WARNING]
> Visma Scanner will be deprecated by the end of 2026.

### Enabling Visma Scanner or DocScan

The receiver company needs a Maventa account with invoice receiving enabled. The sender needs the Visma Scanner mobile app or the DocScan web app (from Visma Home).

## Supplier activation service

The supplier activation service identifies suppliers who currently send invoices through the scanning service but could send them electronically instead.

**Version 1** identifies suitable suppliers and sends the list to the buyer by email. The buyer then contacts suppliers directly using their own email systems or other channels. This version requires opting in through the `scan_notification_interval` company setting.

**Version 2**, branded as **Request e-invoices**, replaces the email report with an API and user interface that allows the buyer to trigger Maventa to send activation emails directly to suppliers.

Both versions are available and can be used independently or simultaneously.

### Version 1

The supplier activation feature helps customers identify suppliers who currently send PDF or scanned invoices but could send e-invoices instead. The report makes it easier to reach out to suppliers and encourage them to switch to e-invoicing, helping reduce manual work and scanning costs. The report is generated from invoice data transmitted through Maventa over the past six months.

Maventa sends the supplier list by email. The customer can choose how often to receive the report: daily, weekly, or monthly. The report is sent to one or more email addresses defined in the company settings.

The feature is also available through the [Detect](/integration-guide/invoice-receiving/detect/) service, providing similar insights per invoice through the API instead of the report email.

The supplier activation feature is managed through the `supplier_activation` object in the `PATCH /v1/company/settings` endpoint.

Example request body:

```json
{
  "supplier_activation": {
    "notification_interval": "weekly",
    "scan_notification_emails": [
      "info@company.com",
      "reports@company.com"
    ]
  }
}
```

> [!NOTE]
> This setting is not currently visible in the public Swagger documentation.

`notification_interval` defines how often the supplier activation report is sent:

- `off` — report disabled
- `daily` — sent every day
- `weekly` — sent once a week
- `monthly` — sent once a month

`scan_notification_emails` — one or more email addresses where the report is delivered.

### Version 2

Supplier activation version 2, or the Request e-invoices service, allows you to both retrieve supplier information and send preformatted e-invoice request emails to suppliers, all through the API.

#### List suppliers

Use [POST /v1/company/suppliers/query](https://swagger.maventa.com/#/company/postV1CompanySuppliersQuery) to get a list of suppliers who have sent PDF (scanned) invoices to the account but are capable of sending e-invoices to others. The parameter `oldest_invoice_time` defines how far back Maventa looks for scanned invoices. The maximum lookback period is one month. Note that `include_notified` has no effect yet.

### Request

```json
{
  "include_notified": false,
  "oldest_invoice_time": "2026-01-13T09:32:38.130Z"
}
```

### Response

```json
{
  "status": "completed",
  "suppliers": [
    {
      "company_bid": "123456780",
      "company_country": "FI",
      "invoice_count": 23,
      "company_email": "supplier.contactperson@email.com",
      "company_name": "Example Supplier Company Oy"
    }
  ]
}
```

`invoice_count` indicates the number of PDF invoices the supplier has sent during the selected time period. The `company_email` field is currently not populated but may be added in future updates if this information becomes available from the scanned invoice data.

#### Send the e-invoice request email to suppliers

Use [POST /v1/company/suppliers/notifications](https://swagger.maventa.com/#/company/postV1CompanySuppliersNotifications) to send notification emails to suppliers. You can use the supplier details retrieved from the query endpoint above, or if contact information is missing, specify the supplier names and email addresses manually. The `language` parameter determines the language of the notification email. Templates are available in English (`en`) and in the local language of the company. Currently supported countries are Sweden (`se`), Finland (`fi`), the Netherlands (`nl`), and Norway (`no`).

### Request

```json
{
  "suppliers": [
    {
      "email_address": "supplier.contactperson@email.com",
      "name": "Example Supplier Company AB",
      "language": "se"
    }
  ]
}
```

### Response

Example of failed sends:

```json
{
  "failures": [
    {
      "email": "supplier.contactperson@email.com",
      "reason": "Unsupported language fi"
    }
  ]
}
```

> [!NOTE]
> The response is an empty JSON `{}` if all sends succeeded. Any failed sends are listed in the response.

##### Email content

The notification email includes the following details about the company:

* Peppol ID — if the company is registered to receive invoices through the Peppol network
* E-invoicing address
* Organisation number or VAT number — depending on how the company is registered in Maventa and the country of registration
* Contact email — taken from the company account's invoice email if defined; otherwise, the general company email is used

Example of what the email looks like for a Swedish company:

![Notification email example](/assets/pages/01-integration-guide/02-invoice-receiving/02-scanning/supplier_activation_email.png)

---

## Detect
Source: https://documentation.maventa.com/integration-guide/invoice-receiving/detect/

Detect is an automated service that verifies incoming invoices and their supplier details. It helps companies automate invoice processing, identify potential fraud attempts, and prevent errors in payments and accounting. Detect is integrated into the invoice receiving flow, so notifications appear in the right context alongside the invoice.

## Available checks

### VAT check

`VAT` — For invoices that include value-added tax (VAT), Detect verifies that the sender is registered in the relevant VAT register. If the total VAT amount on the invoice is below 1 EUR/NOK/SEK (depending on currency), the check is skipped.

The data sources depend on the sender's country:

- Norway: Brønnøysundregistrene – [https://brreg.no](https://brreg.no)
- EU countries: VIES – [https://ec.europa.eu/taxation_customs/vies/](https://ec.europa.eu/taxation_customs/vies/)
- Other countries: not supported

### Supplier activation check

`SUPPLIER_ACTIVATION` — For scanned invoices, Detect checks whether the supplier could have sent the invoice electronically instead.

### BID check

`SENDER_BID_STATUS` — Verifies the sender's business identifier against central business and bankruptcy registers. This check is available for invoices from Norwegian and Finnish senders. For Finland, it also includes a check against the Prepayment Register.

The check validates that the sender's business ID is registered and active in the national company register. It also returns information about whether the company is undergoing insolvency or bankruptcy proceedings.

The registers used depend on the sender's country:

- Finland: YTJ – [https://www.ytj.fi](https://www.ytj.fi)
- Norway: Brønnøysundregistrene – [https://brreg.no](https://brreg.no)
- Other countries: not supported

### Warning list check

`SENDER_WARNING_LIST` — Verifies the invoice sender against registers that list suspected fraudsters and businesses involved in scams. See the [warning list guide](#warning-list-guide) section below for details.

### Bank account change check

`BANK_ACCOUNT_CHANGED` — Checks whether the sender has changed their bank account number since the previous invoice. Available for invoices received via Peppol and scanning.

![Check descriptions](/assets/pages/01-integration-guide/02-invoice-receiving/03-detect/detect_intro.png)

## How Detect works

Detect is integrated into the incoming invoice workflow via the REST API. The flow works as follows:

1. The receiving company activates the desired checks. Once activated, Maventa automatically runs them on all incoming invoices for that company.
2. When an invoice becomes available for download, the corresponding check results are also available to retrieve and display.
3. Maventa provides predefined descriptions, notification statuses, and messages. Translations are available in English, Norwegian, Finnish, Swedish, Danish, and Dutch.
4. The integrated system (the company's financial software or ERP) is responsible for activating the checks and displaying the results to the end user.

## Integration requirements

### Process

1. Activate Detect checks — [PATCH /v1/services/detect/checks](https://swagger.maventa.com/#/services/patchV1ServicesDetectChecks)
2. Fetch results for each invoice — [GET /v1/invoices/{id}/detect_results](https://swagger.maventa.com/#/invoices/getV1InvoicesIdDetectResults)
3. Display the results to the user

### Contractual requirements

- The customer has accepted the Terms of Service for Maventa.
- The customer has accepted the General Disclaimer for the service (available at the [end of this page](#general-disclaimer)).

### Authentication

Authenticate as a company and use the `analysis` scope.

## Example flow: activation and usage

### Step 1. Activate the service

To start using Detect, activate the checks you want to use for the company.

> [!NOTE]
> The end user must be shown and must accept the General Service Disclaimer before any checks are activated.

Use [GET /v1/definitions/detect/checks](https://swagger.maventa.com/#/definitions/getV1DefinitionsDetectChecks) to retrieve all available checks and their details, including which registers each check uses. Display this information to the user.

Use [PATCH /v1/services/detect/checks](https://swagger.maventa.com/#/services/patchV1ServicesDetectChecks) to activate checks:

- Provide an array of check identifiers to activate for the company.
- A successful activation returns status OK. From that point on, the selected checks run automatically on all incoming invoices for the company.

Use [GET /v1/services/detect/checks](https://swagger.maventa.com/#/services/getV1ServicesDetectChecks) to confirm which checks are currently active.

Example of check activation in the Maventa user interface:

![Checks activation](/assets/pages/01-integration-guide/02-invoice-receiving/03-detect/detect_checks_activation2.png)

### Step 2. Run checks on incoming invoices

Once activated, Maventa automatically checks all incoming invoices for the company. When the checks are complete, the invoice is released to the customer's inbox and the results become available via the REST API.

Invoices and attachments are downloaded as usual. Detect results are retrieved with a separate call:

Use [GET /v1/invoices/{id}/detect_results](https://swagger.maventa.com/#/invoices/getV1InvoicesIdDetectResults) to fetch results for a specific invoice.

![Fetch results](/assets/pages/01-integration-guide/02-invoice-receiving/03-detect/detect_results.png)

- The response includes results for all activated checks — only one call is needed.
- Invoices are not listed or available for download until all checks are complete.
- If a check fails to run (for example, an external register is unavailable), Maventa retries it automatically.
- The maximum waiting time for invoice release is 4 hours. If a check cannot be completed within that time, it is marked as failed.

### Step 3. Display notifications to the user

After fetching the check results, display relevant notifications to the user. If an issue is detected, show a notification message within the integrated system — for example, in invoice listings, booking views, or approval screens.

All possible check results and their descriptions are available via [GET /v1/definitions/detect/checks](https://swagger.maventa.com/#/definitions/getV1DefinitionsDetectChecks).

Example of result display in a user interface:

![Detect check results](/assets/pages/01-integration-guide/02-invoice-receiving/03-detect/detect_results_invoice.png)

### Step 4. Deactivate checks

Use the same endpoint to deactivate checks:

- Call [PATCH /v1/services/detect/checks](https://swagger.maventa.com/#/services/patchV1ServicesDetectChecks) to modify the active checks.
- To fully close the service, deactivate all checks.

## General disclaimer

> [!WARNING]
> Visma does not warrant that the customer's use of the check services will be uninterrupted or error-free, or that the service and/or the information obtained by the customer through the services will meet the customer's requirements. The customer acknowledges and agrees that the check services will evolve over time and that functionality may be added and removed from time to time.
>
> The customer assumes sole responsibility for results obtained from the use of the check services and for conclusions drawn from them. Visma shall have no liability for any damage caused by errors or omissions in any information, instructions, warnings, or flags provided to the customer in connection with the check services, or the customer's actions or non-actions in response to such information.

## Warning list guide

This section explains the warning list check in detail. It can be shared directly with end users or used as a basis for customer support documentation.

### What is a warning list?

A warning list is a register containing alerts about suspected fraudsters and companies involved in scams or business swindles.

### How does the warning list check work?

When an invoice is received, the sender's company information is compared against a set of warning lists. If a match is found, a notification is issued to the invoice receiver.

The check uses the following information from the sender:

- Company name
- Business ID

<details>
<summary>I received a notification that my invoice is from a company on a warning list. What does this mean?</summary>

The invoice sender has been identified in either a third-party register or a Visma user-generated warning list.

Receiving a warning means that the company name or business ID matches information in at least one of the registers.

In the notification message, the "Source" field indicates which register the sender was found in. If the sender appears on multiple registers, all matching register names are included in the notification.

See the list of registers and the criteria for listing companies below.
</details>

### Sources

The warning list check uses a combination of well-known third-party warning lists and user-reported warnings from Visma customers.

> [!WARNING]
> - This set of registers is not exhaustive. A company not appearing on a list does not guarantee the invoice or sender is legitimate.
> - The information provided by the registers varies. Some may include example invoices, descriptions of past fraud attempts, or other details about reported cases.

#### EUIPO

The European Union Intellectual Property Office list contains warnings focused on companies involved in trademark and design services scams. Typically, the name, logo, or service appears very similar to a real organisation.

- Link to register: [https://euipo.europa.eu/ohimportal/en/misleading-invoices](https://euipo.europa.eu/ohimportal/en/misleading-invoices)
- Criteria for listing: based on reported cases
- Contact information:
  - Telephone: `+34 965 139 100`
  - Email: `information@euipo.europa.eu`
- How to get unlisted: contact EUIPO

#### Svenskhandel Varningslistan

Svenskhandel Varningslistan contains warnings about fraudulent invoices, companies with unscrupulous sales practices, and offers or mailings that may be perceived as misleading.

- Link to register: [https://www.svenskhandel.se/sakerhetscenter/varningslistan/](https://www.svenskhandel.se/sakerhetscenter/varningslistan/)
- Criteria for listing: [https://www.svenskhandel.se/sakerhetscenter/varningslistan/kriterier-for-publicering/](https://www.svenskhandel.se/sakerhetscenter/varningslistan/kriterier-for-publicering/)
- Contact information:
  - Telephone: `010-47 18 500`
  - Email: `info@svenskhandel.se`
  - URL: [https://www.svenskhandel.se/om-svensk-handel/kontakta-oss/](https://www.svenskhandel.se/om-svensk-handel/kontakta-oss/)
- How to get unlisted: contact Svenskhandel

#### Trygg Handel

The Trygg Handel warning list contains warnings against active fraudsters and business scams.

- Link to register: [https://go.trygghandel.no/warninglist](https://go.trygghandel.no/warninglist)
- Criteria for listing: [https://go.trygghandel.no/criteria](https://go.trygghandel.no/criteria)
- Contact information:
  - Telephone: `+47 31 00 31 00`
  - Email: `support@trygghandel.no`
- How to get unlisted: contact Trygg Handel

#### Visma

Visma users can report an invoice if they suspect the sender is fraudulent. The warning message shows how many different invoice receivers have reported the company.

- Link to register: not publicly available
- Criteria for listing: see [Visma warning list criteria](#visma-warning-list-criteria) below
- Contact information:
  - Regular Visma support channel, or `support.maventa@visma.com` for non-Visma customers
- How to get unlisted: contact Visma

### How to handle warnings

Having a routine in place for handling suspected fraud is important. When a warning appears, consider the following steps:

1. Confirm with the supplier whether they actually sent the invoice.
2. Review the invoice details and compare them against any existing agreements.
3. If the invoice appears to be illegitimate, dispute it through the appropriate channel.
4. Report suspected fraud — see [fraud reporting](/integration-guide/invoice-receiving/fraud-reporting/) for details.

Check the relevant regulations and recommended practices for your country and area of business.

### Useful links

#### Financial supervisory authorities

- Norway: Finanstilsynet — [https://www.finanstilsynet.no/](https://www.finanstilsynet.no/) ([English](https://www.finanstilsynet.no/en))
- Finland: FIN-FSA Finanssivalvonta — [https://www.finanssivalvonta.fi/](https://www.finanssivalvonta.fi) ([English](https://www.finanssivalvonta.fi/en/))
- Sweden: Finansinspektionen — [https://www.fi.se/](https://www.fi.se/) ([English](https://www.fi.se/en/))
- Denmark: Finanstilsynet — [https://www.finanstilsynet.dk/](https://www.finanstilsynet.dk/) ([English](https://www.dfsa.dk/))
- Netherlands: Autoriteit Financiële Markten — [https://www.afm.nl/nl-nl](https://www.afm.nl/nl-nl) ([English](https://www.afm.nl/en))

#### Central business registers

- Norway: Brønnøysundregistrene — [https://www.brreg.no/](https://www.brreg.no/)
- Finland: YTJ / PRH — [https://www.ytj.fi/](https://www.ytj.fi/) | [https://www.prh.fi/](https://www.prh.fi/)
- Sweden: Bolagsverket — [https://bolagsverket.se/](https://bolagsverket.se/)
- Denmark: CVR - Det Centrale Virksomhedsregister — [https://datacvr.virk.dk/](https://datacvr.virk.dk/)
- Netherlands: KVK Chamber of Commerce — [https://www.kvk.nl/english/](https://www.kvk.nl/english/)

## Visma warning list criteria

The Visma invoice sender warning list is a crowdsourced list of companies suspected by users of Visma's invoice services, or by a business partner of the sender, to be engaged in suspicious or fraudulent activities.

As part of the warning list check, Detect uses fraud reports from customers. See [fraud reporting](/integration-guide/invoice-receiving/fraud-reporting/) for details on how to integrate fraud reporting.

Companies are listed based on one or more of the following criteria. The decision to add a company to the list is made through a combination of automated and manual evaluation on a case-by-case basis.

If you suspect a company is listed by mistake, contact Visma through regular support channels or email `support.maventa@visma.com`.

- **Product or service does not exist** — The company is selling a product or service that likely does not exist.

- **Offers sent as invoices** — The company sends offers or quotes as invoices, or in a format that can be mistaken for an invoice.

- **Invoices without prior contact** — The company sends invoices to companies it has not previously been in contact with, or refers to agreements that do not exist.

- **Invoices not compliant with laws and regulations** — The company issues invoices that are missing mandatory information or are otherwise suspected of not following relevant laws and regulations.

- **Misleading name** — The company uses a name that can easily be confused with an existing, legitimate company in the same industry.

- **Complaints about business activities** — There have been a significant number of complaints about the company's business activities.

- **No contact information** — The company has no contact information, or it is impossible to reach them using the information provided. Key details such as organisation number or legal entity are missing.

- **Misleading marketing or sales** — The company has a misleading offering or markets to customers in a way that is suspected to be misleading. The total price of the product or service is not stated in the offer.

- **Suspected illegal business practices** — The company's business is suspected of violating laws and regulations or not following good business practices. This includes missing required registrations in national company and tax registers, not having a board, or being in violation of the EU's Anti-Money Laundering Directive or other AML/CTF regulations.

- **Known from earlier fraud attempts** — The company has attempted fraud before, or is connected to companies known for fraud attempts. This includes the use of falsified signatures, bank accounts or addresses previously known in suspicious contexts, or board members connected to other companies with a history of suspicious activity.

- **Known from earlier suspicious activities** — The company has been in the media or is otherwise known for suspicious behaviour. This also applies if the company has connections to other companies or individuals known for suspicious activities.

---

## Fraud reporting
Source: https://documentation.maventa.com/integration-guide/invoice-receiving/fraud-reporting/

Maventa's fraud reporting feature lets end users flag received invoices they suspect to be fraudulent. By adding a “Report fraud” button to your integration, you give users a simple way to report suspicious invoices as part of their normal workflow.

Fraud reporting is a crowd-sourced warning service available through the **AutoXChange API**. When multiple receivers report the same sender, that sender may be added to a warning list. Invoices from listed senders can then trigger alerts through the [Detect](/integration-guide/invoice-receiving/detect/) service.

> [!WARNING]
> Fraud reporting cannot be used to dispute an invoice or refuse payment. Reports are not automatically forwarded to the invoice sender or the authorities.

## How it works

- Each report is linked to a specific received invoice
- The user selects one or more reason categories and provides a contact email
- The user can optionally describe the suspected fraud in more detail
- All UI texts and translations are available via the API
- Only one report per invoice is allowed

## Submitting a report — example flow

Add a button or similar action in your system that lets users report a received invoice as suspected fraud.

![Report button](/assets/pages/01-integration-guide/02-invoice-receiving/04-fraud-reporting/fraud_reporting_button.png)

### Step 1: Show information text

Display an informational text explaining the purpose and limitations of fraud reporting.

Fetch the text and translations using [GET /v1/invoices/reports/definitions](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/getV1InvoicesReportsDefinitions). Available languages: EN, FI, SE, NO, DK, NL.

![Fraud report information text](/assets/pages/01-integration-guide/02-invoice-receiving/04-fraud-reporting/fraud_reporting_information_text.png)

### Step 2: Select reason categories

The user selects one or more reasons for their report from predefined categories. At least one reason must be selected.

Fetch the categories and their descriptions using the same [GET /v1/invoices/reports/definitions](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/getV1InvoicesReportsDefinitions) endpoint. Texts are available in EN, FI, SE, NO, DK, NL.

![Fraud report categories](/assets/pages/01-integration-guide/02-invoice-receiving/04-fraud-reporting/fraud_reporting_categories.png)

### Step 3: Review and submit

The user reviews a summary of the report, provides a contact email, and optionally adds a description.

Submit the report using [POST /v1/invoices/{id}/reports](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/postV1InvoicesIdReports).

Parameters:

- **`id`** (required) — Maventa invoice ID (path parameter)
- **`reason`** (required) — one or more reason categories
- **`email`** (required) — contact email for potential follow-up (not displayed to others)
- **`description`** (optional) — free-text description of the suspected fraud

![Fraud report summary](/assets/pages/01-integration-guide/02-invoice-receiving/04-fraud-reporting/fraud_reporting_summary.png)

> [!NOTE]
> The reporting process does not need to follow a step-by-step flow. You can present all fields on a single screen if that suits your system better. Regardless of the approach, make sure that:
>
> - The user sees the informational text, so they understand what fraud reporting is and is not.
> - At least one reason category is selected, to ensure sufficient case information.
> - A contact email is provided, as it may be used for follow-up.

## View report status

Fetch the status of a fraud report for a specific invoice. Use this to check whether an invoice has already been reported, or to get the report ID needed to delete a report.

Use [GET /v1/invoices/{id}/reports](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/getV1InvoicesIdReports).

## Delete a report

Allow users to delete a report they previously submitted, for example if they no longer suspect fraud or need to correct their report.

Use [DELETE /v1/invoices/{id}/reports/{report_id}](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/deleteV1InvoicesIdReportsReportId).

---

## Webhooks
Source: https://documentation.maventa.com/integration-guide/integration-tools/webhooks/

Maventa supports registering webhooks that allow your system to receive real-time notifications about important events. Instead of polling the API for updates, you simply create a webhook subscription using the AX API. Whenever one of the subscribed events occurs, for example, when a new invoice arrives or its status changes, Maventa sends an HTTP POST request to the endpoint you have defined. These incoming POST requests are what we refer to as receiving events. This makes your integration more efficient, faster, and easier to scale.

## Registering to receive events via webhooks

You can register webhook subscriptions using [POST /v1/company/notifications](https://swagger.maventa.com/#/company/postV1CompanyNotifications).

### For a single company

If you authenticate as an individual company, you can register a webhook that receives events only for that company.

| Key               | Type    | Description   |
| ----------------- | ------- | ------------- |
| destination_type  | string  | WEBHOOK       |
| destination       | string  | Endpoint url  |

Example registering for DELIVERED, DELIVERY_CONFIRMED and FAILED events for invoices

### Request

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

### Response

```json
{
  "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 all networks and all event types

### Request

```json
{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
   "NETWORKS.*"
  ]
}
```

### Response

```json
{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
   "NETWORKS.*"
  ]
}
```

Example registering for RECEIVED events for invoices

### Request

```json
{
  "destination_type": "WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.INVOICE.RECEIVED"
  ]
}
```

### Response

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

### For all companies linked to a partner (vendor webhooks)

Partners can register webhooks that automatically apply to all companies linked to the partner’s vendor API key. This is a one-time setup. Once the subscription is active, your webhook endpoint receives events for every company associated with that vendor key.

> [!NOTE]
> Linking and unlinking vendor API keys is required for this feature to work.

To register vendor webhooks, authenticate with the partner company’s credentials and set `destination_type` to `VENDOR_WEBHOOK`.

| Key               | Type    | Description    |
| ----------------- | ------- | -------------- |
| destination_type  | string  | VENDOR_WEBHOOK |
| destination       | string  | Endpoint url   |

Example registering for all events for all document types

### Request

```json
{
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.*.*"
  ]
}
```

### Response

```json
{
  "id": "d726d240-4631-483e-a4e3-61bbefa0e7b7",
  "destination_type": "VENDOR_WEBHOOK",
  "destination": "https://your.example/endpoint",
  "events": [
    "DOCUMENTS.*.*"
  ]
}
```

#### Vendor key specific webhooks

If you manage multiple vendor API keys and want events separated per key, include `vendor_key` in the subscription payload to filter which events you receive.

| Key               | Type    | Description     |
| ----------------- | ------- | --------------- |
| destination_type  | string  | VENDOR_WEBHOOK  |
| destination       | string  | Endpoint url    |
| vendor_key        | string  | your_vendor_key |

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

### Request

```json
{
  "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"
  ]
}
```

### Response

```json
{
  "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"
  ]
}
```

Example registering for RECEIVED events for invoices with vendor webhooks

### Request

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

### Response

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

## Handling webhook events

Webhook events are delivered as HTTP POST requests to the endpoint URL (destination) configured during registration. Your webhook endpoint should remain lightweight and respond quickly, handling only minimal processing.

For example, when receiving a DOCUMENTS.INVOICE.RECEIVED event, you should store the event_data and trigger a background process to download the invoice instead of performing heavy or long-running logic in the webhook handler. Webhook requests are expected to complete within 5 seconds. Requests that time out are treated as failures and will be retried.

Maventa webhooks use an at-least-once delivery model. This means the same event may be delivered multiple times, and your system must handle deduplication to prevent duplicate processing of invoice events. A webhook delivery is considered successful only if the endpoint responds with an HTTP 200, 201, or 204 status code. Any other response or a timeout is treated as a failure and will trigger a retry. Retries are performed once per hour, up to a maximum of 24 attempts.

Because webhooks are not guaranteed to be 100% reliable, you should implement safeguards to ensure no events are missed. This can be done by subscribing to unacknowledged webhook events or by using the REST API as a fallback to poll for missing data.

If all webhook deliveries for a subscription continue to fail for one month, the webhook subscription will be automatically disabled.

```json
{
  "event":           "<event_name>",
  "company_id":      "<company-uuid>",
  "event_timestamp": "<ISO8601-timestamp>",
  "event_data":      { }
}
```

The `event` is the name of the event e.g. `DOCUMENTS.INVOICE.RECEIVED`.

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

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

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

<details>
<summary>Examples of event_data</summary>

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

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

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

```json
type DocumentsInvoiceFailed
{
  "invoice_id":     "string",
  "invoice_number": "string",
  "destination":    "string", // e.g. "PEPPOL"
  "recipient_name": "string",
  "recipient_bid":  "string",
  "error_message":  "string"
}
```
</details>

### Payload examples

Example of a payload when an invoice is delivered:

```json
{
  "event":"DOCUMENTS.INVOICE.DELIVERED",
  "company_id":"53a4e05d-42f0-4e76-acd6-xxxxxxx",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"12f88354-5998-495b-8675-xxxxxxxx",
    "invoice_number":"1003",
    "destination":"PEPPOL",
    "recipient_name":"Recipient",
    "recipient_bid":"933646920"
  }
}
```

Example of a payload when invoice sending fails:

```json
{
  "event":"DOCUMENTS.INVOICE.FAILED",
  "company_id":"53a4e05d-42f0-4e76-acd6-xxxxxxxxx",
  "event_timestamp":"2019-11-23T12:03:48+02:00",
  "event_data": {
    "invoice_id":"da01a81d-1995-440c-971b-xxxxxxxxx",
    "invoice_number":"1001",
    "destination":"PEPPOL",
    "recipient_name":"Recipient",
    "recipient_bid":"933646920",
    "error_message": "Error that happened"
  }
}
```

Example of a payload when an invoice is received:

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

## Subscribe to unacknowledged webhooks

To improve reliability and ensure that no webhook events are missed, Maventa strongly recommends subscribing to UNACKNOWLEDGED_WEBHOOKS. This subscription notifies you when webhook deliveries have repeatedly failed and provides a controlled mechanism for recovering those events.

When an unacknowledged webhook notification is received, your system can fetch all failed webhook events in a single call using the API method [POST /v1/company/notifications_resend_unacknowledged](https://swagger.maventa.com/#/company/postV1CompanyNotificationsResendUnacknowledged). This endpoint resends all unacknowledged webhook events for the company. Once an event has been successfully processed, any further retry attempts for that event will stop. If all webhook deliveries for a subscription continue to fail for one month, the webhook subscriptions for the company will be automatically disabled.

To enable this functionality, register to the UNACKNOWLEDGED_WEBHOOKS event using the [POST /v1/company/notifications](https://swagger.maventa.com/#/company/postV1CompanyNotifications).

Example payload:

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

The notification itself is delivered as the following payload:

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

Subscribing to unacknowledged webhooks provides proactive visibility into delivery issues. If your system fails to acknowledge webhook events for 24 hours, you will receive a single notification summarizing all unacknowledged events. These notifications are sent once per company per day and can continue for up to one month, helping ensure that delivery failures do not go unnoticed.

## Security

To ensure that messages sent to your webhook endpoint originate from Maventa, Maventa recommends adding an authorisation mechanism to the webhook URL.

You can use one of the following approaches:

- HTTP Basic Authentication

Example: https://user:examplesecret@your-erp.com/webhooks

When a webhook URL is registered in this format, Maventa will call https://your-erp.com/webhooks and include the HTTP header Authorization: Basic dGVzdDpzZWNyZXQ=

- Secret as a URL parameter

Example: https://your-erp.com/webhooks?secret=examplesecret

Please note that the webhook endpoint must support TLS 1.2. Older protocols, including SSLv2, SSLv3, TLS 1.0, and TLS 1.1, are not supported.

## Event types

Maventa supports the following events:

### DOCUMENTS.*.DELIVERED

Triggered when a document has been successfully handed over to the selected delivery channel (e.g., Peppol, email, print). DELIVERED indicates that Maventa has completed its part of the transmission, but it does not guarantee that the final recipient received or accepted the document. For example, an email invoice may still fail later if the message bounces due to an invalid address or a full inbox.

You can show this status to your customers, but note that DELIVERED does not always represent final delivery success.

### DOCUMENTS.*.DELIVERY_CONFIRMED

The DELIVERY_CONFIRMED status indicates that the delivery channel has successfully acknowledged receipt or completed the delivery. Note that not all delivery routes provide this confirmation. When an invoice receives DELIVERY_CONFIRMED, it is considered fully delivered, and the status will no longer change to FAILED.

### DOCUMENTS.*.FAILED

Triggered when a document fails to be delivered due to a final error. This may occur even after a DELIVERED event. The event does include the error details.

### DOCUMENTS.*.RECEIVED

Triggered when your company receives an invoice or any document.

### NETWORKS.*

Triggered for changes in network registrations, such as for Finnish bank network registration (BANK), opening a scan account (SCAN) or registering your company to receive from Peppol network (PEPPOL). Each event reflects a specific lifecycle action: CREATED, ENABLED, or DISABLED.

For example, when the Finnish bank network connection is successfully opened (might take few days from opening), an event NETWORKS.BANK.ENABLED is triggered.

### COMPANIES.AUTHORIZATION.*

When a company’s authorization status changes to either VERIFIED, UNVERIFIED or UNKNOWN.

### UNACKNOWLEDGED_WEBHOOKS

Happens when your system experiences issues and fails to respond within 24 hours, the company will receive a single notification encompassing all unacknowledged webhook events. Unacknowledged webhooks are dispatched once per company per day and will continue for up to one month

---

## Reference implementations
Source: https://documentation.maventa.com/integration-guide/integration-tools/reference-implementations/

Maventa provides reference implementations for **Java** and **C#** to help you get started with the REST API. These projects demonstrate common integration patterns — from authentication and account setup to invoice sending, receiving, and webhook handling.

> [!WARNING]
> The reference implementations are **examples**, not production-ready libraries. Use them as a starting point and learning resource for your own integration, but don't use them as-is in production. Review, adapt, and test the code to fit your specific requirements.

## Available implementations


### Java

A Maven multi-module project with a client wrapper (`maventa-api-client`), auto-generated API client code, and an example project showing how to use them together.

[View Java on GitLab](https://gitlab.com/maventa/reference-implementation-java)

### C#

A .NET project with a client wrapper that mirrors the REST API endpoint structure, making it straightforward to find and call the endpoints you need.

[View C# on GitLab](https://gitlab.com/maventa/reference-implementation-csharp)


## What they cover

Both implementations include examples for the most common integration tasks:

- **Authentication** — Built-in token management that handles access tokens automatically. When authentication parameters change, the client fetches a new token without manual intervention.
- **Account creation** — Creating users, setting up companies, linking to your vendor account, and verifying customer accounts.
- **Invoice sending** — Looking up recipient e-invoicing addresses, sending invoices, monitoring delivery status, and handling routing errors.
- **Invoice receiving** — Registering for receiving networks, fetching incoming invoices, and downloading invoice files.
- **Webhooks** — Subscribing to event notifications for invoice status changes, received documents, and company authorisation updates.
- **Invoice searching** — Querying sent and received invoices with filters like status, date range, and reference numbers.
- **Consumer invoicing (B2C)** — Country-specific examples for Finland, with references to Norwegian and Swedish documentation.

## Getting started

To use either reference implementation, you need:

- An authorised company in Maventa's staging or production environment
- A vendor API key (provided by Maventa)
- A user API key
- A company UUID
- A list of authorisation scopes

Both projects include setup instructions and environment variable configuration in their README files. The client code follows the same structure as the [Swagger documentation](https://swagger.maventa.com), so finding the right method for an API endpoint is straightforward.

If you don't have API keys yet, see the [Getting started](/integration-guide/getting-started/) page for instructions on how to set up your integration credentials.

## How the clients work

The client wrappers organise API endpoints into a namespace structure that mirrors the REST API paths. For example, `/v1/company/settings` maps to `client.company.settings` in both implementations.

### Java

```java
MaventaConfigBuilder builder = new MaventaConfigBuilder()
    .autoXchangeBaseUrl("https://ax.maventa.com")
    .validateBaseUrl("https://validator-api.maventa.com")
    .userApiKey("your-user-api-key")
    .companyUuid("your-company-uuid")
    .vendorApiKey("your-vendor-api-key")
    .authScopes("eui global company");
Config config = builder.build();
MaventaApiClient client = new MaventaApiClient(config);
```

### C#

```csharp
var config = new Maventa.RestApi.Config()
{
    AutoXChangeBaseUrl = "https://ax.maventa.com",
    ValidateBaseUrl = "https://validator-api.maventa.com",
    UserApiKey = "your-user-api-key",
    CompanyUuid = "your-company-uuid",
    VendorApiKey = "your-vendor-api-key",
    AuthScopeString = "eui global company"
};
var client = new Maventa.RestApi.ApiClient(config);
```

---

## Maventa Connector
Source: https://documentation.maventa.com/integration-guide/integration-tools/maventa-connector/

Maventa Connector is a Windows service application that moves electronic documents between Maventa service and local folders on your computer or server. It is typically used to integrate Maventa with ERP systems that do not have direct Maventa integration available.

We do not recommend using Maventa Connector for new integrations. Instead, please consider using Maventa API directly.

## Versions

### Latest version

Latest release 4.8.2022 version number: 2.0.8250.23671

Download the installer from: [MaventaConnectorInstaller_2.0.8250.msi](/assets/pages/01-integration-guide/03-integration-tools/09-maventa-connector/MaventaConnectorInstaller_2.0.8250.msi)

> [!NOTE]
> Note that Connector version 2.0+ requires .NET Framework 4.6.1.

### Old versions

We do not recommend using old versions of Maventa Connector. For special cases we keep some old versions available. Please contact our support for more information.

> [!WARNING]
> **Notes for users of Connector version 1.2**
>
> Connector version 2.0+ has a new installer (MSI) and might not be able to automatically update. Please stop any running MaventaService and uninstall the old Connector version before attempting to install the new version. Your settings and log entries should be restored automatically.

## Security

Connector's security depends 100% on the OS security and folder privileges that it is running on. Connector client program moves documents between a folder and Maventa API using HTTPS same as all other ERP traffic. As the client program only makes API calls and copies files between API and folder and is triggered from the OS side there are no additional security aspects to consider as there are no incoming ports the software listens to. All local users that are given access to the filesystem that contain the configuration files can read the contents (API keys) thus the application should be protected from the OS side users using folder permissions.

The program is using an old framework so software framework itself is outdated and this should be taken into consideration when thinking about using it.  

## FAQ

<details>
<summary>Question: Installer stops with error like "service already exists", what to do?</summary>

The old Connector service called "MaventaService" already exists and needs to be removed manually. Follow these steps:

1. Run (as as admin) the command "services.msc" or browse to the Windows Services Management. See if "Maventa Connector Service" is listed. If it's running, stop it.
2. Open an admin command prompt and run the command: `sc DELETE MaventaService`
3. Reboot computer might be a good idea here
4. Launch new Connector installer which should now be able to pass
</details>

<details>
<summary>Question: Which operating systems are supported?</summary>

Maventa Connector no longer supports older operating systems that have no support for .NET version 4.6.1 or TLS v1.2 encryption. You can use Maventa Connector with these operating systems:

* Windows 7
* Windows 8
* Windows 10
* Windows 11
* Windows Server 2008 R2
* Windows Server 2012
* Windows Server 2012 R2
* Windows Server 2016
* Windows Server 2019
* Windows Server 2022

However, you should not be using an operating system that is no longer supported by Microsoft and expect it to keep working properly forever. For security reasons, always use a supported operating system that still receives security updates from Microsoft.
</details>

## Help

In case of issues with installing or running the Connector, find help at [Maventa Connector at Maventa Knowledge Base](https://maventa.com/knowledge-base/maventa-connector)

There you can also contact customer support in case you need more help.

---

## Embeddable User Interface
Source: https://documentation.maventa.com/integration-guide/integration-tools/embeddable-user-interface/

The Embeddable User Interface (EUI) allows ERP integrators to embed Maventa's interface directly into their product. End customers get access to Maventa features and services without waiting for ERP-side development, reducing time to market for new capabilities.

## What to handle via API vs EUI

Although most functionality is available through the EUI, some functions are best handled through a direct API integration:

- Customer onboarding — [registering](/integration-guide/account-management/companies-and-settings/) companies with Maventa
- [Sending](/integration-guide/invoice-sending/invoice-sending/) and [receiving](/integration-guide/invoice-receiving/) invoices and other documents
- Invoice handling workflows such as approval
- Adding new [users](/integration-guide/account-management/users/) to a Maventa company account

Everything else can be handled through the EUI:

- Listing invoices and documents, and viewing their details
- Resending and rerouting invoices
- Managing Maventa settings
- Registering to receive through different networks
- Searching for receiver's e-invoice addresses
- Listing consumer agreements (Norway)
- Enabling and using services such as [consumer invoicing](/integration-guide/invoice-sending/consumer-invoicing/no/) (currently Norway only), [receivables management](/receivables-customer-guide-fi/) (Finland), Detect, and Visma Scanner

## How the EUI looks

![EUI view for settings](/assets/pages/01-integration-guide/03-integration-tools/11-embeddable-user-interface/eui_settings_invoice_sending_new.png)

## How to take the EUI into use

### Decide what to show and how

Start by deciding which parts of the EUI your end customers need. Then consider how to present those views:

- **Single entry point** — One button that opens the full EUI, letting customers navigate to the page they need
- **Contextual embedding** — Different EUI views embedded in relevant parts of the ERP (e.g. a settings view in the ERP's settings section, invoice lists alongside the ERP's invoice listing)

Read more about [customising the EUI](#customise-your-own-view-of-the-eui). To get started, contact Maventa support and request an [ERP profile](#erp-profiles). Maventa will set up a profile based on your preferences.

### Choose an embedding method

Maventa offers two embedding methods:

1. **[Script embedding](#method-1---script-embedding)** — Include a script tag on your HTML page. Recommended for products that run in the user's browser.
2. **[Iframe embedding](#method-2---iframe-embedding)** — Use an iframe or similar solution. Note that cross-domain content loading may cause issues with this method.

Both methods require [fetching an access token](#fetch-an-access-token-for-the-company) for the company.

### Hosting domains

The EUI is hosted under the following domains:

**Production:**

- `autointerface-embeddable.maventa.com`
- `autointerface-embeddable.autoinvoice.visma.com`
- `autointerface-embeddable.visma.net` (Visma internal use)

**Testing:**

- `autointerface-embeddable-stage.maventa.com`
- `autointerface-embeddable-stage.autoinvoice.visma.com`
- `autointerface-embeddable-stage.visma.net` (Visma internal use)

### Fetch an access token for the company

The EUI uses token-based authentication with `company_uuid`, `user_api_key`, and `vendor_api_key`.

Fetch the token from the [AutoXChange OAuth2 endpoint](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/oauth2/postOauth2Token) using the following parameters:

| Parameter        | Description                                | Value/example                        |
| ---------------- | ------------------------------------------ | ------------------------------------ |
| vendor_api_key   | The vendor API key for the ERP             | 37fc1ebc-dd4f-11ea-87d0-0242ac130003 |
| scope            | The scope required — `eui` is mandatory    | eui                                  |
| grant_type       | The OAuth2 grant type                      | client_credentials                   |
| client_id        | The company UUID                           | 298c6ce2-dd4f-11ea-87d0-0242ac130003 |
| client_secret    | The user API key                           | 32d74434-dd4f-11ea-87d0-0242ac130003 |

**Endpoints:**

- Testing: `https://ax-stage.maventa.com/oauth2/token`
- Production: `https://ax.maventa.com/oauth2/token`

<details>
<summary>cURL example for fetching a token</summary>

```bash
curl -X POST "https://ax-stage.maventa.com/oauth2/token" \
-H "accept: application/json" \
-H "Content-Type: multipart/form-data" \
-F "grant_type=client_credentials" \
-F "client_id=company_uuid" \
-F "client_secret=user_api_key" \
-F "scope=eui" \
-F "vendor_api_key=erp_vendor_api_key"
```
</details>

<details>
<summary>Example of a successful token response</summary>

```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudG......",
  "token_type": "bearer",
  "expires_in": 3600,
  "scope": "eui"
}
```
</details>

Once you have an access token, use it with your chosen embedding method: [script embedding](#method-1---script-embedding) or [iframe embedding](#method-2---iframe-embedding).

### Method 1 - Script embedding

Add a `<script>` tag to your HTML page:

```html
<body>
    <div style="height: 1024px" id="eui-container"></div>
    <script src="https://autointerface-embeddable.maventa.com/embed"
            data-token="eyJ0eXAiOiJKV1QiLCJraWQiOiJjODJhZTdiZTU...."
            data-container-id="eui-container"
            data-default-path="/invoices"
            data-profile="my_erp_profile_name"
            data-locale="en"
            data-setup-top_menu="false"
    ></script>
</body>
```

| Parameter              | Description                                                                            | Value/example                                      |
| ---------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------- |
| src                    | Main URL for EUI                                                                       | https://autointerface-embeddable.maventa.com/embed |
| data-token             | The `access_token` from the OAuth2 response                                            | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9....          |
| data-container-id      | Must match the `id` of the container div. The EUI renders inside this element          | eui-container                                      |
| data-default-path      | Page to open on load. See [direct URLs](#direct-urls)                                  | /invoices                                          |
| data-profile           | The ERP's [profile](#erp-profiles) name for customisation                              | my_erp_profile_name                                |
| data-locale            | Language of the EUI (`fi`, `se`, `no`, `dk`, `nl`, `en`)                               | fi (default: company's country)                    |
| data-setup-top_menu    | [Setup parameter](#setup-parameters) for further customisation                         | false = hide / true = show                         |
| div style="height:.."  | A height must be set on the container, either static or dynamic. Without it, the EUI will not be visible | height: 1024px                    |

In the example above, the EUI opens directly to the invoices page with the language set to English and the top menu hidden.

> [!WARNING]
> With script embedding, there is no way to renew the token. The access token expires after one hour, ending the user's session. Make sure your application allows users to refresh the page and re-authenticate when the token expires.

### Method 2 - Iframe embedding

**Endpoints:**

|                                               | Testing                                                                 | Production                                                        |
| --------------------------------------------- | ----------------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Get access token**                          | https://ax-stage.maventa.com/oauth2/token                               | https://ax.maventa.com/oauth2/token                               |
| **Initiate EUI session**                      | https://autointerface-embeddable-stage.maventa.com/authentication/token | https://autointerface-embeddable.maventa.com/authentication/token |
| **Renew token**                               | https://autointerface-embeddable-stage.maventa.com/authentication/renew | https://autointerface-embeddable.maventa.com/authentication/renew |

#### Monitor token expiry for automatic session renewal

While the EUI session is active, monitor the token expiry time. The `expires_in` attribute in the token response indicates how long the access token is valid. Deduct a few minutes from this value to avoid session interruptions. Stop the renewal process when the user closes the EUI or logs out.

To enable token renewal, pass a unique ID as the `session_id` parameter in the initial authentication request (see the next step). This ID associates the session with subsequent renewal requests.

> [!NOTE]
> If the token is not renewed before it expires, the session ends and the user must re-authenticate.

#### Open the EUI session in a browser component

Once you have a token, open the EUI in a browser component. Depending on the component's capabilities, pass the token either in **the POST body** or in **the Authorization header** as a Bearer token.

| Parameter        | Description                                                                          | Value/example                            |
| ---------------- | ------------------------------------------------------------------------------------ | ---------------------------------------- |
| token            | The `access_token` from the OAuth2 response                                         | eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.... |
| profile          | The ERP's [profile](#erp-profiles) name for customisation                            | my_erp_profile_name                      |
| locale           | Language of the EUI (`fi`, `se`, `no`, `dk`, `nl`)                                   | no                                       |
| redirect_to      | Page to open on load. See [direct URLs](#direct-urls)                                | /invoices                                |
| session_id       | Unique session identifier (UUID recommended)                                         | erp_users_session_id                     |

<details>
<summary>cURL for initiating an EUI session with POST</summary>

```bash
curl -X POST "https://autointerface-embeddable-stage.maventa.com/authentication/token" \
-H "Content-Type: multipart/form-data" \
-F "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9......" \
-F "profile=my_erp_profile_name" \
-F "locale=no" \
-F "redirect_to=/invoices" \
-F "session_id=erp_users_session_id"
```
</details>

<details>
<summary>HTML form example for token login</summary>

```html
<!DOCTYPE html>
<html>
<head></head>
<body>
  <form action="https://autointerface-embeddable-stage.maventa.com/authentication/token" method="POST" target="_blank">
    <fieldset>
      <legend>Authentication using token</legend>
      <br/>
      <label>token:</label>
      <input type="text" name="token" size="100" />
      <br/>
      <label>session_id:</label>
      <input type="text" name="session_id" size="70" />
      <br/>
      <label>redirect_to:</label>
      <input type="text" name="redirect_to" size="70" />
      <br/>
      <label>profile:</label>
      <input type="text" name="profile" size="40" />
      <br/>
      <br/>
      <input type="submit" value="Log in"/>
    </fieldset>
  </form>
</body>
```
</details>

#### Renew the token for an existing session

When the token is about to expire, [fetch a new access token](#fetch-an-access-token-for-the-company) and pass it to the EUI renewal endpoint together with the `session_id` from the initial request. If you can extract the session cookie from the browser component, you can use that instead of the `session_id`.

<details>
<summary>cURL for renewing an EUI session token</summary>

```bash
curl -X POST "https://autointerface-embeddable-stage.maventa.com/authentication/renew" \
-H "Content-Type: multipart/form-data" \
-F "token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpZGVudGl0eSI6InVzZXIiLCJ1c......" \
-F "session_id=erp_users_session_id"
```
</details>

## Customise your own view of the EUI

The EUI is highly customisable. Each ERP can control which views and features are visible to end customers — for example, hiding the received invoices list if the ERP does not support invoice receiving. Customisation is done through [ERP profiles](#erp-profiles) and optional [setup parameters](#setup-parameters).

### ERP profiles

ERP profiles are the primary way to customise the EUI. Each profile is created by the Maventa team based on the ERP's requirements. Contact Maventa support to request a profile before starting the integration.

```bash
...&profile=name_of_the_profile
```

Key points about profiles:

- Each ERP can have multiple profiles (e.g. one per product version or customer group)
- Profiles control which views, settings, and services are visible
- When Maventa adds new services or features to the EUI, the Maventa team contacts ERP integrators to discuss enabling them. Some new services work entirely through the EUI, while others may require ERP-side or API integration changes.

### Setup parameters

Setup parameters provide additional control on top of profiles. They use the same structure as profiles but override profile settings at the request level. This is useful for adjusting views for specific customers without creating separate profiles. Empty values for any setup parameter are treated as `false`.

For example, to hide invoice receiving for customers who do not use that feature:

```bash
...&setup[sections][invoices][inbound]=false
&setup[sections][settings][invoice][receiving]=false
```

<details>
<summary>List of setup parameters</summary>

Use these parameters to show or hide specific parts of the EUI. To request additional parameters, contact Maventa support.

**Menu**

- `menu` — show/hide **all menus (top and left)**
  - `menu` `top_menu` — show/hide only **the top menu**
  - `menu` `left_menu` — show/hide only **the left menu**

**Invoice lists**

- `sections` `invoices`
  - `sections` `invoices` `inbound` — show/hide **the received invoices list**
  - `sections` `invoices` `outbound` — show/hide **the sent invoices list and invoices in error state list**

**Settings**

- `sections` `settings` — show/hide **the entire settings tab from the top menu**
  - `sections` `settings` `company` — show/hide **company settings from the left menu**
    - `sections` `settings` `company` `details` — show/hide **company details**
    - `sections` `settings` `company` `address` — show/hide **company address information**
  - `sections` `settings` `invoice` — show/hide **all invoice settings from the left menu**
    - `sections` `settings` `invoice` `receiving` — show/hide **invoice receiving settings**
    - `sections` `settings` `invoice` `sending` — show/hide **invoice sending settings**
    - `sections` `settings` `invoice` `layout_settings` — show/hide **invoice layout settings**
    - `sections` `settings` `invoice` `notifications` — show/hide **invoice notification settings**

**Other documents**

- `sections` `documents`
  - `sections` `documents` `order` — show/hide **orders**
  - `sections` `documents` `order_response` — show/hide **order responses**
  - `sections` `documents` `catalogue` — show/hide **catalogues**
  - `sections` `documents` `catalogue_response` — show/hide **catalogue responses**
</details>

### Direct URLs

Direct URLs open the EUI on a specific page. Use these to provide contextual navigation — for example, linking to the invoice list from the ERP's invoicing section, or opening the settings page from the ERP's settings area. You can also link directly to a single invoice's details.

<details>
<summary>Available URLs</summary>

**Dashboard**

- `/` — Dashboard (currently a blank page with menus)

**Invoice lists**

- `/invoices` — Received invoices
- `/invoices/outbound` — Sent invoices
- `/invoices/error` — Sent invoices in error state

**Invoice details**

- `/invoices/{invoice_id}` — Details for a received invoice
- `/invoices/outbound/{invoice_id}` — Details for a sent invoice

**Invoice settings**

- `/settings/invoice/sending/index` — Invoice sending settings
- `/settings/invoice/notifications/index` — Invoice notification settings
- `/settings/invoice/receiving/index` — Invoice receiving settings (network activation, scanning service)
- `/settings/invoice/bank_network_no/index` — Consumer invoicing settings (Norway)
- `/settings/invoice/bank_network_fi/index` — Bank network activation (Finland)

**Company settings**

- `/settings/company/details/index` — Company details
- `/settings/company/address/index` — Company address information

**Other document lists**

- `/documents` — Received documents
- `/documents/outbound` — Sent documents
- `/documents/error` — Sent documents in error state

**Other document settings**

- `/settings/document/receiving/index` — Receiving settings for non-invoice documents
- `/settings/additional_services/visma_scanner_receiving/index` — Visma Scanner activation

**Services**

- `/finder` — Finder (search for e-invoice addresses)
- `/receivables` — Receivables management (Finland)
- `/consumer_vendor_registry` — Consumer agreements (Norway)

**Receivables details**

- `/receivables/{invoice_id}` — Details for a receivable assignment
</details>

### Supported browsers

- Chrome
- Firefox
- Safari
- Edge

---

## Peppol Network
Source: https://documentation.maventa.com/integration-guide/peppol/peppol-network/

Peppol provides a standardised way to exchange electronic business documents between buyers and suppliers, both domestically and across borders. Document exchange takes place through Peppol **Access Points** (Certified service providers that connect businesses to the Peppol network, handling the secure sending and receiving of electronic documents), which connect trading partners to the network.

Maventa is a certified Peppol Access Point, registered in the Peppol network as Visma Software International AS. By integrating with Maventa, you can offer Peppol connectivity to your customers.

## Sending invoices via Peppol

Sending invoices through the Peppol network does not require separate registration. Maventa customers can send invoices to Peppol recipients the same way they send invoices through any other network.

To send an invoice via Peppol, provide the recipient's Peppol address and set `PEPPOL` as the operator.

### Peppol addresses

A Peppol address is the recipient's electronic invoicing address within the Peppol network. It consists of two parts:

- **Identifier prefix** — indicates the type of identifier used. The prefix varies by country. See the official [ICD code list](https://docs.peppol.eu/poacc/billing/3.0/codelist/ICD/) for details.
- **Company identification number** — uniquely identifies the company (for example, an organisation number).

For example, in Norway the prefix for organisation numbers is `0192`. A Norwegian company with organisation number `123456789` would have the Peppol address `0192:123456789`.

### Recipient lookup

To check whether a company can receive invoices via Peppol, use [Maventa's Peppol participant lookup tool](https://lookup.maventa.com/) or the [GET /v1/lookup/receivers](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/lookup/getV1LookupReceivers) API method.

The lookup confirms whether the recipient is registered in the Peppol network and returns their Peppol address and supported document types (such as `INVOICE` or `CREDIT_NOTE`).

For detailed instructions on using the lookup API — including parameters, request examples, and automatic routing — see the [recipient lookup and routing](/integration-guide/invoice-sending/invoice-sending/#recipient-lookup-and-routing) section in the invoice sending guide.

> [!WARNING]
> When searching for Peppol recipients through the lookup API, there is a known limitation. To perform a Peppol Directory lookup, use the `name` field for either the recipient's name or business ID. The `bid` field does not currently work for Peppol lookups. This will be corrected in a future version of the API.

### Testing Peppol sending

The Maventa testing environment is connected to the Peppol test network, so Peppol sends are processed as real transactions within the test network. You can register one of your test accounts as a Peppol receiver — the registration is created in the Peppol test environment. Then send an invoice to that account from another test account to verify the full Peppol flow end to end. You can also use [Peppol's public test endpoints](https://peppol.helger.com/public/locale-en_US/menuitem-tools-test-endpoints) to send test invoices without needing a real Peppol recipient.

### Format handling

Invoices sent through Peppol must comply with Peppol format rules. If the original invoice is not in a Peppol format, Maventa converts it automatically before sending. All invoices are validated against Peppol rules before transmission — invoices that fail validation cannot be sent.

For more information about Peppol formats, see the [Peppol profiles and specifications](https://peppol.eu/what-is-peppol/peppol-profiles-specifications/).

## Receiving invoices via Peppol

To receive invoices through the Peppol network, a company must be registered as a Peppol receiver.

Once registered, the company can receive electronic invoices from any sender connected to the Peppol network. The company's details are published in the [Peppol Directory](http://directory.peppol.eu/), which serves as a shared address book listing all registered receivers, their supported document types, and format versions.

### Document types

During registration, the company selects which document types it wants to receive:

- **Invoices and credit notes** — Registering with the `INVOICE_AND_CREDIT_NOTE` profile automatically registers both document types: Peppol BIS Billing UBL Invoice V3 (`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`) and Peppol BIS Billing UBL Credit Note V3 (`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`). Some countries also support additional, country-specific formats that are included automatically. See the country-specific guides for supported formats.
- **Self-billing** — Companies that want to receive self-billing invoices can register an additional profile for self-billing invoices and credit notes.

### Registering as a Peppol receiver

Once a company account has been created in Maventa and receiving is enabled (VISMA network), the company can be registered as a Peppol receiver by creating a Peppol profile.

Maventa registers the company in the Peppol **SMP** (Service Metadata Provider — a registry that stores which organisations can receive documents via Peppol and how to reach them), which then synchronises with the Peppol Directory.

> [!WARNING]
> If the company is already registered to receive invoices through a different Access Point, that registration must be removed by the previous Access Point before Maventa can complete the new registration.

> [!NOTE]
> **Company email requirement**
>
> The company email must be set on the Maventa account before registration (required at minimum in Norway).

#### Register for invoices and credit notes

Call [POST /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/postV1CompanyProfiles) with the following parameters:

- **profile**: `INVOICE_AND_CREDIT_NOTE`
- **network**: `PEPPOL`

After registration completes, the response includes the Peppol address the company was registered with.

To receive notifications when registration completes, register a [webhook](/integration-guide/integration-tools/webhooks/) with the `NETWORKS` event type.

Use [GET /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/company/getV1CompanyProfiles) to view active profiles for the `PEPPOL` network.

#### Register for self-billing

Call [POST /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/postV1CompanyProfiles) with the following parameters:

- **profile**: `SELF_BILLING_INVOICE` or `SELF_BILLING_CREDIT_NOTE`
- **network**: `PEPPOL`

Use [GET /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/company/getV1CompanyProfiles) to view active profiles for the `PEPPOL` network.

#### Remove a registration

To remove a company from the Peppol network, call [DELETE /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/deleteV1CompanyProfilesId) with the profile ID of the registration to delete.

### Supported countries and identifiers

Maventa registers companies with the following identifiers (schemes):

| Country | Identifier | Prefix |
|---|---|---|
| Finland | **OVT** (Organisaatioiden Välinen Tiedonsiirto — a Finnish electronic address identifier created by combining prefix '0037' with the Business ID) | `0216` |
| Sweden | Organisation number | `0007` |
| Norway | Organisation number | `0192` |
| Denmark | **CVR** (Det Centrale Virksomhedsregister — the Danish Central Business Register number) | `0184` |
| Netherlands | **KVK** (Kamer van Koophandel — the Dutch Chamber of Commerce registration number) or VAT number | **`0106` or `9944`** (Depends on which identifier was used to register the company account in Maventa) |
| Belgium | Organisation number (**CBE** (Crossroads Bank for Enterprises — the Belgian business register number, also known as KBO in Dutch)) | `0208` |
| Germany | VAT number | `9930` |
| Estonia | VAT number | `9931` |
| Latvia | VAT number | `9939` |

> [!NOTE]
> To register a participant outside of these countries or with a different identifier, contact Maventa.

> [!IMPORTANT]
> **Registration timing**
>
> Registrations are usually processed immediately. If there are issues with the Peppol register, there may be a delay of up to a few days.

### Before registering

Before creating a new registration, check the company's existing registrations:

- If the company is already registered through Maventa, no further action is needed.
- If the company is registered through a different Access Point, the previous registration must be removed before Maventa can complete the new one. The company needs to contact the previous Access Point to deregister.

---

## Document Exchange
Source: https://documentation.maventa.com/integration-guide/peppol/document-exchange/

In addition to invoices, Maventa supports the exchange of other trading documents via the Peppol network. This includes ordering documents (orders, order responses, catalogues, invoice responses, reminders and more).

Exchanging structured ordering documents through Peppol automates the purchase-to-pay process. Steps like approvals, order picking, and invoicing can be handled electronically, reducing manual work and errors.

- [Peppol BIS ordering](https://docs.peppol.eu/poacc/upgrade-3/profiles/28-ordering/)
- [All Peppol document types and profile versions](https://docs.peppol.eu/poacc/upgrade-3/)

## Documents endpoint

> [!NOTE]
> The Documents endpoint is meant for other trading documents such as orders, catalogues, despatch advice, and reminders. For exchanging invoices and credit notes, use the [Invoices API](/api-specification/rest-api/invoices-api/).

> [!WARNING]
> Format conversions and full recipient lookup features are not supported for the Documents endpoint.

### Document sending

Documents are sent by uploading a document file in XML format along with the required parameters in the API call.

Use [POST /v1/documents](https://swagger.maventa.com/#/documents/postV1Documents) to send a document. The call returns a document ID.

**Parameters:**

| Parameter | Required | Description |
|---|---|---|
| `file` | Yes | The document file in XML format |
| `type` | No | Type of document (e.g. ORDER, CATALOGUE). If not provided, Maventa will try to determine the type from the XML content. |
| `recipient_eia` | No | Electronic invoicing address of the recipient |
| `recipient_operator` | No | Operator of the recipient (e.g. PEPPOL) |
| `recipient_name` | No | Name of the recipient |
| `recipient_country` | No | Recipient country in ISO 3166-1 alpha-2 format |
| `sender_eia` | No | Electronic invoicing address of the sender |
| `sender_name` | No | Name of the sender |
| `sender_country` | No | Sender country in ISO 3166-1 alpha-2 format |
| `transmission_id` | No | Unique transmission ID for idempotency (see [Transmission ID and idempotency](#transmission-id-and-idempotency)) |
| `reference_id` | No | ID of a related document to link to (requires `reference_id_type` and `type`) |
| `reference_id_type` | No | Type of reference: `document_id`, `external_storage_key`, or `document_file_id` |

For ORDER_RESPONSE documents, additional parameters are available:

| Parameter | Description |
|---|---|
| `order_response[response_code]` | ACCEPTED or REJECTED |
| `order_response[response_reason]` | Reason for rejection (required if rejected, max 256 characters) |
| `order_response[contact_name]` | Contact person name (max 64 characters) |
| `order_response[contact_email]` | Contact email (max 256 characters) |
| `order_response[contact_phone]` | Contact phone (max 32 characters) |

> [!WARNING]
> When `response_code` is REJECTED, `response_reason` is required and at least one contact field (`contact_name`, `contact_email`, or `contact_phone`) must be provided.

> [!NOTE]
> Currently, POST /v1/documents does not perform automatic recipient lookup. To send a document, provide both the recipient's full Peppol ID (`recipient_eia`) and the operator (`recipient_operator` set to PEPPOL) in the request parameters.

Use [GET /v1/documents/{id}](https://swagger.maventa.com/#/documents/getV1DocumentsId) to check the status of a sent document, to see whether it was delivered successfully or failed. You can also use [webhooks](/integration-guide/integration-tools/webhooks/) to receive real-time notifications of document status changes.

### Document statuses

Documents go through the following statuses during their lifecycle:

| Status | Description |
|---|---|
| `PROCESSING` | The document has been received by Maventa and is being processed for delivery. |
| `DELIVERED` | The document has been successfully delivered to the recipient. |
| `CONFIRMED_DELIVERY` | The recipient has confirmed that the document has been downloaded and processed. This status is set by the recipient using [PATCH /v1/documents/{id}](https://swagger.maventa.com/#/documents/patchV1DocumentsId). |
| `FAILED` | The document could not be delivered. Check the [document events](#document-events) for details about the failure. |

### Document receiving

To receive documents, first register the company as a document receiver using [POST /v1/company/profiles](https://swagger.maventa.com/#/profiles/postV1CompanyProfiles).

Once registered, documents are received by listing new incoming documents in Maventa and then downloading them into the financial system:

1. Use [GET /v1/documents](https://swagger.maventa.com/#/documents/getV1Documents) with parameters `direction=RECEIVED`, `created_at_start`, and `created_at_end` to get a list of documents available for download. Use the `per_page` and `page` parameters for pagination.
2. Use [GET /v1/documents/{id}](https://swagger.maventa.com/#/documents/getV1DocumentsId) to download the document.
3. Use [PATCH /v1/documents/{id}](https://swagger.maventa.com/#/documents/patchV1DocumentsId) to mark the document status to `CONFIRMED_DELIVERY` after downloading. Only when the document is in `CONFIRMED_DELIVERY` status is the download process considered completed by the system.

> [!WARNING]
> Only the recipient of a document can set the status to `CONFIRMED_DELIVERY`, and only when the document is in `DELIVERED` state. The API returns an error if you attempt to confirm delivery on a sent document or a document not in `DELIVERED` state.

### Querying documents

Use [GET /v1/documents](https://swagger.maventa.com/#/documents/getV1Documents) to list and filter documents. The following query parameters are available:

| Parameter | Description |
|---|---|
| `direction` | Filter by direction: `RECEIVED` or `SENT` |
| `type` | Filter by document type (e.g. ORDER, CATALOGUE) |
| `status` | Filter by document status |
| `ids` | Retrieve a batch of documents by ID (comma-separated, max 100) |
| `number` | Filter by document number (exact match) |
| `reference` | Filter by document reference (exact match) |
| `query` | Search across multiple fields — matches on document ID, reference, and number |
| `created_at_start` | Start of date range for document creation |
| `created_at_end` | End of date range for document creation |
| `sort` | Sort results by field: `id`, `type`, `status`, `number`, `reference`, `created_at`, or `received_at`. Prefix with `-` for descending order (e.g. `-created_at`). Default: `created_at` ascending. |
| `page` | Page number for pagination |
| `per_page` | Number of results per page (default: 10, max: 100) |

The response includes pagination headers: `X-Total`, `X-Total-Pages`, `X-Page`, `X-Next-Page`, `X-Prev-Page`, `X-Per-Page`, and a `Link` header.

### Transmission ID and idempotency

The `transmission_id` parameter in POST /v1/documents prevents duplicate document sends. If a `transmission_id` is provided and a document with the same value already exists, the API returns an error instead of creating a duplicate. Using `transmission_id` is recommended for production integrations to prevent duplicates caused by retries or network issues.

### Document events

Use [GET /v1/documents/{id}/events](https://swagger.maventa.com/#/documents/getV1DocumentsIdEvents) to retrieve the event history of a document. Each event contains:

| Field | Description |
|---|---|
| `code` | Event code identifier |
| `message` | Human-readable event message |
| `details` | Additional information about the event |
| `created_at` | Timestamp of the event |

Events provide an audit trail of what has happened to a document during its lifecycle — for example, delivery attempts, status changes, and errors.

### Linking related documents

In a purchase-to-pay flow, multiple document types relate to the same transaction — an order leads to an order response, then a despatch advice, and eventually an invoice. Maventa does not perform automatic order matching, but it provides tools for the integrating system to link related documents and track the full document chain.

**Linking via reference parameters**

When sending an ORDER_RESPONSE, you can link it to the original ORDER by providing `reference_id` (the document ID of the order) and `reference_id_type` set to `document_id`. This links the response to the original order in Maventa.

Example — sending an order response linked to the original order:

```json
{
  "type": "ORDER_RESPONSE",
  "reference_id": "d290f1ee-6c54-4b01-90e6-d701748f0851",
  "reference_id_type": "document_id",
  "order_response": {
    "response_code": "ACCEPTED",
    "contact_name": "Jane Doe",
    "contact_email": "jane@example.com"
  }
}
```

**Tracking documents by reference**

Each document can carry a `reference` field (extracted from the XML content), which typically contains a purchase order number or other business reference. Use this field to correlate documents across the transaction lifecycle:

- Filter documents by reference: `GET /v1/documents?reference=PO-2025-001`
- Search across ID, reference, and number: `GET /v1/documents?query=PO-2025-001`

For example, if an order, despatch advice, and invoice all carry the same purchase order reference, you can retrieve all related documents with a single query. The integrating system can then perform its own matching logic — such as three-way matching between order, goods receipt, and invoice.

### Registering for document types

To receive ordering and other document types, register the company for each desired profile using [POST /v1/company/profiles](https://swagger.maventa.com/#/profiles/postV1CompanyProfiles). Specify the profile name, network, and profile version.

Example request:

```json
{
  "network": "PEPPOL",
  "profiles": ["INVOICE_RESPONSE"],
  "profile_version": "PEPPOLBIS30"
}
```

> [!WARNING]
> Ordering profiles (ORDER, ORDER_RESPONSE, CATALOGUE, CATALOGUE_RESPONSE, DESPATCH_ADVICE, and REMINDER) require a profile version — either `PEPPOLBIS30` or `EHF30`. Registration without a profile version will fail. Make sure the integrating system is able to process the requested profile version.

#### Supported profiles and versions

<details>
<summary>ORDER</summary>

The buyer sends an Order to a supplier to request goods or services. The order contains details such as item descriptions, quantities, prices, delivery dates and delivery addresses. It serves as the formal starting point of a purchase transaction in the Peppol procurement flow.

**Profile versions:** PEPPOLBIS30, EHF30

**Markets:** FI, NO, SE, DK, NL

**Peppol document identifiers:**

- **PEPPOLBIS30:** `urn:oasis:names:specification:ubl:schema:xsd:Order-2::Order##urn:fdc:peppol.eu:poacc:trns:order:3::2.1`
- **EHF30:** `urn:oasis:names:specification:ubl:schema:xsd:Order-2::Order##urn:fdc:peppol.eu:poacc:trns:order:3:extended:urn:fdc:anskaffelser.no:2019:ehf:spec:3.0::2.2`
</details>

<details>
<summary>ORDER_RESPONSE</summary>

The supplier sends an Order Response back to the buyer after receiving an order. The response indicates whether the order is accepted, rejected, or accepted with changes — for example, adjusted quantities or delivery dates. This closes the loop on the ordering process before fulfilment begins.

**Profile versions:** PEPPOLBIS30, EHF30

**Markets:** FI, NO, SE, DK, NL

**Peppol document identifiers:**

- **PEPPOLBIS30:** `urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2::OrderResponse##urn:fdc:peppol.eu:poacc:trns:order_response:3::2.1`
- **EHF30:** `urn:oasis:names:specification:ubl:schema:xsd:OrderResponse-2::OrderResponse##urn:fdc:peppol.eu:poacc:trns:order_response:3:extended:urn:fdc:anskaffelser.no:2019:ehf:spec:3.0::2.2`
</details>

<details>
<summary>CATALOGUE</summary>

A supplier sends a Catalogue to a buyer to present the available products or services, including item details, pricing, and classification. Catalogues form the basis for structured ordering — the buyer can reference catalogue items directly when placing orders, reducing manual entry and errors.

**Profile versions:** PEPPOLBIS30, EHF30

**Markets:** FI, NO, SE, DK, NL

**Peppol document identifiers:**

- **PEPPOLBIS30:** `urn:oasis:names:specification:ubl:schema:xsd:Catalogue-2::Catalogue##urn:fdc:peppol.eu:poacc:trns:catalogue:3::2.1`
- **EHF30:** `urn:oasis:names:specification:ubl:schema:xsd:Catalogue-2::Catalogue##urn:fdc:peppol.eu:poacc:trns:catalogue:3:extended:urn:fdc:anskaffelser.no:2019:ehf:spec:3.0::2.2`
</details>

<details>
<summary>CATALOGUE_RESPONSE</summary>

The buyer sends a Catalogue Response back to the supplier to confirm whether a received catalogue has been accepted or rejected. This allows the supplier to know if their catalogue is active and available for ordering on the buyer's side.

**Profile versions:** PEPPOLBIS30, EHF30

**Markets:** FI, NO, SE, DK, NL

**Peppol document identifiers:**

- **PEPPOLBIS30:** `urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:catalogue_response:3::2.1`
- **EHF30:** `urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:catalogue_response:3:extended:urn:fdc:anskaffelser.no:2019:ehf:spec:3.0::2.2`
</details>

<details>
<summary>DESPATCH_ADVICE</summary>

The supplier sends a Despatch Advice to the buyer when goods are shipped. It lists what was actually sent — item descriptions, quantities, batch numbers, and packaging details. The buyer can use it to prepare for goods reception and match the shipment against the original order before the invoice arrives.

**Profile versions:** PEPPOLBIS30, EHF30

**Markets:** FI, NO, SE, DK, NL

**Peppol document identifiers:**

- **PEPPOLBIS30:** `urn:oasis:names:specification:ubl:schema:xsd:DespatchAdvice-2::DespatchAdvice##urn:fdc:peppol.eu:poacc:trns:despatch_advice:3::2.1`
- **EHF30:** `urn:oasis:names:specification:ubl:schema:xsd:DespatchAdvice-2::DespatchAdvice##urn:fdc:peppol.eu:poacc:trns:despatch_advice:3:extended:urn:fdc:anskaffelser.no:2019:ehf:spec:3.0::2.2`
</details>

<details>
<summary>VOUCHER</summary>

A Voucher is a financial document typically used in the public sector to authorise or record a payment, such as expense claims, internal transfers, or other non-invoice payment authorisations. In Maventa, VOUCHER is supported on the scanning network (VISMASCANNER) — there is no Peppol document identifier for this type. Read more about [scanning](/integration-guide/invoice-receiving/scanning/).

**Network:** VISMASCANNER

**Markets:** FI, NO, SE, DK, NL
</details>

<details>
<summary>SELF_BILLING_INVOICE</summary>

A Self-Billing Invoice is created by the buyer instead of the supplier. In a self-billing arrangement, the buyer calculates the amount owed and issues the invoice on behalf of the supplier. This is common in industries with frequent deliveries or consignment stock, where the buyer has better visibility into what was received. Self-billing is supported via the invoices endpoint. Read more about [self-billing support](/integration-guide/peppol/self-billing-support/).

**Profile versions:** PEPPOLBIS30

**Peppol document identifier:**

- `urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1`
</details>

<details>
<summary>SELF_BILLING_CREDIT_NOTE</summary>

A Self-Billing Credit Note follows the same principle as a Self-Billing Invoice — it is issued by the buyer on behalf of the supplier. It is used to correct or reverse a previously issued self-billing invoice, for example when goods are returned or an amount was calculated incorrectly. Self-billing is supported via the invoices endpoint. Read more about [self-billing support](/integration-guide/peppol/self-billing-support/).

**Profile versions:** PEPPOLBIS30

**Peppol document identifier:**

- `urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0::2.1`
</details>

<details>
<summary>RECEIPT</summary>

A Receipt Advice is sent by the buyer to the supplier to confirm that goods or services have been received. It can report full or partial receipt, and may include details about rejected or damaged items. The supplier can use this as confirmation before invoicing.

**Profile versions:** PEPPOLBIS30
</details>

<details>
<summary>REMINDER</summary>

A Reminder is a payment reminder sent to a buyer when an invoice is overdue. This is a Norwegian-specific profile based on the EHF Reminder specification. Technically, it reuses the Invoice document type with a reminder-specific conformance identifier, which means the XML structure follows the invoice format but is identified as a reminder through the customisation ID.

**Profile versions:** PEPPOLBIS30, EHF30

**Markets:** FI, NO, SE, DK, NL

**Peppol document identifier:**

- `urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0#conformant#urn:fdc:anskaffelser.no:2019:ehf:reminder:3.0::2.2`
</details>

<details>
<summary>INVOICE_RESPONSE</summary>

The buyer sends an Invoice Response to communicate the processing status of a received invoice back to the supplier. The response can indicate that the invoice has been received, is under processing, has been approved, rejected, or is conditionally accepted. This gives suppliers visibility into where their invoice stands in the buyer's approval workflow.

**Profile versions:** PEPPOLBIS30

**Markets:** FI, NO, SE, DK, NL, BE

**Peppol document identifier:**

- `urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1`
</details>

<details>
<summary>MESSAGE_LEVEL_RESPONSE</summary>

A Message Level Response (MLR) is an automated technical acknowledgement sent by the receiving access point or end system. Unlike the Invoice Response, which reflects a business decision, the MLR indicates whether the document was successfully received and could be processed at a technical level — for example, whether the XML was valid and the recipient could be identified. It is part of the Peppol infrastructure layer rather than the business document flow.

**Profile versions:** PEPPOLBIS30

**Markets:** FI, NO, SE, DK, NL, BE

**Peppol document identifier:**

- `urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:mlr:3::2.1`
</details>

<details>
<summary>INVOICE **Deprecated**</summary>

Use INVOICE_AND_CREDIT_NOTE instead. Invoices and credit notes are handled via the [Invoices API](/api-specification/rest-api/invoices-api/), not the Documents endpoint. Read more about [invoice sending](/integration-guide/invoice-sending/invoice-sending/).
</details>

<details>
<summary>CREDIT_NOTE **Deprecated**</summary>

Use INVOICE_AND_CREDIT_NOTE instead. Invoices and credit notes are handled via the [Invoices API](/api-specification/rest-api/invoices-api/), not the Documents endpoint. Read more about [invoice sending](/integration-guide/invoice-sending/invoice-sending/).
</details>

<details>
<summary>ORDER_CHANGE **Removed**</summary>

Order change documents are defined in the Peppol advanced ordering specification but are not currently fully supported by Maventa. If you are interested in this document type, please contact Maventa support.
</details>

<details>
<summary>ORDER_CANCELLATION **Removed**</summary>

Order cancellation documents are defined in the Peppol advanced ordering specification but are not currently fully supported by Maventa. If you are interested in this document type, please contact Maventa support.
</details>

<details>
<summary>EXPRESSION_OF_INTEREST_REQUEST **Removed**</summary>

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.
</details>

<details>
<summary>EXPRESSION_OF_INTEREST_RESPONSE **Removed**</summary>

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.
</details>

<details>
<summary>TENDER_STATUS_REQUEST **Removed**</summary>

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.
</details>

<details>
<summary>CALL_FOR_TENDERS **Removed**</summary>

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.
</details>

<details>
<summary>TENDER **Removed**</summary>

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.
</details>

<details>
<summary>TENDER_RECEIPT **Removed**</summary>

Part of the Peppol pre-award (tendering) domain. Not currently fully supported by Maventa. If you are interested in tendering document support, please contact Maventa support.
</details>

<details>
<summary>BANK_FILE **Removed**</summary>

Not currently fully supported by Maventa. If you are interested in this document type, please contact Maventa support.
</details>

<details>
<summary>SCAN **Removed**</summary>

Scanning is handled through a separate scanning service and the profiles API, not the Documents endpoint. Read more about [scanning](/integration-guide/invoice-receiving/scanning/).
</details>

> [!NOTE]
> If you are interested in a document type not listed here, please contact Maventa support.

---

## Invoice Response
Source: https://documentation.maventa.com/integration-guide/peppol/invoice-response/

## What is an invoice response?

An invoice response is a message between buyer and seller that provides an efficient way to communicate the processing status of a received invoice in the Peppol network.

For example, the buyer can inform the seller whether an invoice has been rejected, is under query, has been approved, or has been paid.

For detailed use cases and the full specification, see the [Peppol BIS Invoice Response 3.2 documentation](https://docs.peppol.eu/poacc/upgrade-3/profiles/63-invoiceresponse/).

## Setting up invoice responses

### For a company sending invoices (seller)

When a company sends invoices, it is the seller and therefore the receiver of invoice responses from the buyer. Follow these steps to enable receiving.

#### Step 1: Register for invoice response receiving

Register a receiving profile for invoice responses in the Peppol network.

Call [POST /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/postV1CompanyProfiles) with the following parameters:

- **profile**: `INVOICE_RESPONSE`
- **network**: `PEPPOL`

Once the profile is created, use [GET /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/company/getV1CompanyProfiles) to verify that the profile has been activated for the `PEPPOL` network.

#### Step 2: Integrate with the documents endpoint

Incoming invoice responses are received through the documents endpoint. See the [document receiving](/integration-guide/peppol/document-exchange/#document-receiving) section for details on listing and downloading received documents.

#### Step 3: Process the received invoice response

Parse the received XML and update your system accordingly. For details about the content and structure of invoice responses, see the [Peppol documentation](https://docs.peppol.eu/poacc/upgrade-3/profiles/63-invoiceresponse/).

### For a company receiving invoices (buyer)

When a company receives invoices, it is the buyer and therefore the sender of invoice responses to the seller. Follow these steps to enable sending.

#### Step 1: Integrate to receive invoices

Set up invoice receiving so you have invoices to respond to.

#### Step 2: Check if the seller supports invoice responses

Before sending an invoice response, check whether the seller can handle invoice response documents. Use the [GET /v1/lookup/receivers](https://swagger.maventa.com/#/lookup/getV1LookupReceivers) endpoint with the seller's identifier from the received invoice.

In a Peppol BIS 3.0 document, the seller's identifier is in the `EndpointID` element:

```xml
  <cbc:ID>567</cbc:ID>
  ...
  <cac:AccountingSupplierParty>
    <cac:Party>
      <cbc:EndpointID schemeID="0216">003751734872004</cbc:EndpointID>
      ...
    </cac:Party>
  </cac:AccountingSupplierParty>
```

The lookup requires three parameters:

- `network` — set to `PEPPOL`
- `document_type` — set to `INVOICE_RESPONSE`
- `eia` — the seller's identifier in the format `0216:003751734872004` (taken from the received invoice)

### Request (curl)

```bash
curl -X 'GET' \
  'https://ax-stage.maventa.com/v1/lookup/receivers?network=PEPPOL&eia=0216%3A003751734872004&document_type=INVOICE_RESPONSE' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer TOKEN'
```

### Response (json)

```json
[
  {
    "eia": "0216:003751734872004",
    "network": "PEPPOL",
    "operator": "PEPPOL",
    "document_types": [
      {
        "document_type": "INVOICE_RESPONSE",
        "document_identifier": "urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2::ApplicationResponse##urn:fdc:peppol.eu:poacc:trns:invoice_response:3::2.1",
        "process_identifier": "urn:fdc:peppol.eu:poacc:bis:invoice_response:3"
      },
      ...
    ],
    "participant": {
      "name": "Seller",
      "country": "FI"
    }
  }
]
```

If the seller is registered for invoice responses, the endpoint returns matching entries. If not, the response is an empty array.

#### Step 3: Generate and send an invoice response

Create a compliant invoice response XML document. For details about the business content and structure, see the [Peppol BIS Invoice Response specification](https://docs.peppol.eu/poacc/upgrade-3/profiles/63-invoiceresponse/).

Below is an example invoice response payload that acknowledges receipt of invoice `567` from seller `0216:003751734872004`:

```xml
<?xml version="1.0" encoding="UTF-8"?>

<ApplicationResponse xmlns="urn:oasis:names:specification:ubl:schema:xsd:ApplicationResponse-2" xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2" xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <cbc:CustomizationID>urn:fdc:peppol.eu:poacc:trns:invoice_response:3</cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:poacc:bis:invoice_response:3</cbc:ProfileID>
  <cbc:ID>1</cbc:ID>
  <cbc:IssueDate>2024-01-01</cbc:IssueDate>
  <cac:SenderParty>
    <cbc:EndpointID schemeID="0216">003751734872001</cbc:EndpointID>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Buyer</cbc:RegistrationName>
    </cac:PartyLegalEntity>
  </cac:SenderParty>
  <cac:ReceiverParty>
    <cbc:EndpointID schemeID="0216">003751734872004</cbc:EndpointID>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Seller</cbc:RegistrationName>
    </cac:PartyLegalEntity>
  </cac:ReceiverParty>
  <cac:DocumentResponse>
    <cac:Response>
      <cbc:ResponseCode listID="UNCL4343OpSubset">AB</cbc:ResponseCode>
    </cac:Response>
    <cac:DocumentReference>
      <!-- Reference to the original received invoice -->
      <cbc:ID>567</cbc:ID>
      <cbc:DocumentTypeCode listID="UNCL1001">380</cbc:DocumentTypeCode>
    </cac:DocumentReference>
  </cac:DocumentResponse>
</ApplicationResponse>
```

Send the invoice response XML via the [POST /v1/documents](https://swagger.maventa.com/#/documents/postV1Documents) endpoint:

```bash
curl -X 'POST' \
  'https://ax-stage.maventa.com/v1/documents' \
  -H 'accept: application/json' \
  -H 'content-type: multipart/form-data' \
  -F 'file=@response.xml;type=text/xml' \
  -F 'recipient_eia=0126:003751734872004' \
  -F 'recipient_operator=PEPPOL'
```

Response:

```json
{
  "id": "e6c1e92b-ceba-4155-89fd-072e7ba6148f",
  "type": "INVOICE_RESPONSE"
  ...
}
```

## Response codes

Each invoice response carries a single status code that communicates the current processing state of the invoice. The code is set in the `ResponseCode` element using the [UNCL4343 code list subset](https://docs.peppol.eu/poacc/upgrade-3/codelist/UNCL4343-T111/).

| Code | Status | Description |
|---|---|---|
| `AB` | Message acknowledgement | The invoice has been received and is ready for processing. |
| `IP` | In process | The invoice is being processed in the buyer's system. |
| `UQ` | Under query | Processing is on hold — the buyer needs additional information from the seller. |
| `CA` | Conditionally accepted | The invoice is accepted under conditions, such as pending minor corrections. |
| `RE` | Rejected | The buyer will not process the invoice. The seller typically needs to issue a corrected invoice. |
| `AP` | Accepted | The invoice has been accepted and approved for payment. |
| `PD` | Paid | The invoice has been paid in full or in part. |

Status codes follow a general progression: `AB` → `IP` → `UQ` → `CA`/`RE`/`AP` → `PD`. Not all statuses need to be used — for example, a buyer may go directly from `AB` to `AP`. The statuses `RE` and `PD` are final; no further responses should be sent after these.

> [!NOTE]
> Each invoice response message carries one status code at a time. To communicate a status change, send a new invoice response with the updated code.

## References

- [BIS Invoice Response 3.2 specification](https://docs.peppol.eu/poacc/upgrade-3/profiles/63-invoiceresponse/)

---

## Self-billing support
Source: https://documentation.maventa.com/integration-guide/peppol/self-billing-support/

## What is self-billing?

Self-billing is a process where the buyer issues and sends an invoice on behalf of the supplier through the Peppol network. The invoice refers to goods or services that the buyer has received and is responsible for documenting.

In Peppol, this process is defined in the [Peppol BIS Self-Billing 3.0 specification](https://docs.peppol.eu/poacc/self-billing/3.0/bis-sb/), which ensures interoperability and VAT compliance across participating countries. Self-billed invoices must contain the same required data elements as standard invoices, including buyer and supplier identifiers, tax details, and references to the underlying commercial transaction.

Before self-billing can be used, the supplier and buyer must have a prior agreement that explicitly authorises the buyer to issue invoices on the supplier's behalf, as required by VAT and e-invoicing legislation. This agreement is handled outside Maventa between the parties themselves.

### Key distinction

Legally and according to Peppol standards, the buyer creates the invoice on behalf of the supplier, and the supplier is the recipient. The supplier remains the legal seller, and VAT liability stays with the supplier.

From an accounting perspective:

- The supplier records the self-billing invoice as an incoming invoice, treating it as a sales record.
- The buyer is responsible for issuing the invoice in their system. Since the buyer already generated the invoice, the supplier does not issue another invoice for the same transaction.

Integrators should make sure this distinction is clear in the accounting system so there is no confusion about responsibilities.

### Country support

Self-billing via Maventa is available in all countries where Maventa supports Peppol invoice receiving, except Norway.

## Sending self-billing invoices

The buyer creates a compliant Peppol BIS Self-Billing document with the correct profiles and type codes, and sends it like any other invoice via the REST API. Maventa automatically identifies the document as a self-billing invoice or credit note and delivers it to the supplier via Peppol — provided the supplier is registered to receive self-billing documents. If the supplier is not registered, the invoice will fail, as no fallback routing is available for self-billing documents.

> [!NOTE]
> Maventa reads routing data from the XML for self-billing invoices. Any routing information provided in the API metadata (such as `recipient_eia` or `recipient_operator`) is ignored.

The self-billing document must include the following identifiers in the XML. The `CustomizationID` and `ProfileID` are the same for both invoices and credit notes — only the document type code and root element differ:

```xml
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0</cbc:CustomizationID>
```

```xml
<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:selfbilling:01:1.0</cbc:ProfileID>
```

### Self-billing invoice

The root element is `<Invoice>` with type code `389`:

```xml
<cbc:InvoiceTypeCode>389</cbc:InvoiceTypeCode>
```

## Receiving self-billing invoices

To receive self-billing documents, a company must explicitly register dedicated Peppol self-billing profiles via the API — one for self-billing invoices and one for self-billing credit notes. These are separate registrations from the standard `INVOICE_AND_CREDIT_NOTE` profile. There is no UI available for self-billing profile registrations.

> [!NOTE]
> Self-billing is supported only in the Peppol BIS format. No conversion to other formats is available, meaning the receiving ERP must be capable of downloading and handling Peppol BIS invoices.

### Register self-billing profiles

Call [POST /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/postV1CompanyProfiles) with the following parameters:

- **profile**: `SELF_BILLING_INVOICE` (for receiving self-billing invoices) or `SELF_BILLING_CREDIT_NOTE` (for receiving self-billing credit notes)
- **network**: `PEPPOL`

Once the profiles are created, use [GET /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/company/getV1CompanyProfiles) to verify that they are active for the `PEPPOL` network. This separate registration is necessary because not all ERPs support self-billing by default.

### Downloading and processing self-billing invoices

Downloading self-billing invoices works the same way as downloading any other received invoice — use the standard [invoice receiving](/integration-guide/invoice-receiving/) flow.

After downloading, the receiving system must identify the document as a self-billing document by checking the `CustomizationID` and document type code in the XML. Both types use the self-billing customization ID (`urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0`):

- **Self-billing invoice**: `InvoiceTypeCode` = `389`
- **Self-billing credit note**: `CreditNoteTypeCode` = `261`

Based on these identifiers, the receiving system should handle the document as a sales record rather than a purchase record.

## Summary

Self-billing via Peppol allows buyers to issue compliant electronic invoices on behalf of suppliers. It requires:

- A prior commercial agreement between buyer and supplier.
- Proper Peppol BIS Self-Billing 3.0 XML with correct type codes and identifiers.
- Supplier registration for `SELF_BILLING_INVOICE` and/or `SELF_BILLING_CREDIT_NOTE` Peppol profiles.

---

## Invoicing formats
Source: https://documentation.maventa.com/integration-guide/invoicing-formats/invoicing-formats/

XML presents invoice data in a structured way.  e-invoicing supports wide variety of XML based standard invoice formats and automatically converts the invoices from one format to another when needed. See the supported formats and XML examples below.

In general, we recommend using the **Peppol BIS 3.0** format for invoice exchange. The format is widely supported and is well suitable for sending and receiving invoices across countries.

If you are planning to operate in the Finnish market only and have a need to send consumer invoices, we recommend **Finvoice 3.0** or **TEAPPSXML**. Both of the formats can handle both **B2B** and **B2C** invoicing.

All three formats fully support the **European **EN16931** (The European standard for electronic invoicing (SFS-EN 16931-1:2017), defining the minimum required invoice data elements and business rules for cross-border B2B and B2G transactions) invoicing standard**. Please read more about the [European invoicing standard](/eu-standard-info/).

## Supported XML formats

### Recommended formats

### Peppol BIS 3.0

International standard for cross-border invoicing. Widely supported across Europe.

[View example XML](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_peppol_bis_30_invoice.xml)

### Finvoice 3.0

Finnish standard supporting both B2B and B2C invoicing. EN16931 compliant.

[View example XML](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_finvoice_30_invoice_en16931.xml)

### TEAPPS 3.0

Finnish XML format supporting B2B and B2C invoicing. EN16931 compliant.

[View example XML](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_teapps_30_invoice.xml)

> [!NOTE]
> Finvoice 3.0 is also available with [MessageTransmissionDetails](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_finvoice_30_invoice_with_MessageTransmissionDetails.xml) wrapper for direct operator delivery.

### Other supported formats

### Finnish formats

- **finvoice 1.3** (Finvoice — the Finnish e-invoicing standard maintained by Finance Finland, widely used for B2B and B2C invoicing via banks and operator networks)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_finvoice_13_invoice_with_MessageTransmissionDetails.xml))
- **finvoice20** (Finvoice 2.0 — includes version 2.01, the most widely adopted Finvoice version in Finnish B2B invoicing)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_finvoice_20_invoice_with_MessageTransmissionDetails.xml))
- **finvoice30** (Finvoice 3.0 — the latest version, adding support for EU e-invoicing standard EN16931 and enhanced B2C capabilities. Uses SOAP.)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_finvoice_30_invoice_with_SOAP.xml))
- **teapps 2.7.2** (TietoEnator Application XML — a Finnish invoice format originally developed by TietoEnator (now Tietoevry), widely used in Finnish ERP integrations)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_teapps_272_invoice.xml))
- **liinos** (Liinos — a Finnish ERP-specific invoice format used by the Liinos software family)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_liinos_invoice.xml))

### Visma formats

- **vismaxml 5.3** (Visma XML — Visma's proprietary invoice format used across Visma ERP products in the Nordics)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_visma_xml_53_invoice.xml))
- **vismaxml60** (Visma XML 6.0 — the latest version of Visma's proprietary XML format with expanded field support)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_visma_xml_60_invoice.xml))
- **vismaubl 1.0** (Visma UBL — Visma's UBL-based invoice format combining UBL structure with Visma-specific extensions)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_visma_ubl_10_invoice.xml))
- **vismaubl30** (Visma UBL 3.0 — the latest Visma UBL version, aligned with Peppol BIS 3.0 and EN16931)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_visma_ubl_30_invoice.xml))

### Nordic & international

- **peppolbis20** (Peppol BIS 2.0 — the previous version of the Peppol Business Interoperability Specification for cross-border e-invoicing)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_peppol_bis_20_invoice.xml))
- **siubl / siubl12 / siubl20** (Simplerinvoicing UBL — a Dutch e-invoicing profile based on UBL, used for domestic Peppol traffic in the Netherlands.\nVersions: 1.0, 1.2, and 2.0.)<br>([example xml 2.0](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_si_ubl_20_invoice.xml))
- **ehf / ehf20** (Elektronisk Handelsformat — the Norwegian standard for electronic business documents, based on UBL and aligned with Peppol BIS.\nVersions: 1.0 and 2.0.)<br>([example xml 2.0](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_ehf_20_invoice.xml))
- **svefaktura** (A Swedish e-invoice format based on UBL, historically used for domestic invoicing in Sweden before Peppol BIS adoption)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_svefaktura_invoice.xml))
- **sedi** (SEDI — a Danish e-invoice format used in the Danish market for electronic document interchange)<br>([example xml](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_sedi_30_invoice.xml))

See all example XML files from [maventa/invoicexmlexamples](https://gitlab.com/maventa/invoicexmlexamples).

## Document types

Maventa supports several document types beyond standard invoices. The document type is determined by fields within the invoice XML — the exact field depends on the format used.

* **Invoice** — A standard invoice requesting payment for goods or services.
* **Credit note** — Reverses or corrects a previously sent invoice. The total amount is negative. Used when an invoice needs to be cancelled or adjusted after it has been sent.
* **Self-billing invoice** — An invoice created by the buyer on behalf of the seller. Supported through the Peppol network with a dedicated profile.

How each format identifies the document type varies. For example, in Peppol BIS 3.0, invoices and credit notes use separate XML root elements (`Invoice` and `CreditNote`). In Finvoice, the `InvoiceTypeCode` field determines the type (e.g., INV01 for a standard invoice, INV02 for a credit note). In TEAPPSXML, the `INVOICE_TYPE` field is used.

Routing and delivery work the same way for all document types. The recipient must support the specific document type — for example, when sending via Peppol, the recipient's Peppol registration must include `CREDIT_NOTE` as a supported document type.

When registering to receive invoices via Peppol through Maventa, the `INVOICE_AND_CREDIT_NOTE` profile automatically registers both the invoice and credit note document types:

<details>
<summary>Peppol BIS Billing UBL Invoice V3</summary>

**Document identifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**Process identifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing UBL Credit Note V3</summary>

**Document identifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**Process identifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

For a detailed breakdown of type codes across all supported formats and how they behave during format conversion, see [Document types and type codes](/integration-guide/invoicing-formats/document-types/).

---

## Validation
Source: https://documentation.maventa.com/integration-guide/invoicing-formats/validation/

Before invoices are sent there are certain validations made to ensure that the invoice XML contains the necessary data and is set up correctly. The validation requirements depend on where the invoice is sent to. Some of the routes such as **Peppol** network, require validation on structure and the invoice content level, for example that the invoice line amounts match the total amounts given on the invoice. If the route where invoice is going to requires validation, Maventa does this before distributing the invoice and returns an error if the invoice is not valid.

## Against what are invoices validated to

### Minimum invoice information requirements

* Finland: [https://www.valtiokonttori.fi/palvelu/verkkolaskutus/#laskun-vahimmaistietosisalto_laskun-vahimmaistietosisalto](https://www.valtiokonttori.fi/palvelu/verkkolaskutus/#laskun-vahimmaistietosisalto_laskun-vahimmaistietosisalto)
* For all invoices, incl. Print/eMail/internal delivery

### XML schematron validation

* Invoice structure and content validation
* Used for **Peppol BIS**, **SI-UBL**, **EN16391** tagged **Finvoice 3.0** or **TEAPPSXML 3.0**
  * If the outgoing format is **Peppol BIS** (always EN-16931 content) the content is validated with Peppol provided schematron.
  * If the outgoing invoice is **Finvoice** or **TEAPPSXML** and it is marked as EN-16931 compatible it is validated by the schematron used commonly by the finnish operator network (Verkkolasku Foorumi).
* If the invoice is routed to Print / eMail / internal delivery, the schematron result is ignored

### Bank network validation

* Bank network specific validations if invoice is sent to netbank (e.g. due date, **Finvoice** **EPIDetails** element in **B2C** invoices)

> [!NOTE]
> **Note:** In all cases when Maventa converts files, the converted files are made to be structurally correct, i.e. they follow XML schema (**XSD**) of the target conversion format.

## How do I know which validations need to be made?

Maventa does automatically the required validations and returns an error if the invoice is not valid for the route it is sent to.

First validation on minimum invoice information requirements is done before invoice appears on the outgoing invoice listing (UI / API calls). If the invoice doesn't meet the requirements it will be rejected on the API.

The other validations schematron and bank network will be done if needed once the invoice is  routed and prepared for sending. The status of the invoice will indicate whether it has been sent (1) or still in the sending process (0) or it has failed (99).

## How can I make sure that the invoice doesn't fail on validation?

Make sure that the material you are sending is following the specifications of the format you are using. This ensures also that conversion of the XML will work in a good way. Maventa handles conversions between the supported XML formats.

> [!WARNING]
> **Important:** There may be some limitations if the format version you are using is very old, i.e. there can be some elements that cannot be properly converted. We recommend to use the latest versions of the formats to ensure the best compatibility on conversions.

Links to some commonly used format documentation

* [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/)
* [Finvoice 3.0](https://www.finanssiala.fi/finvoice/Sivut/default.aspx)  
* [TEAPPSXML 3.0](https://bix.tieto.com/#/teappsxml)  
* [Finvoice 3.0 & TEAPPSXML 3.0 mappings](https://bix.tieto.com/infoFiles/Finvoice3.0_TEAPPSXML3.0_correlation_20210607.pdf)

## Finvoice & TEAPPSXML phase-in error message

Validation rules require changes time to time. There is an error message which reveals the upcoming changes.

The phase-in error message is due to phase-in feedback having revealed an error in e-invoicing data that must be corrected. If not corrected, the error will cause an invoice to be rejected in the next version of rules. This provides a way for billers and developers to correct the discovered error now, before the launch of the next ruleset.

## Can I validate my material before sending?

There are different validation tools that can be used for validating the material you are about to send.

Maventa offers possibility to validate documents with [Validator API](/api-specification/rest-api/validator-api/).

---

## Peppol BIS 3.0
Source: https://documentation.maventa.com/integration-guide/invoicing-formats/peppolbis30/

Peppol BIS Billing 3.0 is the recommended format for invoice exchange through Maventa. It implements the European standard EN16931-1:2017 using UBL 2.1 XML syntax, and is mandatory for cross-border invoicing over the Peppol network. Some countries also accept national formats for domestic Peppol traffic.
> [!NOTE]
> This page covers the XML format itself. For Peppol network registration and participant lookup, see the [Peppol network](/integration-guide/peppol/peppol-network/) page. For sending and receiving documents via the API, see the [document exchange](/integration-guide/peppol/document-exchange/) page.

> [!WARNING]
> The Peppol BIS 3.0 specification is updated regularly. Required and conditional fields may change between releases. Always check the [latest implementation guidelines](https://docs.peppol.eu/poacc/billing/3.0/) for current rules.

## Document identifiers

Every Peppol BIS 3.0 invoice must include `CustomizationID` and `ProfileID` elements that identify the document specification and business process.

```xml
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
```

These values are the same for both invoices and credit notes. The document type is determined by the root element (`Invoice` or `CreditNote`) and the `InvoiceTypeCode` / `CreditNoteTypeCode` element.

For the full document identifier strings used in Peppol registration, see the [document types](/integration-guide/invoicing-formats/invoicing-formats/) section on the invoicing formats page.

## Invoice structure overview

A Peppol BIS 3.0 invoice uses the UBL 2.1 `Invoice` root element. The following table lists the required and commonly used top-level elements.

| Element | Required | Description |
|---------|----------|-------------|
| `cbc:CustomizationID` | Yes | Specification identifier (see above) |
| `cbc:ProfileID` | Yes | Business process identifier (see above) |
| `cbc:ID` | Yes | Invoice number |
| `cbc:IssueDate` | Yes | Invoice date (YYYY-MM-DD) |
| `cbc:DueDate` | Conditional | Payment due date. Either `DueDate` or `PaymentTerms` must be provided. |
| `cbc:InvoiceTypeCode` | Yes | `380` for commercial invoice, `384` for corrected invoice, `389` for self-billing invoice, `751` for invoice information for accounting purposes |
| `cbc:DocumentCurrencyCode` | Yes | ISO 4217 currency code (e.g., `EUR`) |
| `cbc:BuyerReference` | Yes | Buyer's reference or order number. Required by Peppol even if the buyer has not provided one — use `N/A` as fallback. |
| `cac:AccountingSupplierParty` | Yes | Seller details |
| `cac:AccountingCustomerParty` | Yes | Buyer details |
| `cac:TaxTotal` | Yes | Tax breakdown |
| `cac:LegalMonetaryTotal` | Yes | Invoice totals |
| `cac:InvoiceLine` | Yes | At least one invoice line |

### Minimal invoice skeleton

The following shows the high-level structure of a Peppol BIS 3.0 invoice. Each section is covered in detail below.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<Invoice xmlns="urn:oasis:names:specification:ubl:schema:xsd:Invoice-2"
         xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
         xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">

  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
  <cbc:ID>INV-2024-001</cbc:ID>
  <cbc:IssueDate>2024-01-15</cbc:IssueDate>
  <cbc:DueDate>2024-02-15</cbc:DueDate>
  <cbc:InvoiceTypeCode>380</cbc:InvoiceTypeCode>
  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
  <cbc:BuyerReference>PO-12345</cbc:BuyerReference>

  <cac:AccountingSupplierParty><!-- ... --></cac:AccountingSupplierParty>
  <cac:AccountingCustomerParty><!-- ... --></cac:AccountingCustomerParty>
  <cac:TaxTotal><!-- ... --></cac:TaxTotal>
  <cac:LegalMonetaryTotal><!-- ... --></cac:LegalMonetaryTotal>
  <cac:InvoiceLine><!-- ... --></cac:InvoiceLine>

</Invoice>
```

## Parties (supplier and buyer)

Both `AccountingSupplierParty` and `AccountingCustomerParty` follow the same structure. The key required elements are:

| Element | Required | Description |
|---------|----------|-------------|
| `cbc:EndpointID` | Yes | Electronic address with `schemeID` attribute (e.g., `0216` for Finnish OVT code) |
| `cac:PartyIdentification/cbc:ID` | No | Additional party identifier |
| `cac:PartyName/cbc:Name` | No | Trading name |
| `cac:PostalAddress` | Yes | Street, city, postal code, country |
| `cac:PartyTaxScheme` | No | VAT number (`cbc:CompanyID`) with tax scheme `VAT`. Not all companies have a VAT identifier. |
| `cac:PartyLegalEntity/cbc:RegistrationName` | Yes | Legal registration name |
| `cac:PartyLegalEntity/cbc:CompanyID` | No | Company registration number |

```xml
<cac:AccountingSupplierParty>
  <cac:Party>
    <cbc:EndpointID schemeID="0216">003712345678</cbc:EndpointID>
    <cac:PartyName>
      <cbc:Name>Supplier Oy</cbc:Name>
    </cac:PartyName>
    <cac:PostalAddress>
      <cbc:StreetName>Esimerkkikatu 1</cbc:StreetName>
      <cbc:CityName>Helsinki</cbc:CityName>
      <cbc:PostalZone>00100</cbc:PostalZone>
      <cac:Country>
        <cbc:IdentificationCode>FI</cbc:IdentificationCode>
      </cac:Country>
    </cac:PostalAddress>
    <cac:PartyTaxScheme>
      <cbc:CompanyID>FI12345678</cbc:CompanyID>
      <cac:TaxScheme>
        <cbc:ID>VAT</cbc:ID>
      </cac:TaxScheme>
    </cac:PartyTaxScheme>
    <cac:PartyLegalEntity>
      <cbc:RegistrationName>Supplier Oy</cbc:RegistrationName>
      <cbc:CompanyID>1234567-8</cbc:CompanyID>
    </cac:PartyLegalEntity>
  </cac:Party>
</cac:AccountingSupplierParty>
```

The `EndpointID` `schemeID` value identifies the type of electronic address. Common scheme IDs and endpoint ID formats include:

| Scheme ID | Country | Endpoint ID format |
|-----------|---------|-------------------|
| `0216` | Finland | OVT code (e.g., `003712345678`) |
| `0007` | Sweden | Organization number (e.g., `5567891234`) |
| `0088` | International | GLN (Global Location Number) |
| `0184` | Denmark | CVR number (e.g., `12345678`) |
| `0192` | Norway | Organization number (e.g., `987654321`) |
| `0106` | Netherlands | KvK number (e.g., `12345678`) |

For a full list, see the [EAS code list](https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/) in the Peppol documentation. For endpoint ID formats and details for each country Maventa supports, see the [Services & Reach](/services-and-reach/overview/) country pages.

## Tax and totals

### TaxTotal

The `TaxTotal` element provides a total tax amount and a breakdown by tax category. Each `TaxSubtotal` groups all line amounts with the same tax rate and category.

```xml
<cac:TaxTotal>
  <cbc:TaxAmount currencyID="EUR">240.00</cbc:TaxAmount>
  <cac:TaxSubtotal>
    <cbc:TaxableAmount currencyID="EUR">1000.00</cbc:TaxableAmount>
    <cbc:TaxAmount currencyID="EUR">240.00</cbc:TaxAmount>
    <cac:TaxCategory>
      <cbc:ID>S</cbc:ID>
      <cbc:Percent>24.00</cbc:Percent>
      <cac:TaxScheme>
        <cbc:ID>VAT</cbc:ID>
      </cac:TaxScheme>
    </cac:TaxCategory>
  </cac:TaxSubtotal>
</cac:TaxTotal>
```

Common tax category codes:

| Code | Description |
|------|-------------|
| `S` | Standard rate |
| `Z` | Zero rated |
| `E` | Exempt from tax |
| `AE` | Reverse charge (VAT paid by buyer) |
| `K` | Intra-community supply |
| `O` | Not subject to VAT |

Tax categories with a zero percent rate (`E`, `AE`, `K`, `O`) require a `TaxExemptionReasonCode` or `TaxExemptionReason` (free text) inside the `TaxCategory` element to explain why VAT is not charged.

```xml
<cac:TaxCategory>
  <cbc:ID>E</cbc:ID>
  <cbc:Percent>0.00</cbc:Percent>
  <cbc:TaxExemptionReasonCode>vatex-eu-132</cbc:TaxExemptionReasonCode>
  <cbc:TaxExemptionReason>Exempt based on article 132 of Council Directive 2006/112/EC</cbc:TaxExemptionReason>
  <cac:TaxScheme>
    <cbc:ID>VAT</cbc:ID>
  </cac:TaxScheme>
</cac:TaxCategory>
```

### LegalMonetaryTotal

The `LegalMonetaryTotal` element summarizes the invoice amounts. All amounts must use 2 decimal places.

```xml
<cac:LegalMonetaryTotal>
  <cbc:LineExtensionAmount currencyID="EUR">1000.00</cbc:LineExtensionAmount>
  <cbc:TaxExclusiveAmount currencyID="EUR">1000.00</cbc:TaxExclusiveAmount>
  <cbc:TaxInclusiveAmount currencyID="EUR">1240.00</cbc:TaxInclusiveAmount>
  <cbc:PayableAmount currencyID="EUR">1240.00</cbc:PayableAmount>
</cac:LegalMonetaryTotal>
```

| Element | Required | Description |
|---------|----------|-------------|
| `LineExtensionAmount` | Yes | Sum of all invoice line net amounts |
| `TaxExclusiveAmount` | Yes | Total amount without VAT (line extension + document-level charges - document-level allowances) |
| `TaxInclusiveAmount` | Yes | Total amount with VAT |
| `AllowanceTotalAmount` | No | Sum of document-level allowances |
| `ChargeTotalAmount` | No | Sum of document-level charges |
| `PayableRoundingAmount` | No | Rounding amount to reach `PayableAmount` |
| `PayableAmount` | Yes | Amount to be paid |

## Invoice lines

Each `InvoiceLine` represents a line item on the invoice.

```xml
<cac:InvoiceLine>
  <cbc:ID>1</cbc:ID>
  <cbc:InvoicedQuantity unitCode="EA">10</cbc:InvoicedQuantity>
  <cbc:LineExtensionAmount currencyID="EUR">1000.00</cbc:LineExtensionAmount>
  <cac:Item>
    <cbc:Name>Product name</cbc:Name>
    <cac:ClassifiedTaxCategory>
      <cbc:ID>S</cbc:ID>
      <cbc:Percent>24.00</cbc:Percent>
      <cac:TaxScheme>
        <cbc:ID>VAT</cbc:ID>
      </cac:TaxScheme>
    </cac:ClassifiedTaxCategory>
  </cac:Item>
  <cac:Price>
    <cbc:PriceAmount currencyID="EUR">100.00</cbc:PriceAmount>
  </cac:Price>
</cac:InvoiceLine>
```

| Element | Required | Description |
|---------|----------|-------------|
| `cbc:ID` | Yes | Line identifier (unique within the invoice) |
| `cbc:InvoicedQuantity` | Yes | Quantity with `unitCode` attribute (UN/ECE Rec 20 codes, e.g., `EA` for each, `HUR` for hour, `KGM` for kilogram) |
| `cbc:LineExtensionAmount` | Yes | Net amount for the line (quantity x price, adjusted for line-level allowances/charges) |
| `cac:Item/cbc:Name` | Yes | Item name or description |
| `cac:Item/cac:ClassifiedTaxCategory` | Yes | Tax category and rate for the line |
| `cac:Price/cbc:PriceAmount` | Yes | Unit price excluding VAT |

For item identification, you can optionally include:

- `cac:Item/cac:SellersItemIdentification/cbc:ID` — seller's article number
- `cac:Item/cac:StandardItemIdentification/cbc:ID` — standard identifier (e.g., GTIN) with `schemeID` attribute
- `cac:Item/cac:CommodityClassification/cbc:ItemClassificationCode` — classification code (e.g., UNSPSC)

For unit codes, see the [UN/ECE Recommendation 20 and 21](https://docs.peppol.eu/poacc/billing/3.0/codelist/UNECERec20/) reference.

### Line-level allowances and charges

Line-level allowances and charges appear inside `InvoiceLine` and affect the `LineExtensionAmount` of that line. They do not include a `TaxCategory` (the line's tax category applies).

Provide either `AllowanceChargeReasonCode` (from the [UNCL7161](https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL7161/) code list) or `AllowanceChargeReason` (free text), or both.

```xml
<cac:InvoiceLine>
  <cbc:ID>1</cbc:ID>
  <cbc:InvoicedQuantity unitCode="EA">10</cbc:InvoicedQuantity>
  <cbc:LineExtensionAmount currencyID="EUR">900.00</cbc:LineExtensionAmount>
  <cac:AllowanceCharge>
    <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
    <cbc:AllowanceChargeReasonCode>95</cbc:AllowanceChargeReasonCode>
    <cbc:AllowanceChargeReason>Discount</cbc:AllowanceChargeReason>
    <cbc:Amount currencyID="EUR">100.00</cbc:Amount>
  </cac:AllowanceCharge>
  <cac:Item>
    <cbc:Name>Product name</cbc:Name>
    <!-- ... -->
  </cac:Item>
  <cac:Price>
    <cbc:PriceAmount currencyID="EUR">100.00</cbc:PriceAmount>
  </cac:Price>
</cac:InvoiceLine>
```

In this example, 10 units at 100.00 EUR = 1000.00, minus a 100.00 EUR discount, gives a `LineExtensionAmount` of 900.00 EUR.

## Allowances and charges

Allowances (discounts) and charges can also be applied at the document level. Both use the same `AllowanceCharge` structure, distinguished by the `ChargeIndicator` element. Provide either `AllowanceChargeReasonCode` (from the [UNCL7161](https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL7161/) code list) or `AllowanceChargeReason` (free text), or both.

### Document-level allowances and charges

Document-level allowances and charges appear directly under the `Invoice` root element and affect the invoice totals.

```xml
<!-- Document-level allowance (discount) -->
<cac:AllowanceCharge>
  <cbc:ChargeIndicator>false</cbc:ChargeIndicator>
  <cbc:AllowanceChargeReasonCode>95</cbc:AllowanceChargeReasonCode>
  <cbc:AllowanceChargeReason>Discount</cbc:AllowanceChargeReason>
  <cbc:Amount currencyID="EUR">50.00</cbc:Amount>
  <cac:TaxCategory>
    <cbc:ID>S</cbc:ID>
    <cbc:Percent>24.00</cbc:Percent>
    <cac:TaxScheme>
      <cbc:ID>VAT</cbc:ID>
    </cac:TaxScheme>
  </cac:TaxCategory>
</cac:AllowanceCharge>

<!-- Document-level charge (e.g., shipping) -->
<cac:AllowanceCharge>
  <cbc:ChargeIndicator>true</cbc:ChargeIndicator>
  <cbc:AllowanceChargeReasonCode>FC</cbc:AllowanceChargeReasonCode>
  <cbc:AllowanceChargeReason>Freight charge</cbc:AllowanceChargeReason>
  <cbc:Amount currencyID="EUR">15.00</cbc:Amount>
  <cac:TaxCategory>
    <cbc:ID>S</cbc:ID>
    <cbc:Percent>24.00</cbc:Percent>
    <cac:TaxScheme>
      <cbc:ID>VAT</cbc:ID>
    </cac:TaxScheme>
  </cac:TaxCategory>
</cac:AllowanceCharge>
```

- `ChargeIndicator` = `false` for allowances (discounts), `true` for charges
- Document-level allowances and charges must include a `TaxCategory`

## Credit notes

Credit notes use a separate root element `CreditNote` instead of `Invoice`. The XML namespaces and structure are otherwise the same, with a few key differences:

| Aspect | Invoice | Credit note |
|--------|---------|-------------|
| Root element | `Invoice` | `CreditNote` |
| Type code element | `InvoiceTypeCode` | `CreditNoteTypeCode` |
| Type code value | `380` (standard) | `381` (credit note) |
| Quantity element | `InvoicedQuantity` | `CreditedQuantity` |
| Line element | `InvoiceLine` | `CreditNoteLine` |

Amounts in a credit note are **positive** — the credit note document type itself indicates that the amounts are to be subtracted.

### Referencing the original invoice

Use `BillingReference` to link the credit note to the original invoice:

```xml
<CreditNote xmlns="urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2"
            xmlns:cac="urn:oasis:names:specification:ubl:schema:xsd:CommonAggregateComponents-2"
            xmlns:cbc="urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2">

  <cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0</cbc:CustomizationID>
  <cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:billing:01:1.0</cbc:ProfileID>
  <cbc:ID>CN-2024-001</cbc:ID>
  <cbc:IssueDate>2024-02-01</cbc:IssueDate>
  <cbc:CreditNoteTypeCode>381</cbc:CreditNoteTypeCode>
  <cbc:DocumentCurrencyCode>EUR</cbc:DocumentCurrencyCode>
  <cbc:BuyerReference>PO-12345</cbc:BuyerReference>

  <cac:BillingReference>
    <cac:InvoiceDocumentReference>
      <cbc:ID>INV-2024-001</cbc:ID>
      <cbc:IssueDate>2024-01-15</cbc:IssueDate>
    </cac:InvoiceDocumentReference>
  </cac:BillingReference>

  <!-- Remaining structure follows the same pattern as Invoice -->
</CreditNote>
```

## Attachments

Peppol BIS 3.0 supports embedding attachments in the invoice XML using the `AdditionalDocumentReference` element.

### Supported MIME types

| MIME type | Description |
|-----------|-------------|
| `application/pdf` | PDF document |
| `image/png` | PNG image |
| `image/jpeg` | JPEG image |
| `text/csv` | CSV file |
| `application/vnd.openxmlformats-officedocument.spreadsheetml.sheet` | Excel spreadsheet (.xlsx) |
| `application/vnd.oasis.opendocument.spreadsheet` | OpenDocument spreadsheet (.ods) |

### Embedding an attachment

```xml
<cac:AdditionalDocumentReference>
  <cbc:ID>ATT-001</cbc:ID>
  <cbc:DocumentDescription>Timesheet for January 2024</cbc:DocumentDescription>
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf"
                                       filename="timesheet-2024-01.pdf">
      <!-- Base64 encoded content -->
      JVBERi0xLjQKMSAwIG9iago8PAovVHlwZSAvQ2F0YWxvZw...
    </cbc:EmbeddedDocumentBinaryObject>
  </cac:Attachment>
</cac:AdditionalDocumentReference>
```

You can also reference an external document by URL instead of embedding:

```xml
<cac:AdditionalDocumentReference>
  <cbc:ID>ATT-002</cbc:ID>
  <cac:Attachment>
    <cac:ExternalReference>
      <cbc:URI>https://example.com/documents/timesheet.pdf</cbc:URI>
    </cac:ExternalReference>
  </cac:Attachment>
</cac:AdditionalDocumentReference>
```

## Validation

Peppol BIS 3.0 invoices are validated at three levels:

1. **UBL 2.1 XSD schema validation** — Checks that the XML structure conforms to the UBL 2.1 schema (correct elements, data types, and structure).
2. **EN16931 schematron rules** — European standard business rules that check calculation correctness, required fields, and cross-field consistency.
3. **Peppol business rules** — Additional rules specific to the Peppol network (e.g., `EndpointID` must be present, `CustomizationID` must match the Peppol BIS 3.0 identifier).

Maventa automatically validates outgoing Peppol invoices against all three rule sets. If validation fails, the invoice is rejected with an error describing which rule was violated.

For more details on validation and how to pre-validate your invoices, see the /integration-guide/invoicing-formats/validation/ page and the [Validator API](/api-specification/rest-api/validator-api/).

## Key code lists

| Code list | Usage | Reference |
|-----------|-------|-----------|
| EAS | `EndpointID` scheme IDs | [Peppol EAS list](https://docs.peppol.eu/poacc/billing/3.0/codelist/eas/) |
| ICD (ISO 6523) | `PartyIdentification/ID` and `PartyLegalEntity/CompanyID` scheme IDs | [Peppol ICD list](https://docs.peppol.eu/poacc/billing/3.0/codelist/ICD/) |
| ISO 4217 | Currency codes (`DocumentCurrencyCode`, amounts) | [Peppol currency list](https://docs.peppol.eu/poacc/billing/3.0/codelist/ISO4217/) |
| UNCL5305 (subset) | Tax category codes (`S`, `Z`, `E`, `AE`, etc.) | [Peppol tax category list](https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL5305/) |
| UNCL7161 | Allowance/charge reason codes | [Peppol UNCL7161 list](https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL7161/) |
| UNCL1001 (subset) | Invoice type codes (`380`, `381`, `384`, etc.) | [Peppol invoice type list](https://docs.peppol.eu/poacc/billing/3.0/codelist/UNCL1001-inv/) |
| UN/ECE Rec 20 + 21 | Unit of measure codes (`EA`, `HUR`, `KGM`, etc.) | [Peppol unit codes](https://docs.peppol.eu/poacc/billing/3.0/codelist/UNECERec20/) |
| MIME types | Attachment content types | [Peppol MIME list](https://docs.peppol.eu/poacc/billing/3.0/codelist/MimeCode/) |

## External resources

- [Peppol BIS Billing 3.0 specification](https://docs.peppol.eu/poacc/billing/3.0/) — official documentation with syntax bindings, rules, and code lists
- [Peppol BIS Billing 3.0 latest release (2025-Q4)](https://docs.peppol.eu/poacc/billing/3.0/2025-Q4/) — most recent published version
- [Peppol Post-Award technical documentation](https://peppol.org/documentation/technical-documentation/post-award-documentation/) — latest releases and announcements from Peppol
- [UBL 2.1 schema files](http://docs.oasis-open.org/ubl/os-UBL-2.1/UBL-2.1.html) — OASIS UBL XML schema definitions
- [Example Peppol BIS 3.0 invoice XML](https://gitlab.com/maventa/invoicexmlexamples/-/blob/master/anon_peppol_bis_30_invoice.xml) — Maventa example file
- [All example XML files](https://gitlab.com/maventa/invoicexmlexamples) — example invoices in all supported formats

---

## Finvoice 3.0
Source: https://documentation.maventa.com/integration-guide/invoicing-formats/finvoice/

Finvoice is the Finnish national e-invoice format, maintained by Finance Finland (Finanssiala ry). It is widely used for B2B, B2G, and B2C invoicing through Finnish operator and bank networks. Finvoice 3.0 is the current version and is aligned with the European EN16931 standard.

Maventa supports Finvoice versions 1.3, 2.0, 2.01, and 3.0. Finvoice 3.0 is recommended for all new integrations.

> [!NOTE]
> For details on Finnish delivery channels, consumer invoicing, and country-specific requirements, see the [e-invoicing in Finland](/services-and-reach/finland/) page.

## Validation

Finvoice 1.3, 2.0, 2.01, and non-EN16931 versions of Finvoice 3.0 have XSD validation only. XSD validation verifies the structure of the document and performs simple data type checks, but it cannot detect calculation or logical errors in the invoice content.

Finvoice 3.0 invoices marked as EN16931 (with `<SpecificationIdentifier>EN16931</SpecificationIdentifier>` in the `MessageDetails`) are validated against the full EN16931 rule set in addition to XSD validation.

## Discounts and charges in invoice rows

Finvoice supports multiple ways to express discounts and charges on invoice rows. Understanding the calculation logic is important for producing valid invoices.

### Row amount calculation

The VAT-excluded amount for a row is calculated as:

```text
RowVatExcludedAmount =
    (InvoicedQuantity × UnitPriceNetAmount)
  - RowDiscountAmount (or sum of RowProgressiveDiscountDetails/RowDiscountAmount)
  + sum of RowChargeDetails/Amount
```

The unit price net amount is:

```text
UnitPriceNetAmount = UnitPriceAmount - UnitPriceDiscountAmount
```

`UnitPriceAmount` and `UnitPriceNetAmount` must always be positive, regardless of whether the document is an invoice or a credit note. `InvoicedQuantity` can be negative (used in credit notes).

### Discount and charge types

Finvoice supports three types of adjustments on invoice rows:

| Type | Element | Description |
|------|---------|-------------|
| Unit price discount | `UnitPriceDiscountAmount` | Discount applied to the unit price before quantity multiplication |
| Row discount | `RowDiscountAmount` | Single discount applied to the row total |
| Progressive row discounts | `RowProgressiveDiscountDetails` | Multiple sequential discounts, each applied to the result of the previous one |
| Row charge | `RowChargeDetails/Amount` | Additional charge added to the row total |

> [!WARNING]
> `RowDiscountAmount` and `RowProgressiveDiscountDetails` are mutually exclusive. Use one or the other on a single row, not both.

### Discount examples

The following examples show different ways to apply discounts and charges on a Finvoice invoice row.

<details>
<summary>Row without discounts or charges</summary>

No adjustments applied. The row amount is simply the quantity multiplied by the unit price.

```xml
<InvoiceRow>
  <ArticleName>Article</ArticleName>
  <InvoicedQuantity QuantityUnitCode="kpl" QuantityUnitCodeUN="EA">1,00</InvoicedQuantity>
  <UnitPriceAmount AmountCurrencyIdentifier="EUR">80,64516</UnitPriceAmount>
  <UnitPriceNetAmount AmountCurrencyIdentifier="EUR">80,64516</UnitPriceNetAmount>
  <RowVatRatePercent>24,00</RowVatRatePercent>
  <RowVatCode>S</RowVatCode>
  <RowVatAmount AmountCurrencyIdentifier="EUR">19,36</RowVatAmount>
  <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">80,65</RowVatExcludedAmount>
  <RowAmount AmountCurrencyIdentifier="EUR">100,01</RowAmount>
</InvoiceRow>
```
</details>

<details>
<summary>Single row discount (50%)</summary>

A single discount applied to the row total after quantity multiplication.

```xml
<InvoiceRow>
  <ArticleName>Article</ArticleName>
  <InvoicedQuantity QuantityUnitCode="kpl" QuantityUnitCodeUN="EA">1,00</InvoicedQuantity>
  <UnitPriceAmount AmountCurrencyIdentifier="EUR">80,64516</UnitPriceAmount>
  <UnitPriceNetAmount AmountCurrencyIdentifier="EUR">80,64516</UnitPriceNetAmount>
  <RowDiscountPercent>50,00</RowDiscountPercent>
  <RowDiscountAmount AmountCurrencyIdentifier="EUR">40,33</RowDiscountAmount>
  <RowDiscountBaseAmount AmountCurrencyIdentifier="EUR">80,65</RowDiscountBaseAmount>
  <RowDiscountTypeCode>95</RowDiscountTypeCode>
  <RowVatRatePercent>24,00</RowVatRatePercent>
  <RowVatCode>S</RowVatCode>
  <RowVatAmount AmountCurrencyIdentifier="EUR">9,68</RowVatAmount>
  <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">40,32</RowVatExcludedAmount>
  <RowAmount AmountCurrencyIdentifier="EUR">50,00</RowAmount>
</InvoiceRow>
```
</details>

<details>
<summary>Unit price discount only</summary>

A discount applied directly to the unit price before quantity multiplication.

```xml
<InvoiceRow>
  <ArticleName>Article</ArticleName>
  <InvoicedQuantity QuantityUnitCode="kpl" QuantityUnitCodeUN="EA">1,00</InvoicedQuantity>
  <UnitPriceAmount AmountCurrencyIdentifier="EUR">80,64516</UnitPriceAmount>
  <UnitPriceDiscountAmount AmountCurrencyIdentifier="EUR">40,32258</UnitPriceDiscountAmount>
  <UnitPriceNetAmount AmountCurrencyIdentifier="EUR">40,32258</UnitPriceNetAmount>
  <RowVatRatePercent>24,00</RowVatRatePercent>
  <RowVatCode>S</RowVatCode>
  <RowVatAmount AmountCurrencyIdentifier="EUR">9,68</RowVatAmount>
  <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">40,32</RowVatExcludedAmount>
  <RowAmount AmountCurrencyIdentifier="EUR">50,00</RowAmount>
</InvoiceRow>
```
</details>

<details>
<summary>Unit discount combined with row discount</summary>

A unit price discount followed by an additional row-level discount.

```xml
<InvoiceRow>
  <ArticleName>Article</ArticleName>
  <InvoicedQuantity QuantityUnitCode="kpl" QuantityUnitCodeUN="EA">1,00</InvoicedQuantity>
  <UnitPriceAmount AmountCurrencyIdentifier="EUR">80,64516</UnitPriceAmount>
  <UnitPriceDiscountAmount AmountCurrencyIdentifier="EUR">40,32258</UnitPriceDiscountAmount>
  <UnitPriceNetAmount AmountCurrencyIdentifier="EUR">40,32258</UnitPriceNetAmount>
  <RowDiscountPercent>50,00</RowDiscountPercent>
  <RowDiscountAmount AmountCurrencyIdentifier="EUR">20,16</RowDiscountAmount>
  <RowDiscountBaseAmount AmountCurrencyIdentifier="EUR">40,32</RowDiscountBaseAmount>
  <RowDiscountTypeCode>95</RowDiscountTypeCode>
  <RowVatRatePercent>24,00</RowVatRatePercent>
  <RowVatCode>S</RowVatCode>
  <RowVatAmount AmountCurrencyIdentifier="EUR">4,84</RowVatAmount>
  <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">20,16</RowVatExcludedAmount>
  <RowAmount AmountCurrencyIdentifier="EUR">25,00</RowAmount>
</InvoiceRow>
```
</details>

<details>
<summary>Multiple progressive row discounts</summary>

Multiple sequential discounts using `RowProgressiveDiscountDetails`. Each discount is applied to the result of the previous one, plus a fixed discount at the end.

```xml
<InvoiceRow>
  <ArticleName>Article</ArticleName>
  <InvoicedQuantity QuantityUnitCode="kpl" QuantityUnitCodeUN="EA">1,00</InvoicedQuantity>
  <UnitPriceAmount AmountCurrencyIdentifier="EUR">80,64516</UnitPriceAmount>
  <UnitPriceNetAmount AmountCurrencyIdentifier="EUR">80,64516</UnitPriceNetAmount>
  <RowProgressiveDiscountDetails>
    <RowDiscountPercent>50,00</RowDiscountPercent>
    <RowDiscountAmount AmountCurrencyIdentifier="EUR">40,33</RowDiscountAmount>
    <RowDiscountBaseAmount AmountCurrencyIdentifier="EUR">80,65</RowDiscountBaseAmount>
    <RowDiscountTypeCode>95</RowDiscountTypeCode>
  </RowProgressiveDiscountDetails>
  <RowProgressiveDiscountDetails>
    <RowDiscountPercent>50,00</RowDiscountPercent>
    <RowDiscountAmount AmountCurrencyIdentifier="EUR">20,16</RowDiscountAmount>
    <RowDiscountBaseAmount AmountCurrencyIdentifier="EUR">40,32</RowDiscountBaseAmount>
    <RowDiscountTypeCode>95</RowDiscountTypeCode>
  </RowProgressiveDiscountDetails>
  <RowProgressiveDiscountDetails>
    <RowDiscountAmount AmountCurrencyIdentifier="EUR">10,16</RowDiscountAmount>
    <RowDiscountBaseAmount AmountCurrencyIdentifier="EUR">20,16</RowDiscountBaseAmount>
    <RowDiscountTypeCode>95</RowDiscountTypeCode>
  </RowProgressiveDiscountDetails>
  <RowVatRatePercent>24,00</RowVatRatePercent>
  <RowVatCode>S</RowVatCode>
  <RowVatAmount AmountCurrencyIdentifier="EUR">2,40</RowVatAmount>
  <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">10,00</RowVatExcludedAmount>
  <RowAmount AmountCurrencyIdentifier="EUR">12,40</RowAmount>
</InvoiceRow>
```
</details>

<details>
<summary>Unit discount with progressive row discounts</summary>

A unit price discount combined with multiple progressive row discounts.

```xml
<InvoiceRow>
  <ArticleName>Article</ArticleName>
  <InvoicedQuantity QuantityUnitCode="kpl" QuantityUnitCodeUN="EA">1,00</InvoicedQuantity>
  <UnitPriceAmount AmountCurrencyIdentifier="EUR">80,64516</UnitPriceAmount>
  <UnitPriceDiscountAmount AmountCurrencyIdentifier="EUR">40,32258</UnitPriceDiscountAmount>
  <UnitPriceNetAmount AmountCurrencyIdentifier="EUR">40,32258</UnitPriceNetAmount>
  <RowProgressiveDiscountDetails>
    <RowDiscountPercent>50,00</RowDiscountPercent>
    <RowDiscountAmount AmountCurrencyIdentifier="EUR">20,16</RowDiscountAmount>
    <RowDiscountBaseAmount AmountCurrencyIdentifier="EUR">40,32</RowDiscountBaseAmount>
    <RowDiscountTypeCode>95</RowDiscountTypeCode>
  </RowProgressiveDiscountDetails>
  <RowProgressiveDiscountDetails>
    <RowDiscountPercent>50,00</RowDiscountPercent>
    <RowDiscountAmount AmountCurrencyIdentifier="EUR">10,08</RowDiscountAmount>
    <RowDiscountBaseAmount AmountCurrencyIdentifier="EUR">20,16</RowDiscountBaseAmount>
    <RowDiscountTypeCode>95</RowDiscountTypeCode>
  </RowProgressiveDiscountDetails>
  <RowVatRatePercent>24,00</RowVatRatePercent>
  <RowVatCode>S</RowVatCode>
  <RowVatAmount AmountCurrencyIdentifier="EUR">2,42</RowVatAmount>
  <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">10,08</RowVatExcludedAmount>
  <RowAmount AmountCurrencyIdentifier="EUR">12,50</RowAmount>
</InvoiceRow>
```
</details>

<details>
<summary>Unit discount, row discount, and row charge</summary>

All three adjustment types combined on a single row: unit price discount, row discount, and a row charge.

```xml
<InvoiceRow>
  <ArticleName>Article</ArticleName>
  <InvoicedQuantity QuantityUnitCode="kpl" QuantityUnitCodeUN="C62">1,00</InvoicedQuantity>
  <UnitPriceAmount AmountCurrencyIdentifier="EUR"
                   UnitPriceUnitCode="kpl"
                   QuantityUnitCodeUN="C62">110,00</UnitPriceAmount>
  <UnitPriceDiscountAmount AmountCurrencyIdentifier="EUR">10,00</UnitPriceDiscountAmount>
  <UnitPriceNetAmount AmountCurrencyIdentifier="EUR">100,00</UnitPriceNetAmount>
  <RowDiscountPercent>55,0</RowDiscountPercent>
  <RowDiscountAmount AmountCurrencyIdentifier="EUR">55,00</RowDiscountAmount>
  <RowDiscountBaseAmount AmountCurrencyIdentifier="EUR">100,00</RowDiscountBaseAmount>
  <RowDiscountTypeText>Discount #1</RowDiscountTypeText>
  <RowChargeDetails>
    <ReasonText>Charge #1</ReasonText>
    <Amount AmountCurrencyIdentifier="EUR">50,00</Amount>
  </RowChargeDetails>
  <RowVatRatePercent>24,00</RowVatRatePercent>
  <RowVatCode>S</RowVatCode>
  <RowVatAmount AmountCurrencyIdentifier="EUR">22,80</RowVatAmount>
  <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">95,00</RowVatExcludedAmount>
  <RowAmount AmountCurrencyIdentifier="EUR">117,80</RowAmount>
</InvoiceRow>
```

Calculation: (1 × 100.00) - 55.00 + 50.00 = 95.00 EUR (VAT excluded)
</details>

## Credit notes

When creating a credit note in Finvoice, the `InvoicedQuantity` is set to a negative value. The `UnitPriceAmount` and `UnitPriceNetAmount` remain positive.

If the original invoice row included discounts or charges, these amounts must be negated in the credit note as well.

### Original invoice row

```xml
<InvoiceRow>
  <ArticleName>Article</ArticleName>
  <InvoicedQuantity QuantityUnitCode="kpl" QuantityUnitCodeUN="C62">1,00</InvoicedQuantity>
  <UnitPriceAmount AmountCurrencyIdentifier="EUR"
                   UnitPriceUnitCode="kpl"
                   QuantityUnitCodeUN="C62">110,00</UnitPriceAmount>
  <UnitPriceDiscountAmount AmountCurrencyIdentifier="EUR">10,00</UnitPriceDiscountAmount>
  <UnitPriceNetAmount AmountCurrencyIdentifier="EUR">100,00</UnitPriceNetAmount>
  <RowDiscountPercent>55,0</RowDiscountPercent>
  <RowDiscountAmount AmountCurrencyIdentifier="EUR">55,00</RowDiscountAmount>
  <RowDiscountBaseAmount AmountCurrencyIdentifier="EUR">100,00</RowDiscountBaseAmount>
  <RowDiscountTypeText>Discount #1</RowDiscountTypeText>
  <RowChargeDetails>
    <ReasonText>Charge #1</ReasonText>
    <Amount AmountCurrencyIdentifier="EUR">50,00</Amount>
  </RowChargeDetails>
  <RowVatRatePercent>24,00</RowVatRatePercent>
  <RowVatCode>S</RowVatCode>
  <RowVatAmount AmountCurrencyIdentifier="EUR">22,80</RowVatAmount>
  <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">95,00</RowVatExcludedAmount>
  <RowAmount AmountCurrencyIdentifier="EUR">117,80</RowAmount>
</InvoiceRow>
```

### Credit note (with discounts and charges)

Negate the quantity and all discount/charge amounts. Unit prices remain positive.

```xml
<InvoiceRow>
  <ArticleName>Article</ArticleName>
  <InvoicedQuantity QuantityUnitCode="kpl" QuantityUnitCodeUN="C62">-1,00</InvoicedQuantity>
  <UnitPriceAmount AmountCurrencyIdentifier="EUR"
                   UnitPriceUnitCode="kpl"
                   QuantityUnitCodeUN="C62">110,00</UnitPriceAmount>
  <UnitPriceDiscountAmount AmountCurrencyIdentifier="EUR">10,00</UnitPriceDiscountAmount>
  <UnitPriceNetAmount AmountCurrencyIdentifier="EUR">100,00</UnitPriceNetAmount>
  <RowDiscountPercent>55,0</RowDiscountPercent>
  <RowDiscountAmount AmountCurrencyIdentifier="EUR">-55,00</RowDiscountAmount>
  <RowDiscountBaseAmount AmountCurrencyIdentifier="EUR">-100,00</RowDiscountBaseAmount>
  <RowDiscountTypeText>Discount #1</RowDiscountTypeText>
  <RowChargeDetails>
    <ReasonText>Charge #1</ReasonText>
    <Amount AmountCurrencyIdentifier="EUR">-50,00</Amount>
  </RowChargeDetails>
  <RowVatRatePercent>24,00</RowVatRatePercent>
  <RowVatCode>S</RowVatCode>
  <RowVatAmount AmountCurrencyIdentifier="EUR">-22,80</RowVatAmount>
  <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">-95,00</RowVatExcludedAmount>
  <RowAmount AmountCurrencyIdentifier="EUR">-117,80</RowAmount>
</InvoiceRow>
```

### Credit note (simplified)

Alternatively, credit the row using the net unit price directly, without separate discount and charge elements.

```xml
<InvoiceRow>
  <ArticleName>Article</ArticleName>
  <InvoicedQuantity QuantityUnitCode="kpl" QuantityUnitCodeUN="C62">-1,00</InvoicedQuantity>
  <UnitPriceAmount AmountCurrencyIdentifier="EUR"
                   UnitPriceUnitCode="kpl"
                   QuantityUnitCodeUN="C62">95,00</UnitPriceAmount>
  <UnitPriceNetAmount AmountCurrencyIdentifier="EUR">95,00</UnitPriceNetAmount>
  <RowVatRatePercent>24,00</RowVatRatePercent>
  <RowVatCode>S</RowVatCode>
  <RowVatAmount AmountCurrencyIdentifier="EUR">-22,80</RowVatAmount>
  <RowVatExcludedAmount AmountCurrencyIdentifier="EUR">-95,00</RowVatExcludedAmount>
  <RowAmount AmountCurrencyIdentifier="EUR">-117,80</RowAmount>
</InvoiceRow>
```

## Resolving the invoice recipient

When sending a Finvoice invoice, Maventa resolves the invoice recipient from the XML data. To route the invoice successfully, the recipient must have a party name and at least one of the following: an electronic address, an organisation number, a postal address, or an email address.

### Recipient complementation from buyer details

If the `InvoiceRecipientPartyDetails` element is missing or incomplete, Maventa can complement it using data from the `BuyerPartyDetails` element. This ensures the invoice can be routed even when the recipient details are not fully populated.

Complementation occurs when:

- The recipient lacks sufficient information for routing
- All provided recipient details match the buyer details exactly (case-sensitive comparison)
- Some recipient details differ from the buyer, but only in fields that are considered allowed deviations
- The recipient contains only a single detail (email address, contact name, or OVT number) that aligns with buyer information

Allowed deviating details between recipient and buyer:

- Site code
- Department
- Contact person name
- Email address
- Phone number

Complementation does **not** occur when the recipient contains only postal address components (town, postal code, or country code/name) without other identifying information.

### Complementation example

In this example, the invoice has `InvoiceRecipientCommunicationDetails` but no `InvoiceRecipientPartyDetails`. Since the communication details match the buyer, Maventa complements the recipient with the buyer's party details.

### Input (before complementation)

```xml
<Finvoice Version="1.3">
  <InvoiceRecipientCommunicationDetails>
    <InvoiceRecipientPhoneNumberIdentifier>123456</InvoiceRecipientPhoneNumberIdentifier>
    <InvoiceRecipientEmailaddressIdentifier>email@email.com</InvoiceRecipientEmailaddressIdentifier>
  </InvoiceRecipientCommunicationDetails>
  <BuyerPartyDetails>
    <BuyerPartyIdentifier>3333333-3</BuyerPartyIdentifier>
    <BuyerOrganisationName>Name1</BuyerOrganisationName>
    <BuyerOrganisationName>Name2</BuyerOrganisationName>
    <BuyerOrganisationTaxCode>FI33333333</BuyerOrganisationTaxCode>
    <BuyerPostalAddressDetails>
      <BuyerStreetName>StreetName</BuyerStreetName>
      <BuyerTownName>TownName</BuyerTownName>
      <BuyerPostCodeIdentifier>11111</BuyerPostCodeIdentifier>
      <CountryCode>FI</CountryCode>
      <CountryName>Finland</CountryName>
    </BuyerPostalAddressDetails>
  </BuyerPartyDetails>
  <BuyerCommunicationDetails>
    <BuyerPhoneNumberIdentifier>123456</BuyerPhoneNumberIdentifier>
    <BuyerEmailaddressIdentifier>email@email.com</BuyerEmailaddressIdentifier>
  </BuyerCommunicationDetails>
</Finvoice>
```

### Output (after complementation)

Maventa adds the `InvoiceRecipientPartyDetails` element, populated from the buyer's details.

```xml
<Finvoice Version="1.3">
  <InvoiceRecipientPartyDetails>
    <InvoiceRecipientPartyIdentifier>3333333-3</InvoiceRecipientPartyIdentifier>
    <InvoiceRecipientOrganisationName>Name1</InvoiceRecipientOrganisationName>
    <InvoiceRecipientOrganisationName>Name2</InvoiceRecipientOrganisationName>
    <InvoiceRecipientOrganisationTaxCode>FI33333333</InvoiceRecipientOrganisationTaxCode>
    <InvoiceRecipientPostalAddressDetails>
      <InvoiceRecipientStreetName>StreetName</InvoiceRecipientStreetName>
      <InvoiceRecipientTownName>TownName</InvoiceRecipientTownName>
      <InvoiceRecipientPostCodeIdentifier>11111</InvoiceRecipientPostCodeIdentifier>
      <CountryCode>FI</CountryCode>
      <CountryName>Finland</CountryName>
    </InvoiceRecipientPostalAddressDetails>
  </InvoiceRecipientPartyDetails>
  <InvoiceRecipientCommunicationDetails>
    <InvoiceRecipientPhoneNumberIdentifier>123456</InvoiceRecipientPhoneNumberIdentifier>
    <InvoiceRecipientEmailaddressIdentifier>email@email.com</InvoiceRecipientEmailaddressIdentifier>
  </InvoiceRecipientCommunicationDetails>
  <BuyerPartyDetails>
    <BuyerPartyIdentifier>3333333-3</BuyerPartyIdentifier>
    <BuyerOrganisationName>Name1</BuyerOrganisationName>
    <BuyerOrganisationName>Name2</BuyerOrganisationName>
    <BuyerOrganisationTaxCode>FI33333333</BuyerOrganisationTaxCode>
    <BuyerPostalAddressDetails>
      <BuyerStreetName>StreetName</BuyerStreetName>
      <BuyerTownName>TownName</BuyerTownName>
      <BuyerPostCodeIdentifier>11111</BuyerPostCodeIdentifier>
      <CountryCode>FI</CountryCode>
      <CountryName>Finland</CountryName>
    </BuyerPostalAddressDetails>
  </BuyerPartyDetails>
  <BuyerCommunicationDetails>
    <BuyerPhoneNumberIdentifier>123456</BuyerPhoneNumberIdentifier>
    <BuyerEmailaddressIdentifier>email@email.com</BuyerEmailaddressIdentifier>
  </BuyerCommunicationDetails>
</Finvoice>
```

## SpecificationDetails element

Finvoice supports a `<SpecificationDetails>` element that allows free-form specification text on the invoice. This element is rendered in a monospace font (Courier) to preserve column alignment and formatted text exactly as provided in the XML.

```xml
<SpecificationDetails>
  <SpecificationFreeText>LASKUN VAPAAMUOTOISET ERITTELYTIEDOT:</SpecificationFreeText>
  <SpecificationFreeText>Sarake-1              Sarake-2                                                             Sarake-3</SpecificationFreeText>
  <SpecificationFreeText>---------------------------------------------------------------------------------------------------</SpecificationFreeText>
  <SpecificationFreeText>1.sarakkeen tieto     2.sarakkeen tieto                                                       10,00</SpecificationFreeText>
  <SpecificationFreeText>Toinen rivi           Toinen rivi                                                          1 000,00</SpecificationFreeText>
  <SpecificationFreeText>Kolmas rivi           3/2                                                                      1,00</SpecificationFreeText>
</SpecificationDetails>
```

## External resources

- [Finvoice 3.0 specification](https://www.finanssiala.fi/finvoice/Sivut/default.aspx) (Finance Finland)
- [TEAPPSXML 3.0 specification](https://bix.tieto.com/#/teappsxml) (Tietoevry)
- [Finvoice 3.0 & TEAPPSXML 3.0 mapping document](https://bix.tieto.com/infoFiles/Finvoice3.0_TEAPPSXML3.0_correlation_20210607.pdf)

---

## Document types and type codes
Source: https://documentation.maventa.com/integration-guide/invoicing-formats/document-types/

Every invoicing format uses type codes to identify what kind of document is being sent. Maventa processes these codes during import and export, and automatically converts between format-specific codes when converting documents from one format to another.

This page covers the most commonly used formats. Maventa supports additional formats beyond those listed here.

## How document types work

Each format has its own way of indicating the document type:

- **UBL-based formats** (Peppol BIS, EHF, OIOUBL, SI-UBL) use the XML root element to determine the document type. An `<Invoice>` element means it is an invoice, a `<CreditNote>` element means it is a credit note. The `InvoiceTypeCode` field provides additional detail (the subtype) but does not change the document type.
- **Finvoice** uses the `InvoiceTypeCode` element (INV01, INV02, etc.) to determine both the document type and subtype. Codes not in the supported list are rejected.
- **TEAPPS** uses the `INVOICE_TYPE` field with numeric codes. Codes not in the supported list are rejected.

## Finvoice

Finvoice 1.3 supports invoice and credit note. Versions 2.0 and later add direct payment and cancel.

| Type code | Name | Document type | Version |
|-----------|------|---------------|---------|
| INV01 | Commercial Invoice | invoice | 1.3+ |
| INV02 | Credit Note | credit_note | 1.3+ |
| INV02 + OriginCode=Cancel | Cancellation Invoice | cancel | 2.0+ |
| INV03 | Interest Note | invoice | 1.3+ |
| INV04 | Internal Invoice | invoice | 1.3+ |
| INV05 | Collect Note | invoice | 1.3+ |
| INV08 | Reminder Invoice | invoice | 1.3+ |
| INV09 | Direct Payment | direct_payment | 2.0+ |

> [!WARNING]
> The Finvoice specification defines additional codes (INV06 Pro Forma Invoice, INV07 Self Billing, and various non-invoice codes like ORD01, TES01, PRI01) that Maventa does not support. Documents with these codes are identified as Finvoice but cannot be processed.

**Default export codes:** INV01 for invoices, INV02 for credit notes and cancellations, INV09 for direct payments.

### Secure invoices (SEI codes)

Each INV code has a corresponding SEI (Secure E-Invoice) counterpart. Secure invoices are processed as the same document type as their INV equivalent, with an additional security classification flag.

| INV code | SEI equivalent | Document type |
|----------|---------------|---------------|
| INV01 (Commercial Invoice) | SEI01 | invoice |
| INV02 (Credit Note) | SEI02 | credit_note |
| INV03 (Interest Note) | SEI03 | invoice |
| INV04 (Internal Invoice) | SEI04 | invoice |
| INV05 (Collect Note) | SEI05 | invoice |
| INV08 (Reminder Invoice) | SEI08 | invoice |
| INV09 (Direct Payment) | SEI09 | direct_payment |

> [!NOTE]
> SEI06 and SEI07 are defined in the Finvoice specification but are not supported, matching the fact that INV06 and INV07 are also not supported.

The security classification is preserved during conversion between Finvoice and TEAPPS. When converting to any other format, the security classification is lost and the document is treated as a standard invoice or credit note. See [Secure invoice conversion behavior](#secure-invoice-conversion-behavior) for details.

## TEAPPS

TEAPPS 2.7.2 supports invoice and credit note. Version 3.0 adds direct payment and cancel.

| Type code | Name | Document type | Version |
|-----------|------|---------------|---------|
| 00 | Commercial Invoice | invoice | 2.7.2+ |
| 00 (method_of_charge=01) | Direct Payment Invoice | direct_payment | 3.0 |
| 01 | Credit Note | credit_note | 2.7.2+ |
| 01 (method_of_charge=01) | Cancellation Invoice | cancel | 3.0 |
| 02 | Collecting Invoice | invoice | 2.7.2+ |
| 03 | Transit Invoice | invoice | 2.7.2+ |
| 04 | Credit Invoice | credit_note | 2.7.2+ |
| 05 | Credit of Transit Invoice | credit_note | 2.7.2+ |
| 06 | Interest Invoice | invoice | 2.7.2+ |
| 07 | Credit of Interest Invoice | credit_note | 2.7.2+ |
| 08 | Advance Notice | invoice | 2.7.2+ |
| 08 (method_of_charge=01) | Direct Payment Advance Notice | direct_payment | 3.0 |
| 09 | Reminder Invoice | invoice | 2.7.2+ |
| 20 | Vehicle Invoice | invoice | 2.7.2+ |
| 60 | Purchase Credit Note | credit_note | 2.7.2+ |
| 91 | Travel Invoice | invoice | 2.7.2+ |
| 99 | Test Invoice | invoice | 2.7.2+ |

> [!WARNING]
> Codes 30 (Debit Receipt), 31 (Credit Receipt), 32 (Warranty Receipt), 50 (Order), 51 (Order Confirmation), and 90 (Travel Plan) are defined in the TEAPPS specification but are not supported by Maventa.

**Default export codes:** 00 for invoices, 01 for credit notes.

TEAPPS does not have dedicated security invoice type codes. Instead, TEAPPS 3.0 carries security classification in a separate `SECURITY_DETAILS` element with a `SECRECY_CLASS` code and an optional `SECRECY_DESCRIPTION`. When a Finvoice secure invoice (SEI code) is converted to TEAPPS, the invoice type code is mapped to the standard TEAPPS equivalent and the SEI code is stored in `SECRECY_CLASS`. See [Secure invoice conversion behavior](#secure-invoice-conversion-behavior) for details.

## Peppol BIS 3.0

Peppol BIS 3.0 uses UNCL 1001 invoice type codes. The table below lists the most commonly used codes. The full code list is defined in the [Peppol BIS 3.0 specification](https://docs.peppol.eu/poacc/billing/3.0/) and evolves over time — some codes may have country-specific restrictions or conditions.

| Type code | Name | Document type |
|-----------|------|---------------|
| 380 | Commercial Invoice | invoice |
| 381 | Credit Note | credit_note |
| 383 | Debit Note | invoice |
| 384 | Corrected Invoice | invoice |
| 386 | Prepayment Invoice | invoice |
| 389 | Self-Billed Invoice | self_billing_invoice |
| 261 | Self-Billed Credit Note | self_billing_credit_note |
| 326 | Partial Invoice | invoice |
| 393 | Factored Invoice | invoice |
| 396 | Factored Credit Note | credit_note |

**Default export codes:** 380 for invoices, 381 for credit notes.

## OIOUBL (Danish)

Both versions 2.02 and 2.1 support the same types.

| Type code | Name | Document type |
|-----------|------|---------------|
| 325 | Proforma Invoice | invoice |
| 380 | Commercial Invoice | invoice |
| 381 | Credit Note | credit_note |
| 393 | Factored Invoice | invoice |

Also supports **application_response** as a separate document type.

**Default export codes:** 380 for invoices, 381 for credit notes.

## SI-UBL 2.0 (Dutch)

| Type code | Name | Document type |
|-----------|------|---------------|
| 380 | Commercial Invoice | invoice |
| 381 | Credit Note | credit_note |
| 384 | Corrected Invoice | invoice |
| 389 | Self-Billed Invoice | invoice |

---

## Subtype preservation during format conversion

When Maventa converts a document from one format to another, the document type (invoice, credit note) is always preserved. However, the specific subtype (such as Reminder Invoice or Interest Note) is only preserved if the target format recognizes the same subtype. If the target format does not have a matching subtype, the type code falls back to the default for that document type.

> [!NOTE]
> A type code is a label that identifies the kind of document. The actual data that makes a document special (for example, factoring party details on a factored invoice, or overdue payment calculations on an interest invoice) is carried in the document content and is converted independently of the type code. Even when a type code falls back to a generic value, the relevant content fields are still mapped to the target format if that format supports them. See [Content-level feature support](#content-level-feature-support) for details on which features each format can carry in its payload.

### Default fallback codes

| Target format | Invoice default | Credit note default |
|---------------|----------------|---------------------|
| Peppol BIS 3.0 | 380 (Commercial Invoice) | 381 (Credit Note) |
| Finvoice | INV01 (Commercial Invoice) | INV02 (Credit Note) |
| TEAPPS | 00 (Commercial Invoice) | 01 (Credit Note) |
| OIOUBL | 380 | 381 |
| SI-UBL | 380 | 381 |

### Cross-format subtype compatibility

The following table shows which subtypes are shared between format families. A subtype is preserved during conversion only if both the source and target format define it.

The "Content" column indicates whether the document content associated with that subtype (such as factoring details or overdue payment data) can be carried in the target format's payload, even when the type code itself falls back to a generic value.

| Subtype | Finvoice | TEAPPS | Peppol BIS 3.0 | OIOUBL | SI-UBL 2.0 | Content carried by |
|---------|----------|--------|----------------|--------|------------|-------------------|
| Commercial Invoice | INV01 | 00 | 380 | 380 | 380 | All formats |
| Credit Note | INV02 | 01 | 381 | 381 | 381 | All formats |
| Interest Invoice | INV03 | 06 | — | — | — | Row-level details: Finvoice, TEAPPS. Header rate: most formats |
| Internal Invoice | INV04 | — | — | — | — | No specific content |
| Collect Note | INV05 | 02 | — | — | — | No specific content beyond overdue payment details |
| Reminder Invoice | INV08 | 09 | — | — | — | Penalty interest: UBL formats, Finvoice, TEAPPS |
| Direct Payment | INV09 | 00/08 | — | — | — | Finvoice, TEAPPS only |
| Corrected Invoice | — | — | 384 | — | 384 | No specific content |
| Prepayment Invoice | — | — | 386 | — | — | Prepaid amount: UBL formats, Finvoice, TEAPPS |
| Self-Billed Invoice | — | — | 389 | — | 389 | Party reversal: Peppol BIS 3.0 only |
| Factored Invoice | — | — | 393 | 393 | — | Payee/factoring data: most formats |
| Partial Invoice | — | — | 326 | — | — | No specific content |

A dash (—) in the type code columns means the format does not have a dedicated type code for that subtype. When converting to a format that shows a dash, the type code falls back to the default (Commercial Invoice or Credit Note). However, the document content may still be converted if the target format supports the relevant payload fields.

### Conversion examples

| Source format | Source code | Target format | Result code | What happens |
|---------------|-----------|---------------|-------------|--------------|
| Finvoice INV01 | Commercial Invoice | Peppol BIS 3.0 | 380 | Preserved |
| Finvoice INV02 | Credit Note | Peppol BIS 3.0 | 381 | Preserved |
| Finvoice INV03 | Interest Note | Peppol BIS 3.0 | 380 | Type code falls back to Commercial Invoice. Header-level penalty interest rate is carried in PaymentTerms. Row-level overdue payment details are lost. |
| Finvoice INV05 | Collect Note | Peppol BIS 3.0 | 380 | Type code falls back to Commercial Invoice. Overdue payment details on rows are lost. |
| Finvoice INV08 | Reminder Invoice | Peppol BIS 3.0 | 380 | Type code falls back to Commercial Invoice. Penalty interest data is carried in PaymentTerms. |
| Finvoice INV03 | Interest Note | TEAPPS | 06 | Preserved. Row-level overdue payment details are also preserved. |
| Finvoice INV08 | Reminder Invoice | TEAPPS | 09 | Preserved |
| OIOUBL 393 | Factored Invoice | Finvoice | INV01 | Type code falls back to Commercial Invoice. Factoring party details and bank accounts are mapped to FactoringAgreementDetails. |
| Peppol BIS 393 | Factored Invoice | Finvoice | INV01 | Type code falls back to Commercial Invoice. Payee party data is mapped to FactoringAgreementDetails. |
| Peppol BIS 384 | Corrected Invoice | Finvoice | INV01 | Type code falls back to Commercial Invoice |
| Peppol BIS 386 | Prepayment Invoice | Finvoice | INV01 | Type code falls back to Commercial Invoice. Prepaid amount is preserved. |
| Peppol BIS 393 | Factored Invoice | OIOUBL | 393 | Preserved. Payee party data is also preserved. |
| TEAPPS 09 | Reminder Invoice | Peppol BIS 3.0 | 380 | Type code falls back to Commercial Invoice. Penalty interest data is carried in PaymentTerms. |
| TEAPPS 06 | Interest Invoice | Peppol BIS 3.0 | 380 | Type code falls back to Commercial Invoice. Header-level interest rate is carried. Row-level overdue payment details are lost. |
| TEAPPS 06 | Interest Invoice | Finvoice | INV03 | Preserved. Row-level overdue payment details are also preserved. |
| Finvoice SEI05 | Secure Collect Note | Finvoice | SEI05 | Preserved (same format family) |
| Finvoice SEI05 | Secure Collect Note | TEAPPS 3.0 | 02 + security metadata | Security classification preserved as metadata |
| Finvoice SEI05 | Secure Collect Note | Peppol BIS 3.0 | 380 | Security classification and subtype both lost |

### Secure invoice conversion behavior

Finvoice secure invoices (SEI codes) carry a security classification that indicates the document requires special handling. This classification is a feature specific to the Finnish invoicing ecosystem and is only fully supported in Finvoice and TEAPPS formats.

**Finvoice to Finvoice:** The SEI code is passed through as-is. A document sent as SEI05 (Secure Collect Note) is delivered as SEI05.

**Finvoice to TEAPPS:** The security classification is preserved as separate metadata. The invoice type code is mapped to the corresponding non-secure TEAPPS equivalent (for example, SEI05 maps to TEAPPS code 02, which is the Collecting Invoice). The security information travels alongside the document so it can be restored if the document is later converted back to Finvoice.

**TEAPPS to Finvoice:** If the TEAPPS document carries security metadata, the converter restores the SEI code in the Finvoice output. For example, a TEAPPS document with code 02 and a stored security code of SEI05 is exported as Finvoice SEI05.

**Finvoice or TEAPPS to any other format:** The security classification is lost. The document is converted using the underlying invoice subtype only (for example, SEI05 becomes a standard Commercial Invoice with code 380 in Peppol BIS 3.0). There is no mechanism to carry the security classification in UBL or other non-Finnish formats.

| Conversion | Type code result | Security classification |
|------------|-----------------|------------------------|
| Finvoice SEI → Finvoice | SEI code preserved | Preserved |
| Finvoice SEI → TEAPPS 3.0 | Mapped to TEAPPS equivalent | Preserved as metadata |
| TEAPPS (with security) → Finvoice | SEI code restored | Restored |
| Finvoice SEI → Peppol BIS 3.0 | Falls back to 380/381 | Lost |
| Finvoice SEI → any other format | Falls back to default | Lost |

## Content-level feature support

The type code tells the recipient what kind of document it is, but the actual data that makes a document special is carried in the document content. For example, a factored invoice contains factoring party details and bank accounts in its payload. When converting between formats, Maventa maps this content independently of the type code. Even if the target format does not have a dedicated type code for "factored invoice", the factoring data is still converted if the target format has the relevant fields.

The following tables show which formats can carry specific content features in their payload. This is separate from whether the format has a dedicated type code for that feature.

### Factoring and payee party

Factoring information identifies a third party (the factor) who receives payment on behalf of the seller. This data includes the factoring party name, address, bank accounts, and agreement details.

| Format | Support level |
|--------|--------------|
| Finvoice | Full: FactoringAgreementDetails with party name, address, identifier, agreement ID, type code, bank accounts |
| TEAPPS | Full: FACTORING_INFORMATION with agreement number, factoring type, endorsement clause |
| Peppol BIS 3.0 | PayeeParty with name, identifiers, legal entity |
| OIOUBL, SI-UBL | PayeeParty (inherited from UBL base) |

### Overdue payment and interest calculation details

Interest invoices and collect notes typically carry per-row details about the original overdue invoices: original invoice number, dates, amounts, interest rate, interest period, and calculated interest charges.

| Format | Support level |
|--------|--------------|
| Finvoice | Full row-level: RowOverDuePaymentDetails with original invoice ID, dates, amounts, interest rate, interest period, paid/unpaid amounts, collection charges |
| TEAPPS | Full row-level: INFORMATION_OF_OVERDUE_PAYMENTS with interest charges, interest period, interest rate, collection surcharges, original invoice references |
| All UBL formats | Not supported. Row-level overdue payment details are lost during conversion to these formats. |

### Penalty interest rate

A header-level interest rate that applies to late payments. This is a simpler field than the row-level overdue payment details above.

| Format | Support level |
|--------|--------------|
| Finvoice | PaymentOverDueFinePercent, PaymentOverDueFineFreeText |
| TEAPPS | PAYMENT_OVERDUE_FINE with interest rate and free text |
| Peppol BIS 3.0, OIOUBL, SI-UBL | PenaltySurchargePercent and PenaltyPeriod in PaymentTerms |

### Prepaid amount

The amount already paid before the invoice is issued, used for advance payments and prepayment invoices.

| Format | Support level |
|--------|--------------|
| Peppol BIS 3.0, OIOUBL, SI-UBL | Full: PrepaidAmount in LegalMonetaryTotal plus PrepaidPayment details (ID, amount, date) |
| Finvoice 3.0 | InvoicePaidAmount (sum only, no detailed references) |
| TEAPPS | ADVANCE_PAYMENT (sum only) |

### Direct payment

Direct payment (suoramaksu) is a Finnish payment method where the invoice amount is collected directly from the payer's bank account. This is a concept specific to the Finnish invoicing ecosystem.

| Format | Support level |
|--------|--------------|
| Finvoice | Full: OriginCode field, DirectDebitInfo with debited account details, dedicated document type |
| TEAPPS | Full: METHOD_OF_CHARGE field, dedicated document type |
| All other formats | Not supported. Direct payment data is lost during conversion. |

### Self-billing

Self-billing is when the buyer creates the invoice on behalf of the seller. Beyond the type code, this requires reversing the party roles (the buyer becomes the accounting supplier).

| Format | Support level |
|--------|--------------|
| Peppol BIS 3.0 | Full: dedicated document types with party endpoint reversal in mappings |
| SI-UBL 2.0 | Type code support (389) but no party reversal logic |
| All other formats | Not supported |

### Construction invoice specifics

Construction invoices (type codes 875, 876, 877) are distinguished only by their type code. No format has construction-specific payload fields such as completion percentage or site details. The only related structural element is the standard contract reference field, which is available in most formats.

---

## Companies and Settings
Source: https://documentation.maventa.com/integration-guide/account-management/companies-and-settings/

You can use the REST API or the web user interface to open and manage company accounts. However, the user interface requires manual work so if the integration will have multiple companies or a complex set-up, API is recommended.

## How to open and activate company accounts

1. Create company account
2. Configure settings for the account
3. Authorize the account (Customer authentication process) either with
   1. Visma Sign authentication process
   2. Partner's own customer authentication process

### 1. Create company account

When registering a new company through the API, different countries have varying levels of support:

| Country           | Supported business identifiers | Notes                                                                                          |
|-------------------|--------------------------------|------------------------------------------------------------------------------------------------|
| Finland (FI)      | ORGNR, VAT                     | Customer authentication supported by Visma Sign (HETU, Finnish banks and mobile)               |
| Sweden (SE)       | ORGNR, SSN                     | Customer authentication supported by Visma Sign (personal ID or BankID)                        |
| Norway (NO)       | ORGNR                          | Customer authentication supported by Visma Sign (BankID)                                       |
| Denmark (DK)      | CVR                            | Customer authentication supported by Visma Sign (personal ID or NemID)                         |
| Netherlands (NL)  | KVK                            | Customer authentication supported by Visma Sign (iDIN)                                         |
| Estonia (EE)      | CC, VAT                        | Allowed to create but there is no automated authentication process, please contact our support |
| Belgium (BE)      | EN                             | Allowed to create but there is no automated authentication process, please contact our support |
| Germany (DE)      | VAT                            | Allowed to create but there is no automated authentication process, please contact our support |
| Latvia (LV)       | VAT                            | Allowed to create but there is no automated authentication process, please contact our support |
| Italy (IT)        | CFI, IVA                       | Allowed only for specific partners, please contact our support                                 |
| Poland (PL)       | VAT                            | Allowed only for specific partners, please contact our support                                 |
| Other countries   | -                              | Please contact our support                                                                     |

FI, SE, NO, DK, NL companies can be registered without any special arrangements. Because our [customer authentication process](#3-customer-authentication-process) supports these countries.

Creating a company requires a vendor key and a user API key.  

You may use an existing user or create a new one with:

* [POST /v1/users](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/users/postV1Users)

To register a new company with basic settings:

* [POST /v1/companies](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/companies/postV1Companies)

In situations where a new user is created, method returns unique company_uuid and user_api_key. If method is called with an existing user, for security reasons only company_uuid is returned.

#### Existing company

There can be only one company per business id.
If the business id already exists in Maventa you will get an error message when trying to register it again (BID ALREADY TAKEN). Please contact Maventa support (`support@maventa.com`) regarding the management changes of the already existing account.

In REST API you can check beforehand company's availability with

* [POST /v1/partner/lookups/companies](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/partner/getV1PartnerLookupsCompanies)

When registering a new company account, it gets automatically linked to your vendor. If you take an already existing company account into use, remember to link the company account to your vendor. This is necessary for correct reporting and support handling and also mandatory if you wish to use webhooks. Similarly if a company stops using your vendor, it should be unlinked.

* [POST/v1/company/vendors](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/postV1CompanyVendors) Link vendor API key
* [DELETE/v1/company/vendors](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/deleteV1CompanyVendors) Unlink vendor API key

### 2. Configure account settings

When company account has been created, it can be configured by updating company settings and adding new users.

> [!NOTE]
> To be able to send, receive and activate services you need to first verify the account by Know Your Customer process.

API methods:

* [PATCH /v1/company/settings](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/patchV1CompanySettings)
change company's settings.
* [GET /v1/company/settings](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/getV1CompanySettings)
view current settings of a company.
* [POST /v1/users](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/users/postV1Users)
add new or existing user to a company.
* [POST /v1/company/notifications](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/postV1CompanyNotifications) - register webhooks

#### Keep Active

Keep Active is a feature for companies that rarely generate transactions.
To maintain your company account as active even without generating transactions within a year, use the "Keep Active" feature.

As part of our data maintenance efforts, we will disable inactive company accounts, which means accounts with no transactions in the past 13 months. An email alert will be sent to the account after 12 months of inactivity, notifying that the account will be automatically disabled in one month. This provides time for companies to take appropriate action. If there is no activity after 13 months, the account will be disabled.

In REST API you can trigger Keep Active function with

* [POST/v1/company/keep_active](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/postV1CompanyKeepActive)

### 3. Customer authentication process

Customer authentication process is a necessary step to get the company's account authorized. In other words to verify the `company_state`. 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 the Terms of Service. The process is crucial for preventing potential misuse of the service.

The company's account cannot be fully used until authentication is completed.

Please note that for Finnish companies, the process also automatically creates a bank network opening request.

#### Customer authentication options

The customer authentication process can happen with Visma Sign electronic signature service after opening the company's account or it can happen already on the partner's side.

If partner wants to use own authentication process, Maventa needs to approve the partner's customer authentication process.

Visma Sign service is always used if company's account is registered via Maventa UI.

##### Visma Sign authentication process

The authentication takes place within Visma Sign service. A person who has rights to represent company (signing rights or power of attorney) authenticates strongly with bank credentials, BankID or mobileID and signs a document where they confirm that company's account can be authorized and taken into use.

Strong authentication via Visma Sign is currently available for the following countries: Finland, Sweden, Norway, Denmark and Netherlands.

##### Partners own customer authentication process

When company's representative has been already strongly authenticated on the partner's side the account can be taken in use without any additional signing.

The partner must provide an tracable information in `authorization_method` per each company to link the authentication process event on their side (e.g. contract number, signing eventID). If needed partner has to be able to show that the authentication has happened.

Please contact Maventa support to get your own authentication process approved.

<details>
<summary>What is meant by strong authentication</summary>

Strong authentication is a process where service provider (partner) verifies the identity of the company's representative with certainty. It can be implemented e.g. with login codes of online banks, mobileID, bankID, an electronic identity card or passport.
</details>

#### APIs to use

After company's account has been created an API call is used to trigger the authentication process, in other words, a Visma Sign document is sent for signing, see [Visma sign authentication process](#example---visma-sign-authentication-process)

If partner is using own customer authentication process there is still a need to call the authorization method/endpoint, see [Own customer authentication process](#example---partners-own-customer-authentication-process) example.

When the customer authentication is completed the company's account gets authorized and `company_state` changes from **unverified** (-1) to **verified** (1) after this the account is ready to be used fully.

* Authorize a single company [POST /v1/company/authorization](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/company/postV1CompanyAuthorization)
* View company's authorization status [GET /v1/company/authorization](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/getV1CompanyAuthorization)
* Authorize multiple companies [POST /v1/companies/authorizations](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/companies/postV1CompaniesAuthorizations)
* View company's authorization status [GET /v1/companies/{id}/status](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/companies/getV1CompaniesIdStatus)

##### Authorization states

| Company_state   | Description                                                                                                                                                                        |
|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| verified (1)    | Company account is authorized/verified and customer authentication has been completed. Company account can be used normally.                                                       |
| unverified (-1) | Company account not authorized/verified, customer authentication required. Account usage is restricted.                                                                            |
| unknown  (0)    | Customer authentication and company authorization not needed. Company account has not been verified, but can be used normally. This status is possible for older company accounts. |

NOTE! Sending or receiving of invoices is not allowed if `company_state` is unverified (-1) and API will return error message “Unauthorized”.

##### Authorization webhooks

You can use webhooks to get notifications when company's state changes. See the example "Example for companies authorization".

You can also register webhook to monitor bank network opening for Finnish companies.
The request to open bank network is sent after the authentication is completed. The opening is approved by third party (bank) and it usually takes couple of days.

##### Visma Sign authentication process in production

* The signee needs to be a person who has rights to represent company (signing rights or power of attorney).
* You can use parameter *locale* to select the language of the PDF document.
* The invitation to sign is valid for 7 days. If the signature is not made within this time, a new request must be sent.
* Company's authorisation status is automatically updated from Visma Sign every 15 minutes.

##### Visma Sign authentication process in testing and Visma Sign service test credentials

In **testing**, the flow is similar as above but there are no automatic status updates. You need to call API to get the company's state updated.

* [GET /v1/companies/{id}/status](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/companies/getV1CompaniesIdStatus)

You can complete Visma Sign authorization request with these test credentials:

* user ID: `testtest@test.test`
* password: `xO70MVYD0CXaKcQ2`

For bankID you can use Nets test users from <https://www.nets.eu/developer/e-ident/eids/Pages/testusers.aspx>

##### Authenticate multiple company accounts with one go

In cases where single signee has rights to represent multiple companies it is possible to use one signing to authenticate all of the company accounts at the same time. For example in case of a housing company or accounting office that has power of attorney for multiple customers. One API call can be used to authorize up to 50 companies. For authentication to work, companies must be from the same country.

When this option is used the signing invitation contains a list of companies to be authenticated.

## Example - Visma Sign authentication process

You have created company account, at this point authorisation status is (-1) = **unverified**.
To initiate Visma Sign process to call [POST /v1/companies/authorizations](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/companies/postV1CompaniesAuthorizations) API method.

After Visma Sign process has been completed, company account is set to **verified** state (1) and is ready to be used.

<details>
<summary>Visma Sign process</summary>

1) Request to sign is sent to an email given in the API call

![Invitation to sign](/assets/pages/01-integration-guide/06-account-management/01-companies-and-settings/invitation_to_sign.png)

2) Signee logs into Visma Sign service with a password given in the email

![Log in Sign](/assets/pages/01-integration-guide/06-account-management/01-companies-and-settings/log_in_visma_sign.png)

3) Signee sees a document that contains statement of authorisation and accepting attached Terms of Service

![Sign view](/assets/pages/01-integration-guide/06-account-management/01-companies-and-settings/sign_view.png)

* Text in the document:  
  *I assure that I have the right to represent (signing rights or power of attorney) the company "CompanyName (BID)" and hereby authorise it for sending and receiving of electronic documents. By signing this document I accept the Terms of Service (below). The signing of this document does not cause any expenses for the company. Visma Solutions Oy only invoices the company "CompanyName" based on the number of sent and received documents and activated services according to the valid price list.*

* For Finnish companies the document also mentions the bank network opening

4) Signee authenticates strongly and signs the document electronically in Visma Sign service.

* After signee has selected their preferred authentication method and performed the authentication they can see a button **Sign document**.

![auth_methods_FI](/assets/pages/01-integration-guide/06-account-management/01-companies-and-settings/auth_methods_FI.png)

![auth_methods](/assets/pages/01-integration-guide/06-account-management/01-companies-and-settings/auth_methods.png)

5) Signing is ready
</details>

## Example - Partner's own customer authentication process

After company account creation account's authorization status is `-1` = **unverified**.  
To authorize the account call one of these:

* [POST /v1/company/authorization](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/postV1CompanyAuthorization) endpoint
* [POST /v1/companies/authorizations](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/companies/postV1CompaniesAuthorizations) endpoint

In the API call you must provide an identifier in `authorization_method` per each company to link to authorisation event (e.g. contract number, signing eventID). After the API call, account is set automatically to **verified** state `1` and is ready to be used. No need to sign any documents in Visma Sign service.

## Company account creation over UI

New companies with a new user can be created for:

* Testing at https://testing.maventa.com/registrations/
* Production at https://secure.maventa.com/registrations/

If you need to create a new company for an existing user, login to Maventa UI first.

Before account can be used it needs to be authorized using Visma Sign service. When the user logins to the account for the first time, user needs to go through a first time wizard where they add information of the company and configure basic settings. The last step of the wizard is the company authorization process with Visma Sign service. This process is the same as described within the Visma Sign authentication process above, but in this case the signing is initiated from the UI.

> [!NOTE]
> * The language of the PDF document is defined based on company country.
> * The language of the Visma Sign invitation email is defined based on the language that is set for the user interface at the time the authentication request is sent. E.g. when UI is in Finnish, Visma Sign email is sent in Finnish.

## Partner accounts

In Maventa there are two type of accounts; **Company accounts** and **Partner accounts**. Company account is the default account type. Partner accounts are used by the integration partners.

The key difference between a Partner and a Company account is that Partner accounts have extra identifier, `vendor_api_key`, which is used to link API calls to the partner company. The vendor api key is used for billing and reporting purposes. One Partner company can have multiple vendor API keys, for example one for each country they have customers in.

Partners don't need to worry about controlling the account type, all accounts registered to Maventa are first created as Company account and changed to Partner account if and when needed by Maventa.

## FAQ

<details>
<summary>I am testing Visma Sign in test environment, the signing has been done but the status is not updating. What is wrong?</summary>

There is a difference in status updating between stage and production. See [Visma Sign in testing](#visma-sign-authentication-process-in-testing-and-visma-sign-service-test-credentials)
</details>

---

## Department Company
Source: https://documentation.maventa.com/integration-guide/account-management/department-company/

Department Company lets organisations with multiple physical locations or subsidiaries register and manage them as separate accounts while keeping a single parent company registration. Each department operates as its own account with a unique electronic invoicing address (endpoint), while sharing the parent company's Business Identifier (BID).

This works well for retail chains, schools, municipalities, and logistics companies that need to route invoices to specific locations independently.

> [!WARNING]
> The feature is currently in pilot phase and available for approved vendors only. To enable this feature for your vendor, contact Maventa support.

## What are Department Companies?

Department Companies are subsidiary accounts created under a parent company. They share the same BID or VAT number with the parent, but have unique electronic address identifiers — specifically Global Location Numbers (GLN) — for routing invoices.

**Key characteristics**

- Share the same BID as the parent company
- Each has a unique GLN (Global Location Number) endpoint
- Created using the REST API
- Operate as independent accounts with separate inboxes
- Cannot have departments of their own (no nesting)
- Don't go through standard company authorisation process — verified based on the parent company's verification

## Departments vs multiple endpoints


> [!NOTE]
> **Use departments when** your organisation has multiple physical locations that each need separate Maventa accounts. Different business units can handle invoices independently with full operational separation.

> [!IMPORTANT]
> **Use multiple endpoints when** you don't need separate accounts for each location. Multiple GLN endpoints under a single company account let all invoices arrive in one account, with the GLN information in the invoice XML for your own routing logic.


## How to register departments

### Prerequisites

- The parent company must be registered and verified in Maventa
- Your vendor must be approved for the pilot programme

### Registration process

1. Register the parent company with a valid Business Identifier (see [Companies and Settings](/integration-guide/account-management/companies-and-settings/))
2. [Create departments](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/company/postV1CompanyDepartments) using the REST API
3. Provide the department name and unique GLN endpoint
4. For Peppol connectivity, contact Maventa support to register the GLN endpoints

### API endpoint

For detailed API documentation, refer to the [Swagger documentation](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API)

### GLN validation

When registering departments, Maventa validates GLN numbers by cross-referencing with the GS1 registry. You can verify GLN ownership beforehand using the [Verified by GS1 service](https://www.gs1.org/services/verified-by-gs1/iframe)

> [!NOTE]
> Validate all GLN numbers against GS1 before registration. GLNs may be owned by parent companies but allocated to subsidiaries — collect complete GLN details upfront to avoid delays.

## Department account details

- Shares the parent company's BID
- Has a unique GLN endpoint identifier
- Cannot create new users during registration
- Automatically linked to the vendor used when creating them

### Vendor linking

Departments are automatically linked to the creating vendor. If a department needs a different vendor than the parent company, link that vendor to the department account separately after creation.

### Invoice routing

Invoices sent to departments must include the correct GLN endpoint in the invoice XML. Maventa's routing system uses both the BID and the GLN to route invoices to the correct accounts.

### Disabling departments

A parent company cannot be disabled while it has active departments. All department accounts must be disabled first. Contact Maventa support for disabling an account.

## Service support matrix

Not all Maventa services are available for department accounts.

### Sending

| Service | Supported | Notes |
|---------|-----------|-------|
| Internal Routing | **Yes** | Invoices can be sent between Maventa accounts |
| Operator Network | **Yes** | Operator networks supported |
| Peppol | **Yes**  | Peppol network supported |
| Print | **Yes** | Works out of the box |
| B2C (FI/NO/SE) | **Maybe** | Depends on the endpoint ID type |

### Receiving

| Service | Supported | Notes |
|---------|-----------|-------|
| Internal Routing | **Yes** | Receive invoices from internal Maventa accounts |
| Operator Network | **Yes** | Operator network supported |
| Peppol | **Yes*** | Requires manual GLN validation before Peppol registration; automated validation in development |
| Scanning | **Maybe** | Depends on the company country |
| Detect | **Yes** | Fraud detection supported |

*Peppol registration for departments must be arranged with Maventa support. See [Peppol registration for departments](#peppol-registration-for-departments) below.

## Peppol registration for departments

Departments can be registered to [Peppol](/integration-guide/peppol/peppol-network/), but the process currently requires manual validation of the GLN endpoints by Maventa.

### Registration process

1. Create department accounts through the API
2. Contact Maventa support with the list of GLN numbers requiring Peppol registration
3. Maventa validates the GLNs and registers them to Peppol
4. You'll receive confirmation once registration is complete

> [!NOTE]
> Automated validation of GLNs is in development. Once available, departments will be able to register to Peppol directly through the REST API without manual intervention.

## Limitations

- **GLN only** — Only Global Location Numbers are supported as endpoint identifiers. Other identifier types may be added in the future.
- **No nesting** — Departments cannot have their own departments. The structure is limited to two levels: parent company and departments.
- **Pilot access** — Your vendor must be approved for the pilot programme before you can create departments.

## Best practices

<details>
<summary>Test before going to production</summary>

- Test thoroughly in the staging environment with sample GLNs
- Verify Peppol functionality works as expected before enabling in production
- Confirm all required services are available for your use case
- Validate GLN numbers against the GS1 registry
</details>

<details>
<summary>Communicate with your customers</summary>

- Clearly explain whether departments or multiple endpoints are right for their situation
- Document the expected number of departments before registration
- Set clear expectations about Peppol registration timelines
</details>

<details>
<summary>Manage GLN numbers carefully</summary>

- Validate all GLN numbers against GS1 before submitting for Peppol registration
- GLNs may be owned by parent companies but allocated to subsidiaries
- Collect complete GLN details upfront to reduce back-and-forth communication
</details>

## FAQ

<details>
<summary>What's the difference between departments and multiple endpoints?</summary>

Departments create separate Maventa accounts with individual inboxes and separate management. Multiple endpoints register different GLNs to a single company account, with all invoices arriving in one inbox. Use departments if you need operational separation; use multiple endpoints if you just need invoice routing differentiation.
</details>

<details>
<summary>Can departments have departments?</summary>

No. The feature only supports two levels: parent company and departments. Departments cannot have their own departments.
</details>

<details>
<summary>Do departments go through KYC verification?</summary>

No. Departments are automatically trusted based on the parent company's verification status. They don't require separate KYC processing.
</details>

<details>
<summary>Can departments use different vendors?</summary>

Yes. While departments share the parent's BID, they can be linked to different vendors than the parent company. Vendor linking must be handled separately after department creation.
</details>

<details>
<summary>What happens if I disable the parent company?</summary>

A parent company cannot be disabled if it has active departments. All departments must be disabled first.
</details>

<details>
<summary>Are there charges for using departments?</summary>

No. Departments don't have separate pricing. Your existing pricing and contract terms apply as usual.
</details>

---

## Users
Source: https://documentation.maventa.com/integration-guide/account-management/users/

> [!WARNING]
> **User Account Deletion Policy**
>
> To maintain system security and efficiency user accounts (including API users for integrations) that meet the following conditions will be automatically deleted: Users who haven't logged in for a year and have been removed from their last company over six months ago.

## User creation

Users are created to Maventa based on an email address. Creation happens at the time of the company account opening, or separately over API or user interface. A user can be connected to many companies and a company can have many users.

Created company user can be real person or an api-user that is a technical user only. Same api-user can be added to multiple accounts, but usually for integrators with larger amount of customers it is for security reasons recommended to have own api-user per account. For example email could be formatted as `maventauser+companyBID@example_domain.com`.

Access to Maventa web user interface requires access to user email for authentication. If the new users will log in to UI make sure they have access to their email address.

## User roles and rights

You can control the user rights by changing the user role. There are two roles, *user* and *admin* user. Compared to admin, users have more limited rights to service, they cannot for example modify company details or settings or add new users to the company.

## User settings

You can configure user specific setting in Maventa, e.g. notifications which user would like to get.

## API methods for user management

* [POST/v1/users](https://swagger.maventa.com/#/users/postV1Users) to create API user (technical user)
* [POST/v1/company/users](https://swagger.maventa.com/#/company/postV1CompanyUsers) to add a new or existing user to a company (UI user)

---

## Billing
Source: https://documentation.maventa.com/integration-guide/account-management/billing/

Partner and Maventa agree about the way the end customers (users of partner's software) are invoiced for their transactions and use of Maventa services.

## Basis for billing

Billing is transaction based. All transactions are billed based on the partner vendor_api_key that is provided on the API calls or in some cases stored in the company details. Based on the vendor_api_key setting the transactions can be billed from the key owner (partner) or from the end customer directly.  

Billing is partner specific meaning that same transaction is only billed once from a partner and you can refetch invoices to same partner's other systems without additional cost. If a customer receives invoices into different partners' products, i.e. uses multiple ERPs from different partners to receive invoices at the same time, each partner will be billed separately for the invoice they have received into their system.

## Partner billing

We recommend all our Partners to fetch transaction reports using our [Billing API](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Billing%20API). Using Billing API is not tied to Maventa’s billing time and it allows billing / transaction review automatically at any time of the month.

> [!WARNING]
> Current quarter’s data is kept until the 15th of the first month of the next quarter.

API endpoint [/api/billing/v2/reports/billing_company_transactions](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Billing+API+v2#/Billing%20API%20V2/get_api_billing_v2_reports_billing_company_transactions) returns transaction counts that are assigned to the authenticated billing company (partner). The endpoint contains transactions for the current and previous month.

> [!NOTE]
> **The exact amount to be invoiced for the previous month will be checked on the 1st working day of the following month 14:00 EET (A day before Maventa’s actual invoicing).**
>
> For example March transactions are ready to be fetched 3.4.2023 14:00 EET, which is the 1st working day of April.

## Transaction report

All Maventa invoices are attached with a transaction report that contains all the transacations that are billed in the invoice.

The transaction report contains the following information of the transactions:

| Header                               | Value                                                               |
|--------------------------------------|---------------------------------------------------------------------|
| BillingCompanyID                     | unique identifier of the invoiced company in Maventa billing system |
| BillingCompanyName                   | name of the invoiced company in Maventa billing system              |
| BillingCompanyOrganizationIdentifier | business ID of the invoiced company in Maventa billing system       |
| TargetCompanyID                      | unique identifier of the company who has performed the transaction  |
| TargetCompanyName                    | name of the company who has performed the transaction               |
| TargetCompanyOrganizationIdentifier  | business ID of the company who has performed the transaction        |
| MaventaProduct                       | name of the transaction                                             |
| InvoicingProductCode                 | product information on the invoice                                  |
| DimensionItemSoftware                | name of the software used to perform the transaction                |
| NumberOfActions                      | number of transaction                                               |
| ActionOriginTime                     | first day of each invoiced month                                    |
| UnitNetPrice                         | unit price of transaction                                           |
| LineNetSum                           | total line amount                                                   |

See example transaction report: FIX_PENDING_EXAMPLE

Note that the structure of this report is based on a real life example, but the data in the report is made-up.

---

## Accounts receivable
Source: https://documentation.maventa.com/integration-guide/accounts-receivable/

Maventa offers accounts receivable services that handle payment monitoring, reminders, and debt collection on your behalf. These services are provided by collection agencies and delivered through Maventa as part of the Maventa service, with no separate usage fee. However, costs may arise in the later stages of the debt collection process or if assignments are cancelled. Each service page describes the specific cost structure in detail.

## Available services


### [Ropo's reminder and collection service](/integration-guide/accounts-receivable/ropo-debt-collection/)

Reminder and debt collection provided by Ropo. Select individual overdue invoices to transfer to Ropo for reminder handling and collection. Available in Finland, Sweden, and Norway, with more countries coming (timeline TBD).

### [Amili Kassavirta](/integration-guide/accounts-receivable/amili-kassavirta/)

Full-cycle payment monitoring and collection for Finnish companies. Once activated, all invoices are automatically routed through the service. Visma Amili handles payment monitoring, reminders, and debt collection on the sender's behalf.

### [Amili Perintä](/integration-guide/accounts-receivable/amili-perinta/)

Manual reminder and debt collection for Finnish companies. Select individual overdue invoices to hand over to Visma Amili for reminder handling and collection.


## How it works

All accounts receivable services follow the same general flow:

1. **Activate the service** — Start the activation via the API. A company representative completes a KYC (Know Your Customer) check and signs an electronic agreement with the collection agency. Activation is typically completed within 1–2 business days.

2. **Invoices enter the collection process** — Depending on the service, invoices are either routed automatically through the collection agency (Amili Kassavirta) or transferred manually when they become overdue (Ropo's reminder and collection service, Amili Perintä).

3. **Assignments are created** — Each invoice that enters the collection process generates an assignment. Assignments represent the invoice's lifecycle within the collection agency and are the central data model for tracking progress.

4. **Events track what happens** — Both the collection agency and the sender communicate through events on assignments. Events cover payments, reminders sent, credit notes, due date changes, cancellations, and more. Automating event handling from the ERP is strongly recommended.

5. **Payments are settled** — The collection agency collects payments from debtors and settles them to the sender's account.

### Automatic vs. manual collection

The key difference between the services is how invoices enter the collection process:

- **Automatic** (Amili Kassavirta) — Once activated, all invoices are automatically routed through the service. Visma Amili modifies the invoice payment details, monitors payments, and handles reminders and collection without any manual action from the sender.

- **Manual** (Ropo's reminder and collection service, Amili Perintä) — The sender selects which overdue invoices to transfer to the collection agency. This gives more control over which receivables are handed over for collection. The original invoice is sent to the receiver as usual, and the transfer happens separately after the due date has passed.

## Choosing the right service

| | Ropo's reminder and collection service | Amili Kassavirta | Amili Perintä |
|---|---|---|---|
| **Collection model** | Manual transfer | Automatic for all invoices | Manual transfer |
| **Provider** | Ropo | Visma Amili | Visma Amili |
| **B2B and B2C** | Both | Both | Both |
| **Country** | Finland, Sweden, Norway (expanding further, timeline TBD) | Finland | Finland |
| **Best for** | Companies that want to choose which invoices go to collection, or operate across multiple Nordic countries | Companies that want hands-off receivables management for all invoices | Companies that want to selectively outsource collection for specific overdue invoices |

> [!NOTE]
> Ropo's reminder and collection service and Amili Perintä both use the manual transfer model, but they use different collection agencies and API endpoints. Ropo's reminder and collection service is available in Finland, Sweden, and Norway with more countries coming (timeline TBD), while Amili Perintä is available in Finland only.

## API overview

All accounts receivable services share the same [Receivables API](/api-specification/rest-api/receivables-api/) for managing assignments and events. This means the integration for tracking collection progress is largely the same regardless of which service is used.

Service-specific operations — activation, configuration, and invoice transfers — use dedicated endpoints in the AutoXChange API:

| Operation | Ropo's reminder and collection service | Amili Kassavirta / Amili Perintä |
|---|---|---|
| Activate service | `PUT /v2/services/ropo/receivables` | `PUT /v2/services/amili/receivables` |
| Check activation status | `GET /v2/services/ropo/receivables` | `GET /v2/services/amili/receivables` |
| Transfer invoice | `POST /v2/invoices/{id}/assignment/ropo` | `POST /v1/invoices/{id}/assignment` (Amili Perintä only) |
| Close service | `DELETE /v2/services/ropo/receivables` | `DELETE /v2/services/amili/receivables` |

For detailed API documentation, see the [Receivables API](/api-specification/rest-api/receivables-api/) page and the [Swagger documentation](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Receivables+API).

### Integration recommendations

At a minimum, automate the following from the ERP:

- **`paid` events** — Report direct payments (payments received on the sender's own account) so the collection agency can update or close the assignment.
- **`credit_note` events** — Notify the collection agency when a credit note is issued against an invoiced assignment.

Relying on end users to manually report these through the UI is error-prone and can lead to unnecessary collection actions on invoices that have already been paid or credited.

---

## Ropo's reminder and collection service
Source: https://documentation.maventa.com/integration-guide/accounts-receivable/ropo-debt-collection/

With Ropo's reminder and collection service, you can transfer overdue invoices to Ropo for reminder and debt collection.

* B2B invoices can be transferred 7 days after the due date.
* B2C invoices can be transferred 14 days after the due date.

Ropo handles reminder sending and all debt collection activities. The service is available in Finland, Sweden, and Norway, with additional countries such as Denmark and Germany planned (timeline TBD).

The service supports EUR (Finland), SEK (Sweden), and NOK (Norway) currencies.

> [!WARNING]
> Only one currency can be used per account. For example, if an account uses EUR, it cannot also use SEK or NOK. If you need to use multiple currencies, please contact Maventa support.

The service is provided by Ropo and delivered through Maventa as part of the Maventa service, with no separate usage fee. Reminder and collection fees are paid by the debtor (the recipient of the reminder or collection letter), not by the client. However, costs may arise in the later stages of the debt collection process. If a case proceeds to legal collection, any official authority fees incurred are charged from the client (service user). The client must specifically authorise whether a case should progress to legal collection — Ropo does not start this automatically. In addition, if the client is VAT liable, Ropo invoices the VAT portion of reminder and collection fees paid by the debtor. Costs may also occur if assignments are cancelled.

Ropo settles capital to the company's account on a daily basis. In Finland, there are two daily settlements on weekdays. In Norway and Sweden, settlements occur once per day. Late payment interest is settled on the last Wednesday of each month. All settlement reports are accessible and downloadable via the Ropo One user interface.

Once an invoice has been successfully transferred to Ropo, Maventa automatically creates an assignment. ERPs can track these assignments using the [Receivables API](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API), display assignment information to users within the ERP, report direct payments, or cancel assignments via credit invoices.

## Opening the Ropo's reminder and collection service service

To activate the Ropo's reminder and collection service service, call [`PUT /v2/services/ropo/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/services/putV2ServicesRopoReceivables). Use [`GET /v2/services/ropo/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/services/getV2ServicesRopoReceivables) to check the activation status.

Parameters for the PUT /v2/services/ropo/receivables call

| Parameter                     | Description                                                                                                                          |
| ------------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| agreement_contact_email       | Email for a person authorised to act on behalf of the company. Used to send the request to sign the electronic agreement. Mandatory.  |

To complete the activation process, Ropo sends an email with a link to a wizard form to the address specified in `agreement_contact_email`. Through the wizard form, the recipient provides the required company details and electronically signs an agreement with Ropo.

The authorisation can be based on the individual's role within the company or on a power of attorney, which must be attached to the form if applicable. Completing the form requires strong electronic identification (such as online banking credentials, Mobile ID, or BankID depending on the country).

### Activation steps

1. **Wizard form** — The invoicing company fills in the company details required to open a Ropo One profile. The form also collects the details of the contract approver (a person with signing authority). In Finland, the form additionally asks for a separate **KYC form completer** (also with signing authority), who can be a different person from the contract approver.

2. **KYC verification (Finland only)** — After the wizard form is submitted, Ropo sends a KYC email link to the KYC form completer. The KYC form is a separate electronic form outside of Ropo One. In accordance with the Money Laundering Act, Ropo is required to identify its customers and understand their activities.

3. **User credentials** — After the wizard form is submitted, Ropo sends the Ropo One user credentials.

4. **Agreement signing** — The contract approver accepts the agreements the first time they log in to Ropo One. The service cannot be used until the agreements are signed.

5. **Service activation** — Once the agreement is signed and verified by Ropo, the service is activated, typically within 1–2 business days. After activation, invoices can be transferred to Ropo for reminders and debt collection.

> [!NOTE]
> If the activation process is not completed within one week, Ropo sends a reminder email.

## Transferring invoices to reminder and debt collection

Transfer overdue invoices to the Ropo's reminder and collection service service using the following API method:

[`POST /v2/invoices/{id}/assignment/ropo`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/postV2InvoicesIdAssignmentRopo)

Provide the invoice ID (UUID) for an overdue invoice along with the following parameters:

| Parameter          | Required                               | Description                                                                                  |
| -------------------|----------------------------------------|----------------------------------------------------------------------------------------------|
| collection_type    | Yes                                    | `reminder_and_collection` or `collection`                                                    |
| receivables_type   | Yes                                    | `b2b`, `b2c`, `b2b_rental`, or `b2c_rental` (see note on rental receivables below)           |
| amounts            | No                                     | Detailed breakdown of amounts (see below). Cannot be used in combination with `collectable_amount`. |
| payers             | Yes                                    | Array of payer objects (see below)                                                           |
| reminder_date      | When collection_type = `collection`    | Date (YYYY-MM-DD) when the reminder was sent by the sender                                   |
| assignment_summary | Yes                                    | Description of what the assignment refers to (see below)                                     |

> [!NOTE]
> Rental receivables collection (`b2b_rental` and `b2c_rental`) is currently only supported for Finnish customers. In Sweden and Norway, rental receivables require a more complex setup and are not supported at this time. If you need rental receivables collection in Sweden or Norway, please contact Maventa support.

> [!NOTE]
> Duplicate invoice numbers are not allowed. Ensure that each invoice number is unique, avoiding any reuse.

> [!NOTE]
> B2B invoices can be transferred 7 days after the due date.
> B2C invoices can be transferred 14 days after the due date.

### Collection_type

* **reminder_and_collection** — transfer the invoice to a full reminder and debt collection process
* **collection** — transfer the invoice directly to the collection process when you have already handled the reminder sending yourself. When using this type, `reminder_date` is mandatory.

### Amounts

Capital, costs, and interest must always be reported separately. They must not be combined into a single capital amount.

| Field                       | Required | Description                                                                                      |
|-----------------------------|----------|--------------------------------------------------------------------------------------------------|
| capital_amount              | Yes      | Amount of capital invoiced. Must be a positive number (e.g. 100.50).                             |
| reminder_amount             | Yes      | Amount of reminder fees invoiced. Must be a positive number (e.g. 5.00).                         |
| interest_amount             | Yes      | Amount of previous interest invoiced. Must be a positive number (e.g. 10.50).                    |
| interest_calculation_date   | No       | Date (YYYY-MM-DD) from which to start interest calculation, for cases where interest has been collected before assignment creation. |

### Payers

Each payer in the array requires the following fields:

| Field      | Required                                       | Description                                                                    |
|------------|------------------------------------------------|--------------------------------------------------------------------------------|
| type       | Yes                                            | `main_debtor` or `co_debtor`                                                   |
| name       | Yes                                            | Payer's full name                                                              |
| bid        | For `b2b` and `b2b_rental`                     | Business ID                                                                    |
| ssn        | Required for `b2c_rental`                      | Payer's social security number, used for the legal collection process          |
| address    | Yes                                            | Address object (see below)                                                     |

#### Address fields

| Field      | Required | Description       |
|------------|----------|-------------------|
| line1      | Yes      | Street address    |
| line2      | No       | Additional address line |
| post_code  | Yes      | Postal code       |
| city       | Yes      | City              |
| country    | Yes      | Country code      |

Main debtor and co-debtor details must be provided separately in the API. For consumer rental receivables (`b2c_rental`), the payer's SSN is mandatory — if SSN is missing, the assignment cannot be transferred to Ropo.

> [!WARNING]
> The debtor's full address must be provided. If any address details are missing, the invoice cannot be forwarded to Ropo.

### Assignment_summary

Provide a specific description of what the assignment refers to:

* Avoid vague descriptions like "purchase of groceries" or "goods"
* Use clear terms, e.g. "purchase of umbrellas"
* "Worked hours" is acceptable
* Row description from the invoice can be used as an alternative
* If several services are invoiced together, specify them clearly: "waste management services & water/sewage fees"

### Transfer status

Check the status of the transfer using [`GET /v2/invoices/{id}/assignment`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/getV2InvoicesIdAssignment):

* **Pending** — Waiting for the transfer
* **Sent** — Transfer successful and an assignment has been created. The response also contains a link and assignment id to the newly created assignment.
* **Error** — Transfer failed. The most common reason is missing receiver address details. Error reason is visible in `error_reason` field.

### Possible errors

If the invoice is not yet past due, the API returns a 400 error:

```json
{
  "code": "invalid_parameters",
  "message": "Request parameters are invalid",
  "details": [
    "Invoice not expired"
  ]
}
```

### Creating assignments manually

Invoices that have not been sent through Maventa can also be transferred to the Ropo's reminder and collection service service by creating an assignment manually.

To do this, create the invoice using [`POST ​/v1​/invoices`](https://swagger.maventa.com/#/invoices/postV1Invoices) with the `prevent_routing` parameter set to `true`. This marks the invoice immediately as SENT without actually delivering it to the receiver. After the invoice is created, use the Ropo's reminder and collection service APIs described above to transfer it to the reminder and/or debt collection process.

Creating assignments manually will have a debit action and it will be billed according to the existing price lists.

### Reminder and debt collection schedule

When an invoice is transferred for the reminder and collection process, Ropo sends the first reminder 10 days after the due date for B2B invoices and 14 days after the due date for B2C invoices. If the invoice is transferred directly to the collection process, a payment demand is sent first.

Letters are not sent during weekends or public holidays, which may add a few additional days to the schedule in some cases.

Reminders and collection letters use Ropo's bank account and reference details. When funds are collected, they are settled to the client using the original invoice reference.

#### Delivery method of reminders and collection letters

The delivery method depends on the country and how the original invoice was delivered.

**Finland**

- **B2B** — Reminders and collection letters are sent electronically to the same delivery address as the original invoice (e-invoice or email). If the original invoice was sent by post, or if the electronic delivery route is no longer available, the letters are sent by post.
- **B2C** — Always sent by post.

**Norway and Sweden**

- If the original invoice was sent by email, reminders and collection letters are also sent by email.
- In all other cases, they are sent by post.

You can find the detailed and most up-to-date schedule on Ropo’s website:

- [Finland](https://ropo.fi/hallitse-maksujasi/perintamenettely/)
- [Norway](https://ropo.no/handtere-dine-betalinger/innfordringsprosess/)
- Sweden — link coming soon

#### Language of the reminder and debt collection letters

The language used for reminders and debt collection letters is determined from the invoice data:

1. `POST /v1/invoices` parameter `lang`
2. Invoice format language field (e.g. Finvoice `InvoiceRecipientLanguageCode`)
3. If not defined explicitly, the language defaults based on the sender's country

## Assignments

For each invoice transferred to Ropo's reminder and collection service, Maventa creates an assignment. The assignment allows the company to follow up on the collection process and serves as a communication channel between the sender and the collection agency.

To link the sent invoice and the assignment together, the assignment contains `reference_ids` including `invoice_id` with the UUID of the original invoice.

> [!NOTE]
> If Ropo needs information or action from the sender before they can continue processing an assignment, they put the assignment on hold and contact the sender by email. This includes disputed invoices — if a debtor disputes a payment, Ropo puts the invoice on hold and forwards the complaint to the client for investigation. Once the client provides a response, Ropo resumes the process. The assignment continues once the matter is resolved.

The collection process can be stopped at any time by notifying Ropo through the Ropo One user interface.

An assignment can have one of the following statuses:

1. **Open** — The assignment is active and Ropo handles the reminder sending and debt collection process depending on the chosen collection type.
2. **Closed** — The assignment is closed. The invoice has been paid and no charges are open. Ropo has transferred the money to the company's account.

<details>
<summary>Assignment content</summary>

| Parameter            | Description                                                                                                                                                                       | Applicable to Ropo's reminder and collection service                       |
| ---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------|
| id                   | Assignment ID                                                                                                                                                                     |                                                      |
| status               | Open (unpaid) / closed (paid or cancelled) / partially_closed                                                                                                                     |  partially_closed status does not exist with Ropo    |
| collection_status    | Collection status of the assignment. Set based on events added by the agency.                                                                                                     |                                                      |
| service_level        | default (normal process) / premium / vip. Does not apply to Ropo, always default with Ropo                                                                                        |                                                      |
| debtor               | `name`: Name of the customer (receiver of the invoice) and `bid`: customer's business ID                                                                                          |                                                      |
| due_date             | Due date from the original invoice                                                                                                                                                |                                                      |
| issued_at            | Invoice date from the original invoice                                                                                                                                            |                                                      |
| number               | Invoice number from the original invoice                                                                                                                                          |                                                      |
| sum                  | Total sum of the invoice (taken from the invoice data if not given in the API when transferring the assignment)                                                                   |                                                      |
| paid                 | Amount that is paid or credited                                                                                                                                                   |                                                      |
| currency             | Currency from the original invoice                                                                                                                                                |                                                      |
| created_at           | When the assignment was created                                                                                                                                                   |                                                      |
| updated_at           | When the assignment was last updated (e.g. when the paid sum was updated)                                                                                                         |                                                      |
| partially_closed_at  | When the assignment was partially closed                                                                                                                                          |                                                      |
| closed_at            | When the assignment was closed by Ropo                                                                                                                                            |                                                      |
| reference_ids        | Contains three IDs: `agency_id` = Ropo ID, `invoice_id` = ID of the original invoice (UUID), `number` = reference number from the original invoice                                |                                                      |
</details>

<details>
<summary>JSON example of an assignment and its event</summary>

```json
[
  {
    "id": "fa9781ba-20d1-4677-a125-f04bff7bbac0",
    "status": "open",
    "collection_status": "reminder_sent",
    "service_level": "default",
    "debtor": {
      "name": "Test receiver Oy"
    },
    "due_date": "2020-04-20",
    "issued_at": "2020-04-01",
    "number": "64488",
    "sum": 12.3,
    "paid": 10,
    "currency": "EUR",
    "created_at": "2020-04-15T05:47:07Z",
    "partially_closed_at": null,
    "updated_at": "2020-04-15T21:01:18Z",
    "closed_at": null,
    "reference_ids": [
      {
        "type": "agency_id",
        "value": "078dbb88-ef8e-4115-8260-c8a542aaa87c"
      },
      {
        "type": "invoice_id",
        "value": "f6dcf18d-a1bd-4e72-bb8a-80908527b6c8"
      },
      {
        "type": "number",
        "value": "356241887794"
      }
    ],
    "events": [
      {
        "id": "c0c56722-a28b-49d1-aa87-1c4d7f3cf1af",
        "type": "paid",
        "data": {
          "sum_paid": 10,
          "booked_at": "2020-04-16",
          "archive_number": "12345"
        },
        "party_id": "938fc79f-9c00-47af-8507-cdf15838aa96",
        "seens": [
          {
            "seen_at": "2020-04-15T22:00:06Z",
            "seen_by": "938fc79f-9c00-47af-8507-cdf15838aa96"
          }
        ],
        "created_at": "2020-04-15T21:01:18Z",
        "happened_at": "2020-04-16T00:00:00Z"
      }
    ]
  }
]
```
</details>

[Receivables API](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/assignments) for assignment handling.

Collection status of the assignment

| collection_status     | Events that set the collection status                                                         |
| ----------------------|-----------------------------------------------------------------------------------------------|
| unknown               | Default value until a reminder is sent or collection activities are started                   |
| reminder_sent         | reminder_sent / second_reminder_sent                                                          |
| debt_collection       | collection_started (first payment demand is sent) / second_demand_sent / tratta               |
| legal_collection      | legal_collection_started                                                                      |
| recovery_proceedings  | application_for_enforcement                                                                   |
| debt_surveillance     | credit_loss_suggestion (note: the credit_loss event does not change the collection status)    |
| lack_of_means         | lack_of_means                                                                                 |
| payment_plan          | payment_plan                                                                                  |

## Events

Events are added to assignments once something happens on the Ropo side, such as a payment made by the debtor. The sender can also add events to communicate information to Ropo, like direct payments to the sender's own account or a request to credit the invoice.

Automating these events from the ERP is highly recommended. At minimum, automate `paid` and `credit_note` events to ensure they are always communicated to Ropo without relying on end users to remember to do this manually.

[Receivables API](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoInvoice%20Receivables%20API#/events) for event handling.

### Events added by Ropo

| Event type                   | Description                                          |
|------------------------------|------------------------------------------------------|
| reminder_sent                | Reminder has been sent to the debtor                 |
| second_reminder_sent         | Second reminder has been sent                        |
| collection_started           | First payment demand sent, debt collection begins    |
| second_demand_sent           | Second payment demand sent                           |
| tratta_sent                  | Tratta sent (B2B)                                    |
| legal_collection_started     | Legal collection started                             |
| application_for_enforcement  | Application for enforcement filed                    |
| lack_of_means                | Enforcement authority has declared the debtor insolvent |
| payment_plan                 | Payment plan agreed with the debtor                  |
| paid                         | Payment received by Ropo                             |
| close                        | Assignment closed by Ropo                            |

### Events added by the sender

| Event type   | Required fields              | Description                                              |
|--------------|------------------------------|----------------------------------------------------------|
| paid         | `sum_paid`, `booked_at`      | Direct payment received on the company's own account     |
| credit_note  | `credit_sum`, `booked_at`    | Credit the assignment to cancel it                       |
| credit_loss  |                              | Mark the assignment as a credit loss                     |

### Event details

<details>
<summary>Handling payments</summary>

`paid` – Used to report payments made by the customer and to notify direct payments.

Usage scenarios:

1. Customer payment through Ropo.
Ropo sends a paid event when the customer pays the assignment, either fully or partially.

- If the assignment is fully paid, Ropo will automatically close it (`close` event added).
- If the customer pays more than the invoice amount, the excess is refunded to the customer. Ropo does not retain overpayments for future invoices.

2. Reporting direct payments
Use this event to inform Ropo when the customer pays directly to the sender company's account. Payments may be full or partial.

- If additional details are needed, they can be provided using a comment event.
- If the assignment is fully paid, Ropo will close it (`close` event added).

> [!WARNING]
> It is very important that direct payments are reported through this event so that Ropo can update the open balance or close the assignment correctly.
> Automating this event in the ERP is strongly recommended to ensure direct payments are always reported.

The `paid` event updates the paid field in the assignment, but does not modify the sum value.

  ```json
  {
    "type": "paid",
    "data": {
      "sum_paid": 200.5,
      "booked_at": "2019-01-04",
      "archive_number": "12345"
    }
  }
  ```

**Both the company and Ropo can create this event type.**
</details>

<details>
<summary>Closing an assignment</summary>

`close` – Ropo uses this event to mark an assignment as closed. An assignment is closed when any of the following occurs:

- the customer has fully paid the assignment
- you report that it has been fully paid (direct payment)
- you report that it has been fully credited
- you request cancellation of the assignment

Once closed, no further collection activity is carried out for that assignment.

**Only Ropo can create this event type.**
</details>

<details>
<summary>Connecting a credit note to an assignment</summary>

`credit_note` – Use this event to link a credit note to an assignment. Provide the credit note number and the credit sum when sending this event. The credit sum should be entered as a positive value.

- If the credit note fully covers the assignment, Ropo will close the assignment (`close` event added).
- If only part of the assignment is credited, Ropo will continue monitoring payments and follow the debt collection process for the remaining amount.

Automating this event in your ERP is strongly recommended to ensure that a `credit_note` event is always sent when credit notes are created.

**Only the company can create this event type.**
</details>

<details>
<summary>When the first reminder is sent to the customer</summary>

`reminder_sent` – Ropo adds this event when the first payment reminder for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `reminder_sent`, the event will update it accordingly.

**Only Ropo can create this event type.**
</details>

<details>
<summary>When the second reminder is sent to the customer</summary>

`second_reminder_sent` – Ropo adds this event when the second payment reminder for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `reminder_sent`, the event will update it accordingly.

**Only Ropo can create this event type.**
</details>

<details>
<summary>When the first payment demand is sent to the customer</summary>

`collection_started` – Ropo adds this event when the first payment demand for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `debt_collection`, the event will update it accordingly.

**Only Ropo can create this event type.**
</details>

<details>
<summary>When the second payment demand is sent to the customer</summary>

`second_demand_sent` – Ropo adds this event when the second payment demand for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `debt_collection`, the event will update it accordingly.

**Only Ropo can create this event type.**
</details>

<details>
<summary>When the tratta is sent</summary>

`tratta_sent` – A tratta has been issued for an unpaid invoice. This event will update the assignment's `collection_status` to `debt_collection` if it has not already been set.

**Only Ropo can create this event type.**
</details>

<details>
<summary>Legal collection is started</summary>

`legal_collection_started` – A summons application has been submitted and the legal collection process for the assignment has begun. This event will update the assignment's `collection_status` to `legal_collection`.

Ropo does not automatically start legal collection. The client must specifically decide and authorise whether a case should progress to legal collection. When legal collection is required, Ropo requests your confirmation before proceeding.

**Only Ropo can create this event type.**
</details>

<details>
<summary>An application for enforcement is sent</summary>

`application_for_enforcement` – An application for enforcement has been submitted and the assignment has been transferred to the enforcement authority. This event will update the assignment's `collection_status` to `recovery_proceedings`.

**Only Ropo can create this event type.**
</details>

<details>
<summary>The enforcement authority has found the debtor insolvent</summary>

`lack_of_means` – The enforcement authority has declared the debtor insolvent. This event will update the assignment's `collection_status` to `lack_of_means`.

**Only Ropo can create this event type.**
</details>

<details>
<summary>A payment plan has been agreed on the invoice</summary>

`payment_plan` – A payment plan has been agreed on the invoice. This event will set the `collection_status` of an assignment to `payment_plan`.

**Only Ropo can create this event type.**
</details>

<details>
<summary>Marking an assignment as credit loss</summary>

`credit_loss` – You can mark the assignment as a credit loss for accounting purposes. Reporting a credit loss does not affect payment control or monitoring, and Ropo will continue the collection process as usual.

Once submitted, a credit loss entry cannot be reversed or modified.

Ropo provides credit loss recommendations in the Ropo One financial report when collection is no longer viable. Ropo also monitors and notifies clients of bankruptcies or corporate restructurings.

**Only the company can create this event type.**
</details>

## Closing the service

Ropo's reminder and collection service can be closed by calling [`DELETE /v2/services/ropo/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/services/deleteV2ServicesRopoReceivables). Ropo will still handle any open assignments.

> [!NOTE]
> Even after closing the service, the APIs remain available for following up on remaining open assignments and adding events as needed.

## Frequently asked questions

<details>
<summary>Show all questions</summary>

**What currencies are supported?**
Ropo supports local currencies: EUR (Finland), SEK (Sweden), and NOK (Norway). Only one currency can be used per account — if an account uses EUR, it cannot also use SEK or NOK. If you need to use multiple currencies, please contact Maventa support.

**Is rental receivables collection available in all countries?**
Rental receivables collection (`b2b_rental` and `b2c_rental`) is currently only supported for Finnish customers. In Sweden and Norway, rental receivables require a more complex setup and are not supported at this time. If you need this service in Sweden or Norway, please contact Maventa support.

**How are complaints and disputed invoices handled?**
If a debtor disputes a payment, Ropo puts the invoice on hold and forwards the complaint to the client for investigation. Once the client provides a response, Ropo resumes the process.

**Can the collection process be stopped once it has started?**
Yes. The process can be stopped at any time by notifying Ropo through the Ropo One user interface.

**Does Ropo automatically start legal collection?**
No. The client must specifically decide and authorise whether a case should progress to legal collection. Ropo always requests the client's confirmation before proceeding.

**How are credit losses and bankruptcies handled?**
Ropo provides credit loss recommendations in the Ropo One financial report when collection is no longer viable. Ropo also monitors and notifies clients of bankruptcies or corporate restructurings.

**What payment details are used on reminder letters?**
Reminders and collection letters use Ropo's bank account and reference details. When funds are collected, they are settled to the client using the original invoice reference.

**What is the settlement schedule for collected funds?**
In Finland, there are two daily settlements on weekdays. In Norway and Sweden, settlements occur once per day. Late payment interest is settled on the last Wednesday of each month.

**Who is responsible for reminder and collection fees?**
These fees are paid by the debtor (the recipient of the reminder or collection letter), not by the client.

**What happens if a debtor pays the client directly?**
If a debtor pays directly after a reminder has been sent, the client can report this direct payment through the ERP system (if the integration supports this feature) or through the Ropo One interface. It is important to always report direct payments so that Ropo can update the open balance or close the assignment correctly.

**Are settlement reports available for review?**
Yes, all settlement reports are accessible and downloadable via the Ropo One user interface.

**Is there a dedicated portal for debtors to manage payments?**
Yes. Debtors can use MyRopo (myropo.fi / myropo.se / myropo.no) around the clock to make payments, request due date changes, or contact support.

**Who should Maventa partners contact for reminder and collection questions?**
For implementation, integration, and API-related questions, contact Maventa support. All communications regarding reminder and debt collection processes and financial transactions should be made directly to Ropo. Contact details and further information are available in the Ropo One user interface.
</details>

---

## Amili Kassavirta
Source: https://documentation.maventa.com/integration-guide/accounts-receivable/amili-kassavirta/

Amili Kassavirta takes care of payment monitoring, payment allocation, sending reminders, and debt collection on your behalf. The service is available for Finnish companies. You only need to create and send invoices as usual, including handling any invoice-sending errors. The service handles everything after that.

The service is provided by Visma Amili (formerly Visma Financial Solutions Oy) and delivered through Maventa. It is included in the Maventa service with no additional fees. The only potential costs are related to the later stages of the debt collection process or if assignments are cancelled. [Service contract and price list](https://amili.fi/hubfs/Sopimusehdot/Visma-Amili-Palvelusopimus-kanava-asiakkaille-08-24.pdf).

## Amili Kassavirta flow

![Amili Kassavirta flow](/assets/pages/01-integration-guide/07-accounts-receivable/02-amili-kassavirta/Amili_kassavirta_flow.png)

### Step-by-step default process flow

1. **Activation of the service** — Once activated, all invoices are routed through Amili Kassavirta, with a few exceptions. See [what is not routed through the service](#exceptions-for-invoices-routed-through-the-service).

2. **Invoice sending from ERP** — Send invoices from the ERP to Maventa as usual. Ensure the invoice XML is valid and meets the Amili Kassavirta [invoice content requirements](#invoice-content-requirements-and-error-handling).

3. **Invoice processing by Amili Kassavirta** — Maventa passes the invoice XML to Visma Amili. During this process, Visma Amili modifies the invoice XML. For example, the IBAN, payee information, and other relevant fields are updated to reflect Visma Amili's payment details. See the [full list of modified fields](#what-information-on-the-invoice-gets-changed).

4. **Sending modified invoice to receiver** — Since the invoice XML is modified, Maventa generates a new PDF invoice image to match the updated data. The modified invoice, the regenerated PDF, and any original attachments are then sent to the receiver through the standard Maventa process. You remain responsible for any sending errors and ensuring the invoice reaches the receiver. At this stage, an Amili Kassavirta [assignment](#assignments) is created, which can be used to track the process on Visma Amili's side.

5. **Payment** — The receiver pays the invoice using Visma Amili's payment information. Visma Amili then transfers the payment to your account. When an invoice is fully or partially paid, Visma Amili creates an [event](#events) for the assignment to indicate the payment status.

6. **Reminders and debt collection** — If the receiver does not pay on time, Visma Amili handles reminder sending according to their process schedule and, if necessary, the debt collection process. All updates can be tracked via the assignment events.

> [!NOTE]
> If you use your own invoice image and payment details with the service, this process does not fully apply. Learn more about [using your own invoice image and payment details](#use-of-own-invoice-image-and-payment-details).

#### Exceptions for invoices routed through the service

1. Only invoices in EUR are accepted. Invoices in other currencies bypass the service and are sent directly to the receivers, with Visma Amili not responsible for monitoring them.
2. The service does not support the following invoice XML formats: OIOXML, WoodX, BGC, Axflow, Facturae, PX, UBL.
3. Consumer e-invoices to netbanks are not routed through the service immediately after activation. There is a 7-day delay, during which all consumer e-invoices are sent directly to the banks instead of through Amili Kassavirta. This delay allows you enough time to update consumer agreements (SI-messages) with the banks. After the delay, consumer e-invoices are routed through Amili Kassavirta like all other invoices. See more in [requirements for using Amili Kassavirta with consumer e-invoicing](#requirements-for-using-amili-kassavirta-with-consumer-e-invoicing).

#### Invoice content requirements and error handling

##### Full receiver address

Invoices must include the complete address. If any part of the address is missing, the invoice will end up in an error state with an example error:

`SEND ERROR (REASON: RECEIVABLES-SERVICE: Postal code for CITY_NAME xxxxxx not found (code #5))`.

The invoice with missing address details will not be sent to the receiver. You must correct the address, create a new invoice, and resend it.

##### Due date

The invoice due date must be in the future, with at least 3 days until it is due. If the due date has passed or is within 3 days, the invoice will end up in an error state:

`SEND ERROR (REASON: RECEIVABLES-SERVICE: The due date for the invoice is within three (3) days or has already passed (code #13))`.

The invoice with a due date in the past will not be sent. Create a new invoice with a valid due date and resend it.

##### Invoice sum

The sum of the invoice lines must match the total sum of the invoice.

##### Duplicate invoice numbers

Each invoice number must generally be unique. Exceptions:

1. If a new invoice has a different invoice date than an existing assignment (open or closed), a new assignment with the same invoice number is created.
2. If a new invoice has the same invoice date as a closed assignment with no associated payments or credit notes (manually closed or cancelled by the sender), a new assignment with the same invoice number is created.
3. If a new invoice has the same invoice date as an open assignment with no payments or credit notes, and the invoice connected to that assignment is in an error state, the existing assignment is closed, and a new assignment with the same invoice number is created.

If a duplicate invoice number is not allowed, the invoice will fail with:

`SEND ERROR (REASON: RECEIVABLES-SERVICE: An assignment for this invoice number xxxx already exists and is still open. If you want to open a new assignment for this invoice number, you must first cancel the existing one (code #6 ...))`.

You must create a new invoice with a unique number and resend it. Preventing duplicate invoice numbers in the ERP is strongly recommended to avoid these errors.

> [!NOTE]
> If an invoice ends up in any error state prefixed with `SEND ERROR (REASON: RECEIVABLES-SERVICE...)`, the invoice is not sent to the receiver at all. You must correct the invoice content and resend.

##### Handling errors after sending

Invoices are sent through the Amili Kassavirta service just before the invoice leaves Maventa. Errors can occur even days after that. You are responsible for ensuring delivery:

- Wrong e-invoice address: If the receiver no longer accepts invoices at the provided e-invoice address, you must reroute the invoice. Rerouting can be done through the user interface under invoice details or via the ERP API. Rerouting does not create a new assignment.

- XML content errors: If the error is in the invoice XML, create a new corrected invoice. Credit the original erroneous invoice in the ERP and send a `credit_note` event to notify Visma Amili to close the assignment. Automating this process in the ERP is strongly recommended. The new invoice must use a new invoice number to avoid duplicate number errors.

> [!WARNING]
> If the original invoice ends up in the error state and you do not act on it, and if the invoice remains in error state even when the invoice is due, Visma Amili closes the assignment and adds a comment about the closing reason to the assignment details.

#### What information on the invoice gets changed

- IBAN – Visma Amili replaces the payment information on the invoice with their own IBAN. This ensures the receiver pays Visma Amili, who then transfers the funds to you using the account provided in the service activation. The original invoice reference number is used for the payment.

- Reference number – Visma Amili replaces the reference number on the invoice with their own.

- Factoring clause – Visma Amili adds a factoring clause to indicate that the invoice has been assigned to them for payment handling. This informs the receiver to pay Visma Amili instead of the original sender. You can specify your own contact email and phone number for the factoring clause during the activation process.

- InvoiceFreeText – Visma Amili adds new InvoiceFreeText elements to provide a link to their customer service for the receiver:
"VERKKOPALVELU: https://www.laskuhelposti.fi/ KIRJAUTUMISTUNNUS: xxxx." Existing InvoiceFreeText elements are not overwritten; the new ones are added.

- Modified Finvoice XML elements – The following XML elements are updated:
SellerAccountDetails, EpiBfiIdentifier, EpiBeneficiaryPartyDetails, EpiReference, EpiRemittanceInfoIdentifier, VirtualBankBarcode, FactoringAgreementIdentifier, FactoringFreeText, InvoiceFreeText

- Invoice image – Maventa generates a new invoice image from the modified XML to ensure the receiver sees the correct information.

> [!NOTE]
> If you use your own invoice image and payment details with the service, some of these changes do not apply. Learn more about [using your own invoice image and payment details](#use-of-own-invoice-image-and-payment-details).

### Reminder and debt collection schedule

If the receiver does not pay the invoice on time, Visma Amili sends a reminder. For B2B invoices, Visma Amili sends the first reminder 10 days after the due date. For consumer invoices (B2C), the first reminder is sent 14 days after the due date. Reminders are always sent by regular post. Letters are not sent on weekends or public holidays, which may add a few extra days to the schedule.

The customer's language code in the original invoice (Finvoice InvoiceRecipientLanguageCode) determines the language of reminders and debt collection letters. If no language is specified, Finnish is used as the default.

![Receivables management process](/assets/pages/01-integration-guide/07-accounts-receivable/02-amili-kassavirta/receivables_reminder_collection_process_amili_en_1.png)
![Receivables management process](/assets/pages/01-integration-guide/07-accounts-receivable/02-amili-kassavirta/receivables_reminder_collection_process_amili_en_2.png)

<details>
<summary>Schedule in Finnish</summary>

![Receivables management process](/assets/pages/01-integration-guide/07-accounts-receivable/02-amili-kassavirta/receivables_reminder_collection_process_amili_fi_1.png)
![Receivables management process](/assets/pages/01-integration-guide/07-accounts-receivable/02-amili-kassavirta/receivables_reminder_collection_process_amili_fi_2.png)
</details>

> [!WARNING]
> This reminder and debt collection schedule does not apply if the customer has VIP or PREMIUM service level set.

## Activating the Amili Kassavirta service

To activate the Amili Kassavirta service, use the REST API method [`PUT /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/putV2ServicesAmiliReceivables) to start the activation process. You can track the activation status using [`GET /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/getV2ServicesAmiliReceivables).

Activation requires a company representative authorised to act on behalf of the company to complete and sign an electronic agreement with Visma Amili. Authorisation can be based on the individual's position in the company or a power of attorney, which must be attached if applicable. Personal online banking credentials or Mobile ID are needed to complete the form, as required under the Money Laundering Act.

Maventa's partner, Netvisor KYC, handles the authentication and signing process.

There are two ways to handle the KYC step from the ERP:

1. **Authorisation email** – By providing an email address in the `authorization_email` parameter, a link to the Netvisor KYC service is sent to that address. If this parameter is left empty, no email is sent.

2. **Direct link from ERP** – The [`GET /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/getV2ServicesAmiliReceivables) method returns a link in the `activation_url` parameter to the Netvisor KYC service. This link can be displayed directly in the ERP. If using this method, leave the `authorization_email` parameter blank.

> [!NOTE]
> If the KYC process is not completed within a week, a reminder email is sent to the contact person with the activation link.

### Information needed for the activation

Parameters for the [`PUT /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/putV2ServicesAmiliReceivables) call

| Parameter                     | Description                                                                                                                                                                                                                        |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| iban                          | The account (IBAN) where Visma Amili will transfer the funds collected from the invoice recipient. Only one account can be used.                                                                                                   |
| bic                           | Bank identification code e.g. DABAFIHH                                                                                                                                                                                             |
| bank                          | Name of your bank                                                                                                                                                                                                                  |
| contact_person                | Contact person name                                                                                                                                                                                                                |
| contact_email                 | Email for possible problem cases and contacting                                                                                                                                                                                    |
| contact_phone_number          | Phone number for the contact person                                                                                                                                                                                                |
| authorization_email           | Email for sending the request to sign the electronic agreement. If left blank, email is not sent                                                                                                                                   |
| accountable_party             | "vfsfi" (default) or "company". If set as "vfsfi" Visma Amili's account details are used. If "company", company's own account details are used (only allowed for certain vendors)                                                  |
| service_type                  | "full" Amili Kassavirta (default). "express" /integration-guide/accounts-receivable/amili-perinta/                                                                                                                                                              |
| customer_service_email        | This email will appear in the factoring clause that Visma Amili adds to invoices routed through the Amili Kassavirta service.                                                                                                      |
| customer_service_phone_number | This phone number will appear in the factoring clause that Visma Amili adds to invoices routed through the Amili Kassavirta service.                                                                                               |
| billing_address               | Billing address for possible service costs related to the debt collection processes in the later phase. [Price list](https://amili.fi/hubfs/Sopimusehdot/Visma-Amili-Palvelusopimus-kanava-asiakkaille-08-24.pdf)                  |
| postal_address                | Company's postal address                                                                                                                                                                                                           |

Once the agreement is signed and verified by Visma Amili, the service will be activated, usually within 1–2 business days. You can use [`GET /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/getV2ServicesAmiliReceivables) to check the activation status, or register a webhook to receive a notification from Maventa when the service is activated or rejected.

> [!NOTE]
> If you have consumer invoicing enabled, you must add the IBAN provided by Visma Amili to your sender info agreements (SI-messages). The IBAN is returned as a parameter in the `GET /v2/services/amili/receivables` response. Learn more in [requirements for using Amili Kassavirta with consumer e-invoicing](#requirements-for-using-amili-kassavirta-with-consumer-e-invoicing).

The Amili Kassavirta service can also be activated through the Maventa user interface.

#### How to change information given in the activation

If you need to update company information, please contact your support team, as this cannot currently be done through the API.

### Requirements for using Amili Kassavirta with consumer e-invoicing

If Finnish consumer invoicing is enabled for your company, you must update your consumer agreements before Amili Kassavirta can handle e-invoices to netbanks. There is a mandatory 7-day transition period after activation. During this period, all consumer e-invoices are sent directly to banks and do not pass through Amili Kassavirta. After the transition, consumer e-invoices are routed through the service like all other invoices.

#### Key requirements for B2C messaging

To use Amili Kassavirta with consumer e-invoicing, you must update your consumer sender agreements (SI messages) with the following:

1. Add Visma Amili's IBAN
Include the IBAN provided by Visma Amili as one of the accounts used for consumer e-invoices. All IBANs that may ever appear on your e-invoices must be listed in the SI-message, as banks will reject invoices containing any IBAN not included in the message. It is recommended to add the new IBAN as an additional account rather than replacing existing accounts.

2. Update the SellerInvoiceIdentifierType
This defines the identifier consumers must provide when adding the company as a sender in their netbank. Using a reference number is not recommended.

Some banks use automated routines to identify the seller based on the reference number, IBAN, and beneficiary name. When using Amili Kassavirta, the invoices contain Visma Amili's IBAN and beneficiary name. This could cause the consumer to inadvertently create an agreement with Visma Amili instead of your company when a bank suggests an e-invoicing agreement.

Reference numbers are also problematic because the number sent from the ERP differs from the one received by the consumer, as Visma Amili modifies it during processing. If your ERP uses reference numbers to link new consumer agreements, you must retrieve the reference number used by Amili Kassavirta from the assignment details (`GET /v1/assignments/{assignment_id}`, parameter `reference_ids`, type `number`) and connect it in your register.

If you are currently using SellerInvoiceIdentifierType as 01 (national reference number) or 02 (international RF reference), you should change it to 08 (other numeric identifier), 09 (other alphanumeric identifier) or 99 (other identifier) in the SI-message, for a type that banks do not validate.

#### How to make the changes

Create CHANGE-type SI messages for each bank you have an agreement with. Add the new IBAN as one of the seller accounts and update the SellerInvoiceIdentifierType to a more suitable type as described in the previous section.

### Use of own invoice image and payment details

You can choose to use your own invoice image and payment details when sending invoices through the Amili Kassavirta service. When this option is enabled, Visma Amili will not modify the payment information, and Maventa will not replace the original invoice image as it normally does in the standard process.

If you use your own payment details, all payments are made directly to your account. In this setup, the ERP must support the full Amili Kassavirta integration, including an automated process for reporting direct payments to Visma Amili via API. This is required so that Visma Amili can correctly update the assignments (mark as paid/closed). See more about handling payments under the [events](#events) section.

#### Restrictions and requirements

Because all payments (except those paid by VISMA AMILI / VISMA FINANC) must be reported as direct payments through the API, this option is only available for selected ERP vendor keys that have been verified to have a reliable, automated direct-payment reporting solution.

If you wish to enable this feature for your integration, please contact Maventa support to request verification and approval.

> [!WARNING]
> Do not report payments where the payer name starts with "VISMA AMILI" as direct payments. These are reminder/payment demand payments to your company made by Visma Amili.

#### Configuring who receives the payments

During service activation, the parameter `accountable_party` defines who receives the payments:

| Value               | Who receives the payment | Invoice/payment details                                     | Notes                                    |
| ------------------- | ------------------------ | ----------------------------------------------------------- | ---------------------------------------- |
| `vfsfi` *(default)* | Visma Amili              | Service modifies invoice details, Amili's payment details   | Default process                          |
| `company`           | Sender (your company)    | Company's original payment details & invoice image are used | Direct payments must be reported via API |

If `accountable_party` is not set, the default value `vfsfi` is applied. The parameter can also be updated later via: [`PATCH /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/patchV2ServicesAmiliReceivables) → set `accountable_party` = "company".

## Service levels for customers

If you want to limit debt collection for a specific customer, you can add them to a VIP or PREMIUM customer group. The default service level is the most efficient option for cash flow and requires no action. Adding a customer to a VIP or PREMIUM group transfers the responsibility for monitoring assignments, preventing expirations, etc., to you. In some cases, this may incur additional costs.

Grouping works based on the customer's business ID, so ensure it is correct both in your records and in the invoice XML when sending. If you later decide to return to the standard debt collection for a customer, simply remove their business ID from the group. Updating a customer group does not affect assignments that have already been closed.

Service levels can be managed via the API using [`PATCH /v1/service_levels/{customer_bid}`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Receivables+API#/service_levels/patchV1ServiceLevelsCustomerBid).

On an assignment, the parameter `service_level` reflects the group: "VIP" or "PREMIUM" if the customer is in one of those groups and "default" if not in a VIP or PREMIUM group.

A `service_level_changed` event is also logged if the service level is VIP or PREMIUM.

> [!NOTE]
> Service level updates may take a few hours to appear after an invoice is sent and the assignment is created.

### DEFAULT customers

This is the standard payment monitoring process. It is the most efficient for cash flow and requires no action.

![default process](/assets/pages/01-integration-guide/07-accounts-receivable/02-amili-kassavirta/default_pic.png)

### PREMIUM customers

- A payment reminder and demand for payment are sent for overdue invoices.
- Collection ends 30 days after the due date of the demand for payment. After this, monitoring and managing the receivable is the sender's responsibility.
- If the invoice is unpaid, a fee of 30€ + VAT applies for the sender.

![Premium process](/assets/pages/01-integration-guide/07-accounts-receivable/02-amili-kassavirta/premium_pic.png)

### VIP customers

- Only a payment reminder is sent for overdue invoices. No reminder fee is charged to the customer, but the sender is billed for a 5€ + VAT fee for each reminder.
- Collection ends 30 days after the due date of the payment reminder, and the case is closed. After this, monitoring and managing the receivable is the sender's responsibility.

![Vip process](/assets/pages/01-integration-guide/07-accounts-receivable/02-amili-kassavirta/vip_pic.png)

### No payment monitoring

- Invoices for these customers will not be sent through the Amili Kassavirta service.
- The sender's own account number will be used for payments.
- The sender is responsible for monitoring, controlling, and managing these receivables.
- No additional costs are charged for this option.

## Assignments

Every invoice sent through the Amili Kassavirta service automatically generates an assignment. An assignment represents the invoice's lifecycle within Visma Amili and is used to track its status, payment progress, and all communication between Visma Amili and you.

Each assignment contains the fields `reference_ids` and `invoice_id`, which link the assignment to the original invoice using the invoice UUID.

Assignments can have one of three statuses:

- Open – The invoice is still unpaid and Visma Amili continues monitoring and processing it.
- Partially closed – The invoice has been paid, but additional fees or charges remain for Visma Amili to collect.
- Closed – The invoice and all related charges are fully paid, and Visma Amili has transferred the funds to the company, or the assignment has been credited or closed otherwise.

[REST API](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Receivables+API#/assignments/getV1Assignments) for assignment handling.

### Assignment content

  | Parameter            | Description                                                                                                                                                                                                                                                                                                           |
  | ---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
  | id                   | Assignment id                                                                                                                                                                                                                                                                                                         |
  | status               | Open (unpaid) / closed (paid or cancelled) / partially_closed (Invoice is paid but additional fees or charges remain for Visma Amili to collect)                                                                                                                                                                      |
  | collection_status    | Collection status of the assignment. Set based on event added by the agency. Values can be "unknown" (default value until reminder is sent/collection process starts), "reminder_sent", "debt_collection", "legal_collection", "recovery_proceedings", "debt_surveillance", "lack_of_means", "payment_plan"           |
  | service_level        | default (normal process) / premium / vip                                                                                                                                                                                                                                                                              |
  | debtor               | "name": Name of customer (receiver of the invoice) and "bid": customer's bid                                                                                                                                                                                                                                          |
  | due_date             | Due date from the original invoice or new due date if due date change request is accepted                                                                                                                                                                                                                             |
  | issued_at            | Invoice date from the original invoice                                                                                                                                                                                                                                                                                |
  | number               | Invoice number from the original invoice                                                                                                                                                                                                                                                                              |
  | sum                  | Total sum of the invoice                                                                                                                                                                                                                                                                                              |
  | paid                 | Amount that is paid or credited                                                                                                                                                                                                                                                                                       |
  | currency             | Currency from the original invoice                                                                                                                                                                                                                                                                                    |
  | created_at           | When assignment was created                                                                                                                                                                                                                                                                                           |
  | updated_at           | When assignment was updated last time (e.g. when paid sum was updated)                                                                                                                                                                                                                                                |
  | partially_closed_at  | When assignment was partially closed by Visma Amili                                                                                                                                                                                                                                                                   |
  | closed_at            | When assignment was closed by Visma Amili                                                                                                                                                                                                                                                                             |
  | reference_ids        | Contains three ids: "agency_id" = collection agency id, "invoice_id" = id of the original invoice (invoice uuid), "number" = New reference number that was changed to the original invoice                                                                                                                            |

<details>
<summary>JSON example of assignment and its event</summary>

```json
[
  {
    "id": "fa9781ba-20d1-4677-a125-f04bff7bbac0",
    "status": "open",
    "collection_status": "unknown",
    "service_level": "default",
    "debtor": {
      "name": "Hanna's Test Company"
    },
    "due_date": "2020-04-20",
    "issued_at": "2020-04-01",
    "number": "64488",
    "sum": 12.3,
    "paid": 10,
    "currency": "EUR",
    "created_at": "2020-04-15T05:47:07Z",
    "partially_closed_at": null,
    "updated_at": "2020-04-15T21:01:18Z",
    "closed_at": null,
    "reference_ids": [
      {
        "type": "agency_id",
        "value": "078dbb88-ef8e-4115-8260-c8a542aaa87c"
      },
      {
        "type": "invoice_id",
        "value": "f6dcf18d-a1bd-4e72-bb8a-80908527b6c8"
      },
      {
        "type": "number",
        "value": "356241887794"
      }
    ],
    "events": [
      {
        "id": "c0c56722-a28b-49d1-aa87-1c4d7f3cf1af",
        "type": "paid",
        "data": {
          "sum_paid": 10,
          "booked_at": "2020-04-16",
          "archive_number": "12345"
        },
        "party_id": "938fc79f-9c00-47af-8507-cdf15838aa96",
        "seens": [
          {
            "seen_at": "2020-04-15T22:00:06Z",
            "seen_by": "Visma Amili FI"
          }
        ],
        "created_at": "2020-04-15T21:01:18Z",
        "happened_at": "2020-04-16T00:00:00Z"
      }
    ]
  }
]
```
</details>

### Collection status of the assignment

| collection_status     | Events that set the collection status                                                         |
| ----------------------|-----------------------------------------------------------------------------------------------|
| unknown               | Default value until reminder is sent or collection activities are started                     |
| reminder_sent         | reminder_sent / second_reminder_sent                                                          |
| debt_collection       | collection_started (first payment demand is sent) / second_demand_sent / tratta               |
| legal_collection      | legal_collection_started                                                                      |
| recovery_proceedings  | application_for_enforcement                                                                   |
| debt_surveillance     | credit_loss_suggestion (credit_loss event does not change the collection status)              |
| lack_of_means         | lack_of_means                                                                                 |
| payment_plan          | payment_plan                                                                                  |

#### Creating assignments manually (without sending the invoice to the recipient)

Assignments can also be created for the Amili Kassavirta service without delivering an invoice to the customer. This is useful in cases where the invoice itself has already been communicated to the recipient outside Maventa.

A common use case is housing companies: they often send one annual invoice covering the entire year, but still need to track and monitor monthly payments. By creating assignments manually each month, payment reminders and collection processes can be triggered automatically if payments are late.

Manual creation of assignments is done via [`POST /v1/invoices`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/postV1Invoices) using the parameter `prevent_routing` = true.
When this parameter is enabled, the invoice is marked as SENT immediately, without any delivery to the receiver, and an assignment is created in Amili Kassavirta for normal monitoring.

To use this method, you must provide a valid invoice XML including full recipient address details and a due date in the future. This functionality is restricted to approved ERPs (vendor keys). If you want to enable it, please contact the Maventa support team to validate your integration and be added to the allowed list.

> [!NOTE]
> Remember to report payments for these invoices as direct payments, as they were originally sent to the receiver with the sender's own payment details. This means the receiver will pay directly to the sender's account, not through Visma Amili.

> [!NOTE]
> Creating manual assignments results in a debit action and will be billed according to the existing price lists.

## Events

Both the sender company and Visma Amili can add events to communicate changes related to an assignment. Events describe actions that have taken place — for example, when a customer pays an invoice, Visma Amili automatically adds a `paid` event. Events can also be used to update assignment details from the sender side, such as requesting a new due date or notifying about direct payments. In practice, events serve as a communication channel between Visma Amili and the sender.

Automating event creation from your ERP is strongly recommended. At minimum, automate the `paid` and `credit_note` events to ensure they are always delivered to Visma Amili without relying on end users to manually trigger them via the UI.

[REST API](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Receivables+API#/assignments/postV1AssignmentsAssignmentIdEvents) for event handling.

### Event types and usage

<details>
<summary>Comment or question</summary>

`comment` – Add a comment or ask a question.
This event allows you to send comments or questions to Visma Amili regarding the specific assignment. Visma Amili may also use this event type to send comments or questions back to your company.

Monitoring comment events closely is strongly recommended. A good approach is to create a dedicated view that displays only comment events, clearly separating them from other event types. This ensures that you can easily see when Visma Amili has added a comment or question that may require attention or a response.

A new and improved messaging feature is now available for better two-way communication. See the [messaging functionality](#messaging-functionality) section for more details.

**Both the company and Visma Amili can create this event type.**
</details>

<details>
<summary>Handling payments</summary>

`paid` – Used to report payments made by the customer, notify direct payments, and mark credit notes as used.

Usage scenarios:

1. Customer payment through Visma Amili.
Visma Amili sends a paid event when the customer pays the assignment, either fully or partially.

- If the assignment is fully paid, Visma Amili will automatically close it (`close` event added).
- If the customer pays more than the invoice amount, the excess is refunded to the customer. Visma Amili does not retain overpayments for future invoices.
- In account statements (such as SEPA), payments processed by Visma Amili appear with `VISMA AMILI` as the payer name (length may vary depending on bank). This can help distinguish payments by Visma Amili from direct payments, which will show a different payer name.

2. Reporting direct payments
Use this event to inform Visma Amili when the customer pays directly to the sender company's account. Payments may be full or partial.

- If additional details are needed, they can be provided using a comment event.
- If the assignment is fully paid, Visma Amili will close it (`close` event added).

> [!WARNING]
> It is very important that direct payments are reported through this event so that Visma Amili can update the open balance or close the assignment correctly.
> Automating this event in the ERP is strongly recommended to ensure direct payments are always reported.

3. Marking a credit note as used
When a credit note has been issued and linked to an assignment (`credit_note` event), it must be marked as used. This is done using the paid event for the credit note, with the payment amount entered as a negative value.

- This allows Visma Amili to close the credit note (`close` event added).
- If the credit note is linked through the UI, it is automatically marked as used.

The `paid` event updates the paid field in the assignment, but does not modify the sum value.

  ```json
  {
    "type": "paid",
    "data": {
      "sum_paid": 200.5,
      "booked_at": "2019-01-04",
      "archive_number": "12345"
    }
  }
  ```

**Both the company and Visma Amili can create this event type.**
</details>

<details>
<summary>Closing an assignment</summary>

`close` – Visma Amili uses this event to mark an assignment as closed. An assignment is closed when any of the following occurs:

- the customer has fully paid the assignment
- you report that it has been fully paid (direct payment)
- you report that it has been fully credited
- you request cancellation of the assignment

Once closed, no further collection activity is carried out for that assignment.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Partially closing an assignment</summary>

`partially_closed` – Visma Amili uses this event to indicate that an assignment is only partially closed. This situation occurs when the original invoice amount has been fully paid by the customer, but reminder fees or collection charges remain unpaid.
From the sender's perspective the assignment is finished, but the customer still owes an additional amount to Visma Amili. When this event is added, the assignment status changes to partially_closed.

Once the customer pays the remaining reminder or collection charges, Visma Amili will add a `close` event and the assignment status will update to closed.

Closure cannot be reversed or modified.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Handling due date changes</summary>

Request a due date change

`due_date_change_request` – Use this event to request a change to the due date of an assignment. Visma Amili will review the request and either accept or reject it based on the proposed new due date and the current stage of the collection process.

- If the debt collection process has already started, the request will be rejected.
- If the request is accepted, the assignment will receive a confirmation via the `due_date_changed` event, and the assignment's due_date parameter will be updated accordingly.
- If rejected, a `comment` event will be sent with the reason for the rejection.

**Only the company can create this event type.**

Due date change confirmation

`due_date_changed` – Visma Amili sends this event when a due date change request has been approved. It updates the assignment's due_date parameter to reflect the new due date.

> [!NOTE]
> This does not update the original invoice.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Connecting a credit note to an assignment</summary>

`credit_note` – Use this event to link a credit note to an assignment. Provide the credit note number and the credit sum when sending this event. The credit sum should be entered as a positive value.

- If the credit note fully covers the assignment, Visma Amili will close the assignment (`close` event added).
- If the credit note was issued through Maventa, you also need to mark it as used by sending a `paid` event for the credit note assignment, with the amount entered as a negative value.
- If the credit note was issued outside Maventa, this event should still be sent to Visma Amili to update the assignment.
- If only part of the assignment is credited, Visma Amili will continue monitoring payments and follow the debt collection process for the remaining amount.

Summary when the whole assignment is credited:

- Assignment receives a `credit_note` event with the credit sum as a positive value.
- Credit note receives a `paid` event with the paid sum as a negative value.

Automating this event in your ERP is strongly recommended to ensure that a `credit_note` event is always sent when credit notes are created.

**Only the company can create this event type.**
</details>

<details>
<summary>Cancellation of the assignment</summary>

`cancel` – Use this event to cancel the entire Amili Kassavirta process for an assignment.

- Once cancelled, the assignment will be closed (`close` event added), and the closure cannot be reversed or modified.
- Visma Amili will no longer monitor the assignment or take any collection actions. You become fully responsible for tracking the assignment.
- Do not use this event to report a credit loss.

> [!NOTE]
> If reminder or collection actions have already started, Visma Amili will charge a cancellation fee.

**Only the company can create this event type.**
</details>

<details>
<summary>Temporary suspension of debt collection</summary>

Request or update suspension

`freeze` – Use this event to request a temporary suspension of the debt collection process for a specific assignment until a specified date.

- Once the suspension is set, Visma Amili will not monitor the assignment or take any collection actions. You become responsible for tracking the assignment during this period.
- Suspension requests can be made only if legal collection has not started and the enforcement authority has not declared the customer insolvent.
- The debt collection process will automatically resume after the suspension end date.
- You can update the suspension by providing a new end date, or end it early by setting the expiration date to today.

Set the parameter "frozen" to true:

```json
{
  "type": "freeze",
  "data": {
    "frozen": true,
    "end_date": "2019-01-04"
  }
}
```

**Only the company can create this event type.**

Suspension confirmation

`freeze_confirmed` – Visma Amili sends this event to confirm that a temporary suspension has been applied to an assignment.

```json
{
  "type": "freeze_confirmed",
  "data": {
    "happened_at": "2019-01-04",
    "end_date": "2019-02-15"
  }
}
```

**Only Visma Amili can create this event type.**

Termination of suspension

`unfreezed` – Visma Amili sends this event when the temporary suspension has ended and debt collection for the assignment will resume.

```json
{
  "type": "unfreezed",
  "data": {
    "happened_at": "2019-01-04"
  }
}
```

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Information for interest payments</summary>

`interest_paid` – Visma Amili uses this event to notify when interest has been paid for an assignment and to provide the interest amount. It is typically received alongside the paid event.

- Interest payments are made daily, with each payment covering all interest accrued on that day.
- In account statements, the payment will appear with the message: "Korkotilitys PVM".
- The interest in this context is defined by the sender on their invoices for late payments.

> [!NOTE]
> Interest must be specified in the invoice XML. Including it only on the invoice image is not sufficient.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Cash discount applied</summary>

`cash_discount` – Visma Amili uses this event to notify if the customer has applied a cash discount on the payment and to indicate the discount amount.

- The sum of the paid amount and the cash_discount amount equals the total assignment sum.
- This event is typically received together with the paid event.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>When the first reminder is sent to the customer</summary>

`reminder_sent` - Visma Amili adds this event when the first payment reminder for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `reminder_sent`, the event will update it accordingly.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>When the second reminder is sent to the customer</summary>

`second_reminder_sent` - Visma Amili adds this event when the second payment reminder for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `reminder_sent`, the event will update it accordingly.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>When the first payment demand is sent to the customer</summary>

`collection_started` - Visma Amili adds this event when the first payment demand for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `debt_collection`, the event will update it accordingly.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>When the second payment demand is sent to the customer</summary>

`second_demand_sent` - Visma Amili adds this event when the second payment demand for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `debt_collection`, the event will update it accordingly.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>When the tratta is sent</summary>

`tratta_sent` - A tratta has been issued for an unpaid invoice. This event will update the assignment's `collection_status` to `debt_collection` if it has not already been set.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Legal collection is started</summary>

`legal_collection_started` - A summons application has been submitted and the legal collection process for the assignment has begun. This event will update the assignment's `collection_status` to `legal_collection`.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>An application for enforcement is sent</summary>

`application_for_enforcement` - An application for enforcement has been submitted and the assignment has been transferred to the enforcement authority. This event will update the assignment's `collection_status` to `recovery_proceedings`.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>The enforcement authority has found the debtor insolvent</summary>

`lack_of_means` - The enforcement authority has declared the debtor insolvent. This event will update the assignment's `collection_status` to `lack_of_means`.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>A payment plan has been agreed on the invoice</summary>

`payment_plan` - A payment plan has been agreed on the invoice. This event will set the `collection_status` of an assignment to `payment_plan`.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>A recommendation to mark the assignment as credit loss</summary>

`credit_loss_suggestion` - A recommendation from Visma Amili to mark the assignment as credit loss. This event will set the `collection_status` of an assignment to `debt_surveillance`.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Marking an assignment as credit loss</summary>

`credit_loss` – You can mark the assignment as a credit loss for accounting purposes. Reporting a credit loss does not affect payment control or monitoring, and Visma Amili will continue the collection process as usual.

Visma Amili may recommend marking an assignment as a credit loss if it is known that the customer will not pay.

Once submitted, a credit loss entry cannot be reversed or modified.

**Only the company can create this event type.**
</details>

<details>
<summary>Service level of the customer</summary>

`service_level_changed` - Visma Amili creates this event if the customer of the invoice (receiver) is either on the VIP or PREMIUM service level group. If the service level group is changed, a new event is added. This event will set the `service_level` of an assignment to default / vip / premium based on the chosen service level group.

**Only Visma Amili can create this event type.**
</details>

### Other events

<details>
<summary>Delivery status of the original sent invoice</summary>

`delivery_status` - This event is mainly created for Visma Amili to follow up if the original invoice sending has been successful or if it has failed. This is the only way they can get the information. If the original invoice ends up in the error state and you do not act on it, and if the invoice remains in error state even when the invoice is due, Visma Amili closes the assignment and adds a comment about the closing reason to the assignment details.

As an ERP integrator, this event might not bring any additional value in your implementation if you are already following up the statuses of sent invoices through the invoice APIs and communicating the errors to the user. In this case, these events can be filtered out.

If you want to show these events for the users, there are a few things to consider when implementing them:

- There will always be at least one delivery_status "DELIVERED" when the invoice is successfully sent. But in most cases there are multiple delivery_status events with status "DELIVERED" depending on the receiving operator. Maventa creates one for each update on the invoice. It might not be necessary to show them all for the user.
- If there is delivery_status "FAILED", the original invoice related to the assignment is in error state. You need to take action, for example reroute the failed invoice using another route so that it reaches the receiver. After the original invoice is rerouted and sent successfully, a new delivery_status "DELIVERED" is added for the assignment. This is important to show.
- In the Maventa UI, only the first "DELIVERED" event is shown and all the extra ones are filtered out in case they are "DELIVERED" and there are no "FAILED" ones in between. But if the invoice ends up in the error state and delivery_status "FAILED" is added, that is shown. And then the delivery_status events after the "FAILED" ones to update the correct status for the assignment.

**Only Maventa can create this event type.**
</details>

## Messaging functionality

Messaging enables two-way communication between Visma Amili and the customer. Customers can add comments or questions related to their assignments, and Visma Amili can send important information concerning the assignments.

Including this functionality in the integration is strongly recommended to ensure a reliable communication channel and prevent important messages from being missed.

[APIs for handling messages](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Receivables+API#/message_threads).

## Reporting tool

The receivables reporting tool gives you better insight into your receivables and collections activity. Reports can be downloaded for a selected date range (up to 365 days). Two report types are currently available:

- Settlement Report: Provides a summary of all settlements made during the chosen period.
- Credit Loss Recommendation Report: Highlights potential credit losses based on historical data.

Both reports are available in PDF and Excel formats. You can choose the one that suits your needs, whether it's for quick viewing or deeper data analysis.

[APIs for reporting tool](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Receivables+API#/reports)

## Tips for integrators

<details>
<summary>Integration scope for Amili Kassavirta</summary>

|                                        | Full API integration (all done inside the ERP)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Lightweight integration                                                                                                                                                                        | No API integration                                                                                                                                                                                                                                                                                                                                                                                                                |
| -------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Activation        | Through API using [`PUT and GET /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/putV2ServicesAmiliReceivables)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Full API integration / No API                                                                                                                                                                  | Through the UI using the Maventa form                                                                                                                                                                                                                                                                                                                                                                                     |
| [Consumer invoicing](#requirements-for-using-amili-kassavirta-with-consumer-e-invoicing) | ERP creates and sends automatically the SI CHANGE messages when service gets activated. The IBAN needed is in the response of GET /v2/services/amili/receivables. ERP handles the targeting of the new RI messages in case reference number is the connecting information: The reference number Visma Amili used in the invoice can be found from the assignment details "reference_ids" and type "number"                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | Full API integration / No API                                                                                                                                                                  | User creates SI CHANGE messages and then sends them through the Maventa UI. Amili IBAN is shown in the Receivables Settings page. User needs to then also handle the targeting of new RI messages manually                                                                                                                                                                                                                         |
| [Assignment listing](#assignments) | /v1/assignments, /v1/assignments/{assignment_id} and /v1/assignments/{assignment_id}/events. Assignments could be listed as their own view or you could have the assignment information (and possibility to add events) shown under the invoice details.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Full API integration / No API                                                                                                                                                                  | User uses the assignment listing in the Maventa UI                                                                                                                                                                                                                                                                                                                                                                    |
| [Events](#events)             | /v1/assignments, /v1/assignments/{assignment_id}, /v1/assignments/{assignment_id}/events and /v1/events. Consider how much your users would like to follow up the receivables and which events they want to see or add themselves. Is it enough to see if something is happening, for example a comment added by Visma Amili or a reminder sent for a customer that hasn't paid on time? Should these events create a notification on the ERP side when arriving through the API? Adding events to an assignment should be fully integrated as part of the ERP processes. For example, if a direct payment comes in, then a paid event is automatically created from the ERP to the Receivables API. Having separate handling for comment events would also be beneficial so that important comments or questions from Visma Amili do not get lost and it is easy for the user to reply. | It is highly advisable to automate at least the events for direct payments (`paid` event) and connecting credit notes (`credit_note` event). Also the request to change a due date and then the confirmation for that (`due_date_change_request`, `due_date_changed`). | User needs to handle all the events through the Maventa UI, which might in some cases mean double work. For example, requesting a new due date might also then need them to make a change on the ERP side. Informing of direct payments and connecting credit notes are then on the hands of the sender. These are very important to remember so that Visma Amili does not start collection process even though the customer has already paid the invoice. |
</details>

### Testing the service

When testing Amili Kassavirta in the Maventa test environment, please note that activation is not automated. To complete the activation flow, you must contact the Maventa support team as Visma Amili needs to perform a manual configuration. After activation, all other functionality can be tested normally. This manual step applies only to the test environment — activation in production happens automatically.

## Closing the service

The Amili Kassavirta service can be closed by calling [`DELETE /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/deleteV2ServicesAmiliReceivables) or by closing the service through the user interface. After the service is closed, new invoices are no longer routed through Visma Amili. Visma Amili will still handle the open assignments.

> [!NOTE]
> Even after closing the service, API access may still be required to monitor remaining open assignments and perform any necessary actions.

---

## Amili Perintä
Source: https://documentation.maventa.com/integration-guide/accounts-receivable/amili-perinta/

Amili Perintä allows Finnish companies to outsource reminder handling and debt collection to Visma Amili Oy, removing the need to manage these time-consuming tasks yourself. You can select which invoices are handed over to Visma Amili, while still keeping visibility into the process. The progress of reminder and collection activities can be followed via the Maventa APIs and UI.

The service is provided by Visma Amili (formerly Visma Financial Solutions Oy) and delivered through Maventa. It is included in the Maventa service with no additional fees. The only potential costs are related to the later stages of the debt collection process or if assignments are cancelled. [Service contract and price list](https://amili.fi/hubfs/Sopimusehdot/Visma-Amili-Palvelusopimus-kanava-asiakkaille-08-24.pdf).

## Activating the Amili Perintä service

To activate the Amili Perintä service, use the REST API method [`PUT /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/putV2ServicesAmiliReceivables) to start the activation process. You can track the activation status using [`GET /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/getV2ServicesAmiliReceivables).

Activation requires a company representative authorised to act on behalf of the company to complete and sign an electronic agreement with Visma Amili. Authorisation can be based on the individual's position in the company or a power of attorney, which must be attached if applicable. Personal online banking credentials or Mobile ID are needed to complete the form, as required under the Money Laundering Act.

Maventa's partner, Netvisor KYC, handles the authentication and signing process.

There are two ways to handle the KYC step from the ERP:

1. **Authorisation email** – By providing an email address in the `authorization_email` parameter, a link to the Netvisor KYC service is sent to that address. If this parameter is left empty, no email is sent.

2. **Direct link from ERP** – The [`GET /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/getV2ServicesAmiliReceivables) method returns a link in the `activation_url` parameter to the Netvisor KYC service. This link can be displayed directly in the ERP. If using this method, leave the `authorization_email` parameter blank.

> [!NOTE]
> If the KYC process is not completed within a week, a reminder email is sent to the contact person with the activation link.

### Information needed for the activation

Parameters for the [`PUT /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/putV2ServicesAmiliReceivables) call

| Parameter                     | Description                                                                                                                                                                                                                        |
| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| iban                          | The account (IBAN) where Visma Amili will transfer the funds collected from the invoice recipient. Only one account can be used.                                                                                                   |
| bic                           | Bank identification code e.g. DABAFIHH                                                                                                                                                                                             |
| bank                          | Name of your bank                                                                                                                                                                                                                  |
| contact_person                | Contact person name                                                                                                                                                                                                                |
| contact_email                 | Email for possible problem cases and contacting                                                                                                                                                                                    |
| contact_phone_number          | Phone number for the contact person                                                                                                                                                                                                |
| authorization_email           | Email for sending the request to sign the electronic agreement. If left blank, email is not sent                                                                                                                                   |
| accountable_party             | Should be set as "vfsfi" (default) or left out. Does not apply to the Amili Perintä service.                                                                                                                                       |
| service_type                  | Must be set as "express". If left empty, the default value "full" is used, which activates the /integration-guide/accounts-receivable/amili-kassavirta/ service instead.                                                                                        |
| customer_service_email        | For reminder and debt collection letters.                                                                                                                                                                                          |
| customer_service_phone_number | For reminder and debt collection letters.                                                                                                                                                                                          |
| billing_address               | Billing address for possible service costs related to the debt collection processes in the later phase. [Price list](https://amili.fi/hubfs/Sopimusehdot/Visma-Amili-Palvelusopimus-kanava-asiakkaille-08-24.pdf)                  |
| postal_address                | Company's postal address                                                                                                                                                                                                           |

Once the agreement is signed and verified by Visma Amili, the service will be activated, usually within 1–2 business days. You can use [`GET /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/getV2ServicesAmiliReceivables) to check the activation status, or register a webhook to receive a notification from Maventa when the service is activated or rejected.

The Amili Perintä service can also be activated through the Maventa user interface.

## Transferring invoices to a reminder and collection process

A due invoice can be transferred to the Amili Perintä service via the following API methods:

Transfer invoice:
[`POST /v1/invoices/{id}/assignment`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/postV1InvoicesIdAssignment)

You need to provide the invoice id (UUID) for an overdue invoice and the preferred collection type:

- **reminder_and_collection** – Transfer the invoice to a full reminder and debt collection process.
- **collection** – Transfer the invoice directly to the collection process if you have already handled the reminder sending yourself.

Possible errors:

If the due date of the invoice is not in the past, the API returns the following error, as only invoices with a due date in the past can be transferred to the Amili Perintä service:

Error: response status is 400

```json
{
  "code": "invalid_parameters",
  "message": "Request parameters are invalid",
  "details": [
    "Invoice not expired"
  ]
}
```

See the status of the transfer:
[`GET /v1/invoices/{id}/assignment`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/getV1InvoicesIdAssignment)

- **Pending** – Waiting for the transfer.
- **Sent** – Transfer successful and an assignment is created. The response will also contain a link and assignment id to the newly created assignment.
- **Error** – Transfer failed. The most common reason is an invalid XML file or missing receiver address details. Error reason is visible in `error_reason` field.

When the invoice due date is in the past, a button to transfer the invoice to Amili Perintä appears in the UI under the sent invoice details.

<details>
<summary>Invoice content requirements</summary>

- Only invoices with currency EUR are accepted.
- Valid XML file. The service does not support the following invoice XML formats: OIOXML, WoodX, BGC, Axflow, Facturae, PX, UBL.
- Full receiver address information must be provided. If any address details are missing, the invoice will not be successfully forwarded to the Amili Perintä service.
- The sum of the invoice lines must equal the total sum of the invoice.
- Duplicate invoice numbers are not allowed in most cases. Ensure that each invoice number is unique. However, there are a few exceptions:
  - If a new invoice has a different invoice date than an existing assignment (open or closed), a new assignment with the same invoice number is created.
  - If a new invoice has the same invoice date as an existing closed assignment with no associated payments or credit notes (manually closed or cancelled by the sender), a new assignment with the same invoice number is created.
  - If a new invoice has the same invoice date as an existing open assignment with no associated payments or credit notes, and the invoice connected to that assignment is in an error state, the existing assignment is closed, and a new assignment with the same invoice number is created.
</details>

### Reminder and debt collection schedule

When an invoice is transferred to the Amili Perintä service for the reminder and debt collection process, Visma Amili sends the first reminder 10 days after the invoice due date for B2B invoices and 14 days after the due date for consumer (B2C) invoices. If the invoice is transferred directly to the collection process, the first action is the sending of a payment demand.

Reminders and payment demands are always sent via regular postal mail. Letters are not sent on weekends or public holidays, which may extend the timeline by a few days in some cases.

The customer's language code in the original invoice (Finvoice InvoiceRecipientLanguageCode) determines the language of reminders and debt collection letters. If no language is defined, Finnish is used as the default.

![Receivables management process](/assets/pages/01-integration-guide/07-accounts-receivable/03-amili-perinta/reskontravahti_express_reminder_collection_process_en.png)

<details>
<summary>Schedule in Finnish</summary>

![Receivables management process](/assets/pages/01-integration-guide/07-accounts-receivable/03-amili-perinta/reskontravahti_express_reminder_collection_process_fi.png)
</details>

## Assignments

Every invoice transferred to the Amili Perintä service automatically generates an assignment. An assignment represents the invoice's lifecycle within Visma Amili and is used to track its status, payment progress, and all communication between Visma Amili and you.

Each assignment contains the fields `reference_ids` and `invoice_id`, which link the assignment to the original invoice using the invoice UUID.

Assignments can have one of three statuses:

- Open – The invoice is still unpaid and Visma Amili continues monitoring and processing it.
- Partially closed – The invoice has been paid, but additional fees or charges remain for Visma Amili to collect.
- Closed – The invoice and all related charges are fully paid, and Visma Amili has transferred the funds to the company, or the assignment has been credited or closed otherwise.

[REST API](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Receivables+API#/assignments/getV1Assignments) for assignment handling.

### Assignment content

  | Parameter            | Description                                                                                                                                                                                                                                                                                                           |
  | ---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
  | id                   | Assignment id                                                                                                                                                                                                                                                                                                         |
  | status               | Open (unpaid) / closed (paid or cancelled) / partially_closed (Invoice is paid but additional fees or charges remain for Visma Amili to collect)                                                                                                                                                                      |
  | collection_status    | Collection status of the assignment. Set based on event added by the agency. Values can be "unknown" (default value until reminder is sent/collection process starts), "reminder_sent", "debt_collection", "legal_collection", "recovery_proceedings", "debt_surveillance", "lack_of_means", "payment_plan"           |
  | service_level        | default (normal process) / premium / vip                                                                                                                                                                                                                                                                              |
  | debtor               | "name": Name of customer (receiver of the invoice) and "bid": customer's bid                                                                                                                                                                                                                                          |
  | due_date             | Due date from the original invoice or new due date if due date change request is accepted                                                                                                                                                                                                                             |
  | issued_at            | Invoice date from the original invoice                                                                                                                                                                                                                                                                                |
  | number               | Invoice number from the original invoice                                                                                                                                                                                                                                                                              |
  | sum                  | Total sum of the invoice                                                                                                                                                                                                                                                                                              |
  | paid                 | Amount that is paid or credited                                                                                                                                                                                                                                                                                       |
  | currency             | Currency from the original invoice                                                                                                                                                                                                                                                                                    |
  | created_at           | When assignment was created                                                                                                                                                                                                                                                                                           |
  | updated_at           | When assignment was updated last time (e.g. when paid sum was updated)                                                                                                                                                                                                                                                |
  | partially_closed_at  | When assignment was partially closed by Visma Amili                                                                                                                                                                                                                                                                   |
  | closed_at            | When assignment was closed by Visma Amili                                                                                                                                                                                                                                                                             |
  | reference_ids        | Contains three ids: "agency_id" = collection agency id, "invoice_id" = id of the original invoice (invoice uuid), "number" = New reference number that was changed to the original invoice                                                                                                                            |

<details>
<summary>JSON example of assignment and its event</summary>

```json
[
  {
    "id": "fa9781ba-20d1-4677-a125-f04bff7bbac0",
    "status": "open",
    "collection_status": "reminder_sent",
    "service_level": "default",
    "debtor": {
      "name": "Test receiver Oy"
    },
    "due_date": "2020-04-20",
    "issued_at": "2020-04-01",
    "number": "64488",
    "sum": 12.3,
    "paid": 10,
    "currency": "EUR",
    "created_at": "2020-04-15T05:47:07Z",
    "partially_closed_at": null,
    "updated_at": "2020-04-15T21:01:18Z",
    "closed_at": null,
    "reference_ids": [
      {
        "type": "agency_id",
        "value": "078dbb88-ef8e-4115-8260-c8a542aaa87c"
      },
      {
        "type": "invoice_id",
        "value": "f6dcf18d-a1bd-4e72-bb8a-80908527b6c8"
      },
      {
        "type": "number",
        "value": "356241887794"
      }
    ],
    "events": [
      {
        "id": "c0c56722-a28b-49d1-aa87-1c4d7f3cf1af",
        "type": "paid",
        "data": {
          "sum_paid": 10,
          "booked_at": "2020-04-16",
          "archive_number": "12345"
        },
        "party_id": "938fc79f-9c00-47af-8507-cdf15838aa96",
        "seens": [
          {
            "seen_at": "2020-04-15T22:00:06Z",
            "seen_by": "Amili Oy FI"
          }
        ],
        "created_at": "2020-04-15T21:01:18Z",
        "happened_at": "2020-04-16T00:00:00Z"
      }
    ]
  }
]
```
</details>

### Collection status of the assignment

| collection_status     | Events that set the collection status                                                         |
| ----------------------|-----------------------------------------------------------------------------------------------|
| unknown               | Default value until reminder is sent or collection activities are started                     |
| reminder_sent         | reminder_sent / second_reminder_sent                                                          |
| debt_collection       | collection_started (first payment demand is sent) / second_demand_sent / tratta               |
| legal_collection      | legal_collection_started                                                                      |
| recovery_proceedings  | application_for_enforcement                                                                   |
| debt_surveillance     | credit_loss_suggestion (credit_loss event does not change the collection status)              |
| lack_of_means         | lack_of_means                                                                                 |
| payment_plan          | payment_plan                                                                                  |

### Creating assignments manually (without sending the invoice to the recipient)

Assignments can also be created in Maventa without delivering the invoice to the recipient, and then transferred directly to the Amili Perintä service. This is useful in situations where the invoice has already been delivered to the customer outside of Maventa.

Manual creation of assignments is done via [`POST /v1/invoices`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/invoices/postV1Invoices) using the parameter `prevent_routing` = true.
When this parameter is enabled, the invoice is marked as SENT immediately, without any delivery to the receiver.

After the invoice has been created, the Amili Perintä APIs described above can be used to transfer the invoice into the reminder and/or debt collection process.

> [!NOTE]
> Creating manual assignments results in a debit action and will be billed according to the existing price lists.

## Events

Both the sender company and Visma Amili can add events to communicate changes related to an assignment. Events describe actions that have taken place — for example, when a customer pays an invoice, Visma Amili automatically adds a `paid` event. Events can also be used to update assignment details from the sender side, such as notifying about direct payments. In practice, events serve as a communication channel between Visma Amili and the sender.

Automating event creation from your ERP is strongly recommended. At minimum, automate the `paid` and `credit_note` events to ensure they are always delivered to Visma Amili without relying on end users to manually trigger them via the UI.

[REST API](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Receivables+API#/assignments/postV1AssignmentsAssignmentIdEvents) for event handling.

### Event types and usage

<details>
<summary>Comment or question</summary>

`comment` – Add a comment or ask a question.
This event allows you to send comments or questions to Visma Amili regarding the specific assignment. Visma Amili may also use this event type to send comments or questions back to your company.

Monitoring comment events closely is strongly recommended. A good approach is to create a dedicated view that displays only comment events, clearly separating them from other event types. This ensures that you can easily see when Visma Amili has added a comment or question that may require attention or a response.

A new and improved messaging feature is now available for better two-way communication. See the [messaging functionality](#messaging-functionality) section for more details.

**Both the company and Visma Amili can create this event type.**
</details>

<details>
<summary>Handling payments</summary>

`paid` – Used to report payments made by the customer, notify direct payments, and mark credit notes as used.

Usage scenarios:

1. Customer payment through Visma Amili.
Visma Amili sends a paid event when the customer pays the assignment, either fully or partially.

- If the assignment is fully paid, Visma Amili will automatically close it (`close` event added).
- If the customer pays more than the invoice amount, the excess is refunded to the customer. Visma Amili does not retain overpayments for future invoices.
- In account statements (such as SEPA), payments processed by Visma Amili appear with `VISMA AMILI` as the payer name (length may vary depending on bank). This can help distinguish payments by Visma Amili from direct payments, which will show a different payer name.

2. Reporting direct payments
Use this event to inform Visma Amili when the customer pays directly to the sender company's account. Payments may be full or partial.

- If additional details are needed, they can be provided using a comment event.
- If the assignment is fully paid, Visma Amili will close it (`close` event added).

> [!WARNING]
> It is very important that direct payments are reported through this event so that Visma Amili can update the open balance or close the assignment correctly.
> Automating this event in the ERP is strongly recommended to ensure direct payments are always reported.

3. Marking a credit note as used
When a credit note has been issued and linked to an assignment (`credit_note` event), it must be marked as used. This is done using the paid event for the credit note, with the payment amount entered as a negative value.

- This allows Visma Amili to close the credit note (`close` event added).
- If the credit note is linked through the UI, it is automatically marked as used.

The `paid` event updates the paid field in the assignment, but does not modify the sum value.

  ```json
  {
    "type": "paid",
    "data": {
      "sum_paid": 200.5,
      "booked_at": "2019-01-04",
      "archive_number": "12345"
    }
  }
  ```

**Both the company and Visma Amili can create this event type.**
</details>

<details>
<summary>Closing an assignment</summary>

`close` – Visma Amili uses this event to mark an assignment as closed. An assignment is closed when any of the following occurs:

- the customer has fully paid the assignment
- you report that it has been fully paid (direct payment)
- you report that it has been fully credited
- you request cancellation of the assignment

Once closed, no further collection activity is carried out for that assignment.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Partially closing an assignment</summary>

`partially_closed` – Visma Amili uses this event to indicate that an assignment is only partially closed. This situation occurs when the original invoice amount has been fully paid by the customer, but reminder fees or collection charges remain unpaid.
From the sender's perspective the assignment is finished, but the customer still owes an additional amount to Visma Amili. When this event is added, the assignment status changes to partially_closed.

Once the customer pays the remaining reminder or collection charges, Visma Amili will add a `close` event and the assignment status will update to closed.

Closure cannot be reversed or modified.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Connecting a credit note to an assignment</summary>

`credit_note` – Use this event to link a credit note to an assignment. Provide the credit note number and the credit sum when sending this event. The credit sum should be entered as a positive value.

- If the credit note fully covers the assignment, Visma Amili will close the assignment (`close` event added).
- If the credit note was issued through Maventa, you also need to mark it as used by sending a `paid` event for the credit note assignment, with the amount entered as a negative value.
- If the credit note was issued outside Maventa, this event should still be sent to Visma Amili to update the assignment.
- If only part of the assignment is credited, Visma Amili will continue monitoring payments and follow the debt collection process for the remaining amount.

Summary when the whole assignment is credited:

- Assignment receives a `credit_note` event with the credit sum as a positive value.
- Credit note receives a `paid` event with the paid sum as a negative value.

Automating this event in your ERP is strongly recommended to ensure that a `credit_note` event is always sent when credit notes are created.

**Only the company can create this event type.**
</details>

<details>
<summary>Cancellation of the assignment</summary>

`cancel` – Use this event to cancel the entire Amili Perintä process for an assignment.

- Once cancelled, the assignment will be closed (`close` event added), and the closure cannot be reversed or modified.
- Visma Amili will no longer monitor the assignment or take any collection actions. You become fully responsible for tracking the assignment.
- Do not use this event to report a credit loss.

> [!WARNING]
> With Amili Perintä, reminder and/or collection actions start immediately after transferring the invoice. Visma Amili will charge a cancellation fee.

**Only the company can create this event type.**
</details>

<details>
<summary>Temporary suspension of debt collection</summary>

Request or update suspension

`freeze` – Use this event to request a temporary suspension of the debt collection process for a specific assignment until a specified date.

- Once the suspension is set, Visma Amili will not monitor the assignment or take any collection actions. You become responsible for tracking the assignment during this period.
- Suspension requests can be made only if legal collection has not started and the enforcement authority has not declared the customer insolvent.
- The debt collection process will automatically resume after the suspension end date.
- You can update the suspension by providing a new end date, or end it early by setting the expiration date to today.

Set the parameter "frozen" to true:

```json
{
  "type": "freeze",
  "data": {
    "frozen": true,
    "end_date": "2019-01-04"
  }
}
```

**Only the company can create this event type.**

Suspension confirmation

`freeze_confirmed` – Visma Amili sends this event to confirm that a temporary suspension has been applied to an assignment.

```json
{
  "type": "freeze_confirmed",
  "data": {
    "happened_at": "2019-01-04",
    "end_date": "2019-02-15"
  }
}
```

**Only Visma Amili can create this event type.**

Termination of suspension

`unfreezed` – Visma Amili sends this event when the temporary suspension has ended and debt collection for the assignment will resume.

```json
{
  "type": "unfreezed",
  "data": {
    "happened_at": "2019-01-04"
  }
}
```

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Information for interest payments</summary>

`interest_paid` – Visma Amili uses this event to notify when interest has been paid for an assignment and to provide the interest amount. It is typically received alongside the paid event.

- Interest payments are made daily, with each payment covering all interest accrued on that day.
- In account statements, the payment will appear with the message: "Korkotilitys PVM".
- The interest in this context is defined by the sender on their invoices for late payments.

> [!NOTE]
> Interest must be specified in the invoice XML. Including it only on the invoice image is not sufficient.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Cash discount applied</summary>

`cash_discount` – Visma Amili uses this event to notify if the customer has applied a cash discount on the payment and to indicate the discount amount.

- The sum of the paid amount and the cash_discount amount equals the total assignment sum.
- This event is typically received together with the paid event.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>When the first reminder is sent to the customer</summary>

`reminder_sent` - Visma Amili adds this event when the first payment reminder for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `reminder_sent`, the event will update it accordingly.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>When the second reminder is sent to the customer</summary>

`second_reminder_sent` - Visma Amili adds this event when the second payment reminder for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `reminder_sent`, the event will update it accordingly.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>When the first payment demand is sent to the customer</summary>

`collection_started` - Visma Amili adds this event when the first payment demand for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `debt_collection`, the event will update it accordingly.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>When the second payment demand is sent to the customer</summary>

`second_demand_sent` - Visma Amili adds this event when the second payment demand for an unpaid invoice has been sent. If the assignment's `collection_status` is not already set to `debt_collection`, the event will update it accordingly.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>When the tratta is sent</summary>

`tratta_sent` - A tratta has been issued for an unpaid invoice. This event will update the assignment's `collection_status` to `debt_collection` if it has not already been set.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Legal collection is started</summary>

`legal_collection_started` - A summons application has been submitted and the legal collection process for the assignment has begun. This event will update the assignment's `collection_status` to `legal_collection`.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>An application for enforcement is sent</summary>

`application_for_enforcement` - An application for enforcement has been submitted and the assignment has been transferred to the enforcement authority. This event will update the assignment's `collection_status` to `recovery_proceedings`.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>The enforcement authority has found the debtor insolvent</summary>

`lack_of_means` - The enforcement authority has declared the debtor insolvent. This event will update the assignment's `collection_status` to `lack_of_means`.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>A payment plan has been agreed on the invoice</summary>

`payment_plan` - A payment plan has been agreed on the invoice. This event will set the `collection_status` of an assignment to `payment_plan`.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>A recommendation to mark the assignment as credit loss</summary>

`credit_loss_suggestion` - A recommendation from Visma Amili to mark the assignment as credit loss. This event will set the `collection_status` of an assignment to `debt_surveillance`.

**Only Visma Amili can create this event type.**
</details>

<details>
<summary>Marking an assignment as credit loss</summary>

`credit_loss` – You can mark the assignment as a credit loss for accounting purposes. Reporting a credit loss does not affect payment control or monitoring, and Visma Amili will continue the collection process as usual.

Visma Amili may recommend marking an assignment as a credit loss if it is known that the customer will not pay.

Once submitted, a credit loss entry cannot be reversed or modified.

**Only the company can create this event type.**
</details>

### Other events (not applicable for Amili Perintä)

<details>
<summary>Events used with Amili Kassavirta</summary>

The following events exist but are not applicable when using the Amili Perintä service. They are useful when /integration-guide/accounts-receivable/amili-kassavirta/ is in use:

`delivery_status` – Tracks the delivery status of the original sent invoice.

`service_level_changed` – Visma Amili creates this event if the customer of the invoice (receiver) is in the VIP or PREMIUM service level group. If the service level group is changed, a new event is added. This event sets the `service_level` of an assignment to default / vip / premium based on the chosen service level group. Service levels work with Amili Perintä, but there is generally no need to use them.

`due_date_changed` – Visma Amili sends this event when a due date change request has been approved. It updates the assignment's due date.

> [!NOTE]
> This does not update the original invoice.

`due_date_change_request` – Use this event to request a due date change for an assignment. Visma Amili will either accept or reject the request depending on the new due date and the current stage of the collection process. If the debt collection process has already started, the request will be rejected. When accepted, a `due_date_changed` event is added as confirmation and the assignment's `due_date` parameter is updated accordingly.
</details>

## Messaging functionality

Messaging enables two-way communication between Visma Amili and the customer. Customers can add comments or questions related to their assignments, and Visma Amili can send important information concerning the assignments.

Including this functionality in the integration is strongly recommended to ensure a reliable communication channel and prevent important messages from being missed.

[APIs for handling messages](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Receivables+API#/message_threads).

## Reporting tool

The receivables reporting tool gives you better insight into your receivables and collections activity. Reports can be downloaded for a selected date range (up to 365 days). Two report types are currently available:

- Settlement Report: Provides a summary of all settlements made during the chosen period.
- Credit Loss Recommendation Report: Highlights potential credit losses based on historical data.

Both reports are available in PDF and Excel formats. You can choose the one that suits your needs, whether it's for quick viewing or deeper data analysis.

[APIs for reporting tool](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoInvoice+Receivables+API#/reports)

### Testing the service

When testing Amili Perintä in the Maventa test environment, please note that activation is not automated. To complete the activation flow, you must contact the Maventa support team as Visma Amili needs to perform a manual configuration. After activation, all other functionality can be tested normally. This manual step applies only to the test environment — activation in production happens automatically.

## Closing the service

The Amili Perintä service can be closed by calling [`DELETE /v2/services/amili/receivables`](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/deleteV2ServicesAmiliReceivables) or by closing the service through the user interface. After the service is closed, new invoices can no longer be transferred to Visma Amili. Visma Amili will still handle the open assignments.

> [!NOTE]
> Even after closing the service, API access may still be required to monitor remaining open assignments and perform any necessary actions.

---


# Services & Reach

## Maventa services and reach
Source: https://documentation.maventa.com/services-and-reach/overview/

Maventa supports e-invoicing and digital document exchange in Nordics and multiple European countries, covering both domestic and cross-border use cases. Our goal is to make it easy to build one integration that works across markets, without having to deal with country-specific complexity in your own systems or at least keeping it in minimum.

E-invoicing works a bit differently in every country. Local regulations, supported networks, document formats, and delivery methods can all vary. In the section you will find country-specific information such as which networks are supported (for example Peppol and local networks), what invoicing scenarios are available (B2B, B2G, B2C), and any special requirements that may affect how you integrate or onboard customers.

Our reach is continuously expanding, especially as the EU's **ViDA** (VAT in the Digital Age — an EU initiative to modernize VAT reporting through mandatory e-invoicing and real-time digital reporting across member states) initiative and national e-invoicing mandates move forward. As new requirements come into force and more countries adopt e-invoicing, our aim is to extend our services accordingly so you can grow into new markets as well.

Use the map below to see where Maventa currently operates. Each country section gives a quick overview of the most important details, with links to more in-depth documentation.

## Maventa on the map

<reach-map
  svg-path="/assets/img/europe-cropped.svg"
  rest-link="#"
  countries="null"
></reach-map>


## Cross-border invoicing

While each country has its own local networks and routing rules for domestic invoicing, cross-border delivery between countries always goes through the **Peppol network**. Local networks — such as the Finnish operator and bank networks, the Swedish operator network (**NEA** (Nätverket för Elektroniska Affärstransaktioner — the Swedish network for electronic business transactions)), or the Danish **NemHandel** (Denmark's national e-business infrastructure for exchanging electronic documents between businesses and public authorities) — are domestic only and cannot carry invoices across borders.

Maventa's internal network is always tried first in the routing order. If both sender and receiver are Maventa customers, the invoice is delivered internally regardless of country. If the recipient is not a Maventa customer, Peppol is the next electronic channel for cross-border delivery. Providing the operator code `PEPPOL` in the sending metadata forces delivery through Peppol and skips the internal network. If neither internal nor Peppol delivery is possible, email and print are available as fallback options.

When a company is registered as a Peppol receiver through Maventa, Peppol BIS Billing 3.0 is always registered as a supported document type — along with any applicable national Peppol document profiles. Peppol BIS 3.0 is the standard format for cross-border invoicing. Some national formats, such as XRechnung (Germany) and SI-UBL (Netherlands), are restricted to domestic Peppol traffic only.

> [!NOTE]
> When sending cross-border, always provide the recipient's full Peppol endpoint ID including the scheme prefix — for example `0007:5511111111` for a Swedish recipient or `9930:DE123456789` for a German recipient. For Finnish senders in particular, a plain Business ID only triggers domestic operator and bank network lookups — Peppol is not attempted without the full endpoint ID.

| Country | Peppol scheme | Based on | Example endpoint ID | Domestic-only networks |
|---------|---------------|----------|---------------------|------------------------|
| Finland | `0216` | OVT code | `0216:003712345678` | Operator network, bank network |
| Sweden | `0007` | Organisation number | `0007:5511111111` | Operator network (NEA), InExchange |
| Norway | `0192` | Organisation number | `0192:987654321` | — |
| Denmark | `0184` | CVR number | `0184:31000000` | NemHandel (Sproom) |
| Germany | `9930` | VAT number | `9930:DE123456789` | — |
| Netherlands | `0106` | KVK number | `0106:12345678` | — |
| Belgium | `0208` | CBE/KBO number | `0208:0471000000` | — |
| Estonia | `9931` | VAT number | `9931:EE123456789` | — |
| Latvia | `9939` | VAT number | `9939:LV12345678901` | — |
| Poland | `9945` | VAT/NIP number | `9945:PL1234567890` | **KSeF** (Krajowy System e-Faktur — Poland's national e-invoicing system for issuing, receiving, and storing structured electronic invoices) (clearance) |
| Italy | `9906` | VAT number | `9906:IT12345678901` | **SDI** (Sistema di Interscambio — Italy's national clearance platform that validates and routes all electronic invoices between businesses and the tax authority) (clearance) |

---

## e-invoicing in Finland
Source: https://documentation.maventa.com/services-and-reach/finland/

Finland is one of the most mature e-invoicing markets in Europe, with widespread adoption across both the public and private sectors. E-invoicing is mandatory for suppliers to the Finnish public sector (EU Directive 2014/55/EU), and B2B e-invoicing is broadly adopted through the Finnish operator and bank networks. The upcoming EU ViDA (VAT in the Digital Age) regulation is expected to further shape the regulatory landscape.

Maventa supports the full range of Finnish e-invoicing needs — from B2B and B2G invoice delivery through operator and bank networks, to consumer invoicing via netbanks and digital mailboxes, to receivables management and fraud detection. Maventa is a member of the [Verkkolaskufoorumi](https://tieke.fi/palvelut/verkkolaskufoorumi/), a collaborative forum of e-invoice operators, banks, and software vendors that develops Finnish e-invoicing infrastructure and standards. The forum is coordinated by TIEKE and has been advancing digital financial management in Finland since 2002.

## Finnish company account

When registering a new Finnish company via the API, the company’s VAT number or organisation number (y-tunnus) must be used as the identifier. Visma Sign supports Finnish customer authentication using HETU, Finnish banks, or mobile identifier.

| Identifier | Description | Format | Validation |
|------------|-------------|--------|------------|
| Y-tunnus | Finnish Business ID (organisation number) | `1234567-8` | Structural validation with check digit |
| VAT number | Finnish VAT identifier | `FI12345678` | Structural validation via VIES |

## Sending in Finland

### Delivery channels and routing order

For B2B and B2G invoices, Maventa attempts delivery in the following priority order:

1. **Maventa’s internal network** — direct delivery between Maventa customers
2. **Finnish operator network** — delivery via operators in the Verkkolaskufoorumi network
3. **Finnish bank network** — delivery via Finvoice through banks (the bank network connection is activated automatically when the company account is created and authorized)
4. **Peppol network** — delivery to Peppol-registered recipients (requires the full Peppol endpoint ID, see below)
5. **[Email](/integration-guide/invoice-sending/email-invoicing/)** — PDF invoice with a virtual barcode in the email body
6. **[Print](/integration-guide/invoice-sending/printing/fi/)** — physical delivery via Maventa’s Finnish print service, with automatic OmaPosti redirect when available

### Bank network attachment limitation (B2B)

When invoices are delivered through the Finnish bank network, the invoice image and attachments cannot be transmitted directly as separate files. Instead, Maventa automatically adds a link to the invoice display service in the XML file, where recipients can view the image and download attachments.

For B2B invoices, this is a non-secure (public) link. How the link is displayed to the recipient depends on the bank — there may be differences in how each bank presents the link in its online banking interface. For B2C consumer invoices, the link is secure. See the [consumer invoicing (Finland)](/integration-guide/invoice-sending/consumer-invoicing/fi/) guide for more details.

### Recipient identifiers and address resolution

Finnish invoices can be routed using different identifiers depending on the delivery channel. Maventa does not automatically add a Peppol scheme prefix to a plain Finnish Business ID — if only the BID is provided, the invoice is delivered through the operator or bank network.

| Identifier type | Format | Example | Delivery channel |
|-----------------|--------|---------|------------------|
| OVT code + operator code | `0037` + BID (no hyphen) | `003712345678` + `003721291126` | Operator and bank networks |
| Peppol endpoint ID | `0216:` + OVT code | `0216:003712345678` | Peppol network |
| Plain Business ID | Y-tunnus | `1234567-8` | Operator and bank networks (Peppol is not attempted) |

To route an invoice via Peppol, the full endpoint ID with scheme `0216` must be included in the invoice XML. For operator and bank network delivery, the OVT code and operator code are sufficient.

> [!NOTE]
> For details on how OVT codes are constructed and which operator codes to use, see the [OVT codes](#ovt-codes) section under Receiving.

To find a Finnish company's e-invoice address before sending, use the [Verkkolaskuosoitteisto](https://verkkolaskuosoite.fi/client/) — the national e-invoice address directory maintained by Finnish e-invoice operators and banks. The directory is free to search and lets you verify whether a company can receive e-invoices, and through which operator or bank.

### Consumer invoicing (B2C)

For consumer invoices, Maventa supports e-invoicing to Finnish netbanks, [Kivra](https://www.kivra.fi/) digital mailbox, and [OmaPosti](https://www.posti.fi/fi/omaposti) digital postal service. Email and print are available as fallback options.

Consumer e-invoicing in Finland uses a bank messaging protocol with SI-messages (Sender Info), RI-messages (Receiver Info), and RP-messages (Receiver Proposal) to manage e-invoice agreements between the sender and the consumer’s bank. Eight major Finnish banks support this protocol.

For full details on the bank messaging protocol, supported banks, Kivra and OmaPosti integration, and B2C-specific requirements, see the [consumer invoicing (Finland)](/integration-guide/invoice-sending/consumer-invoicing/fi/) guide.

## Receiving in Finland

Companies can receive invoices through several channels once e-invoice receiving is activated. Incoming invoices arrive via Maventa’s internal network, the Finnish operator network, and the Finnish bank network. If the company is also registered with Peppol, Peppol receiving is available as well. Companies can also receive scanned invoices via Scan Network, with AutoScan expected to become available in spring 2026.

### Receiving addresses for Finnish companies

| Address type | Description | Example | Activation |
|--------------|-------------|---------|------------|
| OVT code | Finnish e-invoicing address for operator and bank networks | `003712345678` | Created automatically when e-invoice receiving is activated |
| Peppol address | Identifier for the Peppol network, using scheme `0216` (OVT) | `0216:003712345678` | Created when the company registers to receive from Peppol |

### OVT codes

The OVT code is the unique part of a company’s e-invoicing address that ensures invoices are delivered to the correct recipient when sending through the Finnish operator or bank network.

An OVT identifier is created by combining the Finnish Tax Administration’s prefix `0037` with the company’s Business ID (Y-tunnus) — written without the hyphen (8 digits) — and, if necessary, an optional suffix of up to 5 characters (called osastolaajennos). In total, the OVT code length is typically 12–17 characters.

The second part of the e-invoicing address is the operator code, which defines through which service provider (operator) the invoice is transmitted.

| Network | Operator code | When to use |
|---------|---------------|-------------|
| Finnish operator network | `003721291126` | Default Maventa operator code |
| Finnish bank network (Danske Bank) | `DABAFIHH` | Recommended when sender uses the bank network, since Maventa’s main bank connection is with Danske Bank |
| Finnish bank network (OP or Nordea) | `003721291126` | Maventa’s own operator code can also be used when the sender connects through OP or Nordea |

You can search for companies’ OVT identifiers and operator codes in the [Verkkolaskuosoitteisto](https://verkkolaskuosoite.fi/client/), the national e-invoice address directory. The directory is maintained collectively by Finnish e-invoice operators and banks, and is free to search. Companies can also register and update their own e-invoice address information in the directory at no charge.

### Peppol registration

The Peppol identifier for Finnish companies uses scheme `0216`, which corresponds to the OVT identifier. The Peppol address is formed as `0216:` followed by the OVT code (for example `0216:003712345678`). When a company registers as a Peppol receiver through Maventa, the company becomes visible in the [Peppol Directory](https://directory.peppol.eu/public).

For more details on Peppol registration and capabilities, see the [Peppol network](/integration-guide/peppol/peppol-network/) documentation.

### Scanning

Scan Network is available as a [scanning](/integration-guide/invoice-receiving/scanning/) solution in Finland. AutoScan is expected to become available in H1 2026.

For Scan Network, invoices can be sent to the company’s scan email address in the format `invoice-BID@kollektor.fi`, where BID is the company’s Business ID without the hyphen (for example `invoice-12345678@kollektor.fi`). Paper invoices can also be sent by post to: Company name, Scan ID, PL 100, 80020 Kollektor.

### Fraud detection

Maventa’s [Detect](/integration-guide/invoice-receiving/detect/) service is available in Finland. When activated, Detect automatically checks all incoming invoices for potential fraud, including VAT register verification, Business ID validation against [YTJ](https://www.ytj.fi), warning list cross-referencing, and bank account change detection.

> [!NOTE]
> For step-by-step instructions on enabling receiving, registering for Peppol, and setting up scanning or fraud detection, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## Accounts receivable services

Maventa offers several accounts receivable and debt collection services in Finland, all delivered as part of the Maventa service with no separate usage fee. For full details on each service, including activation, API integration, assignments, and events, see the [Accounts receivable](/integration-guide/accounts-receivable/) section in the Integration Guide.

Available services for Finnish companies:

- **[Ropo's reminder and collection service](/integration-guide/accounts-receivable/ropo-debt-collection/)** — Reminder and debt collection provided by Ropo. Also expanding to other Nordic countries.
- **[Amili Kassavirta](/integration-guide/accounts-receivable/amili-kassavirta/)** — Full-cycle payment monitoring and collection by Visma Amili. All invoices are automatically routed through the service once activated.
- **[Amili Perintä](/integration-guide/accounts-receivable/amili-perinta/)** — Manual reminder and debt collection by Visma Amili. Select individual overdue invoices to hand over for collection.

## Peppol SMP registration

When a Finnish company registers to receive invoices via Peppol through Maventa, the following document types are registered in the SMP (Service Metadata Publisher). These registrations determine which document formats the company can receive over the Peppol network.

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

## Additional services

### Mass printing service

The [Mass Printing Service](/services-and-reach/finland/mass-printing-service/) (Payslip) allows sending PDF files as physical letters through the Finnish printing service. While originally designed for distributing payslips, it can be used for any type of letter. This service is separate from invoice print delivery and is available only for Finnish companies.

### Email invoicing

When invoices are delivered via [email](/integration-guide/invoice-sending/email-invoicing/) for Finnish recipients, a virtual barcode is included in the email body. The email language defaults to Finnish when using Finvoice format, and both Finnish (`FI`) and Swedish (`SV`) are supported.

## Local e-invoicing formats

Finland supports several invoice formats. For integrations that require consumer invoicing (B2C), use Finvoice 3.0 or TEAPPSXML 3.0 as they support the bank messaging protocol required for Finnish consumer e-invoicing. For more details, see the [invoicing formats](/integration-guide/invoicing-formats/invoicing-formats/) guide.

| Format | Standard | B2C support | Notes |
|--------|----------|-------------|-------|
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | No | Recommended for cross-border and Peppol delivery |
| [Finvoice 3.0](/integration-guide/invoicing-formats/finvoice/) | EN16931 | Yes | Finnish national format, required for bank network B2C |
| [TEAPPSXML 3.0](https://bix.tieto.com/#/teappsxml) | EN16931 | Yes | Alternative Finnish format with B2C support |

A [Finvoice 3.0 & TEAPPSXML 3.0 mapping document](https://bix.tieto.com/infoFiles/Finvoice3.0_TEAPPSXML3.0_correlation_20210607.pdf) is available for reference when converting between the two formats.

### Invoice image and attachments

If no invoice image (PDF) is included with the invoice, Maventa automatically generates one from the XML data. Maventa uses two different templates depending on the sender's country. The Finnish market template is used when the sender is a Finnish company, while the other markets template is used when the sender is from another country.
> [!NOTE]
> The Finnish market template includes a payment reference barcode on the last page. The example PDFs below do not include the barcode, but it will appear once valid payment data (IBAN and reference number) is provided in the invoice XML.

For Finvoice and TEAPPSXML formats, attachments are included in a ZIP package alongside the XML file. The XML and the invoice image PDF must share the same filename (for example `12345.xml` and `12345.pdf`). Other attachments do not need to match the XML filename. For TEAPPSXML, attachments must also be referenced inside the XML file. For more details on attachment handling, see the [invoice sending](/integration-guide/invoice-sending/invoice-sending/) guide.

[Example of auto-generated invoice image (Finland)](/assets/pages/02-services-and-reach/01-finland/01-finland/example_for_country_fi_in_language_en.approved.pdf)

### Finvoice 3.0

Examples of auto-generated invoice images for Finvoice 3.0:

- [Finvoice Finnish market template](/assets/pages/02-services-and-reach/01-finland/01-finland/pdf_example_modern_finvoice.pdf)
- [Finvoice other markets template](/assets/pages/02-services-and-reach/01-finland/01-finland/pdf_example_alpha_finvoice.pdf)

For details on Finvoice-specific features such as discount and charge handling, credit notes, and recipient resolution, see the [Finvoice 3.0](/integration-guide/invoicing-formats/finvoice/) format guide.

Finvoice supports a `<SpecificationDetails>` element that allows free-form specification text on the invoice. This element is rendered in a monospace font (Courier) to preserve column alignment and formatted text exactly as provided in the XML.

```xml
<SpecificationDetails>
  <SpecificationFreeText>LASKUN VAPAAMUOTOISET ERITTELYTIEDOT:</SpecificationFreeText>
  <SpecificationFreeText>Sarake-1              Sarake-2                                                             Sarake-3</SpecificationFreeText>
  <SpecificationFreeText>---------------------------------------------------------------------------------------------------</SpecificationFreeText>
  <SpecificationFreeText>1.sarakkeen tieto     2.sarakkeen tieto                                                       10,00</SpecificationFreeText>
  <SpecificationFreeText>Toinen rivi           Toinen rivi                                                          1 000,00</SpecificationFreeText>
  <SpecificationFreeText>Kolmas rivi           3/2                                                                      1,00</SpecificationFreeText>
</SpecificationDetails>
```

### TEAPPSXML 3.0

Examples of auto-generated invoice images for TEAPPSXML 3.0:

- [TEAPPSXML Finnish market template](/assets/pages/02-services-and-reach/01-finland/01-finland/pdf_example_modern_teapps.pdf)
- [TEAPPSXML other markets template](/assets/pages/02-services-and-reach/01-finland/01-finland/pdf_example_alpha_teapps.pdf)

---

## Mass Printing Service
Source: https://documentation.maventa.com/services-and-reach/finland/mass-printing-service/

The Maventa Mass Printing Service, also referred to as Payslip, allows sending PDF files as physical letters through the Finnish printing service. While originally designed for distributing payslips, it can be used for sending any type of letters, provided the printing service rules are followed. This service is available only for Finnish companies.

> [!TIP]
> **Kivra delivery is available.** Letters can be delivered to recipients' Kivra digital mailboxes instead of being printed. [Read more below](#kivra-delivery).

> [!WARNING]
> Invoices intended for print should always be sent via the standard invoice delivery channels, not through this service.

## User account opening

To use the Mass printing API, you need a dedicated user account. Create one by calling the registration endpoint with your existing `sw_api_key` and `company_uuid` from Maventa:

- Production: https://payslip.maventa.com/register
- Staging: https://payslip-stage.maventa.com/register

### Request for registering

| Key                        | Example                              | Description                                                                                                                                                               |
|----------------------------|--------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| sw_api_key                 | d33e92be-a46b-4963-8ada-25452712e0a6 | Existing software API key from Maventa                                                                                                                                    |
| company_uuid               | 99445728-5fd3-428a-96e1-ca0cab692276 | Existing company uuid from Maventa                                                                                                                                        |
| company_name               | Test Company Oy                      | Name of the company                                                                                                                                                       |
| user_email                 | [test@yritys.fi](/assets/pages/02-services-and-reach/01-finland/04-mass-printing-service/test@yritys.fi)     | User email address that will be used as user name, needs to be unique! Each account needs it's own email address                                                          |
| user_pw                    | secret1234                           | Password for the user                                                                                                                                                     |
| disable_notify_on_complete | 1                                    | Set to `0` (default) to receive an email notification when material is printed successfully. Set to `1` to disable notifications.                                         |

### Response for registering

The response code will always be a HTTP 200 and the response body is one of the following:

| Value                                    | Description                                                       |
|------------------------------------------|-------------------------------------------------------------------|
| "OK"                                     | Successful registration, letters can be send and login works      |
| "ERROR: COMPANY UUID ALREADY REGISTERED" | Registration failed, company exists already in Payslip service    |
| "ERROR: USER EMAIL ALREADY REGISTERED"   | Registration failed, user email exists already in Payslip service |
| "ERROR: ONLY FINNISH COMPANIES ALLOWED"  | Only Finnish companies allowed to register                        |
| "ERROR: USER EMAIL INVALID"              | Invalid email address                                             |
| "ERROR: INVALID VENDOR KEY"              | Invalid software API key                                          |
| "ERROR: INVALID COMPANY UUID"            | Invalid company uuid                                              |
| "ERROR: INVALID VALUES"                  | Company_name, user_email or user_pw empty                         |
| "ERROR: REGISTRATION FAILED"             | Most likely company name already exists in Payslip service.       |

## Sending letters

To send a letter to Mass printing service there are currently two supported methods:

1. New JSON-based API (recommended) - [https://payslip.maventa.com/input_json](https://payslip.maventa.com/input_json)
2. Legacy IPOSTXML-based method (deprecated - will be removed in future) - [https://payslip.maventa.com/input_public](https://payslip.maventa.com/input_public)

### JSON API (recommended)

The `POST /input_json` endpoint allows authenticated users to send PDF files for print delivery services. This endpoint accepts multipart form data containing a PDF file and associated metadata for both recipient and sender information.

#### Authentication for JSON API

The endpoint supports multiple authentication methods for backwards compatibility:

Method 1: Bearer token authentication (recommended). Note! This is not using the common OAuth that our other services, it is the static user API key

Header Required:

- Authorization: Bearer {user_api_key}
- X-Client-Id: company_uuid

Method 2: Legacy API key authentication (deprecated)

Headers Required:

- USER_API_KEY: user_api_key
- COMPANY_UUID: company_uuid

Method 3: Legacy username/password authentication (deprecated)

Headers Required:

- USERNAME: Your username
- USERPW: Your password

#### Sending with JSON API

- Method: POST
- Content-type: `multipart/form-data`
- URL: `/input_json`

##### Required parameters

| Parameter          | Type   | Description                                                             |
|--------------------|--------|-------------------------------------------------------------------------|
| pdf                | File   | PDF file to be processed (max 20MB), mime type must be application/pdf  |
| hash               | String | SHA1 hash of the PDF file (lowercase hexadecimal)                       |
| sw_api_key         | String | Software vendor API key                                                 |
| version            | String | Client version identifier (e.g. "MyErp 2.25")                           |

###### Recipient information (required)

| Parameter              | Type   | Description                                          |
|------------------------|--------|------------------------------------------------------|
| recipient[name]        | String | Recipient's full name                                |
| recipient[address]     | String | Street address                                       |
| recipient[post_code]   | String | Postal code                                          |
| recipient[post_office] | String | Post office / city                                   |
| recipient[country]     | String | Country code in ISO 3166-1 alpha-2 code (e.g., "FI") |

##### Optional parameters

###### Optional sender information (required for digital post send)

| Parameter          | Type   | Description                       |
|--------------------|--------|-----------------------------------|
| sender[name]       | String | Sender's name or company name     |
| sender[sender_id]  | String | Sender OVT/EIA (e.g. 00371111111) |

###### Optional recipient information (used for digital post lookups for better matching)

| Parameter          | Type   | Description                                                                                        |
|--------------------|--------|----------------------------------------------------------------------------------------------------|
| recipient[phone]   | String | Recipient's mobile phone number for digital post lookups (international format e.g. +358401234567) |
| recipient[email]   | String | Recipient's email address for digital post lookups                                                 |
| recipient[ssn]     | String | Recipient's social security number / national ID for digital post lookups                          |

###### Printing options

| Parameter              | Type    | Default    | Description                              |
|------------------------|---------|------------|------------------------------------------|
| duplex                 | Boolean | false      | Enable double-sided printing             |
| color_print            | Boolean | false      | Enable color printing                    |
| letter_class           | String  | "priority" | Delivery class ("priority" or "economy") |
| prevent_digital_post   | Boolean | false      | Force physical delivery only             |
| letter_subject         | String  |            | Custom letter subject shown to the recipient in Kivra (default: "Kirje lähettäjältä [company name]") |

###### Licensing parameters

| Parameter         | Type   | Description                                                      |
|-------------------|--------|------------------------------------------------------------------|
| license_key       | String | License key for the sending system if applicable (optional)      |
| license_meta      | String | License metadata for the sending system if applicable (optional) |

##### Response codes and values for sending

###### Success response for sending

- Status code: `201 Created`
- Body: `UUID`of newly created printable letter

###### Error responses for sending

| Status code | Response body             | Description                                                        |
|-------------|---------------------------|--------------------------------------------------------------------|
| 401         | Authorization Required    | Authentication failed or company account is inactive               |
| 400         | Invalid multipart request | Request is not proper multipart/form-data or missing the PDF file  |
| 400         | Missing version parameter | Required metadata is missing or incomplete                         |
| 400         | Missing metadata          | Required metadata is missing or incomplete                         |
| 400         | Invalid vendor key        | The provided `sw_api_key` is not valid                             |
| 409         | Duplicate file            | A file with the same hash has already been processed               |
| 413         | File size too large       | PDF file exceeds size limit (20MB)                                 |
| 415         | Invalid file type         | Wrong mime type in request                                         |
| 422         | Hash values do not match  | Provided hash doesn't match the uploaded file                      |
| 500         | Temporary server error    | File processing failed on the server side, try again later         |

##### Example requests for sending

Using Bearer Token Authentication (Recommended)

```bash
curl -X POST "https://payslip-stage.maventa.com/input_json" \
  -H "Authorization: Bearer your_api_key_here" \
  -H "X-Client-Id: your_company_uuid_here" \
  -F "pdf=@document.pdf" \
  -F "hash=a1b2c3d4e5f6789..." \
  -F "version=MyERP 1.25" \
  -F "sw_api_key=your_sw_api_key_here" \
  -F "recipient[name]=Essi Esimerkki" \
  -F "recipient[address]=Kotikatu 123" \
  -F "recipient[post_code]=00100" \
  -F "recipient[post_office]=Helsinki" \
  -F "recipient[country]=FI" \
  -F "sender[name]=Tulostaja Oy Ab" \
  -F "sender[sender_id]=00371234567890" \
  -F "duplex=true" \
  -F "color_print=false" \
  -F "letter_class=economy"
```

#### GET /file_status/:id API Endpoint

The /file_status/:id endpoint allows authenticated users to check the processing status of a specific payslip using its UUID. The endpoint supports the same authentication methods as the /input_json endpoint described above.

- Method: GET
- URL: `/file_status/{payslip_uuid}`

##### Response codes and values for status call

###### Success response for status call

- Status code: `200 OK`
- Body: Status string indicating current processing state

###### Possible status values for status call

| Status     | Description                                                                               |
|------------|-------------------------------------------------------------------------------------------|
| Pending    | File is being processed or waiting in queue at the print service provider                 |
| Done       | File has been successfully printed and delivered to the mail distributor                  |
| Error      | An error occurred during processing (you will be separately contacted in case of errors)  |

###### Error response for status call

| Status Code | Response Body          | Description                                               |
|-------------|------------------------|-----------------------------------------------------------|
| 401         | Authorization Required | Authentication failed or company account is inactive      |
| 404         | File not found         | No payslip found with the provided UUID for your company  |

##### Example requests for status call

```bash
curl -X GET "https://payslip-stage.maventa.com/file_status/550e8400-e29b-41d4-a716-446655440000" \
  -H "Authorization: Bearer your_api_token_here" \
  -H "X-Client-Id: your_company_uuid_here"
```

### IPOSTXML-based API (deprecated)

#### Authentication for IPOSTXML-based API

The endpoint supports multiple authentication methods for backwards compatibility:

Method 1: Bearer token authentication (recommended). Note! This is not using the common OAuth that our other services, it is the static user API key

Header Required:

- Authorization: Bearer {user_api_key}
- X-Client-Id: company_uuid

Method 2: Legacy API key authentication (deprecated)

Headers Required:

- USER_API_KEY: user_api_key
- COMPANY_UUID: company_uuid

Method 3: Legacy username/password authentication (deprecated)

Headers Required:

- USERNAME: Your username
- USERPW: Your password

#### POST parameters for IPOSTXML-based API

| Key                  | Example                                  | Description                                                                                                                                              |
|----------------------|------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|
| version              | MyOwnERP                                 | Name of the software (and its version) making the sending. Makes problem solving easier                                                                  |
| filename             | letters_2019_12.zip                      | Name of the ZIP package, should be unique                                                                                                                |
| file                 | RVBMMTExMzQ0O                            | The actual ZIP file attached using multipart/form-data                                                                                                   |
| zipHash              | 69a56b2b66d548d7b51f6dcc9003e90bafce2162 | SHA1 hash of ZIP content, will get check in server to make sure package came through as whole                                                            |
| hash                 | 856697ad0cae67ec48f7627be4cef74feaa2f36b | SHA1 hash of PDF content, will get saved to server for duplicate prevention. Same hash key cannot be used for sending again                              |
| document_type        | PDFXML                                   | PDFXML                                                                                                                                                   |
| letter_class         | economy                                  | Economy or priority (default value). Letter class to use for sending                                                                                     |
| sw_api_key           | 5992955a-3b66-4439-94d1-a854a764da49     | Existing software API key from Maventa. Value given in sending call will override the one set for the Payslip company account in registration            |
| license_key          | 1234-5678-MKSK-1234                      | License key of software making the call (255 chars max)                                                                                                  |
| license_meta         | License key for MyOwnERP                 | Additional information about the licensing system                                                                                                        |
| color_print          | true                                     | Colour printing: `true` for colour, `false` for black & white (default)                                                                                  |
| duplex               | true                                     | Duplex printing for both sides of the letter. Default is false                                                                                           |
| prevent_digital_post | true                                     | Prevent sending to OmaPosti. Default is false                                                                                                            |

> [!WARNING]
> **Important:** File upload must be done using the multipart/form-data content type. Do not send the file as a Base64-encoded string in a query parameter. If your integration currently does this, we recommend updating it to use multipart upload.

#### Response for sending with IPOSTXML-based API

The response code will be a HTTP 200 and the response body is one of the following or "401 Unauthorized" if authentication fails:

| Value                                        | Description                                                                                                                    |
|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------|
| "OK: sent_filename.zip"                      | Successful sending                                                                                                             |
| "ERROR: HASH VALUE DOES NOT MATCH"           | Parameter zipHash does not match to the SHA1hash                                                                               |
| "ERROR: ERROR: DUPLICATE FILE"               | Found file with parameter hash                                                                                                 |
| "ERROR: FILE TOO LARGE"                      | API allows max 10Mt files                                                                                                      |
| "ERROR: DOCUMENT TYPE UNSUPPORTED"           | document_type is something else than PDFXML                                                                                    |
| "ERROR: FILE IS NOT ZIP"                     | Parameter filename needs to be .zip                                                                                            |
| "ERROR: ZIP FILE CONTAINS UNSUPPORTED FILES" | Only .pdf files are allowed                                                                                                    |
| "ERROR: ZIP FILE CORRUPTED"                  | Unzipping failed                                                                                                               |
| "ERROR: NO LETTERS FOUND"                    | No letter were found. No .pdf files found inside the zip file                                                                  |
| "ERROR: SINGLE XML REFERENCES MULTIPLE PDFS" | Single iPost-XML can only have reference to one PDF (XML to PDF 1-1 ratio)                                                     |
| "ERROR: sent_filename.zip"                   | Unexpected error, sending failed. Contact our support for more information                                                     |
| "ERROR: LETTER OPTION MISMATCH"              | All IPost-XMLs in a ZIP file must have the same printing options (letter class, colour..) for billing purposes                 |

#### Zip file content

##### PDFs

- One zip file can contain multiple PDF files but only one letter per PDF file. One letter can have multiple pages.
- Each PDF must be accompanied with iPost-XML metadata file (iPost LetterBundle format version 0.4). Note! information given in IPost-XML overrides the API parameters. You can download a zip file containing [iPost-XML v0.4 implementation guidelines](/assets/pages/02-services-and-reach/01-finland/04-mass-printing-service/iPostXML_v04_guide.zip)
- One iPost-XML should only have reference to one PDF letter (iPost-XML to PDF 1-1 ratio)
- Page count on the iPost-XML (pages element) must match to the actual page count of the PDF
- We prefer that one zip file contains only one letter (one PDF file) + iPost-XML metadata file
- When multiple IPost-XMLs in one ZIP file, all IPost-XMLs must have the same printing options (letter class, colour..)
- Always use unique hash for each zip file. zipHash and hash values can be the same since one ZIP file can contain multiple PDF files
- Zip file max size is 1 GB

<details>
<summary>Example of iPost-XML</summary>

```xml
<?xml version="1.0" encoding="ISO-8859-1"?>
<lb:LetterBundle schemaVersion="v0x4" senderFileId="FileD1" xmlns:lb="urn:itella-letterbundle-v0x4" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:itella-letterbundle-v0x4 LetterBundle_V0x4.xsd">
  <lb:Bundle senderBundleId="">
    <lb:BundleCommon creationDate="2020-06-24T13:17:00.0Z" isTest="false">
      <lb:Sender companyName="Your company Oy" contact="" contactPerson="Support" email="support@support.com" phoneNumber="010-5058474" ovtID="003712345678">
        <lb:SenderAddress>
          <lb:Eu1 name="Your company Oy" address="PL 000" postalCode="00101" city="Helsinki" countryCode="FI"/>
        </lb:SenderAddress>
      </lb:Sender>
      <lb:StdBundleProcessing customerId="" departmentClassification="false" electronicArchiving="T" envelope="S" fileFormat="0" isDuplex="true" letterClass="2" paper="0" password="" serviceFunction="0"/>
      <lb:ExternalFile fileName="sent_filename.pdf" format="PDF" senderFileId="wm_0c5c09e0-03d3-4340-bb6b-0c3c14be7f42">
        <lb:CheckSum type="MD5" value="nnnnnnnnnnnnn"/>
      </lb:ExternalFile>
    </lb:BundleCommon>
    <lb:Letter senderLetterId="LetterID1">
      <lb:LetterMeta>
        <lb:Location pages="1" startPage="1"/>
        <lb:Recipient>
          <lb:Address>
            <lb:Eu1 address="Kotikatu 1" city="Helsinki" countryCode="FI" name="Asiakas Anssi" postalCode="01001"/>
          </lb:Address>
        </lb:Recipient>
      </lb:LetterMeta>
    </lb:Letter>
  </lb:Bundle>
</lb:LetterBundle>
```
</details>

#### Checking the status of sent packages for IPOSTXML-based API

To check the status of the sent package, use https://payslip.maventa.com/file_status.

#### Headers for checking the file status

You need to give authentication using HTTP headers. You can give either:

- `USERNAME` and `USERPW` with which you registered your Mass printing API account
- `COMPANY-UUID` and `USER-API-KEY` of your Maventa account

#### GET parameter for checking the file status

| Key      | Example           | Description              |
|----------|-------------------|--------------------------|
| filename | sent_filename.zip | Name of your ZIP package |

#### Response for checking the file status

| Value                    | Description                                                                                                                                             |
|--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------|
| "DONE"                   | Package is processed and sent successfully                                                                                                              |
| "PENDING"                | Package is still in sending process                                                                                                                     |
| "ERROR"                  | Sending of the package has failed (in these cases our support will get notified and they will contact the sender with more detailed reason for error)   |
| "ERROR: No file found"   | No file found with the given filename                                                                                                                   |

## Technical restrictions of the PDF

All files must be of PDF format (or have the same content requirements) for it to be printed correctly. That means that the file cannot contain dynamic components and that all fonts, images and others are included in the file (ie the files should be 100% "self-contained"). All new customers must test their PDF files (all variants of fonts, images, etc.) to verify that the PDFs can be handled. If the PDF contains graphics, such as logos, charts, and other images, they must be of good quality.

- Keep the top and right margins empty
- Do not send any invoice image or attachment with black/dark background  
- No transparencies  
- All fonts must be embedded (subset or complete)  
- All images must be in 250-300dpi. Higher resolution produces little or no quality gain. Lower resolution gives poor quality.
- Text should be stored as text (not bitmap)
- Recommended size per page is 1024kB, smaller the better
- Black / White print: 2-bit colours (black and white only), not grayscale.
- Colour print: Black text should be in black, not 4-colour
- Colour print: All colours must be CMYK
- PDF page size needs to be A4 (210 x 297 millimeters)

## Instructions for letter layout

Your PDF letter needs to follow these [PDF layout rules by Posti](/assets/pages/02-services-and-reach/01-finland/04-mass-printing-service/iPost_layout_design_instruction.pdf).
Addition to Posti as the mail distributor, there is also Jakeluyhtiö Suomi Oy (JYS) which have few additions to the Posti rules. Difference is the tracking barcodes they print on the invoice image, see [the JYS rules merged with the Posti ones](/assets/pages/02-services-and-reach/01-finland/04-mass-printing-service/ipost_and_jys_template.pdf).

Receiver information should be marked as clearly as possible to make sure machine readability.

## Envelope size

The Finnish printing service uses two envelope sizes:

- For invoices of up to 9 sheets, a smaller C5 envelope is used.
- For invoices exceeding 9 sheets, a larger and more expensive C4 envelope is used.

## Storage time

Once Maventa receives final confirmation from the print service provider, the file is completely removed from Maventa's servers. We recommend storing the files on the ERP side for at least a few months after the sending in case there are some support cases related to the sent letters.

## Delivery schedule

Letters that are sent to Maventa before 24:00 will get printed, processed and enveloped overnight and handed over to the mail distributor the following morning. Production does not take place during the weekends and holidays.

Delivery depends on the selected letter class. For Finnish companies sending domestic letters, there are two options: Priority and Economy.

For Finnish domestic letters, the practical difference between Priority and Economy is often minimal. Regional delivery schedules can have more impact on delivery timing than the letter class itself. Priority may still benefit B2B invoicing, but for consumer invoices, the recipient’s local delivery schedule is usually the deciding factor.

For international letters, only priority is available.

## OmaPosti delivery

OmaPosti is an application that allows customers to receive their letters electronically instead of in paper form. When a receiver has an active OmaPosti account and has not opted out of receiving digital letters from a specific sender, the invoice will be redirected to the receiver's OmaPosti account instead of being delivered as a physical letter. To determine if a receiver has an OmaPosti account, a combination of consumer's name and postal address is used for identification.

It is also possible for the sender to exclude the letter from being sent through the OmaPosti route by setting the prevent_digital_post parameter to true in the sending API call.

For the OmaPosti route to function, the necessary information must be provided as an API parameter (or in the IPOSTXML document). This includes the sender's OVT code and the receiver's name and address.

## Kivra delivery

Kivra is a digital mailbox service where consumers choose to receive their letters and documents electronically. When a recipient has a Kivra account, they have actively opted in to digital delivery. Delivering to Kivra reduces printing and postage costs while reaching recipients in their preferred channel.

### How it works

Before a letter is handed over to the print provider, Maventa performs an automatic lookup against the Kivra consumer registry using the recipient's information. If a match is found, the letter is delivered to the recipient's Kivra inbox instead of being printed and mailed. If no match is found, delivery falls through to the normal print route — no changes needed on your end.

Kivra has a maximum PDF size limit of 15 MB. If the letter exceeds this limit, it falls through to the normal print route automatically.

The lookup is performed using the following recipient data (in priority order):

1. Social security number (SSN)
2. Email address
3. Full name + street address + postal code + post office
4. Full name + phone number

> [!NOTE]
> To improve Kivra match rates, provide as much recipient information as possible in your API calls. The JSON API supports optional `recipient[email]` and `recipient[phone]` parameters that enable additional lookup methods beyond name and address matching.

Unlike OmaPosti, Kivra does not require the sender's OVT code. The Kivra sender account (tenant) is based on the company's business ID (BID), so no OVT information needs to be included in the API call for Kivra delivery.

### Automatic sender setup

Each company can have only one sender account (tenant) in Kivra. The tenant represents the company as a recognised sender, and its name is what recipients see in their Kivra inbox.

If a tenant does not already exist for the company, Maventa automatically creates one when the company's first letter is delivered via Kivra — no action is required. Maventa sets the tenant name based on the company's official name from the YTJ registry at the time the company was created in Maventa.

If another service provider has already created a tenant for the company in Kivra, that existing tenant and its name are used. To update the tenant name, contact Kivra directly.

### Custom letter subject

You can customise the letter subject that the recipient sees in their Kivra inbox using the `letter_subject` parameter. By default, the subject is "Kirje lähettäjältä [company name]".

### Opting out of Kivra delivery

To force physical delivery for a specific letter — for example, when a guaranteed paper trail is required — set the `prevent_digital_post` parameter to `true` in the API call. This opts out of both Kivra and OmaPosti delivery for that letter.

### Billing

Kivra deliveries are billed as consumer invoices. The billing action name is `EINVOICE_KIVRA_FI`.

## User account closing

If you wish to close the service, please contact Maventa support.

---

## e-invoicing in Sweden
Source: https://documentation.maventa.com/services-and-reach/sweden/

E-invoicing is well established in Sweden, with broad adoption across both public and private sectors. While a B2B e-invoicing mandate is not yet in place, it is mandatory for suppliers to the Swedish public sector. Ongoing discussions and the EU’s VAT in the Digital Age (ViDA) initiative are expected to shape upcoming regulatory changes.

On the consumer side, Sweden is preparing to launch a “Ja tack till e-faktura” (Yes to All) register in 2026, allowing consumers to opt-in to receive all invoices electronically, similar to Norway’s national model.

## Swedish company account

When registering a new Swedish company via the API, the Swedish organisation number or SSN must be used as the company identifier. Visma Sign supports Swedish customer authentication using either a personal ID or BankID.

| Supported business identifiers    | Explanation                               | Validation and verification of the id             |
| ----------------------------------| ------------------------------------------| --------------------------------------------------|
| ORGNR                             | Organisation number (55XXXX-XXXX)         | Structural validation                             |
| SSN                               | Social Security Number                    | Structural validation                             |

## Sending in Sweden

### Supported delivery channels in Sweden

For B2B and B2G, sending in Sweden is currently supported in the following priority order: through Maventa’s internal network, Peppol, the Swedish operator network, and InExchange for selected operators. If electronic delivery is not possible, email and print serve as fallback options.

For [consumer invoicing](/integration-guide/invoice-sending/consumer-invoicing/se/) (B2C), Maventa enables delivery to Swedish consumers via online banks, digital mail solutions such as Kivra and Billo, as well as through email or print.

### Recipient identifiers and address resolution

For the most reliable delivery, include the full Peppol endpoint ID in the invoice XML. The standard Peppol scheme for Swedish companies is `0007`, based on the organisation number (organisationsnummer). Peppol takes priority over other delivery channels in Sweden — when a Peppol endpoint is found, the invoice is delivered via Peppol first.

| Identifier type | Peppol scheme | Example endpoint ID | Notes |
|-----------------|---------------|---------------------|-------|
| Organisation number | `0007` | `0007:5511111111` | Standard for Swedish companies |
| GLN (Global Location Number) | `0088` | `0088:1234567890128` | EAN location number |

If you provide only the organisation number without a scheme prefix (for example `5511111111`), Maventa automatically prefixes it with `0007:` and performs a Peppol lookup. The organisation number can be provided with or without the `SE` country prefix — both `5511111111` and `SE5511111111` are accepted.

> [!NOTE]
> Providing the full endpoint ID `0007:organisationsnummer` removes any ambiguity and ensures the invoice is routed directly to the correct recipient.

### InExchange network

Maventa partners with InExchange to reach Swedish operators where a direct connection is not available. The primary format used is Peppol BIS Billing 3.0. Svefaktura is a fallback when the Peppol BIS format is not valid for sending.

## Receiving in Sweden

In Sweden, companies can receive invoices through several channels. If a company has activated e-invoice receiving, they can receive invoices via Maventa’s internal network, the Swedish operator network, and InExchange. Additionally, if the company is registered with Peppol, Peppol receiving is available.

### NEA registry

The NEA registry (Nationella Elektroniska Adressregistret) is the National Electronic Address Registry in Sweden. It is a central database that stores information about Swedish companies’ electronic invoice addresses and other identifiers used for routing e-invoices within Sweden.

Maventa registers all Swedish companies to NEA using BID as the e-invoicing address, in addition to the Peppol address if company has registered themselves to receive also through Peppol network.

Maventa recommends registering all Swedish customers as Peppol receivers. When registered in Peppol, customers receive a standard Peppol e-invoice address.

For Swedish companies, Maventa automatically assigns two e-invoice receiving addresses when company activates e-invoice receiving:

| Address Type              | Description                                                                                 | Example address    | Activation Requirement                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------ |
| 752-prefixed address      | Internal routing identifier used also still for InExchange. Not an official ID.             | 752551111111101    | Created automatically when e-invoice receiving is activate for Maventa account |
| BID (Business Identifier) | Official identifier used in the Swedish operator network. Registered in the NEA registry.   | 5511111111         | Created automatically when e-invoice receiving is activate for Maventa account |
| Peppol address            | Official identifier for the Peppol network. Registered in the NEA registry.                 | 0007:5511111111    | Created when company registers themselves to receive also from Peppol          |

### Scanning

Both Scan Network and AutoScan are supported [scanning](/integration-guide/invoice-receiving/scanning/) solutions in Sweden.

For Scan Network, invoices can be sent to the company's scan email address in the format `BID@autoinvoice.se`, where BID is the company's organisation number. Paper invoices can also be sent by post to: Company name, AISEXXXX Scancloud, SE-831 90 ÖSTERSUND, Sweden (where XXXX is the customer number).
### Fraud detection

Maventa's [Detect](/integration-guide/invoice-receiving/detect/) service is available in Sweden. Detect automatically checks received invoices for potential fraud, including VAT register verification and warning list cross-referencing.

> [!NOTE]
> For step-by-step instructions on enabling receiving, registering for Peppol, and setting up scanning or fraud detection, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## Accounts receivable services

[Ropo's reminder and collection service](/integration-guide/accounts-receivable/ropo-debt-collection/) is available for Swedish companies, offering reminder and debt collection services through Ropo. The service allows you to transfer overdue invoices to Ropo for reminder handling and collection directly through the Maventa API. For more details on how the service works, see the [Accounts receivable](/integration-guide/accounts-receivable/) section in the Integration Guide.

## Peppol SMP registration

When a Swedish company registers to receive invoices via Peppol through Maventa, the following document types are registered in the SMP (Service Metadata Publisher). These registrations determine which document formats the company can receive over the Peppol network.

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

## e-invoicing formats used in Sweden

Sweden has its own national invoice format, Svefaktura, alongside the Peppol BIS Billing 3.0 format. The latest version of Svefaktura has been aligned with Peppol BIS, signalling a clear move towards harmonisation. The Swedish government actively encourages Peppol adoption, and usage continues to grow steadily.

| Format | Standard | Notes |
|--------|----------|-------|
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | Recommended for cross-border and Peppol delivery |
| [Svefaktura](https://www.sfti.se/) | EN16931 | Swedish national format, used as fallback when Peppol BIS is not valid |

---

## e-invoicing in Norway
Source: https://documentation.maventa.com/services-and-reach/norway/

Norway is a highly digitalized e-invoicing market and a long-time adopter of structured electronic invoices. E-invoicing has been mandatory for public sector procurement since 2019, with invoices exchanged primarily using EHF or Peppol BIS Billing 3.0 via the Peppol network. While e-invoicing is not legally mandatory for B2B transactions, it is widely used across the private sector. Most Norwegian companies support Peppol-based invoicing, making it the de facto standard for both public and private invoice exchange.
To send and receive e-invoices in Norway, companies typically register in the national e-invoice directory (ELMA) and comply with Norwegian VAT and bookkeeping requirements. The regulatory framework supports long-term adoption and alignment with European Peppol standards.

## Norwegian company account registration

When registering a new Norwegian company via the API, the organisation number (organisasjonsnummer) must be used as the company identifier. The company must be registered in the Central Coordinating Register for Legal Entities (Enhetsregisteret, [Brønnøysundregistrene](https://www.brreg.no/en/)), as this is a requirement for participation in the Peppol network. Visma Sign supports Norwegian customer authentication using BankID.

| Identifier | Description | Format | Validation |
|------------|-------------|--------|------------|
| Organisation number | Norwegian organisation number (organisasjonsnummer) | `987654321` | Structural validation |

## Sending in Norway

### Supported delivery channels in Norway

For B2B and B2G, sending in Norway is currently supported in the following priority order: through Maventa’s internal network, and through the Peppol network. Email and print delivery are also available as fallback options.

For consumers (B2C) via direct debit (AvtaleGiro), netbank and Vipps (eFaktura), Digital postkasse innbygger (DPI, only for municipalities), e-mail and print. Read more about [consumer invoicing in Norway](/integration-guide/invoice-sending/consumer-invoicing/no/)

### Recipient identifiers and address resolution

For the most reliable delivery, include the full Peppol endpoint ID in the invoice XML. The standard Peppol scheme for Norwegian companies is `0192`, based on the organisation number (organisasjonsnummer).

| Identifier type | Peppol scheme | Example endpoint ID | Notes |
|-----------------|---------------|---------------------|-------|
| Organisation number | `0192` | `0192:987654321` | Standard for Norwegian companies |

If you provide only the organisation number without a scheme prefix (for example `987654321`), Maventa automatically prefixes it with `0192:` and performs a Peppol lookup. Any trailing `NO` or `MVA` suffixes on the identifier are stripped automatically before the lookup.

> [!NOTE]
> Providing the full endpoint ID `0192:organisasjonsnummer` removes any ambiguity and ensures the invoice is routed directly to the correct recipient.

## Receiving in Norway

In Norway, companies can receive invoices through different channels. If a company has activated e-invoice receiving, they can receive invoices via Maventa’s internal network. Additionally, if the company is registered with Peppol, Peppol receiving is available.

| Address Type              | Description                                                                                 | Example address    | Activation Requirement                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------- | ------------------ | ------------------------------------------------------------------------------ |
| Peppol address            | Official identifier for the Peppol network. Uses the organisation number with scheme `0192`. | 0192:980858073     | Created when the company registers to receive from Peppol                      |

### ELMA

ELMA (Elektronisk Adresseregister) is Norway’s official electronic address registry, maintained by Digitaliseringsdirektoratet. It stores information about companies’ e-invoicing capabilities and is used to route electronic documents across the Norwegian market.

When a company registers as a Peppol receiver through Maventa, the company is automatically registered in ELMA. This makes the company discoverable as an e-invoice recipient in Norway. You can look up registered companies in the [ELMA participant directory](https://hotell.difi.no/application/difi/elma/participants).

#### Registration requirement: Enhetsregisteret

ELMA requires all registered companies to be listed in the Central Coordinating Register for Legal Entities (Enhetsregisteret), maintained by [Brønnøysundregistrene](https://www.brreg.no/en/). Companies that are no longer registered in Enhetsregisteret cannot remain on the Peppol network.

Maventa periodically reviews Norwegian company registrations and closes accounts for companies no longer listed in Enhetsregisteret. When this happens, the company is unregistered from the Peppol network and all associated Maventa services are terminated.

> [!WARNING]
> If a company's organisation number changes, a new Maventa account must be created with the new organisation number. The company should inform their regular support team so the old account can be closed.

### Scanning

Both Scan Network and AutoScan are supported [scanning](/integration-guide/invoice-receiving/scanning/) solutions in Norway.

For Scan Network, invoices can be sent to the company’s scan email address in the format `BID@autoinvoice.no`, where BID is the company’s organisation number. Postal scanning is not available in Norway.
### Fraud detection

Maventa’s [Detect](/integration-guide/invoice-receiving/detect/) service is available in Norway. Detect automatically checks received invoices for potential fraud, including VAT register verification and warning list cross-referencing.

> [!NOTE]
> For step-by-step instructions on enabling receiving, registering for Peppol, and setting up scanning or fraud detection, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## Accounts receivable services

[Ropo's reminder and collection service](/integration-guide/accounts-receivable/ropo-debt-collection/) is available for Norwegian companies, offering reminder and debt collection services through Ropo. The service allows you to transfer overdue invoices to Ropo for reminder handling and collection directly through the Maventa API. For more details on how the service works, see the [Accounts receivable](/integration-guide/accounts-receivable/) section in the Integration Guide.

## Peppol SMP registration

When a Norwegian company registers to receive invoices via Peppol through Maventa, the following document types are registered in the SMP (Service Metadata Publisher). These registrations determine which document formats the company can receive over the Peppol network.

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

## e-invoicing formats used in Norway

| Format | Standard | Notes |
|--------|----------|-------|
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | Recommended for all invoicing in Norway, both domestic and cross-border |
| [EHF](https://anskaffelser.dev/postaward/g3/spec/) | EN16931 | Norwegian national format (Elektronisk Handelsformat), aligned with Peppol BIS |

---

## e-invoicing in Denmark
Source: https://documentation.maventa.com/services-and-reach/denmark/

Denmark is one of the most mature e-invoicing markets in Europe. E-invoicing has been mandatory for the public sector since 2005, and the country has since built a strong digital infrastructure around electronic document exchange.
Both Peppol and Denmark’s national network Nemhandel are supported, with ongoing developments driven by the new Danish accounting law and broader EU initiatives such as ViDA (VAT in the Digital Age).

In Denmark, most of the e-invoicing is routed through NemHandel, the national infrastructure for electronic documents. Instead of connecting directly to NemHandel, Maventa uses Sproom as an intermediary.

Sproom is a Danish e-invoicing platform and part of Visma. It acts as a technical access point and a routing directory, enabling companies to send and receive electronic invoices via NemHandel. This ensures proper delivery of e-invoices across Denmark. Currently only invoices and credit notes are supported in the Danish set-up.

## Danish company account registration

When registering a new Danish company via the API, the CVR number (Central Business Registration Number) must be used as the company identifier. Visma Sign supports Danish customer authentication using either a personal ID or NemID.

| Identifier | Description | Format | Validation |
|------------|-------------|--------|------------|
| CVR number | Central Business Registration Number | `31000000` | Structural validation |

## Sending in Denmark

### Supported delivery channels and routing order in Denmark

For B2B and B2G, sending in Denmark is currently supported in the following priority order: via NemHandel (Sproom), then through Maventa’s internal network, and finally through the Peppol network. Email and postal delivery (printing) are also available as fallback options. Printing is handled in Norway, and all postal deliveries are sent from Norway.

For B2C, invoices are delivered via email and print only.

### Recipient identifiers and address resolution

Danish invoices are primarily routed through NemHandel via Sproom, where the CVR number is sufficient for delivery. To route an invoice via Peppol instead, the full Peppol endpoint ID with scheme `0184` must be included in the invoice XML.

| Identifier type | Format | Example | Delivery channel |
|-----------------|--------|---------|------------------|
| CVR number | 8-digit number | `31000000` | NemHandel (via Sproom) |
| Peppol endpoint ID | `0184:` + CVR number | `0184:31000000` | Peppol network |
| GLN (Global Location Number) | `0088:` + GLN | `0088:1234567890128` | Peppol network |

Maventa does not automatically add a Peppol scheme prefix to a plain CVR number. If only the CVR number is provided, the invoice is delivered through NemHandel — Peppol routing is not attempted.

> [!NOTE]
> For the most reliable Peppol delivery, include the full endpoint ID `0184:CVRnumber` in the invoice XML. For NemHandel delivery, the plain CVR number is sufficient.

### Sproom and Nemhandel

Whenever your company sends invoices to Denmark to a participant in NemHandel (which includes most of the Danish companies), the process depends on whether the sending company already has an existing Sproom account:

* No existing Sproom account → The invoices are automatically handled through Maventa’s parent account in Sproom. No additional actions are required from the sender.
* Existing Sproom account → The company must explicitly approve Maventa (Visma Software AS) as a parent account in Sproom. This approval links the company’s existing Sproom profile with Maventa, ensuring invoices continue to be routed correctly through NemHandel.

A company can have multiple parent accounts in Sproom, which makes it possible for several software vendors to send and receive invoices on behalf of the same company.

When an invoice is sent from a company that already has a Sproom account, Sproom automatically sends an approval request email. This email is sent to the sender's company email address registered in Maventa, so it’s important to keep it up to date. The email contains a link that the company must follow and sign using MitID (Business or Private, depending on the signatory rights) to complete the approval. Currently, Sproom will continue sending approval requests after each invoice until the approval is completed. At the moment, invoice sending still works, but in the near future, invoices will fail if the approval is not completed after the first attempts.

Today, the approval emails come from Sproom address `notification@sproom.net`. But in the future, Maventa may take over sending these emails, which would then come from Maventa's own domain.

#### email fallback route with Sproom

When an invoice is sent to Sproom, the routing settings or disabled delivery routes defined in Maventa do not necessarily apply on Sproom’s side. This means that Sproom may send the invoice by email if e-invoice delivery fails. The email fallback is triggered when the recipient’s email address is included in the customer party details of the XML file. In Maventa, such invoices are still classified as e-invoices and appear as “e-invoice sent.”

By default, when a company does not have an existing Sproom account and is added as a child company of Maventa, the email sending route is not enabled on the Sproom side. This means that only the e-invoice route is active through Sproom, and if e-invoice delivery fails, Maventa decides whether to use the default delivery route.

For companies that already have an existing Sproom account and it is later linked under Maventa, if they had previously enabled the email sending option, it will remain active. In those cases, Sproom will handle the email sending, and such invoices will still be billed by Maventa as e-invoices.

Maventa recommends disabling the email sending setting on the Sproom side to ensure consistent and predictable delivery behaviour.

## Receiving in Denmark

In Denmark, companies can receive invoices through different channels. If a company has activated e-invoice receiving, they can receive invoices via Maventa’s internal network. Additionally, if the company is registered with Peppol, Peppol receiving is available. To receive from NemHandel, the company needs a separate receiving activation for that network.

| Address Type              | Description                                                                                      | Example address    | Activation Requirement                                                         |
| ------------------------- | ------------------------------------------------------------------------------------------------ | ------------------ | ------------------------------------------------------------------------------ |
| Peppol address            | Official identifier for the Peppol network. Uses the CVR number with scheme `0184`.              | 0184:31000000      | Created when the company registers to receive from Peppol                      |

### Scanning

Both Scan Network and AutoScan are supported [scanning](/integration-guide/invoice-receiving/scanning/) solutions in Denmark.

For Scan Network, invoices can be sent to the company’s scan email address in the format `CVRnumber@autoinvoice.dk`, where CVRnumber is the company’s CVR number.### Invoice response messages

Denmark has introduced a new [accounting law](https://www.pwc.dk/en/publikationer/assets/the-new-danish-bookkeeping-act.pdf) requiring ERP systems to support invoice response messages, XML-based business acknowledgements that communicate the processing status of an invoice between buyer and supplier (e.g. accepted, rejected, pending).

This requirement applies to invoices received through both the Peppol network and Denmark’s national network Nemhandel. The response formats follow:

* Peppol BIS Invoice Response for Peppol
* OIOUBL Application Response for Nemhandel (generated automatically by Sproom when requested via Maventa API)

### How messages responses work with Maventa

When a customer receives an invoice from a Danish sender via Maventa, ERP must handle invoice responses according to the sender’s registered network:

1. Verify whether the sender wants to receive responses via Peppol by using the lookup API endpoint [GET /v1/lookup/receivers](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/lookup/getV1LookupReceivers).

2. Send the invoice response

* If the supplier is registered in Peppol to receive invoice responses, the ERP creates and then sends a Peppol BIS Invoice Response via Maventa’s endpoint: [POST /v1/documents](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/documents/postV1Documents). [Peppol BIS Invoice Response implementation guidelines](https://docs.peppol.eu/poacc/upgrade-3/profiles/63-invoiceresponse/).
* If the supplier is not registered in Peppol, the ERP instead calls Maventa’s endpoint [POST /v1/invoices/{id}/responses/nemhandel](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/invoices/postV1InvoicesIdResponsesNemhandel) with invoice id and response they want to communicate back to the sender. Maventa will then forward the information to the Sproom API to generate and deliver an OIOUBL Application Response to Nemhandel on behalf of the ERP. If the supplier is registered in Nemhandel, Sproom generates and sends the response, which then Maventa returns as a success (200 OK). If the supplier is not registered, the request is ignored and an appropriate error status is returned.

To comply with Danish requirements, ERPs integrating with Maventa should:

* Implement support for generating and sending Peppol BIS 3 invoice response XMLs.
* Implement logic to determine whether the supplier want to receive responses via Peppol.
* Call the appropriate Maventa API endpoints based on the lookup result. Last status should be either accepted or declined.
* Prevent duplicate or invalid response submissions (follow the response order defined in the standards).

> [!NOTE]
> For step-by-step instructions on enabling receiving, registering for Peppol, and setting up scanning, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## Accounts receivable services

> [!NOTE]
> Accounts receivable services for Denmark are coming at a later date (timeline TBD).

[Ropo's reminder and collection service](/integration-guide/accounts-receivable/ropo-debt-collection/) will be available for Danish companies, offering reminder and debt collection services through Ropo. The service allows you to transfer overdue invoices to Ropo for reminder handling and collection directly through the Maventa API. For more details on how the service works, see the [Accounts receivable](/integration-guide/accounts-receivable/) section in the Integration Guide.

## Peppol SMP registration

When a Danish company registers to receive invoices via Peppol through Maventa, the following document types are registered in the SMP (Service Metadata Publisher). These registrations determine which document formats the company can receive over the Peppol network.

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

> [!NOTE]
> OIOUBL is not registered on the Peppol network. It is used for domestic Danish traffic through NemHandel via Sproom.

## e-invoicing formats used in Denmark

| Format | Standard | Network | Notes |
|--------|----------|---------|-------|
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | Peppol | Used for cross-border and Peppol traffic |
| [OIOUBL](https://digst.dk/it-loesninger/nemhandel/det-tekniske-setup-for-nemhandel/oioubl/) | UBL 2.0 | NemHandel | Danish national format, used for domestic traffic through Sproom. Not registered on Peppol |

---

## e-invoicing in the Netherlands
Source: https://documentation.maventa.com/services-and-reach/netherlands/

The Netherlands has a well-developed e-invoicing landscape, driven by EU alignment and strong government support for digital invoicing. E-invoicing has been mandatory for public sector suppliers since 2019, in line with EU Directive 2014/55/EU. While B2B e-invoicing is not yet legally mandated, the Dutch government strongly encourages all businesses to adopt it. The Peppol network is the primary channel for exchanging structured invoices, and the national SI-UBL 2.0 format (NLCIUS) is widely used alongside Peppol BIS Billing 3.0. The Netherlands continues to expand its digital invoicing infrastructure and is aligning with the EU ViDA (VAT in the Digital Age) initiative.

## Dutch company account registration

When registering a new Dutch company via the API, the organisation number (KVK/CoC) must be used as the company identifier. At the moment, company registration requires the vendor to have KYC approval from Maventa. Contact Maventa support to get started.

| Identifier | Description | Format | Validation |
|------------|-------------|--------|------------|
| KVK number | Kamer van Koophandel (Dutch Chamber of Commerce) number | `12345678` | Structural validation |

## Sending in Netherlands

### Supported delivery channels in Netherlands

For B2B and B2G, sending in Netherlands is currently supported in the following priority order: through Maventa’s internal network, and through the Peppol network. Email and print delivery are also available as fallback options.

### Recipient identifiers and address resolution

For the most reliable delivery, include the full Peppol endpoint ID (scheme prefix and identifier) in the invoice XML. If only a plain identifier is provided, Maventa automatically resolves the recipient by trying all applicable scheme prefix combinations against the Peppol network.

The Netherlands uses several identifier types, each mapped to one or more Peppol scheme prefixes:

| Identifier type | Peppol scheme | Example endpoint ID | Notes |
|-----------------|---------------|---------------------|-------|
| KVK number (Chamber of Commerce) | `0106` | `0106:12345678` | Most common for Dutch businesses |
| VAT number | `9944` | `9944:NL123456789B01` | Preferred when the company has a VAT number |
| OIN (government identifier) | `0190` | `0190:00000001234567890000` | Government institutions |
| GLN (Global Location Number) | `0088` | `0088:1234567890128` | EAN location number |

#### Automatic address resolution

When an invoice contains only a plain identifier without a scheme prefix, Maventa determines the identifier type and tries multiple prefix combinations in a Peppol SMP lookup:

- **KVK number** (for example `12345678`) — looked up as both `0106:12345678` and `9944:12345678`
- **VAT number** (for example `NL123456789B01`) — looked up as `9944:NL123456789B01`
- **OIN** — looked up with both `0190:` and `9954:` prefixes

The first successful match determines the delivery endpoint.

> [!NOTE]
> Providing the full endpoint ID with the correct scheme prefix removes any ambiguity and ensures the invoice is routed directly to the correct recipient.

### Invoice XML as email attachment

You can attach a structured invoice XML file to email invoices sent to Dutch recipients. This allows the recipient to receive structured data alongside the PDF, making it easier to import the invoice directly into their invoicing system.

This feature was originally developed for the Netherlands, where Peppol does not support departmental divisions due to the lack of separate Peppol IDs per department. By attaching the XML to the email, departments can still receive structured invoice data and import it manually.

To enable XML attachment, use the `email_settings[xml_format]` parameter in the [POST /v1/invoices](https://swagger.maventa.com/#/invoices/postV1Invoices) request and specify the desired XML format.

> [!WARNING]
> When the `email_settings[xml_format]` parameter is provided, the invoice is sent **only** via email. The email route is forced, and no other delivery channels are attempted even if the email sending fails.

For full details on email delivery options, language detection, header image customisation, and tracking, see the [email invoicing](/integration-guide/invoice-sending/email-invoicing/) guide.

## Receiving in the Netherlands

In the Netherlands, companies can receive invoices through different channels. If a company has activated e-invoice receiving, they can receive invoices via Maventa’s internal network. Additionally, if the company is registered with Peppol, Peppol receiving is available.

### Receiving addresses for Dutch companies

| Address Type          | Description                                                                     | Example address        | Activation Requirement                                          |
| --------------------- | ------------------------------------------------------------------------------- | ---------------------- | --------------------------------------------------------------- |
| Peppol address (KVK)  | Identifier based on the KvK number. Most commonly used for Dutch companies.     | 0106:12345678          | Created when the company registers to receive from Peppol       |
| Peppol address (VAT)  | Identifier based on the VAT number.                                             | 9944:NL123456789B01    | Created when the company registers to receive from Peppol       |

The identifier scheme used depends on which identifier was provided when registering the company in Maventa. Most Dutch companies use the KVK number (prefix `0106`).

### Scanning

Both Scan Network and AutoScan are supported [scanning](/integration-guide/invoice-receiving/scanning/) solutions in the Netherlands.

For Scan Network, invoices can be sent to the company’s scan email address in the format `KvKnumber@autoinvoice.nl` or `VATnumber@autoinvoice.nl`, depending on the registration identifier.
### Fraud detection

Maventa’s [Detect](/integration-guide/invoice-receiving/detect/) service is available in the Netherlands. Detect automatically checks received invoices for potential fraud, including VAT register verification and warning list cross-referencing.

> [!NOTE]
> For step-by-step instructions on enabling receiving, registering for Peppol, and setting up scanning or fraud detection, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## Peppol SMP registration

When a Dutch company registers to receive invoices via Peppol through Maventa, the following document types are registered in the SMP (Service Metadata Publisher). These registrations determine which document formats the company can receive over the Peppol network.

### Peppol BIS Billing 3.0

The standard Peppol BIS Billing 3.0 profiles are registered for cross-border invoicing:

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

### SI-UBL 2.0 (NLCIUS)

In addition to the standard Peppol BIS profiles, Dutch companies are also registered with the SI-UBL 2.0 profiles. SI-UBL 2.0 implements the Dutch national CIUS (Core Invoice Usage Specification) known as NLCIUS, which is required for government invoicing in the Netherlands.

<details>
<summary>SI-UBL 2.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>SI-UBL 2.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

### SI-UBL 2.0 G-Account Extension

Dutch companies can optionally enable the G-Account extension, which registers an additional document type for receiving G-Account invoices. G-Account is a Dutch mechanism for payment guarantees in specific industries. This extension is not enabled by default — see the [invoice receiving guide](/integration-guide/invoice-receiving/) for instructions on how to activate it via the API.

<details>
<summary>SI-UBL 2.0 G-Account — Invoice (optional)</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:nen.nl:nlcius:v1.0#conformant#urn:fdc:nen.nl:gaccount:v1.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

## e-invoicing formats used in the Netherlands

| Format | Standard | Notes |
|--------|----------|-------|
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | Recommended for cross-border and Peppol delivery |
| [SI-UBL 2.0](https://www.nlcius.nl/) (NLCIUS) | EN16931 | Dutch national format, required for government invoicing. UBL implementation of the NLCIUS specification |

---

## e-invoicing in Belgium
Source: https://documentation.maventa.com/services-and-reach/belgium/

Belgium is standardising electronic invoicing across both public and private sectors. Suppliers to the government must already send e-invoices in a structured format (typically Peppol BIS Billing 3.0) in line with EU requirements, and from 1 January 2026 e-invoicing became mandatory for most B2B transactions between Belgian VAT-registered companies. The Peppol network is the primary channel for exchanging structured invoices, and Belgium is progressing toward broader digital reporting and compliance with EU ViDA initiatives.

## Belgium company account

When registering a new Belgian company via the API, the CBE/KBO enterprise number must be used as the company identifier. At the moment, company registration requires the vendor to have KYC approval from Maventa. Contact Maventa support to get started.

| Identifier | Description | Format | Validation |
|------------|-------------|--------|------------|
| CBE/KBO number | Enterprise number (Crossroads Bank for Enterprises / Kruispuntbank van Ondernemingen) | `0471000000` | Structural validation |

## Sending in Belgium

### Supported delivery channels in Belgium

For B2B and B2G, sending in Belgium is currently supported in the following priority order: through Maventa’s internal network, and through the Peppol network. Email and postal delivery (print) are also available as fallback options. Printing is handled in Finland, and all postal deliveries are sent from Finland.

For B2C, invoices are delivered via email and print only.

## Receiving in Belgium

In Belgium, companies can receive invoices through different channels. If a company has activated e-invoice receiving, they can receive invoices via Maventa’s internal network. Additionally, if the company is registered with Peppol, Peppol receiving is available.

### Receiving addresses for Belgian companies

| Address Type   | Description                                                                                                           | Example address    | Activation Requirement                                          |
| -------------- | --------------------------------------------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------- |
| Peppol address | Official identifier for the Peppol network. Uses the CBE/KBO number with scheme `0208`, as required by the Belgian Peppol Authority. | 0208:0471000000    | Created when the company registers to receive from Peppol       |

### Scanning

Both Scan Network and AutoScan are supported [scanning](/integration-guide/invoice-receiving/scanning/) solutions in Belgium.

For Scan Network, invoices can be sent to the company’s scan email address in the format `BE-ENnumber@scan.maventa.com`.
> [!NOTE]
> For step-by-step instructions on enabling receiving, registering for Peppol, and setting up scanning, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## Peppol SMP registration

When a Belgian company registers to receive invoices via Peppol through Maventa, the following document types are registered in the SMP (Service Metadata Publisher). These registrations determine which document formats the company can receive over the Peppol network.

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

## e-invoicing formats used in Belgium

| Format | Standard | Notes |
|--------|----------|-------|
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | Primary format for both B2G and B2B invoicing in Belgium |

## Self-billing support

In Belgium, self-billing is commonly used and fully supported in Maventa via Peppol. Read more about how it works and how to enable it from the [self-billing documentation](/integration-guide/peppol/self-billing-support/).

---

## e-invoicing in Germany
Source: https://documentation.maventa.com/services-and-reach/germany/

Germany is introducing mandatory e-invoicing in phases. Starting from 1st of January 2025, all German companies have been required to be able to receive e-invoices. The obligation to send e-invoices will follow gradually: starting 1st of January 2027 for large and medium-sized companies, and from 1st of January 2028 for all companies, regardless of size.

## German company account registration

When registering a new German company via the API, the VAT number must be used as the company identifier. At the moment, company registration requires the vendor to have KYC approval from Maventa. Contact Maventa support to get started.

| Identifier | Description | Format | Validation |
|------------|-------------|--------|------------|
| VAT number | German VAT identifier (Umsatzsteuer-Identifikationsnummer) | `DE123456789` | Structural validation via VIES |

## Sending in Germany

### Supported delivery channels in Germany

For B2B and B2G, sending in Germany is currently supported in the following priority order: through Maventa’s internal network and through the Peppol network. Email and print delivery are also available as fallback options. Printing is currently handled through the Finnish production facility, with a local German print solution planned (timeline TBD).

For B2C, invoices are delivered via email and print only.

## Receiving in Germany

In Germany, companies can receive invoices through different channels. If a company has activated e-invoice receiving, they can receive invoices via Maventa’s internal network. Additionally, if the company is registered with Peppol, Peppol receiving is available.

| Address Type   | Description                                                                                    | Example address    | Activation Requirement                                          |
| -------------- | ---------------------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------- |
| Peppol address | Official identifier for the Peppol network. Uses the VAT number with scheme `9930`.            | 9930:de811000000   | Created when the company registers to receive from Peppol       |

### Scanning

[Scanning](/integration-guide/invoice-receiving/scanning/) is available in Germany via the AutoScan solution.

> [!NOTE]
> For step-by-step instructions on enabling receiving, registering for Peppol, and setting up scanning, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## Accounts receivable services

> [!NOTE]
> Accounts receivable services for Germany are coming at a later date (timeline TBD).

[Ropo's reminder and collection service](/integration-guide/accounts-receivable/ropo-debt-collection/) will be available for German companies, offering reminder and debt collection services through Ropo. The service allows you to transfer overdue invoices to Ropo for reminder handling and collection directly through the Maventa API. For more details on how the service works, see the [Accounts receivable](/integration-guide/accounts-receivable/) section in the Integration Guide.

## Peppol SMP registration

When a German company registers to receive invoices via Peppol through Maventa, the following document types are registered in the SMP (Service Metadata Publisher). These registrations determine which document formats the company can receive over the Peppol network.

### Peppol BIS Billing 3.0

The standard Peppol BIS Billing 3.0 profiles are registered for cross-border invoicing. Peppol BIS must be used when sending invoices to or from Germany across national borders.

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

### XRechnung 3.0

In addition to the standard Peppol BIS profiles, German companies are registered with XRechnung profiles for domestic traffic. XRechnung is the German national CIUS (Core Invoice Usage Specification) of EN 16931, required for public sector invoicing in Germany.

<details>
<summary>XRechnung 3.0 — Invoice (UBL)</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>XRechnung 3.0 — Credit Note (UBL)</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>XRechnung 3.0 — Invoice (CII)</summary>

**DocumentIdentifier**
`urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100::CrossIndustryInvoice##urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0::D16B`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

### XRechnung 2.3

The previous XRechnung version is also registered to ensure compatibility with senders still using the older version.

<details>
<summary>XRechnung 2.3 — Invoice (UBL)</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_2.3::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>XRechnung 2.3 — Credit Note (UBL)</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_2.3::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>XRechnung 2.3 — Invoice (CII)</summary>

**DocumentIdentifier**
`urn:un:unece:uncefact:data:standard:CrossIndustryInvoice:100::CrossIndustryInvoice##urn:cen.eu:en16931:2017#compliant#urn:xoev-de:kosit:standard:xrechnung_2.3::D16B`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

## e-invoicing formats used in Germany

| Format | Standard | Notes |
|--------|----------|-------|
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | Used for Peppol exchanges |
| [XRechnung](https://xeinkauf.de/xrechnung/) | EN16931 | German national format, used in domestic Peppol traffic |
| [ZuGFeRD](https://www.ferd-net.de/) | EN16931 | Hybrid format (PDF with embedded XML). Support for sending as email attachment planned (timeline TBD) |

---

## e-invoicing in Estonia
Source: https://documentation.maventa.com/services-and-reach/estonia/

Estonia has a well-established e-invoicing ecosystem and requires structured e-invoices for public sector (B2G) transactions. E-invoicing is currently optional for B2B, but widely supported and aligned with the European standard (EN 16931). Invoices are exchanged via service providers and the Peppol network rather than a central platform. Estonia is gradually expanding structured e-invoicing in the private sector as part of its alignment with EU-level digital VAT initiatives.

## Estonian company account

When registering a new Estonian company via the API, the company code or VAT number must be used as the company identifier. At the moment, company registration requires the vendor to have KYC approval from Maventa. Contact Maventa support to get started.

| Identifier | Description | Format | Validation |
|------------|-------------|--------|------------|
| Company code | Estonian company registration code | `12345678` | Structural validation |
| VAT number | Estonian VAT identifier | `EE123456789` | Structural validation via VIES |

## Sending in Estonia

### Supported delivery channels in Estonia

For B2B and B2G, sending in Estonia is currently supported in the following priority order: through Maventa’s internal network and via Peppol network. If electronic delivery is not possible, email and postal delivery (printing) serve as fallback options. Printing is handled in Finland, and all postal deliveries are sent from Finland.

For consumers (B2C), Maventa enables delivery through email or print.

## Receiving in Estonia

In Estonia, companies can receive invoices through different channels. If a company has activated e-invoice receiving, they can receive invoices via Maventa’s internal network. Additionally, if the company is registered with Peppol, Peppol receiving is available.

### Receiving addresses for Estonian companies

| Address Type   | Description                                                                              | Example address    | Activation Requirement                                          |
| -------------- | ---------------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------- |
| Peppol address | Official identifier for the Peppol network. Uses the VAT number with scheme `9931`.      | 9931:ee102000000   | Created when the company registers to receive from Peppol       |

### Scanning

[Scanning](/integration-guide/invoice-receiving/scanning/) is available in Estonia via the AutoScan solution.

> [!NOTE]
> For step-by-step instructions on enabling receiving, registering for Peppol, and setting up scanning, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## Peppol SMP registration

When an Estonian company registers to receive invoices via Peppol through Maventa, the following document types are registered in the SMP (Service Metadata Publisher). These registrations determine which document formats the company can receive over the Peppol network.

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

## e-invoicing formats used in Estonia

| Format | Standard | Notes |
|--------|----------|-------|
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | Primary format for Peppol exchanges |

---

## e-invoicing in Latvia
Source: https://documentation.maventa.com/services-and-reach/latvia/

Latvia is rolling out mandatory B2B e-invoicing in phases. Voluntary adoption opens in March 2026, with full mandatory enforcement from January 2028. Latvia uses a decentralised Continuous Transaction Controls (CTC) model, where invoice data is reported to the State Revenue Service (SRS) within five working days. The expected format is Peppol BIS Billing 3.0, aligning with the EU EN 16931 standard and the ViDA initiative. B2G e-invoicing has been mandatory since January 2025 via the Peppol network or the national e-Address portal, with SRS data reporting required from January 2026.

## Latvian company account

When registering a new Latvian company via the API, the Latvian VAT number must be used as the company identifier. At the moment, company registration requires the vendor to have KYC approval from Maventa. Contact Maventa support to get started.

| Identifier | Description | Format | Validation |
|------------|-------------|--------|------------|
| VAT number | Latvian VAT identifier | `LV40103863798` | Structural validation via VIES |

## Sending in Latvia

### Supported delivery channels in Latvia

For B2B and B2G, sending in Latvia is currently supported in the following priority order: through Maventa's internal network and via the Peppol network. If electronic delivery is not possible, email and postal delivery (printing) serve as fallback options. Printing is handled in Finland, and all postal deliveries are sent from Finland.

For consumers (B2C), Maventa enables delivery through email or print.

## Receiving in Latvia

In Latvia, companies can receive invoices through different channels. If a company has activated e-invoice receiving, they can receive invoices via Maventa's internal network. Additionally, if the company is registered with Peppol, Peppol receiving is available.

### Receiving addresses for Latvian companies

| Address Type   | Description                                                                              | Example address      | Activation Requirement                                          |
| -------------- | ---------------------------------------------------------------------------------------- | -------------------- | --------------------------------------------------------------- |
| Peppol address | Official identifier for the Peppol network. Uses the VAT number with scheme `9939`.      | 9939:lv40000000000   | Created when the company registers to receive from Peppol       |

### Scanning

[Scanning](/integration-guide/invoice-receiving/scanning/) is available in Latvia via the AutoScan solution.

> [!NOTE]
> For step-by-step instructions on enabling receiving, registering for Peppol, and setting up scanning, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## Peppol SMP registration

When a Latvian company registers to receive invoices via Peppol through Maventa, the following document types are registered in the SMP (Service Metadata Publisher). These registrations determine which document formats the company can receive over the Peppol network.

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

## e-invoicing formats used in Latvia

| Format | Standard | Notes |
|--------|----------|-------|
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | Required for B2G and the expected standard for B2B |

---

## e-invoicing in Poland
Source: https://documentation.maventa.com/services-and-reach/poland/

Poland uses KSeF (Krajowy System e-Faktur), the national e-invoicing system, as the centralised platform for all invoice traffic. Both domestic and cross-border invoices are reported to KSeF using the FA(3) structured invoice format defined by the Polish tax authority. For domestic B2B transactions, KSeF is the sole delivery channel — invoices are issued through KSeF, and KSeF handles delivery to the recipient. For cross-border invoicing, invoices are reported to KSeF and additionally sent via the Peppol network when full Peppol address details are provided.

> [!NOTE]
> Poland is currently supported only for selected partners. Please contact Maventa Support for more information on how to set this up with your ERP for Polish companies.

## Polish company account registration

When registering a new Polish company via the API, the Polish VAT number must be used as the company identifier. At the moment, company registration requires the vendor to have KYC approval from Maventa. Contact Maventa support to get started.

| Identifier | Description | Format | Validation |
|------------|-------------|--------|------------|
| VAT number | Polish VAT identifier (NIP) | `PL1234567890` | Structural validation via VIES |

## Sending in Poland

### KSeF reporting and delivery

All invoices sent through Maventa for Polish companies are reported to KSeF. When Maventa sends an invoice to KSeF, the invoice is converted to the FA(3) format — the official KSeF structured invoice schema, mandatory from 1 February 2026. For each successfully submitted invoice, KSeF returns a [UPO confirmation](#upo--official-confirmation-of-receipt) and the sender can download both the UPO and the [cleared FA(3) document](#downloading-the-upo-and-cleared-document) via the API.

**Domestic invoices** are routed exclusively to KSeF by Maventa — the sender does not need to take any additional steps. KSeF acts as the delivery platform and handles forwarding the invoice to the recipient. No other delivery channel is used for domestic traffic.

**Cross-border invoices** are reported to KSeF and additionally sent via the Peppol network — but only when the full Peppol address details are provided in the sending API metadata. This means both the recipient's Peppol endpoint ID and the operator's Peppol identifier must be explicitly included.

> [!WARNING]
> If the full Peppol address details are not provided for a cross-border invoice, the invoice is reported to KSeF but is not delivered to the recipient via Peppol or any other channel. The invoice status shows as SENT because KSeF accepted it, even though the invoice has not actually reached the recipient. Maventa does not automatically reroute these invoices — the sender must manually reroute the invoice to email or print if these delivery channels are enabled for the sender account.

### Email and print delivery

Email and postal delivery (printing) are available as additional delivery channels but are not applied automatically by Maventa. If an invoice needs to be delivered via email or print — for example when Peppol delivery was not possible or no Peppol address was provided — the sender must reroute the invoice to these channels manually. Printing is handled in Finland, and all postal deliveries are sent from Finland.

### UPO — official confirmation of receipt

For every invoice successfully submitted to KSeF, Maventa receives a UPO file (Urzędowe Poświadczenie Odbioru — Official Confirmation of Receipt). The UPO is issued by the Polish tax authority system and serves as formal proof that the invoice was received and registered by KSeF.

The UPO typically contains:

- Submission reference and request ID
- KSeF ID (the unique invoice number assigned by KSeF)
- Date and time of receipt
- Processing status (accepted or rejected)
- Sender details
- Hash and integrity reference

The KSeF ID is also available via [`GET /v1/invoices/{id}/actions`](https://swagger.maventa.com/#/invoices/getV1InvoicesIdActions) in the field `channel_details.external_number`.

### Downloading the UPO and cleared document

Both the UPO file and the CLEARED_DOCUMENT (the FA(3) file as submitted to KSeF) are listed in the `files` array of the [`GET /v1/invoices/{id}`](https://swagger.maventa.com/#/invoices/getV1InvoicesId) response. Each file entry includes an `id`, `filename`, `type`, and `mimetype`.

| File type | Description |
|-----------|-------------|
| `UPO` | Official Confirmation of Receipt from KSeF. Available only for sent invoices. |
| `CLEARED_DOCUMENT` | The FA(3) invoice file as registered with KSeF. Can be downloaded for bookkeeping or legal compliance purposes. |

To download a file, use [`GET /v1/invoices/{id}/files/{file_id}`](https://swagger.maventa.com/#/invoices/getV1InvoicesIdFilesFileId) with the `id` from the file entry.

<details>
<summary>Why is the UPO important?</summary>

The UPO serves as **legal evidence** that the invoice was delivered to the official KSeF platform. It provides an audit trail for compliance, dispute resolution, and customer support. The UPO can be stored in ERP or invoice management systems as the official delivery confirmation for Polish invoices.
</details>

> [!WARNING]
> Archiving is the partner's responsibility. Polish invoices must be archived for 10 years.

## Receiving in Poland

For domestic traffic, invoices sent by other Polish companies arrive via KSeF. Maventa retrieves these invoices from KSeF and delivers them to the recipient’s Maventa account, where they can be downloaded. For international traffic, invoices can be received via the Peppol network or directly from other Maventa customers — this requires Peppol SMP registration (see [below](#peppol-smp-registration)).

> [!NOTE]
> Received cross-border invoices are not currently reported to KSeF. KSeF is primarily the structured invoice system for invoices issued by entities in scope — especially domestic Polish transactions. Invoices from foreign suppliers typically remain outside KSeF unless the supplier has a Polish fixed establishment participating in the supply or voluntarily uses KSeF.

| Address Type   | Description                                                                              | Example address    | Activation Requirement                                          |
| -------------- | ---------------------------------------------------------------------------------------- | ------------------ | --------------------------------------------------------------- |
| Peppol address | Official identifier for the Peppol network. Uses the VAT number with scheme `9945`.      | 9945:xxxxxxxxxxx   | Created when the company registers to receive from Peppol       |

### Peppol SMP registration

To receive invoices via Peppol, a Polish company must first be registered in the SMP (Service Metadata Publisher). The SMP registration determines which document formats the company can receive over the Peppol network.

> [!WARNING]
> Maventa does not yet support Peppol SMP registration for Polish companies. This capability is expected to become available within the coming weeks.

When registration becomes available, the following document types are registered in the SMP:

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

### Scanning

[Scanning](/integration-guide/invoice-receiving/scanning/) is available in Poland via the AutoScan solution.

> [!NOTE]
> For step-by-step instructions on enabling receiving, registering for Peppol, and setting up scanning, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## e-invoicing formats used in Poland

> [!NOTE]
> ERP integrations for Polish companies should use Peppol BIS Billing 3.0 for both sending and receiving. This is currently the only format with a guaranteed working conversion to and from the Polish FA(3) format used by KSeF.

| Format | Standard | Notes |
|--------|----------|-------|
| FA(3) | Polish national standard | Official KSeF structured invoice schema defined by the Polish tax authority, mandatory from 1 February 2026. All invoices sent to KSeF are converted to this format. |
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | Recommended format for ERP integrations. Used for cross-border Peppol delivery alongside KSeF reporting. |

Maventa also supports Polish-localised PDF for both sent and received invoices.

---

## e-invoicing in Italy
Source: https://documentation.maventa.com/services-and-reach/italy/

Italy has one of Europe's most advanced e-invoicing systems. B2G e-invoicing has been mandatory since 2015, and B2B/B2C e-invoicing became mandatory for all VAT-registered businesses in January 2019. All domestic invoices — including cross-border (since July 2022) — must flow through the SDI (Sistema di Interscambio), Italy's centralised clearance platform managed by the Revenue Agency (Agenzia delle Entrate).

> [!NOTE]
> Italy requires setup on both sides before any Italian company can send or receive invoices through Maventa. Contact Maventa support to configure your vendor key for sending to SDI, and ensure the Italian company has registered Maventa as their e-invoicing operator in their SDI account.

## Italy company account registration

When registering a new Italian company via the API, the fiscal code or VAT number (Partita IVA / P.IVA) must be used as the company identifier. At the moment, company registration requires the vendor to have KYC approval from Maventa. Contact Maventa support to get started.

| Identifier | Description | Format | Validation |
|------------|-------------|--------|------------|
| Codice Fiscale | Italian fiscal code | `XXXXXXXXXXXXXXXX` | Structural validation |
| Partita IVA | Italian VAT identifier | `IT12345678901` | Structural validation via VIES |

## Sending in Italy

### SDI reporting and delivery

To start using Maventa as the e-invoicing operator through SDI, the Italian company must register Maventa's Codice Destinatario (operator code) in the SDI portal:

`61M0PS7`

All invoices sent through Maventa for Italian companies are reported to SDI. When Maventa sends an invoice to SDI, the invoice is converted to the FatturaPA format — the official XML format mandatory for all transactions through SDI. When SDI accepts the invoice, Maventa marks it as SENT immediately. However, SDI validates invoices in the background, so an invoice can still fail after it has been marked as SENT.

**Domestic invoices** are routed to SDI by Maventa — the sender does not need to take any additional steps. SDI acts as the clearance and delivery platform, validating the invoice and handling forwarding to the recipient. No other delivery channel is used for domestic B2B, B2G, or B2C traffic.

**Cross-border invoices** are first reported to SDI (mandatory since July 2022). Once SDI confirms the invoice has passed validation — which can take hours or even a few days — Maventa sends the invoice to the recipient through standard routing. This means the invoice is delivered via the best available channel — internal Maventa network or Peppol — based on the recipient's capabilities. Email and print delivery are also available if these fallback routes are enabled on the sender account.

> [!WARNING]
> SDI validates invoices in the background and responses can take hours or even a few days to arrive. If SDI rejects an invoice, Maventa sets the invoice status to error and notifies the sender via [webhooks](/integration-guide/integration-tools/webhooks/).

### Email and print delivery

Email and postal delivery (printing) are available as fallback delivery channels for cross-border invoices when enabled on the sender account. For domestic traffic, SDI handles all delivery — email and print are not used.

## Receiving in Italy

Receiving in Italy is handled via SDI. Peppol is available for cross-border transactions.

### Receiving addresses for Italian companies

| Address Type        | Description                                                                     | Example address   | Activation Requirement                                                             |
| ------------------- | ------------------------------------------------------------------------------- | ----------------- | ---------------------------------------------------------------------------------- |
| Codice Destinatario | 7-character recipient code for B2B/B2C routing through SDI                      | XXXXXXX           | Provided by recipient; used as SDI routing code                                    |
| Peppol address      | Identifier for cross-border Peppol traffic. Uses the VAT number with scheme `9906`. | 9906:ITXXXXXXXXX  | Created when the company registers to receive from Peppol                          |

> [!NOTE]
> For step-by-step instructions on enabling receiving and registering for Peppol, see the [invoice receiving integration guide](/integration-guide/invoice-receiving/).

## Peppol SMP registration

When an Italian company registers to receive invoices via Peppol through Maventa, the following document types are registered in the SMP (Service Metadata Publisher). These registrations determine which document formats the company can receive over the Peppol network.

<details>
<summary>Peppol BIS Billing 3.0 — Invoice</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

<details>
<summary>Peppol BIS Billing 3.0 — Credit Note</summary>

**DocumentIdentifier**
`urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1`

**ProcessIdentifier**
`urn:fdc:peppol.eu:2017:poacc:billing:01:1.0`
</details>

## e-invoicing formats used in Italy

| Format | Standard | Notes |
|--------|----------|-------|
| [FatturaPA](https://www.fatturapa.gov.it/) | Italian national standard | Mandatory XML format for all domestic transactions through SDI |
| [Peppol BIS Billing 3.0](https://docs.peppol.eu/poacc/billing/3.0/) | EN16931 | Used for cross-border and international Peppol exchanges |

---

## e-invoicing in France
Source: https://documentation.maventa.com/services-and-reach/france/

France is one of Europe's most ambitious e-invoicing transitions. Mandatory B2B e-invoicing is being rolled out in phases: from September 2026, all businesses must be able to receive structured e-invoices, and large and mid-sized companies must also begin sending them. SMEs and micro-enterprises follow from September 2027. A key feature of the French model is that all domestic B2B invoices must flow through government-certified Approved Platforms (PDPs — Plateformes de Dématérialisation Partenaires); direct point-to-point invoicing between companies is not permitted. Peppol is one of the accepted exchange formats between PDPs, and a central directory (Annuaire) via the PPF (Portail Public de Facturation) enables recipient lookup. B2G e-invoicing has been mandatory since January 2020 via Chorus Pro.

Maventa's support for France has not yet been decided. This page will be updated with detailed documentation once the service scope and timeline are confirmed.

---

## e-invoicing in Spain
Source: https://documentation.maventa.com/services-and-reach/spain/

Spain has required e-invoicing for public sector suppliers since 2015 for contracts above EU procurement value thresholds, with B2G invoices submitted via FACe (the central government platform) or equivalent regional systems. B2B e-invoicing is set to become mandatory under the Crea y Crece law: first for companies with annual turnover above €8 million, then for all others — rollout is expected from 2027 at the earliest.

Maventa's support for Spain has not yet been decided. This page will be updated with detailed documentation once the service scope and timeline are confirmed.

---


# API Specification

## API overview
Source: https://documentation.maventa.com/api-specification/overview/

Maventa offers two APIs for integrating e-invoicing and document exchange: a modern REST API and a legacy SOAP API.

**We highly recommend using the REST API** for all new integrations. It and provides a more straightforward developer experience and better performance. The REST API gives you full access to Maventa's capabilities with clear, well-documented endpoints.

New functionality is mainly added to the REST API. The SOAP API remains available for existing integrations, but we encourage migrating to REST when possible. If you're starting fresh, REST is the way to go.

Looking for code examples? Maventa provides [reference implementations](/integration-guide/integration-tools/reference-implementations/) for Java and C# to help you get started with the REST API.

---

## Getting Started
Source: https://documentation.maventa.com/api-specification/rest-api/getting-started/

## Authentication

Authentication to REST API is based on the Oauth2 standard. Using of all API functions requires a valid Oauth2 bearer token. Expiry is set on server side and the mechanism to handle the expiry of the token is suggested to be handled gracefully on the client side.

The endpoint for aquiring the token is [POST /oauth2/token](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/oauth2/postOauth2Token). This endpoint provides authentication to all of the Maventa REST APIs.

* When starting a session, request for an authentication token via `POST /oauth2/token`
* Store the token locally, and set it to expire in given time before the server side value returned in response as seconds in `expires_in` field
  * Use the token until the stored validity time is reached, and then request a new token
  * When storing the token note that it is just a signed JSON so the length is not fixed. Be prepare that the number of characters in token may change
* Build in graceful authentication error handling
  * Prepare to handle possible token expiry errors even though using the client side expiry time, by requesting a new token
  * Handle token access and token unauthorized/expired scenarios differently (if token granted per client id&secret does not grant access to given resource, asking for a new token will not help)

### Authenticate as a company

Authenticating requires a `user_api_key` and `company_id`. To create an account in testing, registrations can be done in [Maventa Web UI](https://testing.maventa.com/register).

Also you need a `vendor_api_key`. When you have registered a company account in testing, contact your integration contact point or Maventa support to convert your account into a partner account and create a `vendor_api_key` for you.

Call the `POST /oauth2/token` method with company credentials:

* `client_id` = Company UUID (log in to your Maventa account to get it)
* `client_secret` = User API key (log in to your Maventa account to get it)
* `vendor_api_key`

Notes:

* Currently only one level of user rights, admin, is supported. So all authenticated users will be granted with admin rights
* For Maventa company authentication, the scope does not need to be provided

### Authenticate as an operator

Call the `POST /oauth2/token` method with operator credentials:

* `client_id` = operator_id
* `client_secret` = operator_secret

## Error handling

The client should always handle any server/connection issues gracefully. Do not lock up or throw exceptions directly at your users. There can be both scheduled and unscheduled breaks in the service which should be handled on the client side, for example with messages like "Service unavailable, please try again later".

## Endpoints

Maventa REST API is technically split into multiple URLs:

### Test environment

https://ax-stage.maventa.com/  
https://receivables-stage.maventa.com/  
https://validator-stage.maventa.com/  
https://bling-stage.maventa.com

### Production environment

https://ax.maventa.com/  
https://receivables.maventa.com/  
https://validator.maventa.com/  
https://bling.maventa.com

But you should not care about that too much, the split is only technical. The authentication between all the methods under all these URL endpoint is the same.

---

## Getting Started
Source: https://documentation.maventa.com/api-specification/soap-api/getting-started/

Maventa SOAP API covers:

* invoice sending and receiving
* company set up and configuration

Get familiar with the API and usage examples and start building your integration. Before you continue, make sure you have read our [Integration guide](/integration-guide/getting-started/) and understand the [Partner Agreement](https://maventa.com/terms-and-conditions/)

> [!CAUTION]
> **We recommend new integrations to use the [Maventa REST API](/api-specification/rest-api/getting-started/) instead of the SOAP API.**
>
> While there are no concrete plans for deprecating the SOAP API, we are focusing our development efforts on the REST API and new features will primarily be added there.
>
> Also existing integrations are advised to be moved to the REST API. It is possible to use both APIs simultaneously so you can do the move in your own schedule, method by method.

## How to start

How to get started and get the necessary keys to set up the integration is explained in our [Integration guide](/integration-guide/getting-started/)

You will also also find there feature specific guides for sending, receiving, companies and settings, services and networks and billing that list what API method to use for different tasks.

## Endpoints

You can send Maventa SOAP messages over SSL secured HTTP protocol to the endpoints below.

The Maventa WSDL, which describes the Maventa API in a machine-readable way, is available for

* Testing at `https://testing.maventa.com/apis/v1.1/wsdl`
* Production at `https://secure.maventa.com/apis/v1.1/wsdl`

## Authentication

Authenticity is verified by a Personal API key, which is validated on each request to the Maventa Webservice.

See [API keys](/integration-guide/getting-started//#api-keys) for more information of the keys and how to get them.

### Firewall and ports

Our service operates on the following endpoints:

* `https://testing.maventa.com:443`
* `https://secure.maventa.com:443`

All communication is on port 443 (over SSL). There is no firewall whitelisting required from our side, you can connect from anywhere as soon as you have the API keys.

## Encoding

Maventa SOAP API expects that all content is UTF-8 encoded, using any other encoding will result in broken characters. Maventa does not check or correct your input. Therefore, you must make sure that all information is sent using the correct encoding.

For invoice XML please see the XML format specific guidelines for the correct encoding. In example Finvoice is encoded as ISO 8859-15.

### Response Content Type

The response indicates the response type in the HTTP Content-Type header.

`Content-Type: text/xml;charset=utf-8`

## Date formats

All dates in Maventa API are strings in YYYYMMDD-format. For example 20250131.

This format shall be used when communicating through Maventa API.

## Error return values

All methods can fail with these status errors:

| Error                                                          | Description                                                                                   |
| -------------------------------------------------------------- | ----------------------------------------------------------------------------------------------|
| ERROR: VENDOR API KEY DISABLED                                 | Software vendor has disabled the use of this vendor api key                                   |
| ERROR: USER NOT ACTIVATED                                      | User account must be activated by visiting the activation link in the activation email        |
| ERROR: USER HAS NO RIGHTS TO COMPANY                           | Current user has no rights to company with id given in `company_uuid`                         |
| ERROR: USER BELONGS TO MULTIPLE COMPANIES, NO COMPANY ID GIVEN | No `company_uuid` given                                                                       |
| ERROR: USER NOT FOUND                                          | API key not found                                                                             |
| ERROR: COMPANY NOT FOUND                                       | Given `company_uuid` not found                                                                |
| ERROR: COMPANY ACCOUNT IS LOCKED                               | Company’s account has been locked for some reason (e.g. too many disputes)                    |
| ERROR: COMPANY HAS NOT COMPLETED FIRST TIME WIZARD             | API won’t work until the user that registered for Maventa has completed the first time wizard |

---

## Account Configuration API Methods
Source: https://documentation.maventa.com/api-specification/soap-api/account-configuration-api-methods/

API methods for [account management](/integration-guide/account-management/companies-and-settings/). For new integrations, we recommend using the [REST API](/api-specification/rest-api/companies-and-settings-api/) instead.

## register_with_password

This method is only for partners and requires a partner software API key.

It can be used to register new companies through the API with predefined password (if given).

Method returns a RegistrationParamsOutD struct which includes the new user's API key, the company's UUID and e-invoice address for receiving. This information can then be automatically updated to the software's settings so the users do not need to input API key information by themselves.

> [!NOTE]
> **Important Note**
>
> If given user (e-mail) exists, API key will not be returned for security reasons. The user will then get access to the newly created company with the same user account. In this case the password will not be updated.

Read more about [companies and settings](FIX_LINK_PENDING)

Before created account can be used for sending, receiving and activating services, customer authentication must be completed and account has to be verified.

Partner must make sure the user can read and understand the FIX_LINK_PENDING

Read more about [verifying](FIX_LINK_PENDING).

```plain
/v1.1/api/register_with_password
```

### Input

**registration_params** - *RegistrationParamsIn*

| Key               | Type                     | Description                                                                    |
|:------------------|:-------------------------|:-------------------------------------------------------------------------------|
| vendor_api_key    | string                   | Identifies partner/ERP, mandatory                                              |
| license_agreement | boolean                  | Registering company must accept Maventa user agreement, mandatory              |
| company_name      | string                   | Company name, mandatory. Name has to be at least 3 characters long             |
| company_bid       | string                   | Company Business ID/Organization number/VAT number, mandatory                  |
| company_email     | string                   | Contact email address for company, mandatory                                   |
| no_vat            | boolean                  | Deprecated, no need to provide it anymore                                      |
| receive_invoices  | boolean                  | Select if company wants to receive e-invoices on their account                 |
| user_first_name   | string                   | First name, mandatory                                                          |
| user_last_name    | string                   | Last name, mandatory                                                           |
| user_email        | string                   | Email is used as login to portal and needs to be unique, mandatory             |
| user_phone        | string                   | Depending on invoice format, phone number might be visible on invoices         |
| email_activation  | boolean                  | Possibility to skip email activation by link (partner has verified email)      |
| address1          | string                   | Street address, mandatory                                                      |
| address2          | string                   | Additional address                                                             |
| post_code         | string                   | Postal number/code, mandatory                                                  |
| post_office       | string                   | Post office, mandatory                                                         |
| city              | string                   | Registered city, mandatory                                                     |
| state             | string                   | State of address                                                               |
| country           | string                   | Country code for company, mandatory. Allowed countries FI, SE, NO, DK, NL      |
| bank_accounts     | BankAccountParamsInArray | Array of BankAccountParamsIn                                                   |

### company_bid

Supported business identifiers types per country are

| Country | Type(s)  | Description and example                                                                                |
|:--------|:---------|:-------------------------------------------------------------------------------------------------------|
| FI      | ORGNR, VAT | Finnish organisation number: 1111112-8 or VAT number: FI11111128                                    |
| SE      | ORGNR, SSN | Swedish organisation number: 212000-0142 or social security number: 810101-3608 / 19810101-3608     |
| NO      | ORGNR    | Norwegian organisation number: 111111111                                                              |
| DK      | CVR      | Danish unique identifier for a business in Denmark's Central Business Register: 11111114             |
| NL      | KVK      | Netherlands Chamber of Commerce number: 00006662                                                       |
| EE      | CC, VAT  | Estonian Company Code (CC): 11111116 or VAT number: EE100591422                                       |
| BE      | EN       | Belgian organisation number: 0111111124                                                                |
| DE      | VAT      | German VAT number: DE100000008                                                                        |
| IT      | CFI, IVA | Italian Fiscal Code (CFI): SCRDVD85B24H355B / 12345670017 or VAT number (IVA): IT12345670017        |
| PL      | VAT      | Polish VAT number: PL1132848704                                                                       |

### bank_accounts - *BankAccountParamsInArray*

Bank accounts are not required for registration and needed only if invoicing format does not include bank account details

| Key           | Type    | Description                                                                   |
|:--------------|:--------|:------------------------------------------------------------------------------|
| account       | string  | Bank account number                                                           |
| default       | boolean | Default bank account flag                                                     |
| iban          | string  | International Bank Account Number                                              |
| swift         | string  | SWIFT code for bank                                                           |
| bank          | string  | Bank name                                                                     |
| user_password | string  | If not given, random password will be generated. Minimum length 8 characters. |

### Return values

| Status                                                   |
|:----------------------------------------------------------:|
| OK                                                         |
| ERROR: LICENSE AGREEMENT NEEDS TO BE ACCEPTED             |
| ERROR: COUNTRY CODE INVALID                               |
| ERROR: REGISTRATION FAILED, BID ALREADY TAKEN             |
| ERROR: VAT CHECK FAILED                                   |
| ERROR: POSTAL ADDRESS MISSING REQUIRED INFORMATION        |
| ERROR: USER PASSWORD INVALID                              |
| ERROR: USER DETAILS MISSING REQUIRED INFORMATION          |
| ERROR: REGISTRATION FAILED                                |

## authorize_companies

Taking a new account into use requires that customer authentication process has been completed.
Integrator can use their own customer authentication process or Maventa process provided by Visma Sign.

To complete customer authentication process use this method.  
For Finnish companies the mehtod also initiates bank network opening.

Read more about company authentication from [company account management](FIX_LINK_PENDING).

```plain
/v1.1/api/authorize_companies
```

### Input

api_keys - ApiKeys

| Key                | Type           | Description                     |
| ------------------ | -------------- | ------------------------------- |
| company_uuid       | string         | UUID of current company         |
| user_api_key       | string         | User API key                    |
| vendor_api_key     | string         | Partner software API key        |

| Key                | Type           | Description                                                                                                                                |
| ------------------ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| auth_email         | string         | Email to send the Visma Sign request to. The person signing will be strongly authenticated and should have signing rights or power of attorney to represent the company. |
| company_ids        | stringarray    | Array of company UUIDs to authorize. Admin user needs to have access to all of the companies given.                                        |
| locale             | string         | Locale to use on the sign invitation email, Visma Sign portal, and agreement PDF. Currently supports FI, NO, SE, EN                        |
| options            | string         | Used to provide proof of customer authentication process. Mandatory when partner has own customer authentication process. Expects `authorization_method` key. `authorization_method` - free text for explaining how customer authentication was done as well as giving an identifier(s) that links to event on partners side. E.g. `'{"authorization_method":"We have documents"}'` |

### Output

| Key                | Type           |
| ------------------ | -------------- |
| return             | string         |

### Return values

| Key                | Type           | Message                                                | Description |
| ------------------ | -------------- | ------------------------------------------------------ | ----------- |
| return             | string         | OK: Visma Sign document sent                           | Invitation to sign has been sent to email given in the call. After signing is completed in Visma Sign service company status will change to verified. |
| return             | string         | OK: @x companies authorized                            | Company account has been set to verfied. Account can be used to sending, reseiving and activating services. Happens only when partner has own customer authentication process in use. |
| return             | string         | ERROR: COMPANY AUTHORIZATION STATUS MISMATCH           | Given company / any of the given companies is already authorized. |
| return             | string         | ERROR: VENDOR API KEY CANNOT BE BLANK                  | |
| return             | string         | ERROR: VENDOR API KEY INVALID OR DISABLED              | |
| return             | string         | ERROR: EMAIL ADDRESS INVALID                           | |
| return             | string         | ERROR: LOCALE NOT SUPPORTED                            | Given locale (country) is not supported |
| return             | string         | ERROR: AMOUNT OF COMPANIES TO SIGN NEEDS TO BE BETWEEN 1 to 50 | |
| return             | string         | ERROR: UNKNOWN ERROR                                   | |

## company_auth_status

To check the company authorization status which tells if company has completed customer authentication process.

> [!WARNING]
> **Important:** In order to start sending, receiving and activating services the `company_state` needs to be verified.

Read more about company authorization from [FIX_LINK_PENDING](#3-verify-account--know-your-customer-process).

```plain
/v1.1/api/company_auth_status
```

### Input

api_keys (ApiKeys)

| Key                | Type           | Description                     |
| ------------------ | -------------- | ------------------------------- |
| company_uuid       | string         | UUID of current company         |
| user_api_key       | string         | User API key                    |
| vendor_api_key     | string         | Partner software API key        |

### Output

return (AuthParamsOut)

| Key           | Type   | Description                                                                          |
|---------------|--------|--------------------------------------------------------------------------------------|
| auth_state    | string | Visma Sign request state: `SENT` - Auth request sent to signer but not signed yet, `SIGNED` - Auth request signed, `CANCELLED` - Auth request has been cancelled, e.g. because time has expired, `PENDING` - Auth request created but not sent to signer yet, `ERROR` - Something unexpected has happened |
| auth_email    | string | Email address used to sent the Visma Sign request to                                 |
| company_state | string | `unverified` / `verified` / `unknown`, unverified companies cannot send, receive or activate services. |

### Return values

| Key    | Type   | Message                                    | Description                                                                                                                                                                       |
|--------|--------|--------|---|
| return | string | OK: Visma Sign document sent               | Invitation to sign has been sent to email given in the call. After signing is completed in Visma Sign service company status will change to verified.                             |
|        | string | OK: Company authorized                     | Company account has been set to verified. Account can be used to sending, receiving and activating services. Happens only when partner has own customer authentication process in use. |
|        | string | OK: No authorization requests              | No signing requests have been sent for the company                                                                                                                                 |
|        | string | ERROR: USER NOT FOUND                      |                                                                                                                                                                                   |
|        | string | ERROR: VENDOR API KEY CANNOT BE BLANK      |                                                                                                                                                                                   |
|        | string | ERROR: VENDOR API KEY INVALID OR DISABLED  |                                                                                                                                                                                   |
|        | string | ERROR: Visma Sign status check failed      |                                                                                                                                                                                   |
|        | string | ERROR: UNKNOWN ERROR                       |                                                                                                                                                                                   |

## configure_company

Used for updating company settings.

Read more about [companies and settings](FIX_LINK_PENDING)

```plain
/v1.1/api/configure_company
```

### Input

api_keys (ApiKeys)

| Key                | Type           | Description                     |
| ------------------ | -------------- | ------------------------------- |
| company_uuid       | string         | UUID of current company         |
| user_api_key       | string         | User API key                    |
| vendor_api_key     | string         | Partner software API key        |

settings (SettingValueArray)

| Key                         | Type    | Description                                                                                                                  |
|-----------------------------|---------|------------------------------------------------------------------------------------------------------------------------------|
| website                     | string  | Website of company, displayed on invoice (depending on sending format)                                                       |
| print_and_send_request      | int     | Print&Send enabled request (1 = enabled, 0 = disabled)                                                                       |
| print_and_send_letter_class | int     | Print&Send mail class (1 = priority, 0 = economy). Economy available for FI, SE, NO and NL companies. Others use Priority.   |
| print_and_send_own_pdf      | boolean | Use own PDF images in Print&Send.                                                                                            |
| print_and_send_color        | boolean | Print with colors in Print&Send. Color available for FI, SE, NO and NL companies. Others use black & white.                  |
| print_attachments           | boolean | Enable printing of attachments (true = enabled, false = disabled). The inverse setting, print_attachments_disabled, is also still supported for legacy reason (only one of these parameters should be used).   |
| email_remind_freq           | int     | Frequency of email reminder’s for open invoices in days (e.g. 2)                                                             |
| email                       | string  | Company email                                                                                                                |
| invoice_email               | string  | Company invoice email (inbound invoice notifications)                                                                        |
| errors_to_user              | int     | Send invoice relay errors to the user who was used to send the invoice (1 = enabled, 0 = disabled)                           |
| error_emails                | string  | List of comma separated error emails to notify of invoice relay errors. Even if `errors_to_user` is disabled errors are sent to these addresses. |
| reports                     | int     | E-mail reports activated (0 = disabled, 1 = weekly, 2 = monthly, 3 = daily)                                                  |
| reports_emails              | string  | List of comma separated email addresses to send reports to                                                                   |
| name                        | string  | Name of company, name can't be empty and minimum length three(3) characters                                                  |
| stop_duplicates             | boolean | Prevent (re)sending invoices with the same number                                                                            |
| notify_incoming             | boolean | Enable/disable email notification of incoming invoice. Will be sent to invoice email if defined, else company email          |
| disable_email               | boolean | Enable/disable sending of invoices by email notification. If this is set to true, invoices will only go out as e-invoices or by print. If the only available route for an invoice is email, the invoice will go to error state |
| notifications_disabled      | int     | Enable/disable all e-mail notifications to the company email address, (1 = disable, 0 = enable)                              |
| internal_receive_via_peppol | boolean | Enable/disable internal receive via Peppol. When enabled, all invoices received from companies inside the home network will be converted to EHF/ PEPPOL BIS, routed through the PEPPOL network and validated towards PEPPOL validation rules. If the invoice fails PEPPOL validation, sender will receive an error message and the invoice will not be delivered. |
| send_email_attachments      | int     | With this option we add the invoice image (as PDF) and other attachments on your invoices which get sent by email (total size max 5 megabytes, if larger, recipient is asked to download the attachments from our service using a link provided).   |
| send_invoice_email          | int     | With this option you can decide how the email invoice is sent out. 0 = Do not send invoice via email. 1 = send all invoice e-mails with attachments (max size 5MB). 2 = Send all invoice e-mail with invoice objections. 3 = Send all invoice e-mails with a link to download PDF. 4 = Send all invoice e-mails with attachments (max size 5MB), all PDF attachments and the invoice image merged together in a single PDF file.   |
| invoice_receiving           | int     | Enable/disable invoice receiving, (1 = enabled, 0 = disabled).                                                              |
| invoicing_eia               | string  | Invoicing EIA (Billing information: The delivery method priority is following 1 = eInvoice, 2 = email, 3 = print, if all below values are given. If company prefers invoicing via normal post, invoicing_eia, invoicing_operator and invoicing_email should be left blank). |
| invoicing_operator          | string  | Invoicing operator                                                                                                          |
| invoicing_email             | string  | Invoicing email address                                                                                                     |
| invoicing_street_address1   | string  | Invoicing postal address                                                                                                    |
| invoicing_street_address2   | string  | Invoicing additional postal address                                                                                         |
| invoicing_post_code         | string  | Invoicing post code                                                                                                         |
| invoicing_post_office       | string  | Invoicing post office                                                                                                       |
| billing_company_id          | string  | Company to be set as a billing company                                                                                      |
| message_from_sender         | string  | Only for Norway. Write a message to the invoice receivers that is visible in the recipients e-mail.   |
| b2c_fallback                | string  | Only for B2C NO, can be print or email                                                                                      |
| b2c_reminder                | boolean | Enable/disable B2C NO reminders                                                                                             |
| contact_person              | string  | Contact person, email and phone are shown in the email message when invoice is sent by email                                |
| contact_email               | string  | Contact person, email and phone are shown in the email message when invoice is sent by email                                |
| contact_phone               | string  | Contact person, email and phone are shown in the email message when invoice is sent by email                                |
| scan_notification_interval  | string  | Supplier Activation e-mail interval (Use one of the following to activate the service: ”monthly”, ”weekly”, ”daily”, or to disable the service use something else for example ”disabled”) |
| scan_notification_email     | string  | E-mail address for Supplier Activation e-mail delivery                                                                      |

> [!NOTE]
> **print_attachments setting scope**: This setting only applies for FI, NO and NL companies. Printing of attachments is by default enabled for NO and NL companies, and disabled for FI companies.

> [!WARNING]
> **send_email_attachments notes**: You will not get an acknowledgement of receiving when sending attachments like for normal email invoices. Also, when sending attachments the recipient's email box might get full and then emails are not delivered.

> [!WARNING]
> **send_invoice_email override**: The `send_invoice_email` setting will override `send_email_attachments` and `disable_email` settings.

> [!WARNING]
> **message_from_sender ERP behavior**: If your ERP supports their own message to receiver, the message in the ERP will overwrite this message.

### Output

| Key                | Type           | Description                     |
| ------------------ | -------------- | ------------------------------- |
| return             | string         |                                 |

### Return values

| Key | Type | Message | Description |
| --- | --- | --- | --- |
| return | string | OK | Settings saved successfully |
| | | ERROR: NO RIGHTS TO CHANGE SETTINGS | Only admin user can change settings |
| | | ERROR: COULD NOT SAVE COMPANY SETTINGS | Could not save settings for unknown reason |
| | | ERROR: BILLING E-INVOICING DETAILS INCOMPLETE | E-invoicing address is incomplete: e-invoicing address (invoicing_eia) or operator (invoicing_operator) missing |
| | | ERROR: BILLING EMAIL ADDRESS INVALID | Email address is not valid |
| | | ERROR: BILLING INFORMATION INCOMPLETE | Invoicing postal address is incomplete; address, postcode or postoffice is missing |
| | | ERROR: Cannot update billing company for partner accounts | Partner account can't have billing company |
| | | ERROR: Company cannot be set as its own billing company | |
| | | ERROR: Company is set as a billing company for another company | |
| | | ERROR: Company is linked to an accounting office, billing company cannot be changed | |
| | | ERROR: Invalid billing_company_id | |
| | | ERROR: VAT NUMBER CANNOT BE SET TO BLANK | |
| | | ERROR: INVOICE RECEIVING VALUE IS INVALID | |
| | | ERROR: INVOICE RECEIVING CANNOT BE DISABLED WHEN SCAN ACCOUNT IS OPEN | |
| | | ERROR: B2C REMINDER INVALID | |

## show_company_configuration

Shows current company configuration and available key/value pairs.

Read more about [companies and settings](FIX_LINK_PENDING)

```plain
/v1.1/api/show_company_configuration
```

### Input

**api_keys** — *ApiKeys*

| Key                | Type           | Description                     |
| ------------------ | -------------- | ------------------------------- |
| company_uuid       | string         | UUID of current company         |
| user_api_key       | string         | User API key                    |
| vendor_api_key     | string         | Partner software API key        |

### Output

**return** — *SettingValuesOutArray* (array of SettingValuesOut)

| Key      | Type                 | Description              |
|----------|----------------------|-------------------------|
| status   | string               |                          |
| settings | SettingValueArray    | Array of SettingValue    |

| Key                            | Type    | Description                                                                                                                                         |
|--------------------------------|---------|------------------------------------------------------------------------------------------------------------------------------------------------------|
| website                        | string  | Website of the company                                                                                                                              |
| print_and_send_request         | int     | Print&Send request sent (1=yes,0=no)                                                                                                                |
| print_and_send_letter_class    | integer | Print&Send mail class (1 = Priority, 0 = Economy)                                                                                                   |
| print_and_send_own_pdf         | boolean | Use own PDF images in Print&Send (true/false)                                                                                                       |
| print_and_send_color           | boolean | Print with colors in Print&Send (true/false)                                                                                                        |
| print_attachments              | boolean | Shows if printing of attachments is disabled (false) or enabled (true)                                                                              |
| print_attachments_disabled     | boolean | Shows if printing of attachments is disabled (true) or enabled (false)                                                                              |
| email_remind_freq              | int     | Frequency of email reminder’s for open invoices in days (e.g. 2)                                                                                    |
| email                          | string  | Company email                                                                                                                                       |
| invoice_email                  | string  | Company invoice email (inbound invoice notifications)                                                                                               |
| errors_to_user                 | int     | Send invoice relay errors to users or just error email? (1=yes,0=no)                                                                                |
| error_emails                   | string  | E-mail address for invoice errors                                                                                                                   |
| reports                        | int     | E-mail reports activated (0 = no, 1 = weekly, 2 = monthly, 3 = daily)                                                                               |
| reports_emails                 | string  | E-mail for send reports                                                                                                                             |
| name                           | string  | Name of the company                                                                                                                                 |
| bid                            | string  | Business ID, VAT, organization number etc.                                                                                                          |
| country                        | string  | Country of the company                                                                                                                              |
| stop_duplicates                | boolean | Prevent (re)sending invoices with the same number (true/false)                                                                                      |
| notify_incoming                | boolean | E-mail notification of incoming invoice (true/false)                                                                                                |
| disable_email                  | boolean | Sending of invoices by email notification. (true/false)                                                                                             |
| notifications_disabled         | int     | Enable/disable all e-mail notifications to the company email address, (1=disable, 0=enable)                                                         |
| internal_receive_via_peppol    | boolean | Internal receiving via Peppol (true/false)                                                                                                          |
| send_email_attachments         | int     | Send the invoice image as attachment (true/false)                                                                                                   |
| send_invoice_email             | int     | Shows which email invoice sending method is in use. 0 = Do not send invoice via email. 1 = send all invoice e-mails with attachments (max size 5MB). 2 = Send all invoice e-mail with invoice objections. 3 = Send all invoice e-mails with a link to download PDF. 4 = Send all invoice e-mails with attachments (max size 5MB), all PDF attachments and the invoice image merged together in a single PDF file. Note! This setting will override send_email_attachments and disable_email settings |
| invoice_receiving              | int     | Invoice receiving status, (1=enabled, 0=disabled)                                                                                                   |
| invoicing_eia                  | string  | invoicing EIA                                                                                                                                       |
| invoicing_operator             | string  | invoicing operator.                                                                                                                                 |
| invoicing_email                | string  | invoicing email address.                                                                                                                            |
| invoicing_street_address1      | string  | invoicing postal address.                                                                                                                           |
| invoicing_street_address2      | string  | invoicing additional postal address.                                                                                                                |
| invoicing_post_code            | string  | invoicing post code.                                                                                                                                |
| invoicing_post_office          | string  | invoicing post office.                                                                                                                              |
| billing_company_id             | string  | Billing company id that handles the invoicing of the company                                                                                        |
| print_and_send_enabled         | string  | Print&Send enabled (true/false)                                                                                                                     |
| vat_number                     | string  | Is the Norwegian company VAT registered, returns the VAT number                                                                                     |
| default_receive_vendor_api_key | string  | Default vendor API key for receiving                                                                                                                |
| default_send_vendor_api_key    | string  | Default vendor API key for sending                                                                                                                  |
| peppol_id                      | string  | Peppol ID for the company                                                                                                                           |
| bank_send                      | string  | Is the bank network connection open or not (true/false)                                                                                             |
| marketing_on_invoice           | string  | Electronic invoicing instruction page/marketing page enabled (true/false)                                                                           |
| message_from_sender            | string  | Message from sender that is visible in the e-mail invoices                                                                                          |
| scan_return_email              | string  | Email address for returned scan material if scan account exists (active or disabled)                                                                |
| scan_return_postal             | string  | Postal address for returned scan material if scan account exists (active or disabled)                                                               |
| b2c_fallback                   | string  | Shows B2C NO fallback route . (print/email)                                                                                                         |
| b2c_reminder                   | boolean | Shows if B2C NO reminders are enabled or disabled. (true/false)                                                                                     |
| contact_person                 | string  | Shows contact person that is shown in the email message when invoice is sent by email                                                               |
| contact_email                  | string  | Shows contact email that is shown in the email message when invoice is sent by email                                                                |
| contact_phone                  | string  | Shows contact phone that is shown in the email message when invoice is sent by email                                                                |
| scan_notification_interval     | string  | Supplier Activation e-mail interval (Service is enabled if one of the following is returned: ”monthly”, ”weekly”, ”daily” or disabled if ”disabled” |
| scan_notification_email        | string  | E-mail address for Supplier Activation e-mail delivery                                                                                              |

### Return values

| Key    | Type   | Message | Description |
|--------|--------|---------|-------------|
| status | string | OK      |             |

## company_show

Used for showing current company information.

Read more about [companies and settings](FIX_LINK_PENDING)

```plain
/v1.1/api/company_show
```

### Input

api_keys (ApiKeys)

| Key                | Type           | Description                     |
| :----------------- | :------------- | :------------------------------ |
| company_uuid       | string         | UUID of current company         |
| user_api_key       | string         | User API key                    |
| vendor_api_key     | string         | Partner software API key        |

### Output

return (CompanyParamsOut)

| Key        | Type   | Description |
| :--------- | :----- | :---------- |
| email      | string |             |
| status     | string |             |
| name       | string |             |
| maventa_id | string |             |
| bid        | string |             |
| id         | string |             |
| country    | string |             |

### Return values

| Key     | Type   | Message                          | Description                                          |
| :------ | :----- | :------------------------------- | :--------------------------------------------------- |
| status  | string | OK                               |                                                      |
|         |        | ERROR: COMPANY ACCOUNT IS LOCKED | Company's account is locked and can't be used       |
|         |        | ERROR: USER NOT FOUND            |                                                      |
|         |        | ERROR: UNKNOWN ERROR             |                                                      |

## company_invoice_receiving

Enable/disable receiving of invoices. Read more about [invoice receiving](FIX_LINK_PENDING#receiving)

```plain
/v1.1/api/company_invoice_receiving
```

### Input

**api_keys** - ApiKeys

| Key          | Type    | Description              |
| ------------ | ------- | ------------------------ |
| company_uuid | string  | UUID of current company  |
| user_api_key | string  | User API key             |
| vendor_api_key | string | Partner software API key |

| Key     | Type    | Description |
| ------- | ------- | ----------- |
| receive | boolean |             |

FIX_IMAGE_PENDING

### Output

| Key    | Type   | Description |
| ------ | ------ | ----------- |
| return | string |             |

FIX_IMAGE_PENDING

### Return values

| Key    | Type   | Message                                                          | Description |
| ------ | ------ | ---------------------------------------------------------------- | ----------- |
| return | string | OK                                                               |             |
|        |        | ERROR: USER NOT FOUND                                            |             |
|        |        | ERROR: INVOICE RECEIVING CANNOT BE DISABLED WHEN SCAN ACCOUNT IS OPEN |             |
|        |        | ERROR: UNKNOWN ERROR                                             |             |

## enable_operator

Enables operator connections that require it done separately. Currently needed for PEPPOL receiving.

```plain
/v1.1/api/enable_operator
```

### Input

**api_keys** (ApiKeys)

| Key            | Type   | Description             |
|:---------------|:-------|:------------------------|
| company_uuid   | string | UUID of current company |
| user_api_key   | string | User API key            |
| vendor_api_key | string | Partner software API key|

**operator_struct** (OperatorStruct)

| Key          | Type    | Description                                                                              |
|:-------------|:--------|:-----------------------------------------------------------------------------------------|
| operator_id  | string  | Operator name/code. For peppol network use PEPPOL                                        |
| enabled      | boolean | Enable or disable. When set to false, will remove both invoice and credit note receiving |
| sender_id    | string  | Sender ID if needed (not needed for PEPPOL)                                              |
| recipient_id | string  | Recipient ID if needed (not needed for PEPPOL)                                           |

### Output

| Key    | Type   | Description |
|:-------|:-------|:------------|
| status | string |             |

### Return values

| Key    | Type   | Message                                                                            | Description |
|:-------|:-------|:-----------------------------------------------------------------------------------|:------------|
| return | string | OK                                                                                 |             |
|        |        | ERROR: USER NOT FOUND                                                              |             |
|        |        | ERROR: [OPERATOR] CANNOT BE ENABLED WHILE RECEIVING INVOICES IS DISABLED           |             |

## company_list

Used for listing all the companies user has access to.

```plain
/v1.1/api/company_list
```

### Input

**api_keys** — ApiKeys

| Key              | Type   | Description             |
| :--------------- | :----- | :---------------------- |
| company_uuid     | string | UUID of current company |
| user_api_key     | string | User API key            |
| vendor_api_key   | string | Partner software API key |

### Output

**return** — CompanyParamsOutArray (Array of CompanyParamsOut)

| Key          | Type   | Description |
| :----------- | :----- | :---------- |
| email        | string |             |
| status       | string |             |
| user_api_key | string |             |
| name         | string |             |
| maventa_uuid | string |             |
| maventa_id   | string |             |
| bid          | string |             |
| id           | string |             |
| country      | string |             |

### Return values

| Key    | Type   | Message              | Description |
| :----- | :----- | :------------------- | :---------- |
| status | string | OK                   |             |
|        |        | ERROR: USER NOT FOUND |             |
|        |        | ERROR: UNKNOWN ERROR |             |

## update_logo

Used for uploading company logo to Maventa for PDF template output when PDF template is not generated in ERP.

> [!NOTE]
> **Supported formats:** Most image formats are supported, but not PDF. JPEG or PNG is preferred.
>
> **Note:** PNG with transparency is not supported.

Read more about [logo usage from the printing guide](FIX_LINK_PENDING)

```plain
/v1.1/api/update_logo
```

### Input

**api_keys** (ApiKeys)

| Key             | Type   | Description               |
| --------------- | ------ | ------------------------- |
| company_uuid    | string | UUID of current company   |
| user_api_key    | string | User API key              |
| vendor_api_key  | string | Partner software API key  |

**company_logo_params** (CompanyLogoParams)

| Key    | Type   | Description                 |
| ------ | ------ | --------------------------- |
| logo   | base64 | Company logofile            |
| logo_h | int    | deprecated, not used anymore |
| logo_w | int    | deprecated, not used anymore |
| logo_x | int    | deprecated, not used anymore |
| logo_y | int    | deprecated, not used anymore |

FIX_IMAGE_PENDING

### Output

| Key    | Type   | Description |
| ------ | ------ | ----------- |
| return | string |             |

FIX_IMAGE_PENDING

### Return values

| Key    | Type   | Message                        | Description              |
| ------ | ------ | ------------------------------ | ------------------------ |
| return | string | OK                             |                          |
|        |        | ERROR: COULD NOT UPDATE LOGO   | File format not supported |
|        |        | ERROR: COULD NOT SAVE SETTINGS |                          |

## remove_logo

Removes uploaded logo for company.

Read more about [logo usage from the printing guide](FIX_LINK_PENDING)

```plain
/v1.1/api/remove_logo
```

### Input

*api_keys* *ApiKeys*

| Key              | Type   | Description             |
| ---------------- | ------ | ----------------------- |
| company_uuid     | string | UUID of current company |
| user_api_key     | string | User API key            |
| vendor_api_key   | string | Partner software API key|

### Output

| Key    | Type   | Description |
| ------ | ------ | ----------- |
| return | string |             |

### Return values

| Key    | Type   | Message                         | Description               |
| ------ | ------ | ------------------------------- | ------------------------- |
| status | string | OK                              |                           |
|        |        | ERROR: COULD NOT SAVE SETTINGS  | Logo could not be removed |

## token_login

Returns a URL to access the web UI without needing to login.

Currently supports service parameter: **FI_BANK_NETWORK_OPEN** for opening Finnish bank network and **COMPANY_SETTINGS** for accessing setting page for given company.

Read more about [companies and settings](FIX_LINK_PENDING)

```plain
/v1.1/api/token_login
```

### Input

api_keys - ApiKeys

| Key            | Type   | Description              |
| --------------- | ------ | ----------------------- |
| company_uuid   | string | UUID of current company  |
| user_api_key   | string | User API key             |
| vendor_api_key | string | Partner software API key |
| service        | string |                          |

### Output

| Key    | Type   | Description |
| ------ | ------ | ----------- |
| return | string |             |

### Return values

| Key    | Type   | Message                                     | Description                                        |
| ------ | ------ | ------------------------------------------- | -------------------------------------------------- |
| return | string | https://…                                   | Successfull request, URL can be accessed           |
|        |        | ERROR: No rights to sign bank agreements    | User API key is for normal user                    |
|        |        | ERROR: Only available for Finnish companies | Company uuid is for none Finnish company           |
|        |        | ERROR: Bank agreement already active        | Company has already bank network connection        |
|        |        | ERROR: Bank agreement already pending       | Company has already order the bank network opening |

## link_vendor_api_key

Link company account to a vendor_api_key like company was registered using API with that vendor_api_key.

Read more about [vendor api keys](FIX_LINK_PENDING)

```plain
/v1.1/api/link_vendor_api_key
```

### Input

*api_keys* *ApiKeys*

| Key            | Type   | Description                  |
|----------------|--------|------------------------------|
| company_uuid   | string | UUID of current company      |
| user_api_key   | string | User API key                 |
| vendor_api_key | string | Partner software API key     |

### Output

| Key    | Type   | Description            |
|--------|--------|------------------------|
| return | string | "OK" or "ERROR: …"     |

### Return values

| Key    | Type   | Message                        |
|--------|--------|--------------------------------|
| return | string | OK                             |
|        |        | ERROR: NO VENDOR API KEY GIVEN |
|        |        | ERROR: COULD NOT SAVE CHANGES  |

## unlink_vendor_api_key

Unlinks company from vendor_api_key if company stops using ERP.

Read more about [vendor api keys](FIX_LINK_PENDING)

```plain
/v1.1/api/unlink_vendor_api_key
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                 |
| -------------- | ------ | --------------------------- |
| company_uuid   | string | UUID of current company     |
| user_api_key   | string | User API key                |
| vendor_api_key | string | Partner software API key    |

### Output

| Key    | Type   | Description        |
| ------ | ------ | ------------------ |
| return | string | "OK" or "ERROR: …" |

### Return values

| Key    | Type   | Message                                          |
| ------ | ------ | ------------------------------------------------ |
| return | string | OK                                               |
|        |        | ERROR: COMPANY NOT ASSIGNED TO GIVEN VENDOR API KEY |

<!-- markdownlint-disable-next-line MD041 -->
## list_vendor_inbound_invoices

Allows vendor to list inbound invoices of companies linked to their vendor_api_key.

Read more about [invoice receiving](FIX_LINK_PENDING)

```plain
/v1.1/api/list_vendor_inbound_invoices
```

### Input

api_keys (ApiKeys)

| Key              | Type     | Description              |
|:-----------------|:---------|:------------------------:|
| company_uuid     | string   | UUID of current company  |
| user_api_key     | string   | User API key             |
| vendor_api_key   | string   | Partner software API key |

### Output

items (InboundInvoiceList)

| Key    | Type                        | Description                    |
|:-------|:---------------------------|:-------------------------------|
| status | string                      | Status                         |
| items  | InboundInvoiceListItemArray | Array of InboundInvoiceListItem |

items (InboundInvoiceListItemArray)

| Key          | Type   | Description                                                                                  |
|:-------------|:-------|:--------------------------------------------------------------------------------------------:|
| invoice_id   | string | Unique ID of invoice, to be used in method inbound_invoice_show                              |
| recipient_id | string | company_uuid of recipient company                                                            |
| timestamp    | string | Timestamp when invoice was received on account, is what is checked against with the list methods timestamps |

### Return values

| Key    | Type   | Message                            | Description |
|:-------|:-------|:-----------------------------------|:------------|
| status | string | OK                                 |             |
|        |        | ERROR: TIMESTAMP START FORMAT ERROR |             |
|        |        | ERROR: TIMESTAMP END FORMAT ERROR   |             |
|        |        | ERROR: NO RIGHTS TO VENDOR API KEY  |             |

## user_create_e

Used for creating a new or adding an existing user to a company.

After a new user creation an activation message will be sent to the given email address. This message will also include a randomly generated password for the user.

If on the user_create_e call either of the parameters notifications_disabled or emails_disabled is set as false, the account will not be usable until the user account is activated via accessing a link in the email.

If on the user_create_e call both parameters notifications_disabled and emails_disabled are set to true, the account will be activated immediately and no email activation is required. This is the recommended process for API only integrations.

Read more about [companies and users](FIX_LINK_PENDING)

```plain
/v1.1/api/user_create_e
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                  |
|:---------------|:-------|:-----------------------------|
| company_uuid   | string | UUID of current company      |
| user_api_key   | string | User API key                 |
| vendor_api_key | string | Partner software API key     |

user_params (UserParamsIn)

| Key                    | Type    | Description                                                                                                                             |
|:-----------------------|:--------|:----------------------------------------------------------------------------------------------------------------------------------------|
| email                  | string  | Email address, needs to be unique                                                                                                       |
| user_role              | string  | Role can be ADMIN or USER. ADMIN has access to company settings etc.                                                                    |
| first_name             | string  | First name for user, mandatory                                                                                                          |
| last_name              | string  | Last name of user, mandatory                                                                                                            |
| phone                  | string  | Phone number                                                                                                                             |
| notifications_disabled | boolean | If set to true, user will not receive e-mail notifications for their invoices e.g. when receiver accepts invoice etc. (only applies inside Maventa network) |
| emails_disabled        | boolean | If set to true, user will not receive any e-mail notifications e.g. invoice send errors and such.                                      |

### Output

| Key    | Type   |
|:-------|:-------|
| return | string |

### Return values

| Key    | Type   | Message                       | Description                                                                              |
|:-------|:-------|:------------------------------|:--------------------------------------------------------------------------------------------------|
| return | string | OK: USER ADDED                | When an existing user added to the company. The API key is not returned here for security reasons |
|        |        | 36 char uuid                  | API key for a new user                                                                   |
|        |        | ERROR: NO RIGHTS TO ADD USERS | Only admin user can add new users                                                       |
|        |        | ERROR: @errormessage          | Error message with validation errors for the user                                       |

## user_list

Used for listing your company's users.

```plain
/v1.1/api/user_list
```

### Input

api_keys (ApiKeys)

| Key              | Type     | Description                   |
|:-----------------|:---------|:------------------------------|
| company_uuid     | string   | UUID of current company       |
| user_api_key     | string   | User API key                  |
| vendor_api_key   | string   | Partner software API key      |

FIX_XML_REQUEST_PENDING

### Output

return (UserParamsOutArray - Array of UserParamsOut)

| Key        | Type   |
|:-----------|:-------|
| status     | string |
| email      | string |
| user_role  | string |
| first_name | string |
| last_name  | string |
| phone      | string |
| id         | string |

FIX_XML_RESPONSE_PENDING

### Return values

| Key    | Type   | Message              |
|:-------|:-------|:---------------------|
| status | string | OK                   |
|        |        | ERROR: UNKNOWN ERROR |

## user_show

Used for showing information about a specific user.

```plain
/v1.1/api/user_show
```

### Input

**api_keys** (ApiKeys)

| Key            | Type   | Description               |
|:---------------|:-------|:--------------------------|
| company_uuid   | string | UUID of current company   |
| user_api_key   | string | User API key              |
| vendor_api_key | string | Partner software API key  |

| Key | Type   | Description                                                                                                                               |
|:----|:-------|:------------------------------------------------------------------------------------------------------------------------------------------|
| id  | string | Optional. Id of the user whuich information to return. If parameter is not given, information of the authenticating user will be returned |

### Output

**return** (UserParamsOut)

| Key        | Type   |
|:-----------|:-------|
| status     | string |
| email      | string |
| user_role  | string |
| first_name | string |
| last_name  | string |
| phone      | string |
| id         | string |

### Return values

| Status                   | Type   | Message                      |
|:-------------------------|:-------|:-----------------------------|
| OK                       | string | Success                      |
| ERROR: NO RIGHTS TO USER | string | User has no rights           |
| ERROR: UNKNOWN ERROR     | string | An unexpected error occurred |

## user_update_e

Used for updating users details on your company account. You cannot update a user's email address through the API.

```plain
/v1.1/api/user_update_e
```

### Input

**api_keys** **ApiKeys**

| Key            | Type   | Description              |
|:---------------|:-------|:--------------------------|
| company_uuid   | string | UUID of current company  |
| user_api_key   | string | User API key             |
| vendor_api_key | string | Partner software API key |

| Key | Type   |
|:----|:-------|
| id  | string |

**user_params** **UserParamsIn**

| Key                    | Type    | Description                                                                                                         |
|:-----------------------|:--------|:-----------------------------------------------------------------------------------------------------------------------|
| email                  | string  |                                                                                                                     |
| user_role              | string  |                                                                                                                     |
| first_name             | string  |                                                                                                                     |
| last_name              | string  |                                                                                                                     |
| phone                  | string  |                                                                                                                     |
| notifications_disabled | boolean | If set to true, user will not receive e-mail notifications for their invoices e.g. when receiver accepts invoice etc. (only applies inside Maventa network) |
| emails_disabled        | boolean | If set to false, user will not receive any e-mail notifications e.g. invoice send errors and such.                  |

### Output

| Key    | Type   | Description |
|:-------|:-------|:------------|
| return | string |             |

### Return values

| Key    | Type   | Message                         | Description                                                      |
|:-------|:-------|:--------------------------------|:------------------------------------------------------------------|
| return | string | OK: USER SAVED                  | User updated successfully                                        |
|        |        | ERROR: USER COULD NOT BE SAVEDS | User could not be saved for some reason                          |
|        |        | ERROR: NO RIGHTS TO USER        | Only the user in question or an admin can update user information |
|        |        | ERROR: USER NOT FOUND           | User with given user_id was not found                            |

## user_delete

Used for deleting user from your company account. You cannot delete your own account.

```plain
/v1.1/api/user_delete
```

### Input

**api_keys** ApiKeys

| Key            | Type   | Description                 |
|:---------------|:-------|:----------------------------|
| company_uuid   | string | UUID of current company     |
| user_api_key   | string | User API key                |
| vendor_api_key | string | Partner software API key    |

| Key | Type   | Description |
|:----|:-------|:------------|
| id  | string |             |

FIX_INCLUDE_PENDING

### Output

| Key    | Type   | Description |
|:-------|:-------|:------------|
| return | string |             |

FIX_INCLUDE_PENDING

### Return values

| Key    | Type   | Message                        | Description                                      |
|:-------|:-------|:-------------------------------|:-------------------------------------------------|
| status | string | OK: USER DELETED FROM COMPANY  | User deleted successfully                        |
|        |        | ERROR: NO RIGHTS TO USER       | Only an admin can delete users                   |
|        |        | ERROR: USER NOT FOUND          | User with given user_id was not found            |
|        |        | ERROR: CANNOT DELETE YOURSELF  | User cannot delete himself                       |
|        |        | ERROR: COULD NOT DELETE USER   | User could not be deleted for somea reason       |

## postal_address_create

Used for adding a postal address for the company.

```plain
/v1.1/api/postal_address_create
```

### Input

*api_keys* *ApiKeys*

| Key            | Type   | Description                 |
|:---------------|:-------|:----------------------------|
| company_uuid   | string | UUID of current company     |
| user_api_key   | string | User API key                |
| vendor_api_key | string | Partner software API key    |

*company_postal* *PostalAddressParamsIn*

| Key          | Type    |
|:-------------|:--------|
| default      | boolean |
| company_name | string  |
| lang         | string  |
| state        | string  |
| post_code    | string  |
| post_office  | string  |
| phone        | string  |
| address1     | string  |
| gsm          | string  |
| address2     | string  |
| country      | string  |
| city         | string  |
| fax          | string  |

### Output

| Key    | Type   |
|:-------|:-------|
| return | string |

### Return values

| Key    | Type   | Message                                                             | Description                                                        |
|:-------|:-------|:--------------------------------------------------------------------|:-------------------------------------------------------------------|
| status | string | OK: POSTAL ADDRESS SAVED                                            | Postal address created successfully                                |
|        |        | ERROR: @errormessage                                                | Error message with validation errors for the postal address        |
|        |        | ERROR: COMPANY ALREADY HAS ADDRESS INFORMATION FOR @country / @lang | Company can only have one postal address for each country/language |
|        |        | ERROR: COUNTRY CODE INVALID                                         | Given country code does not exist or is not supported              |

## postal_address_list

Used for listing all the company’s postal addresses.

```plain
/v1.1/api/postal_address_list
```

### Input

**api_keys** *ApiKeys*

| Key                | Type           | Description                     |
| ------------------ | -------------- | ------------------------------- |
| company_uuid       | string         | UUID of current company         |
| user_api_key       | string         | User API key                    |
| vendor_api_key     | string         | Partner software API key        |

FIX_EXAMPLE_PENDING

### Output

**return** *PostalAddressParamsOutArray* (Array of PostalAddressParamsOut)

| Key         | Type    |
|-------------|---------|
| status      | string  |
| default     | boolean |
| lang        | string  |
| state       | string  |
| post_code   | string  |
| phone       | string  |
| post_office | string  |
| address1    | string  |
| gsm         | string  |
| city        | string  |
| country     | string  |
| id          | string  |
| address2    | string  |
| fax         | string  |

FIX_EXAMPLE_PENDING

### Return values

| Key         | Type    | Message              |
|-------------|---------|----------------------|
| status      | string  | OK                   |
|             |         | ERROR: UNKNOWN ERROR |

## postal_address_show

Used displaying information for a specific postal address.

```plain
/v1.1/api/postal_address_show
```

### Input

*api_keys* *ApiKeys*

| Key          | Type   | Description                 |
|:-------------|:-------|:----------------------------|
| company_uuid | string | UUID of current company     |
| user_api_key | string | User API key                |
| vendor_api_key | string | Partner software API key    |

| Key | Type   | Description                                                                                              |
|:----|:-------|:---------------------------------------------------------------------------------------------------------|
| id  | string | ID of the postal address to show. Postal address IDs can be fetched with the postal_address_list method. |

### Output

*return* *PostalAddressParamsOut*

| Key         | Type    |
|:------------|:--------|
| status      | string  |
| default     | boolean |
| lang        | string  |
| state       | string  |
| post_code   | string  |
| phone       | string  |
| post_office | string  |
| address1    | string  |
| gsm         | string  |
| city        | string  |
| country     | string  |
| id          | string  |
| address2    | string  |
| fax         | string  |

### Return values

| Key    | Type   | Message                                        |
|:-------|:-------|:-----------------------------------------------|
| status | string | OK                                             |
|        |        | ERROR: POSTAL ADDRESS NOT FOUND OR NO RIGHTS   |
|        |        | ERROR: UNKNOWN ERROR                           |

## postal_address_update

Used for updating an existing postal address.

```plain
/v1.1/api/postal_address_update
```

### Input

**api_keys** (ApiKeys)

| Key            | Type     | Description                 |
|:---------------|:---------|:----------------------------|
| company_uuid   | string   | UUID of current company     |
| user_api_key   | string   | User API key                |
| vendor_api_key | string   | Partner software API key    |

| Key | Type   | Description                                                                                                                                                    |
|:----|:-------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| id  | string | ID of the postal address to update. If set to nil, will default to the default address. Postal address IDs can be fetched with the postal_address_list method. |

**company_postal** (PostalAddressParamsIn)

| Key          | Type    |≤≤
|:-------------|:--------|
| default      | boolean |
| company_name | string  |
| lang         | string  |
| state        | string  |
| post_code    | string  |
| post_office  | string  |
| phone        | string  |
| address1     | string  |
| gsm          | string  |
| address2     | string  |
| country      | string  |
| city         | string  |
| fax          | string  |

### Output

| Key    | Type   |
|:-------|:-------|
| return | string |

### Return values

| Key    | Type   | Message                                                             | Description                                                                                    |
|:-------|:-------|:--------------------------------------------------------------------|:-----------------------------------------------------------------------------------------------|
| status | string | OK: POSTAL ADDRESS SAVED                                            | Postal address updated successfully                                                            |
|        |        | ERROR: POSTAL ADDRESS NOT FOUND OR NO RIGHTS                        | Given postal_address_id not found for current company                                        |
|        |        | ERROR: COUNTRY CODE INVALID                                         | Given country code does not exist or is not supported                                         |
|        |        | ERROR: COMPANY ALREADY HAS ADDRESS INFORMATION FOR @country / @lang | Company can only have one postal address for each country and language pair                 |
|        |        | ERROR: @errormessage                                                | Error message with validation errors for the postal address                                   |

## postal_address_delete

Used for deleting postal address.

```plain
/v1.1/api/postal_address_delete
```

### Input

*api_keys* *ApiKeys*

| Key          | Type   | Description             |
|:-------------|:-------|:------------------------|
| company_uuid | string | UUID of current company |
| user_api_key | string | User API key            |
| vendor_api_key | string | Partner software API key |

| Key | Type   | Description |
|:----|:-------|:------------|
| id  | string |             |

### Output

| Key    | Type   | Description |
|:-------|:-------|:------------|
| return | string |             |

### Return values

| Key    | Type   | Message                                      | Description                                           |
|:-------|:-------|:---------------------------------------------|:------------------------------------------------------|
| status | string | OK: POSTAL ADDRESS DELETED                   | Postal address deleted successfully                   |
|        |        | ERROR: COULD NOT DELETE POSTAL ADDRESS       | Postal address could not be deleted                   |
|        |        | ERROR: POSTAL ADDRESS NOT FOUND OR NO RIGHTS | Given postal_address_id not found for current company |

## scan_account_order

Open a new scan account for your company or for updating already existing one when called again. If first time ordering is successful, returns the scan address where suppliers send their invoices (paper or email).

> [!WARNING]
> It is very important to give suppliers the full returned scanning address. Also note that you cannot open a scan account if your account has receiving e-invoices turned off.

When called again for already existing scan account, will return OK: RETURN ADDRESS UPDATED

> [!IMPORTANT]
> User accepts the pricing including scan minimum fee when opening the account.

Read more about [FIX_LINK_PENDING](FIX_LINK_PENDING)

```plain
/v1.1/api/scan_account_order
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                     |
|:---------------|:-------|:--------------------------------|
| company_uuid   | string | UUID of current company         |
| user_api_key   | string | User API key                    |
| vendor_api_key | string | Partner software API key        |

return_address (ScanAddress)

Your company’s postal address. Given to scan provider so they can return mail which is not proper invoices that have been sent to scanning address (like contracts etc.)

| Key         | Type   | Description                                              |
|:------------|:-------|:---------------------------------------------------------|
| name        | string |                                                          |
| address1    | string | either address1 or address2 mandatory                    |
| address2    | string |                                                          |
| post_code   | string | mandatory                                                |
| post_office | string | mandatory                                                |
| state       | string |                                                          |
| country     | string | mandatory                                                |
| email       | string | for sending notifications in error situations, mandatory |

### Output

return (ScanAccountParamsOut)

| Key     | Type        | Description                                                                             |
|:--------|:------------|:----------------------------------------------------------------------------------------|
| status  | string      | Status                                                                                  |
| address | ScanAddress | Company's scanning address (i.e the address suppliers should use when sending invoices) |

address (ScanAddress)

| Key         | Type   | Description                                                                  |
|:------------|:-------|:-----------------------------------------------------------------------------|
| name        | string |                                                                              |
| address1    | string | For sending non-invoice material that has been sent to your scanning address and cannot be sent to your return email address (e.g. packages)                                           |
| address2    | string |                                                                              |
| post_code   | string |                                                                              |
| post_office | string |                                                                              |
| state       | string |                                                                              |
| country     | string |                                                                              |
| email       | string | For sending non-invoice material that has been sent to your scanning address |

### Return values

| Key    | Type   | Message                                                                                    | Description                                                                                                                                 |
|:-------|:-------|:-------------------------------------------------------------------------------------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|
| status | string | OK                                                                                         | Scan account opened, return value includes address information of the new scan account                                                    |
|        |        | OK: RETURN ADDRESS UPDATED                                                                 |                                                                                                                                           |
|        |        | ERROR: REGISTRATION FAILED                                                                 | Unexpected error, contact support                                                                                                       |
|        |        | ERROR: SCAN ACCOUNT EXISTS                                                                 | Company already has a scan account, you can have only one                                                                                |
|        |        | ERROR: SCAN ACCOUNT CURRENTLY AVAILABLE FOR FINNISH, NORWEGIAN, SWEDISH, DANISH AND DUTCH COMPANIES ONLY |                                                                                                                                           |
|        |        | ERROR: RETURN ADDRESS EMPTY OR INVALID                                                    |                                                                                                                                           |
|        |        | ERROR: RECEIVING INVOICES NOT ENABLED ON ACCOUNT                                          |                                                                                                                                           |
|        |        | ERROR: INVALID SCAN RETURN EMAIL DOMAIN                                                   |                                                                                                                                           |
|        |        | ERROR: SCAN ACCOUNT ACTIVATION FAILED MAVENTA SUPPORT WILL CONTACT YOU TO RESOLVE THE ISSUE | The scan account activation has failed and you will be contacted to help resolve the issue an activate the account.                    |
|        |        | ERROR: SCAN ACCOUNT ACTIVATION IS PENDING                                                 | The scan account is pending activation before it will be available to use.                                                              |
|        |        | ERROR: COMPANY DATA MISSING                                                                | In order to activate the scan account please make sure your company address information is complete (address, postal code, city, email) and you have filled in the return addresses. |
|        |        | ERROR: UNKNOWN ERROR                                                                       |                                                                                                                                           |

## scan_account_show

Show company's scanning address (i.e the address suppliers should use when sending invoices).

> [!WARNING]
> **Important!** It is very important to give suppliers the full returned scanning address.

Read more about [scanning](FIX_LINK_PENDING)

```plain
/v1.1/api/scan_account_show
```

### Input

**api_keys** - ApiKeys

| Key                | Type           | Description                     |
| :----------------- | :------------- | :------------------------------ |
| company_uuid       | string         | UUID of current company         |
| user_api_key       | string         | User API key                    |
| vendor_api_key     | string         | Partner software API key        |

### Output

**return** - ScanAddress

| Key         | Type   | Description                                   |
| :---------- | :----- | :-------------------------------------------- |
| status      | string | Status                                        |
| name        | string |                                               |
| address1    | string |                                               |
| address2    | string |                                               |
| post_code   | string |                                               |
| post_office | string |                                               |
| state       | string |                                               |
| country     | string |                                               |
| email       | string | For sending PDFs per email for interpretation |

### Return values

| Key    | Type   | Message                         |
| :----- | :----- | :------------------------------- |
| status | string | OK                              |
|        |        | ERROR: SCAN ACCOUNT DISABLED    |
|        |        | ERROR: SCAN ACCOUNT NOT FOUND   |
|        |        | ERROR: USER NOT FOUND           |

## scan_account_disable

Close scan account.

Read more about [scanning](FIX_LINK_PENDING)

```plain
/v1.1/api/scan_account_disable
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                 |
|:---------------|:-------|:----------------------------|
| company_uuid   | string | UUID of current company     |
| user_api_key   | string | User API key                |
| vendor_api_key | string | Partner software API key    |

### Output

| Key    | Type   | Description |
|:-------|:-------|:------------|
| return | string |             |

### Return values

| Key    | Type   | Message                                                    |
|:-------|:-------|:-----------------------------------------------------------|
| status | string | OK                                                         |
|        |        | ERROR: Scan account not found                              |
|        |        | ERROR: Multiple scan accounts found, please contact support |
|        |        | ERROR: Unexpected error, contact customer support         |

---

## Invoice Sending API Methods
Source: https://documentation.maventa.com/api-specification/soap-api/invoice-sending-api-methods/

API methods for [invoice sending](/integration-guide/invoice-sending/invoice-sending/). For new integrations, we recommend using the [REST API](/api-specification/rest-api/invoices-api/) instead.

## company_lookup_with_operator

Used for finding recipient's invoicing information from Maventa, it doesn't do any external lookups. Differs from company_lookup only by returning also *operator_code* inside `edis` value.

```plain
/v1.1/api/company_lookup_with_operator
```

### Input

**api_keys** - *ApiKeys*

| Key          | Type   | Description             |
|:-------------|:-------|:------------------------|
| company_uuid | string | UUID of current company |
| user_api_key | string | User API key            |
| vendor_api_key | string | Partner software API key |

**company_lookup_params** - *CompanyLookupParams*

| Key          | Type    | Description |
|:-------------|:--------|:------------|
| search_string | string | Search string can be company name, BID (organisation number), VAT code or e-invoice address (EDI, OVT, EAN, GLN…) |
| country_code | string | Limit hits to specific country. If left blank, returns hits from all countries |
| limit | int | Maximum number of results to return, default 20 and maximum 200 |
| disable_vies | boolean | Disable external directory lookup fallback when no results from Maventa Network. If set to false or left blank, Maventa will do queries on external services if no match is found in Maventa Finder, this might slow down query. |

FIX_IMAGE_PENDING

### Output

**company_lookup_with_operatorResponse** - *CompanyLookupOutExtendedArray*

| Key | Type | Description |
|:----|:-----|:------------|
| status | string | |
| edis | ElectronicInvoiceAddressArray | ElectronicInvoiceAddress content is two strings, 'eia' with the electronic invoice address and 'operator_code' |
| name | string | |
| state | string | |
| post_code | string | |
| post_office | string | |
| maventa_id | string | |
| bid | string | |
| address1 | string | |
| country | string | |
| address2 | string | |
| receive_invoices | boolean | Can only be true for Maventa network users (e.g. maventa_id field is not blank), for all others this is always false and does not necessarily mean they cannot receive e-invoices |
| receive_orders | boolean | Only applies for Maventa network users |

### Return values

| Key | Type | Message | Description |
|:----|:-----|:--------|:------------|
| status | string | OK | |
| | | ERROR: NO RESULTS | |
| | | ERROR: TOO MANY RESULTS | If result set contains more than 200 hits |
| | | ERROR: SEARCH STRING BLANK OR TOO SHORT (MIN 3 CHARS) | |

## list_operators

Lists currently supported roaming operators and their operator codes.  

```plain
/v1.1/api/list_operators
```

### Input

list_operators

### Output

*return* *OperatorInfoArray*

| Key         | Type   | Description   |
|-------------|--------|---------------|
| operator_id | string | Operator code |
| name        | string | Operator name |

## invoice_put_invoice_with_metadata

Used for creating new invoices from existing XML invoice files or ZIP files with XML files and attachments. Additional information can be given in metadata.

If the same information is given in invoice XML, metadata will override it.

*Note!* Version in the JSON struct should always be 1.1

Read more about [sending invoices](FIX_LINK_PENDING)

```plain
/v1.1/api/invoice_put_invoice_with_metadata
```

### Input

**api_keys** *ApiKeys*

| Key            | Type   | Description               |
|:---------------|:-------|:--------------------------|
| company_uuid   | string | UUID of current company   |
| user_api_key   | string | User API key              |
| vendor_api_key | string | Partner software API key  |

**file_in** *FileAttachment*

| Key             | Type   | Description                                                                    |
|:----------------|:-------|:-------------------------------------------------------------------------------|
| attachment_type | string | Not needed on input                                                            |
| filename        | string | Allowed characters [A-z0-9_.-] (no spaces or other special characters allowed) |
| file            | base64 | File content itself (XML or ZIP)                                               |

| Key       | Type   | Description                                                                                             |
|:----------|:-------|:--------------------------------------------------------------------------------------------------------|
| xmlformat | string | Supported formats:<br>`teapps30`<br>`siubl20`<br>`teapps`<br>`siubl12`<br>`peppolbis30`<br>`vismaubl30`<br>`vismaxml`<br>`svefaktura`<br>`sedi`<br>`oioubl`<br>`finvoice`<br>`finvoice30`<br>`ehf`<br>`peppolbis20`<br>`siubl11`<br>`vismaubl`<br>`e2b` |

**metadata** *string*

JSON struct, supports following parameters:

- **version** *string* - Always `1.1`.
- **uuid** *string* - Specify unique invoice uuid, generated automatically if not specified.
- **lang** *string* - Set invoice language. Language of PDF generated by us and email what recipient receives. Supported languages: `FI` `SE` `NO` `DK` `NL` `EN`
- **routing** *array* - Routing details.
  - **receiver_eia** *string* - Receivers electronic address (e.g. EIA, OVT, GLN).
  - **receiver_operator_id** *string* - Receivers operator code.
  - **receiver_email** *string* - Address the invoice is sent to if delivered by email.
  - **route_order** *array* - Only in Norway, used with **recipient_type** `consumer` to define preferred order of routes.
  Possible routes are:
    - `netbank`
    - `dpi`
    - `email`
    - `print`
- **recipient_type** *string* - Only in Norway, set to `consumer` to use **route_order** array.
- **disabled_routes_out** *array* - Routes that will not be tried, `true` means the route is disabled.
  - **paper** *boolean*
  - **email** *boolean*
  - **relay** *boolean*
- **payment_instruction_identifier** *string* -     PaymentInstructionIdentifier, used in Finnish B2C invoicing only.
- **extra** *array*
  - **sender_comment** *string* - Text that will be added in the email message if invoice is delivered by email (max length 500 characters).

Example:

```json
{
  "version":"1.1",
  "lang":"EN"
  "routing":{
    "receiver_eia":"00371111111",
    "receiver_operator_id":"003721291126"
  },
  "disabled_routes_out":{
    "paper":"false",
    "email":"false",
    "relay":"false"
  },
  "extra":{
    "sender_comment": "Text to the email"
  }
}
```

### Output

**return** *InvoiceStatus*

| Key        | Type   | Description                                              |
|:-----------|:-------|:---------------------------------------------------------|
| status     | string | Status string, includes OK or ERROR                      |
| invoice_id | string | 36 character UUID of new invoice if successfully created |

### Return values

| Message | Description |
|:--------|:------------|
| OK: INVOICE CREATED SUCCESSFULLY | |
| ERROR: UNSUPPORTED XML FORMAT | |
| ERROR: FILE OR FILENAME BLANK | |
| ERROR: FILENAME CONTAINS INVALID CHARACTERS | |
| ERROR: FILENAME INSIDE ZIP CONTAINS INVALID CHARACTERS OR IS INVALID TYPE | |
| ERROR: INVALID ZIP FILE | |
| ERROR: COULD NOT SAVE FILES TO DISK | |
| ERROR: FILENAME CONTAINS INVALID CHARACTERS OR IS INVALID TYPE | |
| ERROR: FILE IS EMPTY | |
| ERROR: NO XML FILE OR MORE THAN ONE FOUND | |
| ERROR: UNAUTHORIZED | Company needs to complete customer authentication and be verified before sending |
| ERROR: UNKNOWN ERROR | |

## invoice_list_between_dates

Used for getting list of outbound invoices. With timestamps its possible to recheck an intervall if there's reason to believe something was missed or need to redownload invoices.

```plain
/v1.1/api/invoice_list_between_dates
```

### Input

**api_keys** (ApiKeys)

| Key            | Type     | Description                |
|:---------------|:---------|:---------------------------|
| company_uuid   | string   | UUID of current company    |
| user_api_key   | string   | User API key               |
| vendor_api_key | string   | Partner software API key   |

| Key             | Type   | Description                                                                                   |
|:----------------|:-------|:----------------------------------------------------------------------------------------------|
| timestamp_start | string | start time for search, format "YYYYMMDDHHMMSS"                                                |
| timestamp_end   | string | end time for search, format "YYYYMMDDHHMMSS"                                                  |
| all             | int    | nil => open invoices, 1 => archived invoices, 2 => all invoices, 3 => invoices in error state |

FIX_LINK_PENDING

### Output

**return** (InvoiceParamsOutCArray)

| Key                  | Type   | Description                                                               |
|:---------------------|:-------|:--------------------------------------------------------------------------|
| status               | string | Status                                                                    |
| id                   | string | Invoice db-id                                                             |
| state                | int    | Invoice state                                                             |
| currency             | string | Currency abbrevation                                                      |
| invoice_nr           | string | Invoice number                                                            |
| order_nr             | string | Order number                                                              |
| sum                  | string | Total sum without tax                                                     |
| sum_tax              | string | Total sum with tax                                                        |
| delivery_date        | string | Delivery date, YYYYMMDD                                                   |
| delivery_type        | string | Delivery type (e.g. mail)                                                 |
| reference_nr         | string | Invoice reference number                                                  |
| date                 | string | Invoicing date, YYYYMMDD                                                  |
| date_due             | string | Invoice due date, YYYYMMDD                                                |
| company_interest     | string | Company’s interest rate (e.g. 11.5)                                       |
| company_reminder     | string | Company’s reminder fee in invoices currency (e.g. 5.50)                   |
| company_paper_fee    | string | Company’s paper fee, added if customer requests paper invoice (e.g. 3.25) |
| customer_reference   | string | Reference for customer (“Viitteenne”)                                     |
| company_reference    | string | Reference for company (“Viitteemme”)                                      |
| company_comment      | string | Comment for email invoice                                                 |
| customer_comment     | string | Customer comment (from decline invoice)                                   |
| notes                | string | Additional information for invoice                                        |
| lang                 | string | Language code for invoice (e.g. ‘FI’)                                     |
| customer_nr          | string | Customer number                                                           |
| customer_name        | string | Name                                                                      |
| customer_email       | string | Email                                                                     |
| customer_bid         | string | Business ID, VAT, etc                                                     |
| customer_contact_p   | string | Contact person’s name                                                     |
| customer_address1    | string | First line of street address                                              |
| customer_address2    | string | Second line of street address                                             |
| customer_post_code   | string | Postal code                                                               |
| customer_post_office | string | Postal office                                                             |
| customer_state       | string | State                                                                     |
| customer_country     | string | Country (e.g. 'FI')                                                       |
| customer_ovt         | string | EDI-code (OVT)                                                            |
| work_order_nr        | string | Work order nr                                                             |
| payment_terms        | string | Payment terms                                                             |

### Return values

| Key    | Type   | Message                              |
|:-------|:-------|:-------------------------------------|
| status | string | OK                                   |
|        |        | ERROR: TIMESTAMP START FORMAT ERROR  |
|        |        | ERROR: TIMESTAMP END FORMAT ERROR    |

## invoice_show

Used for getting information about a specific outbound invoice.  

```plain
/v1.1/api/invoice_show
```

### Input

*api_keys* *ApiKeys*

| Key              | Type       | Description                 |
|:-----------------|:-----------|:----------------------------|
| company_uuid     | string     | UUID of current company     |
| user_api_key     | string     | User API key                |
| vendor_api_key   | string     | Partner software API key    |

| Key           | Type    | Description                             |
|:--------------|:--------|:----------------------------------------|
| id            | string  | invoice id                              |
| include_files | boolean | download invoice image and attachments  |
| xmlformat     | string  | **Supported formats:**<br>`nil`<br>`finvoice`<br>`finvoice20`<br>`finvoice30`<br>`teapps`<br>`teapps30`<br>`ubl`<br>`liinos`<br>`svefaktura`<br>`sedi`<br>`ehf`<br>`ehf20`<br>`vismaxml`<br>`vismaxml60`<br>`e2b`<br>`woodx`<br>`axflow`<br>`facturae`<br>`bgc`<br>`peppolbis20`<br>`peppolbis30`<br>`siubl`<br>`siubl12`<br>`siubl20`<br>`vismaubl`<br>`vismaubl30` |

FIX_XML_REQUEST_EXAMPLE

### Output

*return* *InvoiceParamsOutD*

| Key                  | Type   | Description                                                               |
|:---------------------|:-------|:--------------------------------------------------------------------------|
| status               | string | Status                                                                    |
| id                   | string | Invoice db-id                                                             |
| state                | int    | Invoice state                                                             |
| currency             | string | Currency abbrevation                                                      |
| invoice_nr           | string | Invoice number                                                            |
| order_nr             | string | Order number                                                              |
| sum                  | string | Total sum without tax                                                     |
| sum_tax              | string | Total sum with tax                                                        |
| delivery_date        | string | Delivery date, YYYYMMDD                                                   |
| delivery_type        | string | Delivery type for invoiced product (e.g. truck, mail…)                    |
| reference_nr         | string | Invoice payment reference number                                          |
| date                 | string | Invoicing date, YYYYMMDD                                                  |
| date_due             | string | Invoice due date, YYYYMMDD                                                |
| company_interest     | string | Company"s interest rate (e.g. 11.5)                                       |
| company_reminder     | string | Company"s reminder fee in invoices currency (e.g. 5.50)                   |
| company_paper_fee    | string | Company"s paper fee, added if customer requests paper invoice (e.g. 3.25) |
| customer_reference   | string | Reference for customer (“Viitteenne”)                                     |
| company_reference    | string | Reference for company (“Viitteemme”)                                      |
| company_comment      | string | Comment for email invoice                                                 |
| customer_comment     | string | Recipient comment (from decline invoice)                                  |
| notes                | string | Additional freetext information for invoice                               |
| lang                 | string | Language code for invoice (e.g. "FI")                                     |
| customer_nr          | string | Customer number                                                           |
| customer_name        | string | Name of recipient                                                         |
| customer_email       | string | Email of recipient. If left blank, no email notification can/will be sent |
| customer_bid         | string | Business ID, VAT, organization number etc                                 |
| customer_contact_p   | string | Contact person"s name                                                     |
| customer_address1    | string | First line of street address                                              |
| customer_address2    | string | Second line of street address                                             |
| customer_post_code   | string | Postal code                                                               |
| customer_post_office | string | Postal office                                                             |
| customer_state       | string | State                                                                     |
| customer_country     | string | Country (e.g. "FI")                                                       |
| customer_ovt         | string | EDI-code (OVT), e-invoice address                                         |
| work_order_nr        | string | Work order nr                                                             |
| payment_terms        | string | Payment terms                                                             |
| **items**            | **ItemsOutArray**                | **Array of ItemsOut**                |
| **attachments**      | **FileAttachmentArray**          | **Array of FileAttachment**          |
| **accounts**         | **InvoiceAccountParamsOutArray** | **Array of InvoiceAccountParamsOut** |
| **actions**          | **InvoiceActionParamsOutArray**  | **Array of InvoiceActionParamsOut**  |

*items* *ItemsOutArray*

| Key        | Type   | Description                                                           |
|:-----------|:-------|:----------------------------------------------------------------------|
| subject    | string | Subject string                                                        |
| amount     | double | Invoiced quantity, dot as decimal separator, e.g. 1.50                |
| price      | string | Unit price, dot as decimal separator, e.g. '123.45'                   |
| tax        | double | VAT percentage, dot as decimal separator, e.g. 24.0 is 24%            |
| sum        | string | VAT exclusive sum of the row, dot as decimal separator, e.g. '162.03' |
| sum_tax    | string | VAT inclusive sum of the row, dot as decimal separator, e.g. '200.92' |
| item_code  | string | Item code                                                             |
| definition | string | Additional definition for item (free text)                            |
| position   | int    | Position in item list                                                 |
| unit_type  | string | Unit of item, e.g. 'km' or 'h'                                        |
| discount   | double | Discount percentage, dot as decimal separator, e.g. 12.5 is 12.5%     |

*attachments* *FileAttachmentArray*

| Key             | Type    |
|:----------------|:--------|
| attachment_type | string  |
| filename        | string  |
| file            | base64  |

*accounts* *InvoiceAccountParamsOutArray*

| Key     | Type   |
|:--------|:-------|
| status  | string |
| account | string |
| iban    | string |
| bank    | string |
| swift   | string |

*actions* *InvoiceActionParamsOutArray*

| Key       | Type   |
|:----------|:-------|
| timestamp | string |
| action    | string |

FIX_XML_RESPONSE_EXAMPLE

### Return values

| Key    | Type   | Message                               |
|:-------|:-------|:--------------------------------------|
| status | string | OK                                    |
|        |        | ERROR: INVOICE NOT FOUND OR NO RIGHTS |
|        |        | ERROR: UNKNOWN ERROR                  |

## invoice_state_list

Used for getting list of states for given set of invoices and can be used to update state of multiple invoices at once.

```plain
/v1.1/api/invoice_state_list
```

### Input

api_keys ApiKeys

| Key              | Type     | Description                  |
|:-----------------|:---------|:-----------------------------|
| company_uuid     | string   | UUID of current company      |
| user_api_key     | string   | User API key                 |
| vendor_api_key   | string   | Partner software API key     |

| Key      | Type        | Description                        |
|:---------|:------------|:-----------------------------------|
| invoices | StringArray | Array of string, containing invoice id's |

FIX_IMAGE_PENDING

### Output

return InvoiceStateArray (array of InvoiceState)

| Key        | Type   |
|:-----------|:-------|
| status     | string |
| state      | int    |
| invoice_id | string |

FIX_IMAGE_PENDING

### Return values

| Key    | Type   | Message                  | Description |
|:-------|:-------|:------------------------|:------------|
| status | string | OK                       |             |
|        |        | ERROR: NO INVOICES FOUND |             |
|        |        | ERROR: UNKNOWN ERROR     |             |

### Examples

FIX_IMAGE_PENDING

## sent_invoices_status

Used querying the status and possible error message of the sent invoices.

> [!WARNING]
> **API method has limitations on invoice age**: If the invoice is older than 2 years, the method will not function. Additionally, if more than 1000 IDs are provided, the limit is further reduced to 3 months.

```plain
/v1.1/api/sent_invoices_status
```

### Input

**api_keys** (ApiKeys)

| Key              | Type     | Description                  |
|:-----------------|:---------|:-----------------------------|
| company_uuid     | string   | UUID of current company      |
| user_api_key     | string   | User API key                 |
| vendor_api_key   | string   | Partner software API key     |

| Key      | Type        | Description     |
|:---------|:------------|:----------------|
| invoices | StringArray | array of string |

FIX_IMAGE_PENDING

### Output

**return** (InvoiceStateArray)

| Key           | Type   |
|:--------------|:-------|
| invoice_id    | string |
| state         | string |
| sent_by       | string |
| error_message | string |

FIX_IMAGE_PENDING

### Return values

| Key    | Type   | Message                     |
|:-------|:-------|:----------------------------|
| status | string | OK                          |
|        |        | ERROR: NO INVOICE IDS GIVEN |

#### Possible state values are

| State    |
|:---------|
| SENT     |
| ACCEPTED |
| PAID     |
| VIEWED   |
| PENDING  |
| DECLINED |
| DISPUTED |
| ERROR    |

#### Possible sent_by values are

| Sent By                  |
|:-------------------------|
| Sent inside home network |
| Sent e-invoice           |
| Sent to bank network     |
| Sent by email            |
| Sent by print            |
| Sent by print PRIORITY   |
| Sent by print EU         |
| Sent by print WORLD      |
| Sent by N/A              |

## invoice_reroute

Used for re-routing a existing specific outbound invoice.  

```plain
/v1.1/api/invoice_reroute
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                 |
|:---------------|:-------|:----------------------------|
| company_uuid   | string | UUID of current company     |
| user_api_key   | string | User API key                |
| vendor_api_key | string | Partner software API key    |

| Key   | Type   | Description              |
|:------|:-------|:-------------------------|
| id    | string | invoice id               |
| route | string | einvoice, email or print |

params (InvoiceRerouteParams)

| Key                | Type   | Description                                      |
|:-------------------|:-------|:-------------------------------------------------|
| recipient_eia      | string | Recipient's electronic invoicing address         |
| recipient_operator | string | Recipient's operator code                        |
| email              | string | Recipient email address                          |
| customer_name      | string | If routing to print, fill in the address details |
| customer_address1  | string |                                                  |
| customer_address2  | string |                                                  |
| customer_post_code | string |                                                  |
| customer_post_office | string |                                                |
| customer_state     | string |                                                  |
| customer_country   | string |                                                  |

### Output

return (InvoiceParamsOutD)

| Key    | Type   | Description                     |
|:-------|:-------|:--------------------------------|
| return | string | Status, did the re-routing work |

### Return values

| Type   | Message                                   |
|:-------|:------------------------------------------|
| string | OK: Invoice routed successfully           |
| string | ERROR: Invalid parameters                 |
| string | ERROR: Invalid route                      |
| string | ERROR: Invoice reroute failed: #{message} |
| string | ERROR: Invoice not found or no rights     |

## collection_send

> [!NOTE]
> If you want to outsource the whole receivables management we highly recommend you to check out our new [Receivables management service](FIX_LINK_PENDING) done in a collaboration with Visma Amili Oy!

Method for forwarding specific invoices for debt collection (COLLECTION) or to outsource reminder sending (NOTICE) for invoices that have past the due date. Reminders are sent and debt collection is handled by our partner Visma Amili Oy. Note! This service is only available for Finnish companies. When forwarding invoices to Visma Duetto for the first time you will get an email sent to your company email address to register as Visma Duetto customer and to confirm your assignments.

> [!WARNING]
> If an invoice is sent to Duetto using parameter NOTICE, the receiver will be reminded, after which the invoice will automatically go to collection if not paid. So there is no possibility to only outsource reminder sending.

```plain
/v1.1/api/collection_send
```

### Input

**api_keys** **ApiKeys**

| Key            | Type   | Description                 |
| :------------- | :----- | :-------------------------- |
| company_uuid   | string | UUID of current company     |
| user_api_key   | string | User API key                |
| vendor_api_key | string | Partner software API key    |

| Key             | Type        | Description                                                     |
| :-------------- | :---------- | :-------------------------------------------------------------- |
| invoices        | StringArray | Array of string, containing invoice id's for collection/notice  |
| collection_type | string      | collection or notice (reminder)                                 |

### Output

**return** **CollectionResponseArray** (array of CollectionResponse)

| Key        | Type   | Description                                                                                                           |
| :--------- | :----- | :-------------------------------------------------------------------------------------------------------------------- |
| status     | string | OK for those invoice sent successfully to Visma Duetto. ERROR and reason for the failed ones, e.g. ERROR: NOT EXPIRED |
| invoice_id | string |                                                                                                                       |

### Return values

| Key    | Type   | Message                                               |
| :----- | :----- | :---------------------------------------------------- |
| status | string | OK                                                    |
|        |        | ERROR: COLLECTION TYPE MUST BE COLLECTION OR NOTICE   |
|        |        | ERROR: NO INVOICES FOUND                              |
|        |        | ERROR: SERVICE NOT ACTIVE                             |
|        |        | ERROR: UNKNOWN ERROR                                  |

---

## Invoice Receiving API Methods
Source: https://documentation.maventa.com/api-specification/soap-api/invoice-receiving-api-methods/

API methods for [invoice receiving](/integration-guide/invoice-receiving/). For new integrations, we recommend using the [REST API](/api-specification/rest-api/invoices-api/) instead.

## invoice_download

Used for downloading company's received invoices.

```plain
/v1.1/api/invoice_download
```

### Input

api_keys ApiKeys

| Key                | Type           | Description                     |
| ------------------ | -------------- | ------------------------------- |
| company_uuid       | string         | UUID of current company         |
| user_api_key       | string         | User API key                    |
| vendor_api_key     | string         | Partner software API key        |

| Key           | Type    | Description                                                          |
|---------------|---------|----------------------------------------------------------------------|
| id            | string  | invoice id                                                           |
| xmlformat     | array   | Specify 1-n formats for download. If the original file being downloaded is any of the specified formats, the original file is returned. Otherwise the first format of the array is returned. Supported formats: finvoice, finvoice20, finvoice30, teapps, teapps30, ubl, liinos, svefaktura, sedi, ehf, ehf20, vismaxml, vismaxml60, e2b, woodx, axflow, facturae, bgc, peppolbis20, peppolbis30, siubl, siubl12, siubl20, vismaubl, vismaubl30 |
| include_metadata | boolean | Return invoice related information in the metadata. See the fields included in the metadata from the example response below |
| options       | InvoiceDownloadOptionArray | Array Of InvoiceOptions |

### options

options InvoiceDownloadOptionArray

| Key                       | Type    | Description |
|---------------------------|---------|-------------|
| generate_image_if_missing | boolean | If there is no original invoice image specified, setting this to true creates a custom Maventa invoice image PDF based on the invoice XML data. False by default. |

FIX_IMAGE_PENDING

### Output

| status      | string  | |
| attachments | FileAttachmentArray | Array of attachments. Contains always the invoice XML. For XML formats not supporting embedded attachments, image and attachments are returned as separate objects. For XML formats supporting embedded attachments, the original attachments are returned only embedded to the XML file. With the exception that if the generate_image_if_missing is set as true, then the image we have created will be returned as a separate attachment, and not embedded into the XML file. |
| metadata    | InvoiceDownloadMetadata | Information about the invoice, that may be used for invoice handling related controls. Returned only if requested. |

### attachments

attachments FileAttachmentArray

| Key             | Type    | Description |
|-----------------|---------|-------------|
| attachment_type | string  | For invoice XML value is the XML format requested e.g. PEPPOLBIS30. For invoice image, INVOICE_IMAGE and for other attachments ATTACHMENT |
| filename        | string  | Original or service generated filename |
| file            | base64  | File contents in base64 format |

### metadata

metadata InvoiceDownloadMetadata

| Key               | Type    | Description |
|-------------------|---------|-------------|
| origin            | string  | Source of the invoice, either EINVOICE or SCAN |
| original_format   | string  | Original XML format, value is empty if requested format is same as invoice's original format |
| company_name      | string  | Sender company name |
| company_bid       | string  | Sender company business identifier |
| invoice_nr        | string  | |
| reference_nr      | string  | |
| sum               | string  | Invoice total without VAT |
| sum_tax           | string  | Invoice total including VAT (payable amount) |
| currency          | string  | |
| date              | string  | |
| date_due          | string  | |

### Return values

| Key    | Type   | Message                                           | Description                                           |
|--------|--------|---------------------------------------------------|-------------------------------------------------------|
| status | string | OK                                                |                                                       |
|        |        | ERROR: INVOICE NOT FOUND OR NO RIGHTS             | Requested invoice doesn't exist for the company      |
|        |        | ERROR: USER NOT FOUND                             |                                                       |
|        |        | ERROR: FORMAT NOT SUPPORTED                       | Invoice format specified is not supported            |
|        |        | ERROR: INVOICE NOT COMPATIBLE WITH SELECTED FORMAT | Invoice format specified is not compatible with original invoice format |
|        |        | ERROR: VENDOR KEY MISSING                         | Invalid or no vendor key provided                    |

## invoice_list_ids

Used for getting a list of invoice id's. Otherwise the same as invoice_list_between_dates and invoice_list_inbound_between_dates but a lot faster as it only returns the invoice id's.

```plain
/v1.1/api/invoice_list_ids
```

### Input

api_keys ApiKeys

| Key                | Type           | Description                          |
| ------------------ | -------------- | ------------------------------------ |
| company_uuid       | string         | UUID of current company              |
| user_api_key       | string         | User API key                         |
| vendor_api_key     | string         | Partner software API key (mandatory) |

| Key             | Type   | Description                                        |
|-----------------|--------|----------------------------------------------------|
| direction       | string | IN or OUT                                          |
| timestamp_start | string | Start time for search, format "YYYYMMDDHHMMSS"     |
| timestamp_end   | string | End time for search, format "YYYYMMDDHHMMSS"       |
| options         | string | Not yet implemented any                            |

### Output

return InvoiceListIdsStruct

| Key                        | Type                        | Description            |
|----------------------------|-----------------------------|------------------------|
| status                     | string                      | Status of the API call |
| invoice_ids                | Array                       | Invoice DB-id          |

### Return values

| Key    | Type   | Message                                   | Description                               |
|--------|--------|-------------------------------------------|-------------------------------------------|
| status | string | OK                                        |                                           |
|        |        | ERROR: VENDOR API KEY MISSING             |                                           |
|        |        | ERROR: VENDOR API KEY INVALID OR DISABLED |                                           |
|        |        | ERROR: TIMESTAMP START FORMAT ERROR       |                                           |
|        |        | ERROR: TIMESTAMP END FORMAT ERROR         |                                           |
|        |        | ERROR: TIMEFRAME TOO LONG                 | Max one month between start and end       |
|        |        | ERROR: INVALID DIRECTION                  |                                           |
|        |        | ERROR: USER NOT FOUND                     |                                           |
|        |        | ERROR: Unexpected error                   |                                           |

## invoice_list_inbound_between_dates

Used for getting list of inbound invoices. With timestamps its possible to recheck an intervall if there's reason to believe something was missed or need to redownload invoices. Recommended that 'id' of downloaded invoices is saved locally to be able to check for duplicates.  

```plain
/v1.1/api/invoice_list_inbound_between_dates
```

### Input

**api_keys** **ApiKeys**

| Key                | Type           | Description                     |
| ------------------ | -------------- | ------------------------------- |
| company_uuid       | string         | UUID of current company         |
| user_api_key       | string         | User API key                    |
| vendor_api_key     | string         | Partner software API key        |

| Key             | Type   | Description                                    |
|-----------------|--------|------------------------------------------------|
| timestamp_start | string | start time for search, format "YYYYMMDDHHMMSS" |
| timestamp_end   | string | end time for search, format "YYYYMMDDHHMMSS"   |

FIX_EXAMPLE_PENDING

### Output

**return** **InboundInvoiceParamsOutCArray**

| Key                                                      | Type                            | Description                                    |
| -------------------------------------------------------- | ------------------------------- | ---------------------------------------------- |
| status                                                   | string                          | Status                                         |
| id                                                       | string                          | Invoice db-id                                  |
| state                                                    | int                             | Invoice state                                  |
| currency                                                 | string                          | Currency abbrevation                           |
| invoice_nr                                               | string                          | Invoice number                                 |
| order_nr                                                 | string                          | Order number                                   |
| sum                                                      | string                          | Total sum without tax                          |
| sum_tax                                                  | string                          | Total sum with tax                             |
| delivery_date                                            | string                          | Delivery date, YYYYMMDD                        |
| delivery_type                                            | string                          | Delivery type (e.g. mail)                      |
| reference_nr                                             | string                          | Invoice reference number                       |
| date                                                     | string                          | Invoicing date, YYYYMMDD                       |
| date_due                                                 | string                          | Invoice due date, YYYYMMDD                     |
| customer_reference                                       | string                          | Reference for customer (“Viitteenne”)          |
| company_reference                                        | string                          | Reference for company (“Viitteemme”)           |
| company_comment                                          | string                          | Comment for email invoice                      |
| notes                                                    | string                          | Additional information for invoice             |
| lang                                                     | string                          | Language code for invoice (e.g. ‘FI’)          |
| customer_nr                                              | string                          | Customer number                                |
| customer_name                                            | string                          | Recipient name                                 |
| customer_email                                           | string                          | Recipient email                                |
| customer_bid                                             | string                          | Recipient BID/VAT/org number                   |
| customer_contact_p                                       | string                          | Recipient contact person’s name                |
| customer_address1                                        | string                          | Recipient street address                       |
| customer_address2                                        | string                          | Recipient additional address                   |
| customer_post_code                                       | string                          | Recipient postal code                          |
| customer_post_office                                     | string                          | Recipient postal office                        |
| customer_state                                           | string                          | Recipient address state                        |
| customer_country                                         | string                          | Recipient country code                         |
| customer_ovt                                             | string                          | Recipient e-invoice address (EDI/OVT/GLN/EAN…) |
| company_name                                             | string                          | Sender name                                    |
| company_bid                                              | string                          | Sender BID/VAT/org number                      |
| company_address1                                         | string                          | Sender street address                          |
| company_address2                                         | string                          | Sender additional address                      |
| company_post_code                                        | string                          | Sender post code                               |
| company_post_office                                      | string                          | Sender post office                             |
| company_city                                             | string                          | Sender registered city                         |
| company_state                                            | string                          | Sender address state                           |
| company_country                                          | string                          | Sender country code                            |
| company_phone                                            | string                          | Sender phone number                            |
| company_gsm                                              | string                          | Sender GSM number                              |
| company_fax                                              | string                          | Sender fax number                              |
| company_email                                            | string                          | Sender email                                   |
| company_website                                          | string                          | Sender website                                 |
| company_interest                                         | string                          | Invoice late interest rate                     |
| company_reminder                                         | string                          | Invoice reminder fee                           |
| company_paper_fee                                        | string                          | Invoice paper fee                              |
| user_name                                                | string                          | Sender contact person                          |
| user_email                                               | string                          | Sender contact email                           |
| user_phone                                               | string                          | Sender contact phone                           |
| work_order_nr                                            | string                          | Work order nr                                  |
| payment_terms                                            | string                          | Payment terms                                  |
| **invoice_delivery_address** | **InvoiceDeliveryAddressOut** | **Invoice delivery address** |
| **invoice_seller_information** | **InvoiceSellerInformationOut** | **Invoice seller information** |

**invoice_delivery_address** **InvoiceDeliveryAddressOut**

| Key         | Type   |
|-------------|--------|
| post_code   | string |
| address2    | string |
| country     | string |
| post_office | string |
| name        | string |
| state       | string |
| id          | string |
| address1    | string |

**invoice_seller_information** **InvoiceSellerInformationOut**

| Key   | Type   |
|-------|--------|
| phone | string |
| name  | string |
| email | string |
| id    | string |

### Return values

| Key    | Type   | Message                              |
|--------|--------|--------------------------------------|
| status | string | OK                                   |
|        |        | ERROR: TIMESTAMP START FORMAT ERROR  |
|        |        | ERROR: TIMESTAMP END FORMAT ERROR    |
|        |        | ERROR: NO INVOICES                   |
|        |        | ERROR: UNKNOWN ERROR                 |

---

## B2C Norway API Methods
Source: https://documentation.maventa.com/api-specification/soap-api/b2c-norway-api-methods/

API methods for [consumer invoicing in Norway](/integration-guide/invoice-sending/consumer-invoicing/no/). For new integrations, we recommend using the [REST API](/api-specification/rest-api/b2cno-api/) instead.

## b2c_issuer_agreement_order

For opening Norwegian B2C agreement for a company. Input is name and email address of a person with rights to accept such an agreement on behalf of the company.

> [!NOTE]
> The agreement acceptance link is sent via email to the signer. The signer does not need to log in to accept the agreement.

```plain
/v1.1/api/b2c_issuer_agreement_order
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

| Key          | Type   | Description |
|:-------------|:-------|:------------|
| signer_name  | string |             |
| signer_email | string |             |

### Output

| Key    | Type   | Description    |
|:-------|:-------|:---------------|
| return | string | Status message |

### Return values

| Key    | Type   | Message                                              | Description                    |
|:-------|:-------|:-----------------------------------------------------|:-------------------------------|
| status | string | OK: Email sent to @signer_email                      |                                |
|        |        | ERROR: NO RIGHTS                                     | Only admin user can order      |
|        |        | ERROR: signer_name or signer_email missing or invalid |                               |
|        |        | ERROR: ocr_account_number is invalid                 |                                |
|        |        | ERROR: ocr_kid_length is invalid                     |                                |
|        |        | ERROR: ocr_reference_position syntax is invalid      |                                |
|        |        | ERROR: Bid check towards Nets failed                 |                                |
|        |        | ERROR: Unexpected error                              |                                |

## disable_b2c_issuer_agreement

For closing Norwegian B2C agreement for a company. The agreement can be disabled only if it is CONFIRMED. User cannot disable a PENDING agreement.

```plain
/v1.1/api/disable_b2c_issuer_agreement
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

### Output

| Key    | Type   | Description    |
|:-------|:-------|:---------------|
| return | string | Status message |

### Return values

| Key    | Type   | Message                                                      | Description                      |
|:-------|:-------|:-------------------------------------------------------------|:---------------------------------|
| status | string | OK                                                           |                                  |
|        |        | ERROR: NO RIGHTS                                             | Only admin user can disable      |
|        |        | ERROR: Company agreement not found                           |                                  |
|        |        | ERROR: Cannot disable agreement. Issuer state is #{status}   | Agreement is not in correct state |
|        |        | ERROR: Unexpected error                                      |                                  |

## consumer_agreement_status

Checking status of an existing consumer agreement.

> [!NOTE]
> Status of ACTIVE means the consumer is ready to receive invoices.

```plain
/v1.1/api/consumer_agreement_status
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

| Key          | Type   | Description |
|:-------------|:-------|:------------|
| reference_nr | string |             |

### Output

| Key    | Type   | Description    |
|:-------|:-------|:---------------|
| return | string | Status message |

### Return values

| Key    | Type   | Message                  | Description                                                                          |
|:-------|:-------|:-------------------------|:-------------------------------------------------------------------------------------|
| status | string | OK: @status              | One of: REQUEST_SENT, NEW, ACCEPTED, ACTIVE, DELETED, REJECTED, ERROR |
|        |        | ERROR: CONSUMER NOT FOUND |                                                                                     |
|        |        | ERROR: Unexpected error   |                                                                                     |

## consumer_agreements_query

Checking status of existing consumer agreements.

```plain
/v1.1/api/consumer_agreements_query
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

query (ConsumerAgreementQuery)

| Key          | Type   | Description                                                           |
|:-------------|:-------|:----------------------------------------------------------------------|
| name         | string |                                                                       |
| phone        | string |                                                                       |
| email        | string |                                                                       |
| state        | string | One of: REQUEST_SENT, NEW, ACCEPTED, ACTIVE, DELETED, REJECTED, ERROR |
| reference_nr | string |                                                                       |
| customer_nr  | string |                                                                       |
| timestamp    | string | Format YYYYMMDDHHMMSS                                                 |

### Output

return (ConsumerAgreementQueryResponse)

| Key        | Type                 | Description               |
|:-----------|:---------------------|:--------------------------|
| status     | string               |                           |
| agreements | ConsumerInfoOutArray | Array of ConsumerInfoOut  |

agreements (ConsumerInfoOut)

| Key          | Type   | Description                                                           |
|:-------------|:-------|:----------------------------------------------------------------------|
| state        | string | One of: REQUEST_SENT, NEW, ACCEPTED, ACTIVE, DELETED, REJECTED, ERROR |
| name         | string |                                                                       |
| phone        | string |                                                                       |
| email        | string |                                                                       |
| reference_nr | string |                                                                       |
| customer_nr  | string |                                                                       |

### Return values

| Key    | Type   | Message                      | Description              |
|:-------|:-------|:-----------------------------|:-------------------------|
| status | string | OK                           |                          |
|        |        | ERROR: Timestamp format error | Invalid timestamp format |
|        |        | ERROR: No agreements found    |                          |
|        |        | ERROR: Unexpected error       |                          |

## vendor_consumer_agreements_query

Checking status of existing consumer agreements by query for all companies under given vendor_api_key.

```plain
/v1.1/api/vendor_consumer_agreements_query
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

query (ConsumerAgreementQuery)

| Key          | Type   | Description                                                           |
|:-------------|:-------|:----------------------------------------------------------------------|
| name         | string |                                                                       |
| phone        | string |                                                                       |
| email        | string |                                                                       |
| state        | string | One of: REQUEST_SENT, NEW, ACCEPTED, ACTIVE, DELETED, REJECTED, ERROR |
| reference_nr | string |                                                                       |
| customer_nr  | string |                                                                       |
| timestamp    | string | Format YYYYMMDDHHMMSS (For example 20180401152042)                    |

### Output

return (VendorConsumerAgreementQueryResponse)

| Key     | Type                                    | Description                                  |
|:--------|:----------------------------------------|:---------------------------------------------|
| status  | string                                  |                                              |
| results | VendorConsumerAgreementQueryResultArray | Array of VendorConsumerAgreementQueryResult   |

results (VendorConsumerAgreementQueryResult)

| Key        | Type                 | Description               |
|:-----------|:---------------------|:--------------------------|
| company_id | string               |                           |
| agreements | ConsumerInfoOutArray | Array of ConsumerInfoOut  |

agreements (ConsumerInfoOut)

| Key          | Type   | Description                                                           |
|:-------------|:-------|:----------------------------------------------------------------------|
| state        | string | One of: REQUEST_SENT, NEW, ACCEPTED, ACTIVE, DELETED, REJECTED, ERROR |
| name         | string |                                                                       |
| phone        | string |                                                                       |
| email        | string |                                                                       |
| reference_nr | string |                                                                       |
| customer_nr  | string |                                                                       |

### Return values

| Key    | Type   | Message                              | Description |
|:-------|:-------|:-------------------------------------|:------------|
| status | string | OK                                   |             |
|        |        | ERROR: Timestamp format error        |             |
|        |        | ERROR: No rights to vendor API key   |             |
|        |        | ERROR: Unexpected error              |             |

## atg_mandate_list

Lists changes to consumer AvtaleGiro mandates. Returns all changes after given timestamp.

```plain
/v1.1/api/atg_mandate_list
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

| Key       | Type   | Description                       |
|:----------|:-------|:----------------------------------|
| timestamp | string | Format YYYYMMDDHHMMSS             |

### Output

return (AtgMandateListResponse)

| Key          | Type                 | Description    |
|:-------------|:---------------------|:---------------|
| status       | string               |                |
| atg_mandates | AtgMandateParamArray | AvtaleGiro mandates |

atg_mandates (AtgMandateParam)

| Key               | Type    | Description                                                                                      |
|:------------------|:--------|:-------------------------------------------------------------------------------------------------|
| kid               | string  |                                                                                                  |
| account_number    | string  |                                                                                                  |
| notification      | boolean | 1 — consumer wants to be notified of AvtaleGiro sends, 0 — consumer does not want notification  |
| status            | integer | 1 — active, 0 — inactive                                                                        |
| updated_timestamp | string  |                                                                                                  |

### Return values

| Key    | Type   | Message                          | Description |
|:-------|:-------|:---------------------------------|:------------|
| status | string | OK                               |             |
|        |        | ERROR: Timestamp format error    |             |
|        |        | ERROR: No rights to settings     |             |
|        |        | ERROR: Unexpected error          |             |

## atg_agreement_configure

Used after setting up an AvtaleGiro agreement with the bank to inform AutoInvoice about the settings used so that changes to consumer mandates can be imported and used in routing.

```plain
/v1.1/api/atg_agreement_configure
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

| Key                   | Type    | Description                                                                                                                                                                                  |
|:----------------------|:--------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| account_number        | string  | Same account number as in the AvtaleGiro agreement                                                                                                                                           |
| kid_length            | integer | Same KID length as in the AvtaleGiro agreement                                                                                                                                               |
| reference_position    | string  | Same reference position as in the AvtaleGiro agreement. Example `1-6`                                                                                                                        |
| payment_type_position | string  | Same payment type position number as in the AvtaleGiro agreement. Example `1-6`                                                                                                              |
| options               | string  | Can be used to disable print and/or email notifications when sending AvtaleGiro without eFaktura agreement. JSON format with keys `notif_print` and `notif_email` either true or false. Defaults to both true if not given. Example `{"notif_print":false,"notif_email":true}` |

### Output

| Key    | Type   | Description |
|:-------|:-------|:------------|
| return | string |             |

### Return values

| Key    | Type   | Message                                      |
|:-------|:-------|:---------------------------------------------|
| return | string | OK                                           |
|        |        | ERROR: Invalid payment_type_position         |
|        |        | ERROR: Invalid reference_position            |
|        |        | ERROR: Invalid kid_length                    |
|        |        | ERROR: Invalid account_number                |
|        |        | ERROR: OPTIONS PARAMETER FORMAT IS INVALID   |
|        |        | ERROR: UNKNOWN ERROR                         |

---

## B2C Finland API Methods
Source: https://documentation.maventa.com/api-specification/soap-api/b2c-finland-api-methods/

API methods for [consumer invoicing in Finland](/integration-guide/invoice-sending/consumer-invoicing/fi/). For new integrations, we recommend using the [REST API](/api-specification/rest-api/b2cfi-api/) instead. B2C Finland uses a separate WSDL from the main SOAP API:

- Testing: `https://testing.maventa.com/apis/banks/wsdl`
- Production: `https://secure.maventa.com/apis/banks/wsdl`

## message_send

Used for sending SI-messages for B2C Finland. Returns OK and new message ID or ERROR.

> [!NOTE]
> The message needs to be XSD schema valid and complete. It will be sent to the bank as-is — no additions or conversions are made.

> [!WARNING]
> The system returns OK immediately when the message has been sent successfully. Between banks, B2C messages can travel with a delay of up to 1–4 banking days. Possible error messages can arrive even after a week. If the message fails on the bank side you will get an error. If the message is accepted, no separate confirmation message is sent.

```plain
/banks/api/message_send
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

message (base64)

| Key  | Type   | Description      |
|:-----|:-------|:-----------------|
| file | base64 | SI-message file  |

### Output

return (MessageResponse)

| Key        | Type   | Description                                              |
|:-----------|:-------|:---------------------------------------------------------|
| status     | string | Status string, includes OK or ERROR                      |
| message_id | string | 36 character UUID of new SI-message if successfully created |

### Return values

| Key    | Type   | Message                                    | Description                 |
|:-------|:-------|:-------------------------------------------|:----------------------------|
| return | string | OK                                         |                             |
|        |        | ERROR: DUPLICATE MESSAGEID                 | Given message ID is duplicate |
|        |        | ERROR: ONLY ONE MESSAGE PER FILE ALLOWED   |                             |
|        |        | ERROR: SOAP HEADER MISSING                 |                             |
|        |        | ERROR: USER NOT FOUND                      |                             |
|        |        | ERROR: COMPANY BANK CONNECTION NOT ACTIVE  |                             |
|        |        | ERROR: INVALID SENDER INTERMEDIATOR        |                             |
|        |        | ERROR: MESSAGE NOT FOUND OR NO RIGHTS      |                             |

## message_status

Used for getting the status of a sent SI-message. Uses the UUID returned by the message_send method.

> [!NOTE]
> In case an SI-message ends up in an error state on the sending bank side, error_message_list only returns the SI-message status as ERROR and does not return any error reasons.

```plain
/banks/api/message_status
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

| Key        | Type   | Description     |
|:-----------|:-------|:----------------|
| message_id | string | UUID message_id |

### Output

return (MessageStatus)

| Key     | Type   | Description                          |
|:--------|:-------|:-------------------------------------|
| status  | string | Status string, includes OK or ERROR  |
| message | string | Message                              |

### Return values

| Key    | Type   | Message                               | Description |
|:-------|:-------|:--------------------------------------|:------------|
| return | string | OK                                    |             |
|        |        | ERROR: USER NOT FOUND                 |             |
|        |        | ERROR: MESSAGE NOT FOUND OR NO RIGHTS |             |

## error_message_list

Used for listing error messages based on given timestamps. Returns status and a table that contains `id` and `original_id` (refers to the SI-message UUID).

```plain
/banks/api/error_message_list
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

| Key             | Type   | Description                                 |
|:----------------|:-------|:--------------------------------------------|
| timestamp_start | string | Start time for search, format YYYYMMDDHHMMSS |
| timestamp_end   | string | End time for search, format YYYYMMDDHHMMSS   |

### Output

return (ErrorList)

| Key            | Type                | Description                                                            |
|:---------------|:--------------------|:-----------------------------------------------------------------------|
| status         | string              | Status                                                                 |
| error_messages | ErrorListMessageOut | A table that contains `id` and `original_id` (refers to the SI-message UUID) |

error_messages (ErrorListMessageOut)

| Key         | Type   | Description       |
|:------------|:-------|:------------------|
| id          | string | Error message ID  |
| original_id | string | SI-message UUID   |

### Return values

| Key    | Type   | Message                                              | Description |
|:-------|:-------|:-----------------------------------------------------|:------------|
| status | string | OK                                                   |             |
|        |        | ERROR: TIMESTAMP FORMAT INVALID FOR START TIMESTAMP  |             |
|        |        | ERROR: TIMESTAMP FORMAT INVALID FOR END TIMESTAMP    |             |
|        |        | ERROR: USER NOT FOUND                                |             |
|        |        | ERROR: UNKNOWN ERROR                                 |             |

## error_message_show

Used to download a separate message from the bank that contains the error reason.

```plain
/banks/api/error_message_show
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

| Key              | Type   | Description             |
|:-----------------|:-------|:------------------------|
| error_message_id | string | Error message ID (UUID) |

### Output

return (ErrorMessageOut)

| Key           | Type   | Description                    |
|:------------- |:-------|:-------------------------------|
| status        | string | Status of the API call         |
| error_message | base64 | File contents in base64 format |

### Return values

| Key    | Type   | Message                               | Description |
|:-------|:-------|:--------------------------------------|:------------|
| status | string | OK                                    |             |
|        |        | ERROR: USER NOT FOUND                 |             |
|        |        | ERROR: MESSAGE NOT FOUND OR NO RIGHTS |             |

## ri_message_list

Used to list UUIDs for RI (Return Information) messages received based on given timestamps. Returns status and a table that contains UUIDs.

```plain
/banks/api/ri_message_list
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                         |
|:---------------|:-------|:------------------------------------|
| company_uuid   | string | UUID of current company             |
| user_api_key   | string | User API key                        |
| vendor_api_key | string | Partner software API key (mandatory) |

| Key             | Type   | Description                                 |
|:----------------|:-------|:--------------------------------------------|
| timestamp_start | string | Start time for search, format YYYYMMDDHHMMSS |
| timestamp_end   | string | End time for search, format YYYYMMDDHHMMSS   |

### Output

return (RiList)

| Key            | Type   | Description            |
|:---------------|:-------|:-----------------------|
| status         | string | Status of the API call |
| ri_message_ids | Array  | RI-message IDs         |

### Return values

| Key    | Type   | Message                                             | Description |
|:-------|:-------|:----------------------------------------------------|:------------|
| status | string | OK                                                  |             |
|        |        | ERROR: TIMESTAMP FORMAT INVALID FOR START TIMESTAMP |             |
|        |        | ERROR: TIMESTAMP FORMAT INVALID FOR END TIMESTAMP   |             |

## ri_message_show

Used to download an RI (Return Information) message.

```plain
/banks/api/ri_message_show
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

| Key           | Type   | Description          |
|:--------------|:-------|:---------------------|
| ri_message_id | string | RI-message ID (UUID) |

### Output

return (RiMessageOut)

| Key        | Type   | Description                    |
|:-----------|:-------|:-------------------------------|
| status     | string | Status of the API call         |
| ri_message | base64 | File contents in base64 format |

### Return values

| Key    | Type   | Message                               | Description |
|:-------|:-------|:--------------------------------------|:------------|
| status | string | OK                                    |             |
|        |        | ERROR: USER NOT FOUND                 |             |
|        |        | ERROR: MESSAGE NOT FOUND OR NO RIGHTS |             |

## ri_message_delete

Used to remove a single RI (Return Information) message by ID. Returns OK or ERROR as status.

```plain
/banks/api/ri_message_delete
```

### Input

api_keys (ApiKeys)

| Key            | Type   | Description                |
|:---------------|:-------|:---------------------------|
| company_uuid   | string | UUID of current company    |
| user_api_key   | string | User API key               |
| vendor_api_key | string | Partner software API key   |

| Key           | Type   | Description          |
|:--------------|:-------|:---------------------|
| ri_message_id | string | RI-message ID (UUID) |

### Output

| Key    | Type   | Description                     |
|:-------|:-------|:--------------------------------|
| status | string | Status of the API call, OK/ERROR |

### Return values

| Key    | Type   | Message                               | Description |
|:-------|:-------|:--------------------------------------|:------------|
| status | string | OK                                    |             |
|        |        | ERROR: USER NOT FOUND                 |             |
|        |        | ERROR: MESSAGE NOT FOUND OR NO RIGHTS |             |

---

## Other API Methods
Source: https://documentation.maventa.com/api-specification/soap-api/other-api-methods/

## hello_world

Can be used for testing the connection to the API.

```plain
/v1.1/api/hello_world
```

### Input

This method requires no parameters.

### Output

| Key    | Type   | Description      |
|:-------|:-------|:-----------------|
| return | string | Response message |

### Return values

| Key    | Type   | Message                          |
|:-------|:-------|:---------------------------------|
| return | string | Hello from Maventa API v1.1      |

## server_time

Returns the current server time. Can be used for verifying the connection and checking the server time.

```plain
/v1.1/api/server_time
```

### Input

This method requires no parameters.

### Output

| Key    | Type   | Description          |
|:-------|:-------|:---------------------|
| return | string | Current server time  |

---


# Additional pages

## AutoScan
Source: https://documentation.maventa.com/autoscan/

## Faster, smarter invoice scanning

AutoScan is Maventa's recommended scanning solution for receiving PDF invoices. It is a fully automated, email-based service — suppliers send PDF invoices to a dedicated scan email address, and the data is extracted and delivered electronically to your invoice inbox in minutes, not hours or days.

Data extraction is powered by Smartscan, a machine learning-based solution for document data interpretation with continuously improving accuracy. Built-in automated quality checks (VERIFIED) cross-validate key fields like amounts and VAT, so manual verification steps are not needed. The result is a fast, cost-effective scanning pipeline that keeps getting better.

> [!TIP]
> **AutoScan launches in Finland on 12 May 2026.** Finnish companies can start using AutoScan alongside or as a replacement for Scan Network. AutoScan is already available in all other supported markets.

## Why AutoScan?


### Near-instant processing

Invoices are interpreted and delivered in minutes. No queues, no waiting for business hours, no delays over weekends or holidays.

### Automated quality checks

The built-in VERIFIED feature cross-validates key fields like amounts and VAT — catching inconsistencies automatically so you don't have to.

### Continuously improving accuracy

Smartscan learns from every document it processes. The more invoices flow through the system, the better it gets.

### Simple setup

Activate through the API or the Maventa user interface. AutoScan provides a dedicated email address — share it with your suppliers and start receiving invoices.


## How it works

1. Activate AutoScan for your company. Maventa provides a dedicated scan email address in the format `countrycode-BID@autoscan.maventa.com`.
2. Share the scan email address with your suppliers.
3. Suppliers send PDF invoices to the scan email address.
4. AutoScan interprets the invoice data using Smartscan machine learning and delivers the structured invoice along with the original PDF to your Maventa account.
5. Fetch the invoice through the API, just like any other received invoice.

Scanned invoices are treated as standard incoming e-invoices. The same API flow, format conversion, and webhook notifications apply — no separate integration is needed.

> [!NOTE]
> Regardless of the scanning solution used, the recipient should always verify the accuracy of scanned invoices.

## AutoScan vs. Scan Network

For companies already using Scan Network, here is how the two services compare. Both services can also run side by side — each has its own dedicated email address.

|  | AutoScan | Scan Network |
|---|---|---|
| **Technology** | Machine learning (Smartscan) | OCR + manual validation |
| **Processing time** | Minutes | Hours to days |
| **Manual review** | No | Yes — quality control step |
| **Line scanning** | Available (pilot) | Not available |
| **VAT distribution** | Extracted and cross-validated | Calculated from totals |
| **Email scanning** |  |  |
| **Postal scanning** | Not available | Finland and Sweden |
| **Country availability** | All markets (Finland 12 May 2026) | FI, SE, NO, DK, NL, BE |

> [!NOTE]
> For a detailed field-by-field comparison, see the [scanning documentation](/integration-guide/invoice-receiving/scanning/).

## Built-in quality with VERIFIED

Unlike Scan Network, AutoScan does not include manual human-in-the-loop data verification. Instead, it uses the Smartscan Premium VERIFIED feature, which applies automated checks and cross-validation across key invoice fields to ensure the data is mathematically consistent:

- Header totals vs. line totals
- VAT amounts vs. base amounts and VAT percentages
- Line-level totals vs. VAT amounts

If everything matches, the data is marked as verified. If discrepancies are found, Smartscan can often correct values automatically based on cross-validation — reducing the need for manual corrections downstream.

## Line scanning **Pilot**

AutoScan can also interpret invoice line-level data, including item numbers, descriptions, quantities, unit prices, and VAT per line. In the current pilot version, line scanning processes the first 5 pages of the invoice. Contact Maventa support to enable it.

## Getting started

AutoScan is available in Finland from 12 May 2026. Activation requires an active Maventa account with invoice receiving enabled.

Since AutoScan has its own dedicated scan email address, it can be easily tried out alongside an existing Scan Network setup — no need to switch over or make changes to your current scanning flow. We highly recommend giving it a try.

Activate the service through the REST API or the Maventa user interface.

**REST API:** [PUT /v1/services/autoscan](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/services/putV1ServicesAutoscan)

For full technical details, including API examples, return email handling, and VAT processing, see the [scanning integration guide](/integration-guide/invoice-receiving/scanning/).

---

## Peppol Directory statistics
Source: https://documentation.maventa.com/peppol-directory/

<script type="module" src="/assets-dynamic/js/peppol-directory.6edcc110.js"></script>

<div class="not-prose">
    <peppol-directory></peppol-directory>
</div>

---

## Peppol participant lookup
Source: https://documentation.maventa.com/peppol-lookup/

> [!CAUTION]
> This tool is intended for debugging, testing and learning purposes only. This is not intended for day-to-day use by Peppol end users to look up if a recipient is reachable via Peppol or not.
>
> For now this tool is free to use within reasonable limits but provided as-is without any guarantees.

<script type="module" src="/assets-dynamic/js/peppol-lookup-component.34ac673c.js"></script>

<div class="not-prose">
    <peppol-lookup></peppol-lookup>
</div>

## Need a Peppol Access Point?

Maventa offers secure and compliant invoicing in Peppol and more. Through our API, you can add Peppol services to your software without becoming an Access Point yourself. As a trusted and experienced Peppol-certified service provider, we connect your software and customers to the Peppol network safely and securely. Read more about our [Peppol services](https://maventa.com/peppol).

---

## Peppol Self-Billing
Source: https://documentation.maventa.com/peppol-self-billing/

## What is self-billing?

Self-billing is a process where the buyer issues and sends an invoice on behalf of the supplier through the Peppol network. The invoice refers to goods or services that the buyer has received and is responsible for documenting.

In Peppol, this process is defined in the [Peppol BIS Self-Billing 3.0 specification](https://docs.peppol.eu/poacc/self-billing/3.0/bis-sb/), which ensures interoperability and VAT compliance across participating countries. Self-billed invoices must contain the same required data elements as standard invoices, including buyer and supplier identifiers, tax details, and references to the underlying commercial transaction.

Before self-billing can be used, the supplier and buyer must have a prior agreement that explicitly authorises the buyer to issue invoices on the supplier's behalf, as required by VAT and e-invoicing legislation. This agreement is handled outside Maventa between the parties themselves.

### Key distinction

Legally and according to Peppol standards, the buyer creates the invoice on behalf of the supplier, and the supplier is the recipient. The supplier remains the legal seller, and VAT liability stays with the supplier.

From an accounting perspective:

- The supplier records the self-billing invoice as an incoming invoice, treating it as a sales record.
- The buyer is responsible for issuing the invoice in their system. Since the buyer already generated the invoice, the supplier does not issue another invoice for the same transaction.

Integrators should make sure this distinction is clear in the accounting system so there is no confusion about responsibilities.

### Country support

Self-billing via Maventa is available in all countries where Maventa supports Peppol invoice receiving, except Norway.

## Sending self-billing invoices

The buyer creates a compliant Peppol BIS Self-Billing document with the correct profiles and type codes, and sends it like any other invoice via the REST API. Maventa automatically identifies the document as a self-billing invoice or credit note and delivers it to the supplier via Peppol — provided the supplier is registered to receive self-billing documents. If the supplier is not registered, the invoice will fail, as no fallback routing is available for self-billing documents.

> [!NOTE]
> Maventa reads routing data from the XML for self-billing invoices. Any routing information provided in the API metadata (such as `recipient_eia` or `recipient_operator`) is ignored.

The self-billing document must include the following identifiers in the XML. The `CustomizationID` and `ProfileID` are the same for both invoices and credit notes — only the document type code and root element differ:

```xml
<cbc:CustomizationID>urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0</cbc:CustomizationID>
```

```xml
<cbc:ProfileID>urn:fdc:peppol.eu:2017:poacc:selfbilling:01:1.0</cbc:ProfileID>
```

### Self-billing invoice

The root element is `<Invoice>` with type code `389`:

```xml
<cbc:InvoiceTypeCode>389</cbc:InvoiceTypeCode>
```

## Receiving self-billing invoices

To receive self-billing documents, a company must explicitly register dedicated Peppol self-billing profiles via the API — one for self-billing invoices and one for self-billing credit notes. These are separate registrations from the standard `INVOICE_AND_CREDIT_NOTE` profile. There is no UI available for self-billing profile registrations.

> [!NOTE]
> Self-billing is supported only in the Peppol BIS format. No conversion to other formats is available, meaning the receiving ERP must be capable of downloading and handling Peppol BIS invoices.

### Register self-billing profiles

Call [POST /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE%20-%20AutoXChange%20API#/company/postV1CompanyProfiles) with the following parameters:

- **profile**: `SELF_BILLING_INVOICE` (for receiving self-billing invoices) or `SELF_BILLING_CREDIT_NOTE` (for receiving self-billing credit notes)
- **network**: `PEPPOL`

Once the profiles are created, use [GET /v1/company/profiles](https://swagger.maventa.com/?urls.primaryName=STAGE+-+AutoXChange+API#/company/getV1CompanyProfiles) to verify that they are active for the `PEPPOL` network. This separate registration is necessary because not all ERPs support self-billing by default.

### Downloading and processing self-billing invoices

Downloading self-billing invoices works the same way as downloading any other received invoice — use the standard [invoice receiving](/integration-guide/invoice-receiving/) flow.

After downloading, the receiving system must identify the document as a self-billing document by checking the `CustomizationID` and document type code in the XML. Both types use the self-billing customization ID (`urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:selfbilling:3.0`):

- **Self-billing invoice**: `InvoiceTypeCode` = `389`
- **Self-billing credit note**: `CreditNoteTypeCode` = `261`

Based on these identifiers, the receiving system should handle the document as a sales record rather than a purchase record.

## Summary

Self-billing via Peppol allows buyers to issue compliant electronic invoices on behalf of suppliers. It requires:

- A prior commercial agreement between buyer and supplier.
- Proper Peppol BIS Self-Billing 3.0 XML with correct type codes and identifiers.
- Supplier registration for `SELF_BILLING_INVOICE` and/or `SELF_BILLING_CREDIT_NOTE` Peppol profiles.

---

## Perintäpalvelut — asiakasohje
Source: https://documentation.maventa.com/receivables-customer-guide-fi/

## Visma Amilin perintäpalvelut

Maventa tarjoaa yhteistyössä Visma Amilin (ent. Visma Financial Solutions Oy) kanssa kaksi saatavien hallintaratkaisua verkkolaskutuksen tueksi:

- **Amili Kassavirta** — kokonaisvaltainen ja automaattinen palvelu, joka hoitaa maksuvalvonnan, suoritusten kohdistamisen, maksumuistutukset ja perinnän puolestasi. Kaikki lähetetyt laskut kulkevat automaattisesti palvelun kautta.
- **Amili Perintä** — muistutus- ja perintäpalvelu, jonka avulla voit siirtää yksittäisiä erääntyneitä laskuja muistutus- ja perintäprosessiin tai suoraan perintäprosessiin.

Molemmat palvelut kuuluvat Maventa-palveluun ilman erillisiä avaus-, kuukausi- tai vuosimaksuja. Maksat vain lähetetyistä laskuista. Palvelut ovat maksuttomia aina perintätoimiin asti. Mahdolliset lisäkustannukset liittyvät perinnän myöhempiin vaiheisiin tai toimeksiantojen peruuttamiseen.

[Palvelukuvaus ja hinnasto (Visma Amili)](https://amili.fi/hubfs/Sopimusehdot/Visma-Amili-Palvelusopimus-kanava-asiakkaille-08-24.pdf)

### Amili Kassavirta

Amili Kassavirta hoitaa laskujen lähetyksen jälkeiset vaiheet: maksuvalvonnan, suoritusten kohdistamisen, maksumuistutukset ja tarvittaessa perinnän. Laskut luodaan normaaliin tapaan ERP:stä ja Maventa hoitaa loput. Käyttöönotto ei vaadi muutoksia taloushallinnon ohjelmistoosi.

Amili Kassavirta sisältää muun muassa seuraavat ominaisuudet:

- Laskutietojen siirto Maventan tililtä maksuvalvontaan
- Asiakasvaratilin ja siirtolausekkeen lisääminen laskulle
- Myyntireskontran valvontatyöt
- Viitteellisten ja viitteettömien suoritusten kohdistaminen
- Maksuhuomautukset ja vapaaehtoinen perintä
- Väärin maksettujen suoritusten käsittely
- Ohisuoritukset ja palautukset

![Amili Kassavirta -palvelun ylätason prosessikuvaus](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/receivables_process_Maventa.png)

#### Amili Kassavirta -palvelun vaiheet kun lasku maksetaan ajoissa

![Amili Kassavirta -prosessikaavio kun asiakas maksaa laskun ajallaan](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/koko_prosessi.png)

Prosessikaavio laskun lähetyksestä normaalissa tilanteessa, jossa asiakas maksaa laskunsa ajallaan:

1. Lähettäjä lähettää laskunsa normaaliin tapaan ERP-ohjelmastaan.
2. Lasku saapuu Maventalle ja välitetään Visma Amilille muokattavaksi.
3. Visma Amili korvaa laskulta maksutiedot omillaan ja palauttaa laskun Maventalle lähetysprosessiin.
4. Maventa lähettää muokatun laskun vastaanottajalle ja palveluun luodaan toimeksianto.
5. Vastaanottaja maksaa laskun Visma Amilin tilitiedoilla ja toimeksianto merkitään maksetuksi.
6. Visma Amili tilittää saatavat lähettäjän tilille ja toimeksianto suljetaan.

#### Amili Kassavirta -palvelun vaiheet kun laskulle ei tule suoritusta

![Muistutus- ja perintäprosessi osa 1](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/amili_process1.png)
![Muistutus- ja perintäprosessi osa 2](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/amili_process2.png)

#### Amili Kassavirta -palvelun aktivointi

Kun palvelu on aktivoitu, kaikki yrityksen tililtä lähetetyt laskut kulkevat automaattisesti Amili Kassavirta -palvelun kautta.

Voit aktivoida palvelun Maventa-tilin asetusten kautta kohdasta: Perintäpalvelut -> Yleiset asetukset

1. Valitse palvelun tyypiksi Amili Kassavirta.
2. Täytä perustiedot lomakkeelle ja paina "Jatka". Tämä aloittaa aktivointiprosessin.
3. Viimeistele käyttöönotto Netvisor KYC -palvelussa klikkaamalla linkkiä. Tämä viimeistelee aktivointiprosessin.
4. Palvelu on käytössäsi 1–2 arkipäivän sisällä ilman lisämaksuja.

Aktivointi viimeistellään Netvisor KYC -palvelussa täyttämällä tietopyyntölomake. Samalla hyväksytään palvelun sopimusehdot. Lomakkeen täyttämiseksi tarvitaan henkilökohtaiset verkkopankkitunnukset tai mobiilivarmenne.

Rahanpesulain mukaan Visma Amili Oy:n on varmistettava, että he tuntevat asiakkaansa ja heidän toimintansa. Tietopyyntöön vastaavalla henkilöllä tulee olla oikeus toimia organisaation puolesta asemansa tai valtakirjan perusteella. Edustusoikeuden perustuessa valtakirjaan, valtakirja tulee liittää lomakkeeseen.

Jos käyttöönottoa ei viimeistellä viikon kuluessa, lähetetään muistutus yhteyshenkilön sähköpostiosoitteeseen.

Aktivoinnin jälkeen suosittelemme vielä seuraavia toimenpiteitä:

1. Kuluttajalaskuttajilla SI-sanomien muutosilmoitusten lähetys pankkeihin (katso lisätiedot kohdasta Kuluttajien laskutus (B2C)).
2. Yrityksen oman logon lisääminen palvelun luomiin laskukuviin (Asetukset -> Laskuasetukset -> Laskujen lähettäminen -> Laskun kuvan asetukset).

##### Mitä tietoja aktivoinnissa pyydetään

Tällä hetkellä alla olevia tietoja ei voi muokata käyttöliittymän kautta. Jos tietoja on tarvetta päivittää, ota yhteyttä asiakaspalveluun.

**Pankkitilin tiedot:**

Yrityksesi pankkitilin tiedot, jolle Visma Amili maksaa tilitykset. Maksuissa käytetään aina alkuperäisen laskun viitenumeroa, joten saatavien kohdistaminen hoituu ERP:ssä tavalliseen tapaan. Maksajana näkyy VISMA AMILI.

**Yhteystiedot:**

Henkilö, johon voidaan tarvittaessa olla yhteydessä palveluun liittyvissä asioissa.

**Asiakaspalvelun tiedot:**

Yhteystiedot tulevat näkyviin siirtolausekkeeseen, jonka Visma Amili lisää kaikille palvelun kautta kulkeville laskuille.

**Laskutustiedot:**

Laskutustiedot mahdollisia palvelumaksuja varten, esimerkiksi myöhempien perintävaiheiden oikeuskuluihin liittyvät maksut. Velalliselta kertyneen palkkion, korvauksen tai kulun arvonlisävero laskutetaan toimeksiantajalta, mikäli toimeksiantajalla on oikeus vähentää perintäpalkkion arvonlisävero. Tämä arvonlisävero ei lisää perintäkustannuksia, koska se on kokonaan vähennyskelpoinen erä. Lisätietoja palvelumaksuista löytyy Visma Amili Oy:n hinnastosta.

##### Kuluttajien laskutus (B2C)

Jos yritykselläsi on kuluttajalaskutusta suomalaisiin pankkeihin, tulee laskuttajailmoituksiin (SI-sanomiin) tehdä muutoksia, jotta Amili Kassavirta toimii myös näiden laskujen osalta. Tarvittavien muutosten tekemiseen on aikaa 7 arkipäivää siitä hetkestä kun palvelu on aktivoitu. Näiden päivien aikana lähetetyt kuluttajalaskut kulkevat palvelun ohi. Kun siirtymäaika on ohi, reititetään myös kuluttajalaskut Amili Kassavirta -palvelun kautta. Jos muutoksia ei ole tehty, tulevat kuluttajalaskut päätymään virheeseen.

SI-sanomien muutosten lisäksi voi myös olla tarvetta tehdä muutoksia RI-sanomien käsittelyyn ERP:ssä (katso kohta Kuinka toimia uusien kuluttajalaskusopimusten kanssa).

###### Mitä muutoksia laskuttajailmoituksille (SI-sanomat) tulisi tehdä

Lähettäjän tulee lisätä laskuttajailmoitukselle (SI-sanomille) Visma Amilin tilinumero (IBAN). Tämä IBAN löytyy palvelun asetussivulta kun palvelu on aktivoitunut.

Visma Amilin tilinumeron lisäämisen lisäksi tulee myös SellerInvoiceIdentifierType-tunnistetieto vaihtaa, mikäli tällä hetkellä käytätte tyyppiä 01 (kansallinen viitenumero) tai 02 (kansainvälinen RF-velkojan viite). SellerInvoiceIdentifierType määrittelee tunnistetiedon tyypin, joka kuluttajaa pyydetään täyttämään, kun hän lisää myyjän laskuttajakseen verkkopankkiinsa.

Jotkut pankit tekevät automaattisia ehdotuksia laskuttajista laskun IBAN:n, viitetiedon sekä laskuttajan nimen perusteella. Koska Amili Kassavirta -palvelussa laskuilla käytetty IBAN, viitenumero ja laskuttajan nimi kuuluvat Visma Amilille, saattaa kuluttaja päätyä vahingossa tekemään sopimuksen Visma Amilin kanssa varsinaisen lähettäjän sijaan.

Viitenumerot ovat myös ongelmallisia, koska ERP:ltä lähetetty viitenumero ei ole sama kuin se, jonka vastaanottaja saa laskullaan. Jos viitenumeroa käytetään uusien kuluttajasopimusten linkittämiseen asiakasrekisterissä, sinun on tarkistettava Visma Amilin käyttämä viitenumero toimeksiannon tiedoista ja lisättävä se asiakasrekisteriisi kuluttajan tunnistamiseksi.

Suosittelemme käyttämään SellerInvoiceIdentifierType-tunnistetietona tyyppiä 08 (muu numeerinen tunniste), 09 (muu aakkosnumeerinen tunniste) tai 99 (muu tunniste). Näihin tyyppeihin pankit eivät kohdista automaattisia laskuttajaehdotuksia. Helpoin ratkaisu on siirtyä käyttämään esimerkiksi asiakasnumeroa tunniste- ja kohdistustietona.

###### Kuinka tehdä tarvittavat muutokset

Yrityksen tulee lähettää CHANGE-tyyppiset SI-sanomat kaikkiin pankkeihin, joissa yrityksellä on voimassaolevat laskuttajailmoitukset. Uusi tilinumero kannattaa lisätä sopimuksille eikä korvata olemassa olevia. CHANGE-tyyppiset SI-sanomat voi luoda suoraan ERP-järjestelmästä tai [FKL:n tarjoamalla työkalulla](https://www.finanssiala.fi/fkmaterials/laskuttajailmoitus/FinvoiceSenderInfo.htm). Muutossanomien lähetyksen voi hoitaa joko omasta ERP-järjestelmästä tai suoraan Maventan käyttöliittymästä (Kuluttajalaskutus -> Lähetys).

###### Kuinka toimia uusien kuluttajalaskusopimusten kanssa (RI-sanomat)

Amili Kassavirta -palvelussa laskut lähtevät vastaanottajille muutettujen tilitietojen, viitenumeron ja laskuttajan nimen kanssa. Yrityksen laskulle laittama viitenumero ei siis mene sellaisenaan vastaanottajalle. Jos ERP-järjestelmässä käytetään viitenumeroa uusien kuluttaja-asiakkaiden kohdistamisessa, voi olla tarpeen yhdistää alkuperäisen laskun viitenumero vastaanottajalle lähetettyyn viitenumeroon. Vastaanottajalle lähetetty viitenumero löytyy toimeksiannon tiedoista. Toinen vaihtoehto on muuttaa SI-sanomien tunniste (SellerInvoiceIdentifier) johonkin muuhun kuin viitenumeroon.

#### Asiakasryhmittely (asiakaskohtainen perinnän rajaaminen)

Mikäli haluat rajata tiettyjen asiakkaidesi perinnän etenemistä, voit lisätä asiakkaan VIP- tai PREMIUM-asiakasryhmään. Ryhmittely toimii y-tunnuksen perusteella — huolehdi, että asiakkaan tiedoissa on oikea y-tunnus. Mikäli olet lisännyt asiakkaan asiakasryhmään mutta haluatkin jatkaa normaalia perintää, poista y-tunnus asiakasryhmästä. Jo päättyneiden toimeksiantojen perintä ei etene, vaikka asiakasryhmittelyä muutetaan.

Oletuksena maksuvalvonta etenee alla olevan kuvan mukaisesti. Tämä on tehokkain vaihtoehto kassavirran kannalta eikä vaadi sinulta toimenpiteitä:

![Oletusprosessi](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/default_pic_fi.png)

##### PREMIUM-asiakkaat

Erääntyneestä laskusta lähetetään maksumuistutus ja maksuvaatimus, jonka jälkeen perintä päättyy 30 päivän kuluttua maksuvaatimuksen eräpäivästä. Tämän jälkeen vastuu saatavan valvonnasta siirtyy sinulle. Mikäli asiakas ei ole suorittanut avointa saatavaa kokonaisuudessaan, sinulta veloitetaan 30 € + alv toimeksiannon päättämisen yhteydessä.

![PREMIUM-prosessi](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/premium_pic_fi.png)

##### VIP-asiakkaat

Erääntyneestä laskusta lähetetään ainoastaan kuluton maksumuistutus, jonka jälkeen perintä päättyy 30 päivän kuluttua maksumuistutuksen eräpäivästä. Tämän jälkeen vastuu saatavan valvonnasta siirtyy sinulle. Sinulta veloitetaan 5 € + alv per lähetetty maksumuistutus.

![VIP-prosessi](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/vip_pic_fi.png)

##### Ei maksuvalvontaa

Mikäli et halua siirtää asiakkaan laskuja lainkaan Amili Kassavirta -palvelun maksuvalvontaan, lisää asiakkaan y-tunnus tähän ryhmään. Näiden laskujen tiedot eivät siirry Visma Amilille. Laskuille tulostuu oma tilinumerosi ja vastaat itse suoritusten käsittelystä, saatavien valvonnasta ja mahdollisista perintätoimista. Lisäkustannuksia ei synny.

##### Asiakasryhmittelyt käyttöliittymässä

Käyttöliittymän kautta asiakkaita voi asettaa PREMIUM-, VIP- tai Ei maksuvalvontaa -ryhmiin lisäämällä asiakkaan y-tunnus haluttuun ryhmään. Sama y-tunnus ei voi olla useassa ryhmässä samanaikaisesti — jos esimerkiksi lisäät PREMIUM-ryhmässä olevan y-tunnuksen VIP-ryhmään, se siirretään automaattisesti.

![Asiakkaan lisääminen asiakasryhmään](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/adding_new_customer_to_service_level_fi.png)

Kun lähetät laskun PREMIUM- tai VIP-ryhmään kuuluvalle asiakkaalle, asiakasryhmittelyn tieto näkyy toimeksiantojen listauksessa. Tieto päivittyy viiveellä ja näkyy käyttöliittymässä noin 1–2 tunnin sisällä toimeksiannon luonnista.

![Asiakasryhmittelyt toimeksiantojen listauksessa](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/service_level_assginment_listing.png)

#### Laskujen lähetyksen vaiheet Amili Kassavirta -palvelussa

##### 1. Laskujen lähetys ERP:stä

Laskujen lähetys tapahtuu normaaliin tapaan ERP:stä. Sinun ei tarvitse tehdä muutoksia laskuaineiston sisältöön — varmista vain, että aineisto on validia ja sisältää alla olevat pakolliset tiedot.

Huom! Laskun alkuperäistä kuvaa ei toimiteta vastaanottajalle, vaan se poistetaan lähetyksestä, koska aineiston muutosten takia alkuperäisessä kuvassa ei ole enää oikeita maksutietoja. Maventa luo muokatusta aineistosta uuden kuvan. Jos haluat kuvalle yrityksesi logon, lisää logotiedosto tilin asetuksiin (Asetukset -> Laskuasetukset -> Laskujen lähettäminen -> Laskun kuvan asetukset). Laskun mahdollisia erillisiä liitteitä ei poisteta, vaan ne toimitetaan vastaanottajalle normaalisti.

###### Pakolliset tiedot laskulla

- Vastaanottajan täydellinen postiosoite
- Eräpäivä, joka ei ole menneisyydessä ja johon on vähintään 3 pankkipäivää
- Laskun loppusumma vastaa rivien yhteenlaskettua summaa
- Laskulla on viitenumero
- Vastaanottajan kielikoodi (Finvoice InvoiceRecipientLanguageCode), jos maksumuistutukset halutaan muulla kielellä kuin suomeksi. Tuettuna ovat ruotsi ja englanti.
- Yksilöllinen laskunumero. Saman numeron käyttöä uudestaan tulisi välttää. Poikkeukset:

1. Jos uudella laskulla on eri laskupäivämäärä kuin olemassa olevassa toimeksiannossa, luodaan uusi toimeksianto samalla laskunumerolla.
2. Jos uudella laskulla on sama laskupäivämäärä kuin suljetulla toimeksiannolla ilman maksuja tai hyvityslaskuja, luodaan uusi toimeksianto.
3. Jos uudella laskulla on sama laskupäivämäärä kuin avoimella toimeksiannolla ilman maksuja tai hyvityslaskuja ja alkuperäinen lasku on virhetilassa, vanha toimeksianto suljetaan ja uusi luodaan.

###### Mitkä laskut eivät kulje Amili Kassavirta -palvelun kautta

- Vain EUR-valuuttaiset laskut hyväksytään. Muun valuutan laskut ohjataan suoraan vastaanottajille ja niiden saatavia tulee seurata itse.
- Palvelu ei tue seuraavia laskuformaatteja: OIOXML, WoodX, BGC, Axflow, Facturae, PX, UBL.
- Kuluttajien e-laskujen (B2C) välityksessä on aktivoinnin alussa 7 päivän siirtymäaika. Katso lisätiedot kohdasta Kuluttajien laskutus (B2C).

##### 2. Maventa välittää laskun sisällön Visma Amilille muokattavaksi

Maventa välittää laskuaineiston Visma Amilille, joka muokkaa laskulta seuraavat tiedot:

###### Mitä tietoja laskulta muokataan

- **IBAN** — Visma Amili korvaa lähettäjän tilitiedot omillaan, jotta vastaanottaja maksaa laskun Visma Amilin tilille. Visma Amili tilittää saatavat lähettäjälle aktivoinnissa annetun tilinumeron ja alkuperäisen viitenumeron avulla.

- **Viitenumero** — Visma Amili korvaa lähettäjän viitenumeron omallaan. Saatavat tilitetään silti laskun alkuperäisellä viitteellä. Käytetyn viitenumeron näet toimeksiantojen listauksesta.

- **Siirtolauseke** — Visma Amili lisää laskuille siirtolausekkeen, esimerkiksi:

> Olemme siirtäneet laskujen lähettämisen sekä saataviemme eräpäivän jälkeisen seurannan ja sitä koskevat toimenpiteet Visma Amili Oy:n laskutuspalveluun. Palvelua tai tilausta koskevissa asioissa pyydämme ottamaan yhteyttä suoraan: Lähettävä yritys Oy puh: xxx xxx xxx, e-mail: lähettäjä@yritys.com. Maksamiseen liittyvissä asioissa pyydämme ottamaan yhteyttä Visma Amili Oy:n verkkopalveluun tai asiakaspalvelun numeroon 024 808 8020.

- **FreeText** — Visma Amili lisää laskuille myös tekstin, jossa on linkki ja kirjautumistunnukset Visma Amilin verkkopalveluun:

> VERKKOPALVELU: https://www.laskuhelposti.fi/
> KIRJAUTUMISTUNNUS: P3963915-xx-xxxx-xxxx

- Maventa luo laskusta uuden kuvan, joka sisältää kaikki muokatut tiedot.

##### 3. Muokattu lasku lähetetään vastaanottajalle

Muokattu lasku lähetetään asiakkaalle normaalin Maventan lähetysprosessin kautta. Maventa luo laskusta uuden PDF-kuvan. Huom! Lähettäjänä olet edelleen vastuussa laskun perille menosta ja mahdollisten virhetilanteiden selvityksestä.

Kaikista lähetetyistä laskuista luodaan toimeksianto, joka toimii viestintäkanavana yrityksesi ja Visma Amilin välillä. Toimeksiannon tapahtumien kautta voit seurata laskun etenemistä ja ilmoittaa muutoksista.

##### 4. Kun asiakas maksaa laskun

Kun asiakas maksaa laskun Visma Amilille, Visma Amili tilittää saatavan lähettäjälle aktivoinnissa annetun tilinumeron ja alkuperäisen viitenumeron avulla. Toimeksiannolle merkitään tieto maksusta ja se suljetaan. Suljetut toimeksiannot siirtyvät suljettujen toimeksiantojen listaukseen.

##### 5. Jos asiakas ei maksa laskua ajallaan

Jos asiakas ei maksa laskua ajallaan, Visma Amili käynnistää huomautus- ja perintäprosessin. Prosessin etenemistä voit seurata toimeksiannon tiedoista.

### Amili Perintä

Amili Perintä on muistutus- ja perintäpalvelu, jonka avulla voit siirtää yksittäisiä erääntyneitä laskuja muistutus- ja perintäprosessiin tai suoraan perintäprosessiin. Palvelun kautta voit myös seurata muistutus- ja perintätoimien etenemistä rajapinnan tai Maventan käyttöliittymän kautta.

#### Amili Perintä -palvelun aktivointi

Kun palvelu on aktivoitu, yksittäisiä erääntyneitä laskuja voi siirtää muistutus- ja perintäprosessiin tai suoraan perintäprosessiin Visma Amilille.

Voit aktivoida Amili Perintä -palvelun Maventa-tilin asetusten kautta kohdasta: Perintäpalvelut -> Yleiset asetukset

1. Valitse palvelun tyypiksi Amili Perintä.
2. Täytä perustiedot lomakkeelle ja paina "Jatka". Tämä aloittaa aktivointiprosessin.
3. Viimeistele käyttöönotto Netvisor KYC -palvelussa klikkaamalla linkkiä. Tämä viimeistelee aktivointiprosessin.
4. Palvelu on käytössäsi 1–2 arkipäivän sisällä ilman lisämaksuja.

Aktivointi viimeistellään Netvisor KYC -palvelussa täyttämällä tietopyyntölomake. Samalla hyväksytään palvelun sopimusehdot. Lomakkeen täyttämiseksi tarvitaan henkilökohtaiset verkkopankkitunnukset tai mobiilivarmenne.

Rahanpesulain mukaan Visma Amili Oy:n on varmistettava, että he tuntevat asiakkaansa ja heidän toimintansa. Tietopyyntöön vastaavalla henkilöllä tulee olla oikeus toimia organisaation puolesta asemansa tai valtakirjan perusteella. Edustusoikeuden perustuessa valtakirjaan, valtakirja tulee liittää lomakkeeseen.

Jos käyttöönottoa ei viimeistellä viikon kuluessa, lähetetään muistutus yhteyshenkilön sähköpostiosoitteeseen.

##### Mitä tietoja aktivoinnissa pyydetään

Tällä hetkellä alla olevia tietoja ei voi muokata käyttöliittymän kautta. Jos tietoja on tarvetta päivittää, ota yhteyttä asiakaspalveluun.

**Pankkitilin tiedot:**

Yrityksesi pankkitilin tiedot, jolle Visma Amili maksaa tilitykset. Maksuissa käytetään aina alkuperäisen laskun viitenumeroa, joten saatavien kohdistaminen hoituu ERP:ssä tavalliseen tapaan. Maksajana näkyy VISMA AMILI.

**Yhteystiedot:**

Henkilö, johon voidaan tarvittaessa olla yhteydessä palveluun liittyvissä asioissa.

**Asiakaspalvelun tiedot:**

Tiedot, jotka Visma Amili voi tarvittaessa antaa asiakkaalle.

**Laskutustiedot:**

Laskutustiedot mahdollisia palvelumaksuja varten, esimerkiksi myöhempien perintävaiheiden oikeuskuluihin liittyvät maksut. Velalliselta kertyneen palkkion, korvauksen tai kulun arvonlisävero laskutetaan toimeksiantajalta, mikäli toimeksiantajalla on oikeus vähentää perintäpalkkion arvonlisävero. Tämä arvonlisävero on kokonaan vähennyskelpoinen erä.

#### Laskujen siirto muistutus- ja perintäprosessiin

Amili Perintä -palvelussa yksittäisiä erääntyneitä laskuja voi siirtää joko muistutus- ja perintäprosessiin tai suoraan perintäprosessiin. Siirto tapahtuu käyttöliittymästä lähetetyn laskun tiedoista. Kun laskun eräpäivä on mennyt, laskun tietoihin ilmestyy nappi "Siirrä lasku muistutus- tai perintäprosessiin".

**Muistutus ja perintä** — Visma Amili lähettää ensin maksumuistutuksen ja jatkaa perintäprosessia, mikäli suoritusta ei tule.

**Perintä** — Lasku siirretään suoraan perintäprosessiin. Tällöin olet itse hoitanut jo maksumuistuttamisen.

Huom! Siirto Amili Perintä -palveluun ei välttämättä tapahdu välittömästi. Siirron tilaa voit seurata laskun tiedoista:

- **Siirto odottaa** — Lasku odottaa siirtoa.
- **Siirretty onnistuneesti** — Lasku on siirretty Amili Perintä -palveluun ja laskusta on luotu toimeksianto, jota voit seurata Perintäpalvelut-sivulta.
- **Virhe** — Laskun siirto ei onnistunut. Yleisin syy on puuttuvat vastaanottajan osoitetiedot.

##### Pakolliset tiedot laskulla

- Vastaanottajan täydellinen postiosoite
- Eräpäivän on oltava menneisyydessä
- Valuuttana EUR
- Laskun loppusumma vastaa rivien yhteenlaskettua summaa
- Laskulla on viitenumero
- Vastaanottajan kielikoodi (Finvoice InvoiceRecipientLanguageCode), jos maksumuistutukset halutaan muulla kielellä kuin suomeksi. Tuettuna ovat ruotsi ja englanti.
- Yksilöllinen laskunumero. Saman numeron käyttöä tulisi välttää. Poikkeukset ovat samat kuin Amili Kassavirta -palvelussa.

#### Amili Perintä -palvelun muistutuksen ja perinnän vaiheet

![Amili Perintä -prosessi](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/reskontravahti_express_reminder_collection_process_fi.png)

#### Asiakasryhmittely Amili Perintä -palvelussa

Asiakasryhmittelyt toimivat myös Amili Perintä -palvelun osalta, mutta niiden käyttö ei yleensä ole tarkoituksenmukaista.

### Toimeksiannot

Amili Kassavirta -palvelussa toimeksianto luodaan jokaisesta palvelun kautta lähetetystä laskusta. Amili Perintä -palvelussa toimeksianto luodaan jokaisesta palveluun erikseen siirretystä laskusta.

Toimeksianto on viestintäkanava yrityksesi ja Visma Amilin välillä. Visma Amili ilmoittaa toimeksiannon kautta laskulle tapahtuneista muutoksista, esimerkiksi maksuista ja maksumuistutuksista. Voit myös itse lisätä toimeksiannolle tapahtumia, kuten eräpäivän siirtopyyntöjä tai kysymyksiä Visma Amilille.

Toimeksiannot löytyvät käyttöliittymästä ylävalikon "Perintäpalvelut"-sivulta. Oletusnäkymänä on saatavien yleiskatsaus linkkeineen toimeksiantojen listaukseen, kuvaus palvelusta sekä tärkeimmät asetukset.

![Saatavien yleiskatsaus](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/reskontravahti_guide_dashboard2.png)

Sivun vasemmasta reunasta löytyy palvelun valikko:

- **Toimeksiannot:** Listaus kaikista avoimista toimeksiannoista
- **Viestit:** Listaus toimeksiannoista, joissa on viesti tai kommentti. Suosittelemme seuraamaan tätä, jotta tärkeät viestit eivät jää huomaamatta.
- **Suljetut toimeksiannot:** Listaus suljetuista toimeksiannoista (maksetut, manuaalisesti suljetut)
- **Asetukset, yleiset asetukset:** Palvelun aktivointitiedot, mm. siirtolausekkeen tiedot
- **Asetukset, Asiakasryhmittely:** Asiakasryhmittelyjen hallinta (hyödyllinen erityisesti Amili Kassavirta -palvelun kanssa, mutta toimii myös Amili Perintä -palvelun osalta)

![Toimeksiantojen listaus](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/reskontravahti_guide_listing_ass_1.png)

Yksittäisen toimeksiannon tiedot:

![Toimeksiannon tiedot](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/reskontravahti_guide_assignment_details_1.png)

Hyvityslasku toimeksiantona:

![Hyvityslasku toimeksiantona](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/reskontravahti_guide_hyvitys_1.png)

### Toimeksiannon tapahtumat joita asiakas voi lisätä

#### Lisää kommentti tai kysymys

![Kommentin lisääminen](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/reskontravahti_guide_kommentti.png)

#### Lisää ohisuoritus

Jos asiakas on maksanut suoraan yrityksesi tilille, ilmoita siitä Visma Amilille ohisuoritustapahtumalla. Näin Visma Amili tietää lopettaa saatavien valvonnan ja mahdolliset perintätoimet. Ohisuoritus voi olla koko laskun loppusumma tai osa siitä.

![Ohisuorituksen lisääminen](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/Reskontravahti_guide_suoritus.png)

#### Yhdistä hyvityslasku

![Hyvityslaskun yhdistäminen](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/Reskontravahti_guide_hyvitys_ass.png)

#### Pyydä eräpäivän siirtoa

Jos haluat siirtää toimeksiannon eräpäivää, voit tehdä sen kohdasta "Pyydä eräpäivän siirtoa". Visma Amili joko hyväksyy tai hylkää pyynnön. Jos eräpäivä on jo mennyt ja perintätoimet on aloitettu, pyyntö hylätään ja toimeksiantoon lisätään kommentti hylkäyssyyn kera.

#### Pyydä väliaikaista perintäkieltoa

Jos on tarpeen väliaikaisesti jäädyttää toimeksiannon perintä, esimerkiksi selvitystyön ajaksi, voit pyytää perintäkieltoa tiettyyn päivämäärään asti. Perintä jatkuu automaattisesti päättymispäivän jälkeen. Voit muuttaa päättymispäivää tai päättää perintäkiellon asettamalla kuluvan päivän päättymispäiväksi.

Huomaa, että perintäkiellon aikana Visma Amili ei seuraa toimeksiantoa eikä tee perintätoimenpiteitä — yritys vastaa itse toimeksiannon seurannasta. Perintäkieltoa ei voi asettaa, jos oikeudellinen perintä on jo aloitettu tai ulosotto on todennut asiakkaan varattomaksi.

#### Peruuta toimeksianto

Voit perua toimeksiannon pysyvästi. Peruutusta ei voi kumota jälkikäteen. Visma Amili ei valvo saatavaa tai tee perintätoimia peruutuksen jälkeen. Tätä tapahtumaa ei tule käyttää luottotappion kirjaamiseen. Mikäli muistutus- tai perintätoimet on jo aloitettu, Visma Amili veloittaa peruutusmaksun.

#### Kirjaa toimeksianto luottotappioksi

Voit kirjata toimeksiannon luottotappioksi kirjanpitoa varten. Visma Amili jatkaa velan perimistä. Luottotappioksi kirjaamista ei voi kumota jälkikäteen. Yleensä Visma Amili itse ehdottaa luottotappion kirjaamista kun siihen on tarve.

### Toimeksiannon tapahtumat joita Visma Amili voi lisätä

- Kysymys tai kommentti
- Suoritus tai osasuoritus on kirjattu
- Toimeksianto on suljettu
- Toimeksianto on suljettu osittain pääoman osalta (Visma Amili jatkaa kulujen perimistä)
- Eräpäivän siirtopyyntö on hyväksytty
- Perintäkielto on asetettu toimeksiannolle
- Perintäkielto on päättynyt ja perintä jatkuu
- Ilmoitus viivästyskorosta ja sen määrästä
- Ilmoitus käteisalennuksen käytöstä ja sen määrästä
- Ilmoitus kun ensimmäinen maksumuistutus on lähetetty
- Ilmoitus kun toinen maksumuistutus on lähetetty
- Ilmoitus kun ensimmäinen maksuvaatimus on lähetetty
- Ilmoitus kun toinen maksuvaatimus on lähetetty
- Laskusta on lähetetty tratta
- Haastehakemus on laadittu ja toimeksianto on siirretty oikeudelliseen perintään
- Täytäntöönpanohakemus on laadittu ja toimeksianto on siirretty ulosottoon
- Suositus kirjata lasku luottotappioksi
- Ulosotto on todennut asiakkaan varattomaksi
- Laskusta on sovittu maksusuunnitelma
- Ilmoitus asiakasryhmittelyn päivityksestä

## Palvelun asetusten muokkaaminen

Palvelun asetuksia ei tällä hetkellä voi muokata käyttöliittymän kautta. Jos aktivoinnin yhteydessä määriteltyjä tietoja halutaan muuttaa, ota yhteyttä asiakaspalveluun osoitteessa `support@maventa.com`. Palvelun tyypin (Amili Kassavirta tai Amili Perintä) voi vaihtaa asetusten kautta.

## Raportointityökalu

Raportointityökalun avulla saat paremman näkyvyyden myyntisaatavista ja luottotappiosuosituksista. Raportointityökalu löytyy käyttöliittymästä kohdasta Perintäpalvelut -> Raportit.

### Saatavilla olevat raportit

Voit ladata raportteja valitulta ajanjaksolta (enintään 365 päivää). Saatavilla on kaksi raporttityyppiä:

- **Tilitysraportti:** Yhteenveto kaikista valitun ajanjakson aikana tehdyistä tilityksistä.
- **Luottotappiosuositusraportti:** Lista annetuista luottotappiosuosituksista valitulta ajanjaksolta.

Molemmat raportit ovat saatavilla PDF- ja Excel-muodossa.

## Palvelun sulkeminen

Palvelun voi sulkea asetussivulta "Poista käytöstä" -painikkeella. Sulkemisen jälkeen uusia laskuja ei enää välitetä palvelun kautta. Visma Amili jatkaa avoimien toimeksiantojen hoitoa.

## Muuta

### Connectorin käyttäjille

Connectorin asetuksista on suositeltavaa ottaa lähetettyjen laskujen varmuuskopiointi pois käytöstä. Toiminnallisuus saattaa kopioida laskun tiedot ennen kuin Visma Amili ehtii muokata niitä, jolloin varmuuskopio ja vastaanottajalle lähetetty lasku voivat olla sisällöltään erilaisia.

![Connectorin varmuuskopiointi](/assets/pages/99-individual-pages/04-receivables-customer-guide-fi/receivables_connector_varmuuskopiointi.png)

## Hyödyllisiä linkkejä

[Palvelukuvaus ja hinnasto (Visma Amili)](https://amili.fi/hubfs/Sopimusehdot/Visma-Amili-Palvelusopimus-kanava-asiakkaille-08-24.pdf)

[Visma Amili Oy:n yhteystiedot](https://www.visma.fi/yritykset/visma-amili-oy#yhteystiedot)

## Usein kysytyt kysymykset

**Olen aktivoinut Amili Kassavirta -palvelun. Miten saan laskun siirrettyä palveluun?**

Kun palvelu on aktivoitu, kaikki yrityksen tililtä lähetetyt laskut välitetään automaattisesti Amili Kassavirta -palveluun. Ainoat poikkeukset ovat laskut, joissa valuuttana on joku muu kuin euro. Sinun ei tarvitse muuta kuin lähettää laskut tavalliseen tapaan taloushallinto-ohjelmistostasi. Ennen aktivointia lähetettyjä laskuja ei voi siirtää palvelun piiriin.

**Täytyykö minun muuttaa laskulle jotain tietoja, jotta asiakas maksaa suoritukset oikein?**

Ei tarvitse. Maventa välittää laskuaineiston Amili Kassavirta -palveluun, joka huolehtii siitä, että laskulle tulee oikea tilinumero, viitenumero ja siirtolauseke.

**Mitä palvelun käyttö maksaa?**

Molemmat Amili-palvelut kuuluvat Maventa-palveluun ilman lisäkustannuksia. Erillisiä avaus-, kuukausi- tai vuosimaksuja ei ole. Maksat vain lähetetyistä laskuista. Palvelu on maksuton vapaaehtoisen perinnän loppuun asti. Myöhemmistä perintätoimista saattaa aiheutua kuluja, mutta Visma Amili ottaa aina ensin yhteyttä — yllätyskuluja ei siis tule. Velalliselta kertyneen palkkion arvonlisävero laskutetaan toimeksiantajalta, mikäli toimeksiantajalla on oikeus vähentää sen. Tämä arvonlisävero on kokonaan vähennyskelpoinen erä.

**Myöhästymiskorot laskulla**

Jos olet itse määritellyt myöhästymiskoron laskulle (laskun XML-tiedostossa), Visma Amili lisää sen asiakkaalle lähetettäviin maksumuistutuksiin. Korot tilitetään erillisenä koontitilityksenä kerran päivässä. Tiliotteella viesti näkyy muodossa "Korkotilitys PVM". Toimeksiannolle tulee merkintä maksetusta korosta.

**Tuleeko minun seurata lähetettyjen laskujen tiloja ja käsitellä virheet?**

Kyllä. Laskujen perille menosta ja virhetilanteiden selvityksestä lähettäjä on itse vastuussa. Jos lasku menee virheeseen, se tulee joko uudelleenreitittää toiseen osoitteeseen tai hyvittää ja lähettää uusi lasku.

**Mitä mahdollisia virheviestejä palvelusta voi tulla?**

- `SEND ERROR (REASON: RECEIVABLES-SERVICE: Invoice already exists (code #6 ...))` — Lasku samalla numerolla on jo palvelussa eikä uutta toimeksiantoa voida luoda.

- `SEND ERROR (REASON: RECEIVABLES-SERVICE: The due date for the invoice is within three (3) days or has already passed (code #13))` — Laskun eräpäivään on liian vähän aikaa tai se on jo mennyt. Korjaa eräpäivä ja lähetä lasku uudelleen.

- `SEND ERROR (REASON: RECEIVABLES-SERVICE: Postal code for CITY_NAME xxxxxx not found (code #5))` — Vastaanottajan osoitetiedoissa on virhe tai ne ovat puutteelliset. Korjaa osoitetiedot ja lähetä lasku uudelleen.

**Jos laskuni menee virheeseen puuttuvan osoitteen takia, miten toimin?**

Suosittelemme laskun uudelleenreititystä käyttöliittymästä tai ERP-ohjelmistosta. Uudelleenreitityksellä voit määritellä uuden reitin (e-lasku, sähköposti, tulostus) tai uudet osoitetiedot. Uudelleenreititys ei luo uutta toimeksiantoa.

Jos joudut lähettämään kokonaan uuden laskun, luo ERP-järjestelmässä hyvityslasku alkuperäiselle laskulle ja yhdistä se toimeksiannolle, jotta Visma Amili osaa sulkea toimeksiannon. Hyvityslaskua ei tarvitse varsinaisesti lähettää — riittää, että yhdistyksen tekee toimeksiannon tiedoista.

Jos virheessä olevalle laskulle ei tehdä toimenpiteitä, Visma Amili sulkee toimeksiannon eräpäivän jälkeisenä päivänä ja lisää toimeksiannolle viestin asiasta.

Uudella laskulla on käytettävä uutta laskunumeroa.

**Voiko ylisuorituksen kohdistaa muille saman asiakkaan laskuille?**

Ei. Ylisuorituksia ei kohdisteta muille auki oleville toimeksiannoille eikä säilytetä tulevaa varten. Ylisuoritus palautetaan asiakkaalle.

---