Sparkasse online banking: download account statements with a workflow

{
  "title": "Sparkasse online banking: account statements of a month as PDF",
  "parameters": [
    {
      "key": "banking_url",
      "description": "The online banking address of your Sparkasse, which is also the credential's grant URL",
      "required": true
    },
    {
      "key": "month",
      "description": "The statement month to download (YYYY-MM)",
      "required": true
    },
    {
      "key": "archive_webhook",
      "description": "Endpoint that receives the list of statements",
      "required": true
    }
  ],
  "runSequentially": true,
  "sequentialKey": "cred_sparkasse",
  "blocks": [
    {
      "blockType": "login",
      "label": "Sign_in",
      "credentialId": "cred_sparkasse",
      "url": "{{ banking_url }}"
    },
    {
      "blockType": "validation",
      "label": "Overview_shown",
      "criterion": "The financial overview (Finanzübersicht) of the signed-in customer is shown; no PIN entry and no pending pushTAN release remain on the page"
    },
    {
      "blockType": "action",
      "label": "Open_mailbox",
      "instruction": "Open the electronic mailbox (Postfach) and its account statements (Kontoauszüge), filtered to the month {{ month }}"
    },
    {
      "blockType": "extraction",
      "label": "Statements",
      "instruction": "Every account statement listed for {{ month }}: account (IBAN or name), statement number, statement date, whether a PDF is offered",
      "schema": {
        "type": "object",
        "properties": {
          "statements": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "account": {
                  "type": "string"
                },
                "number": {
                  "type": "string"
                },
                "date": {
                  "type": "string"
                },
                "hasPdf": {
                  "type": "boolean"
                }
              },
              "required": [
                "account",
                "date"
              ]
            }
          }
        },
        "required": [
          "statements"
        ]
      }
    },
    {
      "blockType": "loop",
      "label": "Each_statement",
      "over": "{{ Statements_output.statements }}",
      "maxIterations": 30,
      "blocks": [
        {
          "blockType": "action",
          "label": "Download_statement",
          "nextLoopOnFailure": true,
          "instruction": "Download the statement {{ loopValue.number }} dated {{ loopValue.date }} for account {{ loopValue.account }} as PDF"
        }
      ]
    },
    {
      "blockType": "http_request",
      "label": "Post_list",
      "method": "POST",
      "url": "{{ archive_webhook }}",
      "headers": {
        "content-type": "application/json"
      },
      "body": "{{ Statements_output }}"
    }
  ]
}

import { Browserberg } from '@browserberg/sdk';
import template from './sparkasse-statements.json' with { type: 'json' };

const bb = new Browserberg({
  apiKey: process.env.BROWSERBERG_API_KEY,
  baseUrl: 'https://browserberg.com',
});

// The grant URL is your own Sparkasse's banking address; the PIN is typed there only.
const bankingUrl = 'https://www.sparkasse-musterstadt.example/';
const cred = await bb.credentials.create({
  name: 'Sparkasse business account',
  url: bankingUrl,
  fields: { loginName: 'firma-muster', pin: process.env.SPK_PIN },
  nonSecretFields: ['loginName'],
});

const wf = await bb.workflows.publish({
  ...template,
  blocks: template.blocks.map((b) =>
    b.blockType === 'login' ? { ...b, credentialId: cred.id } : b),
});

// pushTAN: the person holding the phone watches the sign-in and releases it in the app.
await using session = await bb.sessions.create();
const { url } = await bb.sessions.watchLink(session.id);
console.log('Watch the sign-in and confirm the pushTAN on the phone:', url);

const run = await bb.workflows.run(wf.workflowId, {
  sessionId: session.id,
  inputs: { banking_url: bankingUrl, month: '2026-08', archive_webhook: 'https://dms.internal.example/hooks/statements' },
});
console.log(run.status, run.endedBy);