> ## Documentation Index
> Fetch the complete documentation index at: https://docs.business-os.de/llms.txt
> Use this file to discover all available pages before exploring further.

# Banking Make App

> PSD2 Banking direkt in Make.com — Konten, Transaktionen und Zahlungen ohne Code

# Banking Make App

Die **Business OS Banking** Custom App für [Make.com](https://www.make.com) gibt dir die komplette Banking-API als drag-and-drop Module — für Konto-Listings, Transaktions-Sync, Daily-Balances und SEPA/SEPA-Instant-Zahlungen über 3.300+ Banken in Deutschland.

## Installation

1. Öffne dein Make.com-Team und gehe zu **Apps** → **Add app**
2. Suche nach **Business OS Banking** oder nutze den direkten Link: [Banking App im Make Marketplace](https://eu1.make.celonis.com/) {/* TODO: konkrete Marketplace-URL einsetzen */}
3. Klicke **Install** — die App ist sofort in deinem Szenario-Builder verfügbar

<Note>
  Die App läuft auf der Celonis-Make-Zone (`eu1.make.celonis.com`). Wenn du eine andere Make-Zone nutzt, kontaktiere [impressum@business-os.de](mailto:impressum@business-os.de) — wir migrieren die App in dein Region.
</Note>

## Connection einrichten

Beim ersten Modul-Drop wirst du nach einer Connection gefragt:

| Feld                | Wert                                                                                                                             |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| **Connection Name** | Frei wählbar (z.B. "Business OS — Live")                                                                                         |
| **API Key**         | Dein Org- oder Agency-API-Key aus dem [Dashboard](https://app.business-os.de) (Format `bo_xxxxx...`)                             |
| **API Typ**         | `Partner API` für regulierte Banken (Sparkasse, Volksbank, Deutsche Bank, ...) oder `Open Banking API` für AMEX, PayPal, Revolut |

<Note>
  **Agency-Keys** funktionieren genauso wie Org-Keys, brauchen aber bei den meisten Modulen zusätzlich entweder eine `Connection ID` (Org wird daraus aufgelöst) oder den optionalen Parameter **Organisation** (UUID der Ziel-Org).
</Note>

## Module

Die App hat **12 Module**, die direkt auf die Banking-API-Endpoints abbilden.

### Connections

| Modul                 | Beschreibung                                     | Endpoint                              |
| --------------------- | ------------------------------------------------ | ------------------------------------- |
| **List Connections**  | Listet alle Banking-Connections der Organisation | `GET /v2/banking/connections`         |
| **Get Connection**    | Ruft eine einzelne Connection ab                 | `GET /v2/banking/connections/{id}`    |
| **Delete Connection** | Löscht eine Banking-Connection                   | `DELETE /v2/banking/connections/{id}` |

### Accounts

| Modul             | Beschreibung                                                      | Endpoint                        |
| ----------------- | ----------------------------------------------------------------- | ------------------------------- |
| **List Accounts** | Listet Konten — optional gefiltert nach Connection oder PIS-fähig | `GET /v2/banking/accounts`      |
| **Get Account**   | Ruft ein einzelnes Konto ab                                       | `GET /v2/banking/accounts/{id}` |

### Transactions

| Modul                 | Beschreibung                                                                                                           | Endpoint                       |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **List Transactions** | Listet Transaktionen (sortiert nach `made_on` aufsteigend). Mindestens `connection_id` oder `account_id` erforderlich. | `GET /v2/banking/transactions` |

### Payments (PIS)

| Modul              | Beschreibung                                                                                                             | Endpoint                        |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | ------------------------------- |
| **Create Payment** | Initiiert eine SEPA- oder SEPA-Instant-Zahlung. Provider/Debitor-IBAN werden automatisch aus der `account_id` aufgelöst. | `POST /v2/banking/payments`     |
| **List Payments**  | Listet alle Zahlungen der Organisation                                                                                   | `GET /v2/banking/payments`      |
| **Get Payment**    | Ruft Zahlungsdetails ab                                                                                                  | `GET /v2/banking/payments/{id}` |

### Webhooks

| Modul               | Beschreibung                                                                                              | Endpoint                      |
| ------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------- |
| **Set Webhook URL** | Setzt die Webhook-URL für Banking-Benachrichtigungen (Refresh-Complete, Payment-Update, Connection-Error) | `PUT /v2/banking/webhook-url` |
| **Get Webhook URL** | Ruft die aktuelle Webhook-URL ab                                                                          | `GET /v2/banking/webhook-url` |

### Agentur-Tools

| Modul                  | Beschreibung                                                                                                           | Endpoint                |
| ---------------------- | ---------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| **List Organizations** | Listet alle Organisationen im Scope des API-Keys (Org-Keys: 1 Org; Agency-Keys: alle Orgs der Agentur). Keine Credits. | `GET /v2/organizations` |

## Beispiel-Szenario: Tägliche Transaktions-Synchronisation

**Trigger:** Make-Scheduler täglich um 06:00 Uhr

```
[Scheduler] → [List Connections]
              ↓ Iterator
              [List Accounts (connection_id)]
                ↓ Iterator
                [List Transactions (account_id, from_date = yesterday)]
                  ↓
                  [Filter: nur posted]
                  ↓
                  [Google Sheet / DATEV-Beleg-Upload]
```

## Beispiel-Szenario: Zahlung aus Rechnungs-Trigger

**Trigger:** Webhook aus deinem ERP wenn Rechnung "freigegeben"-Status erreicht

```
[Webhook] → [Create Payment]
              account_id:     {{erp.bank_account_id}}
              amount:         {{erp.invoice.amount}}
              creditor_name:  {{erp.invoice.creditor_name}}
              creditor_iban:  {{erp.invoice.creditor_iban}}
              description:    "Rechnung {{erp.invoice.number}}"
              reference:      {{erp.invoice.number}}
            ↓
            [Email an Approver mit payment_url für TAN-Bestätigung]
```

<Note>
  `Create Payment` gibt eine `payment_url` zurück — der Endkunde muss diese URL öffnen, um die Zahlung per TAN/2FA zu autorisieren. Erst nach Bestätigung wird die Zahlung ausgeführt und die 3 Credits abgebucht.
</Note>

## Webhook-Integration

Wenn du `Set Webhook URL` nutzt, sendet Business OS folgende Events an deine URL:

| Event                  | Beschreibung                                                                            |
| ---------------------- | --------------------------------------------------------------------------------------- |
| `refresh_complete`     | Refresh einer Connection ist durchgelaufen — neue Transaktionen verfügbar               |
| `connection_error`     | Connection ist in einen Fehlerzustand gegangen (User-Action / transient / auth-expired) |
| `connection_destroyed` | Connection wurde vom Salt-Edge-Provider entfernt                                        |
| `payment_update`       | Status einer Zahlung hat sich geändert (initiated → settled / failed)                   |

Payload-Details findest du in der [API-Reference unter Webhook Events](/api-reference/openapi.json).

## Credit-Verbrauch

Pro Modul-Aufruf werden Credits abgebucht — siehe Beschreibung pro Modul. Übersicht:

| Aktion                                                        | Credits                              |
| ------------------------------------------------------------- | ------------------------------------ |
| Listings (Verbindungen, Konten, Zahlungen, Payment-Templates) | 0                                    |
| Konto / Verbindung abrufen                                    | 0                                    |
| Transaktionen auflisten / Transaktion abrufen                 | 1                                    |
| Zahlungsstatus abrufen / aktualisieren                        | 1                                    |
| Zahlung erstellen                                             | 3 (nur bei erfolgreicher Settlement) |
| Webhook setzen / abrufen                                      | 0                                    |

## Troubleshooting

**"Insufficient credits" (402)** — Verbleibendes Guthaben im Dashboard prüfen oder Top-Up kaufen.

**"connection\_id oder account\_id ist erforderlich" (400)** — Bei `List Transactions` muss mindestens einer der beiden Filter gesetzt sein.

**Agency-Key wirft "Organisation muss angegeben werden" (400)** — Bei Modulen ohne `connection_id` (z.B. Create Payment ohne Konto-Bindung) den optionalen Parameter **Organisation** setzen.

## Feedback & Wünsche

Issues und Module-Wünsche zur Banking-App: [impressum@business-os.de](mailto:impressum@business-os.de).