Exact Online Client

A Spring Boot application for read-only data fetching from Exact Online's REST API. Provides OAuth2 authentication, API client functionality for fetching accounts, subscriptions, transactions, and invoices, webhook handling for receiving notifications, and optional event publishing.

Note: This client is designed for data fetching only. It does not support creating, updating, or deleting data in Exact Online via POST/PUT/PATCH/DELETE operations.

Features

• ✅ Read-Only Data Fetching - Fetch accounts, subscriptions, transactions, and invoices
• ✅ OAuth2 Authentication with automatic token refresh
• ✅ REST API Client with pagination and rate limiting
• ✅ Webhook Support for receiving Exact Online notifications
• ✅ Optional RabbitMQ event publishing
• ✅ Optional Redis caching
• ✅ Docker support with Docker Compose

Scope: This client focuses on reading data from Exact Online. It does not perform write operations (create, update, delete) on Exact Online entities.

Prerequisites

• Docker Engine 20.10+ and Docker Compose 2.0+
• Exact Online App credentials (Client ID, Client Secret, Division ID)

Quick Start with Docker

1. Clone and Setup

git clone <repository-url>
cd exact-online-client

2. Configure Environment

Copy the example environment file:

cp env.example .env

Edit .env with your Exact Online credentials:

# Required
EXACT_ONLINE_CLIENT_ID=your-client-id
EXACT_ONLINE_CLIENT_SECRET=your-client-secret
EXACT_ONLINE_DIVISION_ID=your-division-id

# Optional
EXACT_ONLINE_REDIRECT_URI=http://localhost:8080/callback
EXACT_ONLINE_GL_ACCOUNT_CODE=your-gl-account-code
EXACT_ONLINE_JOURNAL_CODE=your-journal-code

3. Start Services

docker-compose up -d

This starts:

• exact-online-client - Main application (port 8080)
• postgres - PostgreSQL database (port 5432)
• redis - Redis cache (port 6379)
• rabbitmq - RabbitMQ for events (optional, use --profile events)

4. Check Status

# View logs
docker-compose logs -f exact-online-client

# Check service status
docker-compose ps

5. Access the Application

• API Base: http://localhost:8080
• Swagger UI: http://localhost:8080/swagger-ui.html
• API Docs: http://localhost:8080/v3/api-docs

6. Authenticate with Exact Online

Visit the OAuth callback endpoint with your authorization code:

http://localhost:8080/callback?code=YOUR_AUTHORIZATION_CODE

Or use the OAuth flow to get a token automatically.

Getting Your Division ID

1. Log into Exact Online
2. Check your URL: https://start.exactonline.nl/[DIVISION_ID]/
3. Or call the API after authentication: GET /api/v1/current/Me?$select=CurrentDivision

Configuration

All configuration is environment-based. See env.example for all available variables.

Required Variables

• EXACT_ONLINE_CLIENT_ID - Your Exact Online App Client ID
• EXACT_ONLINE_CLIENT_SECRET - Your Exact Online App Client Secret
• EXACT_ONLINE_DIVISION_ID - Your Exact Online Division ID

Optional Variables

• EXACT_ONLINE_REDIRECT_URI - OAuth redirect URI (default: http://localhost:8080/callback)
• EXACT_ONLINE_GL_ACCOUNT_CODE - GL Account Code for transaction filtering
• EXACT_ONLINE_JOURNAL_CODE - Journal Code for transaction filtering
• EXACT_ONLINE_EVENTS_ENABLED - Enable RabbitMQ event publishing (default: false)

API Endpoints

OAuth2

• GET /callback - Handle OAuth2 callback

Accounts

• GET /api/v1/accounts - Fetch all accounts from database
• GET /api/v1/accounts/{id} - Fetch account by ID
• GET /api/v1/internal/exact-online/accounts - Fetch all accounts from Exact Online
• GET /api/v1/internal/exact-online/accounts/{id} - Fetch account by ID from Exact Online

Subscriptions

• GET /api/v1/subscriptions - Fetch all subscriptions
• GET /api/v1/subscriptions/{id} - Fetch subscription by ID
• GET /api/v1/internal/exact-online/subscriptions - Fetch from Exact Online

Transactions

• GET /api/v1/transactions - Fetch transaction lines (with filtering)
• GET /api/v1/transactions/{id} - Fetch transaction by ID

Webhooks

• POST /api/v1/webhook - Receive webhook notifications from Exact Online
• POST /api/v1/webhook/subscribe - Subscribe to a webhook topic (read-only subscription management)
• GET /api/v1/webhook/list-active - List active subscriptions
• DELETE /api/v1/webhook/unsubscribe/{id} - Unsubscribe from webhook (subscription management only)

Running Without Docker

Prerequisites

• Java 21+
• Maven 3.6+
• PostgreSQL 16+
• Redis (optional)
• RabbitMQ (optional)

Build and Run

mvn clean package
java -jar target/exact-online-client-*.jar

Configure via application.yml or environment variables.

Stopping Services

# Stop services
docker-compose down

# Stop and remove volumes (⚠️ deletes data)
docker-compose down -v

Troubleshooting

Application won't start

docker-compose logs exact-online-client

Database connection issues

docker-compose ps postgres

Port conflicts

Modify ports in docker-compose.yml or use different ports in .env.

Documentation

• Examples - Code examples and tutorials
  • OAuth2 Setup - Authentication guide
  • API Client Usage - API usage examples
  • Webhook Setup - Webhook configuration
• Docker Setup Guide - Detailed Docker documentation
• Contributing - How to contribute
• Security Policy - Security reporting
• Changelog - Version history
• Swagger UI - Interactive API documentation

Links

• Exact Online API Documentation
• Exact Online Developer Portal