Core Concepts

A short tour of the concepts that drive Ventoo Pingen Connector — read this once and the rest of the documentation will make sense.

Document Sending Profile as the dispatch switch

The connector uses the standard Business Central Document Sending Profile as its only customer selector. Only customers whose profile matches the code configured in setup (e.g. POST) are pulled into automatic dispatch.

Why that matters:

• A customer moves from email to postal delivery → change the profile on the customer card. The next posted invoice picks up the new behaviour.

• A tenant pauses postal dispatch → clear the profile code in setup.

Important — profile is frozen at posting time: The connector freezes the customer's Document Sending Profile into an internal Pingen Auto-Send flag at the moment each invoice is posted. Profile changes on the customer card afterwards do not retroactively affect already-posted invoices. This prevents old invoices from being unexpectedly sent just because a customer was later switched to the POST profile.

Note: With no profile code configured in setup, the job queue runs but does nothing.

Posting-date delay (Send Days Delay)

Posted invoices don't have to dispatch immediately. The Send Days Delay parameter waits N days after the posting date before an invoice becomes eligible for the job queue:

Dispatch date >= Posting date + Send Days Delay

This gives staff time to spot mistakes, issue credit memos, or block individual documents before letters leave the building.

Processing status per document

Each supported document carries two extension fields that capture its Pingen status:

Note: Use the Disable Pingen Sending and Enable Pingen Sending actions on the document to flip the flag manually.

PDF generation through Report IDs

For each document type, setup stores a Report ID that renders the PDF. The Microsoft standard reports are configured out of the box:

Using a custom report layout? Enter the ID of your own report. The connector calls Report.SaveAs with the document as the filter and ships the resulting PDF to Pingen.

How a letter reaches Pingen

Each dispatch makes four calls against the Pingen API:

1. Authenticate — request an OAuth access token from identity.pingen.com using Client ID + Client Secret.

2. Request upload URL — call /file-upload to receive a pre-signed S3 URL.

3. Upload the PDF — PUT the rendered PDF directly to that S3 URL.

4. Create the letter — call /organisations/{id}/letters with the document metadata (address position, delivery product, print mode, color spectrum).

On failure: If any step fails, the document is not marked as processed. The next job queue run retries it.

Error detail: Failed API calls surface the HTTP status code and Pingen's response body — e.g. Pingen: Letter creation failed (HTTP 422). Response: .... That makes it easy to tell auth (401), validation (422), and network issues apart straight from the job queue log.

Robust batch processing: If a single invoice fails (e.g. incomplete address), the run does not abort. The connector logs the error, skips the document, and continues with the next one. Successful dispatches earlier in the same run are preserved.

Credential storage

The Pingen Client Secret is not stored in a database table. It lives encrypted in the Business Central Isolated Storage (module scope), so it never appears in Show Table views or database backups in plain text. On the setup page, the Client Secret field shows dots when a value is stored — overwrite the dots to replace it.

Related

• General Setup

• Print Settings

• Table and Field Reference