Backend Integration Guide

This page describes the recommended server-to-server integration flow for backend applications. An example is if the submitted forms by the users should be processed by a business application and the status updates being passed back to Digitale-Gemeinde.

For exact request/response details, see the linked API Reference endpoints in each step.

Overview

A typical integration follows these steps:

1. Authenticate (API key → JWT)

2. Retrieve tasks with status New

3. Retrieve details for a specific task

4. Update task status during processing

5. Submit documents / results and complete the task

Step 1 — Authenticate and obtain a JWT token

Goal: Create an authenticated session for subsequent API calls.

What to do

• Call the Token / Authentication endpoint using your API key.

• Store the returned JWT (bearer token) in memory (or a short-lived cache).

• Include the token in the Authorization header for all following requests.

Operational guidance

• Cache the token until shortly before it expires, then refresh it.

• If you receive 401/403, treat it as an invalid/expired token (refresh once) or invalid API key (raise an alert).

Step 2 — Retrieve the number of tasks

Goal: Find the number of tasks for the specified tenant by form and status. This can be used to display an overview list of tasks for the user.

What to do

• Call the Form/count endpoint

Operational guidance

• Polling is the usual approach (e.g., every 30–120 seconds). Note that rate limits apply.

Step 3 — Retrieve tasks with status “New”

Goal: Find submitted orders that your backend system should process.

What to do

• Call the Search submitted forms endpoint with a filter for tasks whose status is Neu.

• The response returns the unqiue identified of the form documentId. This Id can be used in the next step to retrieve the details of the task.

• The API call uses pagination, loop through the different pages if needed.

Operational guidance

• Polling is the usual approach (e.g., every 30–120 seconds)

• Avoid processing the same task twice (see Step 5 for locking pattern).

Step 4 — Retrieve details for one task

Goal: Fetch all information required to display or process a task.

What to do

• For each task you want to handle, call the Get form details by documentId endpoint using the documentid from the previous step.

• Use the returned fields/documents to render the task in your own UI or perform backend processing.

Step 5 — Update the task status during processing

Goal: reflect progress in the Digitale-Gemeinde Cockpit and pass the status information back to the portal as well as prevent duplicate processing. Call the Update form instance field values by documentId endpoint.

Recommended lifecycle

• Neu → In Bearbeitung when your system starts processing

• In Bearbeitung → Abgeschlossen when result submission succeeded or the task is completed in the backend application

• In Bearbeitung → Refund when processing cannot continue . This will also trigger a refund if the payment was made via an online payment provider

What to do

• For each status update call the Update form instance field values by documentId endpoint.

Step 6 — Submit documents

Goal: deliver the generated output (e.g., PDF).

What to do

• Call the Upload a file to a file upload field in a form instance endpoint for the task.

• Ensure submission succeeds.

• Update task status to Abgeschlossen as described in the previous step