---
title: "Reference implementations"
canonical: 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](https://documentation.maventa.com/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);
```