TaskMonkey Handbuch

Rezept: Täglicher Bestell-Report

Jeden Morgen um 9:00 einen PDF-Report aller gestrigen Bestellungen per E-Mail verschicken.

Ein komplettes End-to-End-Beispiel: API-Integration, Tool, Scheduled Task, Mail-Versand. Zum Nachbauen und Anpassen.

Ziel

  • Jeden Morgen um 9:00 läuft automatisch eine Aufgabe
  • Sie holt alle Bestellungen des Vortags aus dem Shop-System
  • Baut daraus einen formatierten Report
  • Schickt ihn per E-Mail an die Geschäftsleitung

Voraussetzungen

  • Eine Shop-API, die Bestellungen per Datum abfragen kann (hier: Shopify-like)
  • Eine SMTP- oder Transaktions-Mail-API (hier: Mailgun-like)

1. API-Keys in apis.php

<?php
return [
    'apis' => [
        'shop_api' => [
            'base_url' => 'https://shop.example.com/api/v2/',
            'headers' => [
                'Authorization' => 'Bearer sk_live_abc123…',
                'Accept' => 'application/json',
            ],
        ],

        'mailgun' => [
            'base_url' => 'https://api.mailgun.net/v3/mg.example.com/',
            'headers' => [
                'Authorization' => 'Basic ' . base64_encode('api:key-abc123…'),
            ],
        ],
    ],
];

2. Tool: Bestellungen des Vortags holen

tools/shop/orders/getYesterdayOrders.php:

<?php
return [
    'tools' => [
        'getYesterdayOrders' => [
            'description' => 'Alle Bestellungen des Vortags aus dem Shop laden.',
            'parameters' => ['type' => 'object', 'properties' => []],
            'handler' => function (array $results, array $args, array $ctx): array {
                $from = (new \DateTime('yesterday'))->format('Y-m-d');
                $to = (new \DateTime('today'))->format('Y-m-d');

                $res = $ctx->http->get(
                    "orders?created_at_min={$from}&created_at_max={$to}&limit=250",
                    [],
                    ['api' => 'shop_api']
                );

                return [
                    'date' => $from,
                    'count' => count($res['orders'] ?? []),
                    'total' => array_sum(array_column($res['orders'] ?? [], 'total')),
                    'orders' => $res['orders'] ?? [],
                ];
            },
        ],
    ],
];

3. Tool: Report bauen

tools/internal/buildOrderReport.php:

<?php
return [
    'tools' => [
        'buildOrderReport' => [
            'description' => 'Baut aus einer Bestellliste einen HTML-Report.',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'date' => ['type' => 'string'],
                    'orders' => ['type' => 'array'],
                ],
                'required' => ['date', 'orders'],
            ],
            'handler' => function (array $results, array $args, array $ctx): array {
                $rows = '';
                foreach ($args['orders'] as $o) {
                    $rows .= sprintf(
                        '<tr><td>%s</td><td>%s</td><td>%.2f €</td><td>%s</td></tr>',
                        htmlspecialchars($o['number']),
                        htmlspecialchars($o['customer']['name']),
                        $o['total'],
                        htmlspecialchars($o['status'])
                    );
                }

                $html = <<<HTML
                <h1>Bestellungen vom {$args['date']}</h1>
                <p>Anzahl: {count($args['orders'])} · Summe: EUR</p>
                <table border="1" cellpadding="6">
                    <tr><th>Nr</th><th>Kunde</th><th>Betrag</th><th>Status</th></tr>
                    {$rows}
                </table>
                HTML;

                return ['html' => $html];
            },
        ],
    ],
];

4. Tool: Mail verschicken

tools/mail/sendMail.php:

<?php
return [
    'tools' => [
        'sendMail' => [
            'description' => 'E-Mail per Mailgun versenden.',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'to' => ['type' => 'string'],
                    'subject' => ['type' => 'string'],
                    'html' => ['type' => 'string'],
                ],
                'required' => ['to', 'subject', 'html'],
            ],
            'api' => 'mailgun',
            'method' => 'POST',
            'path' => 'messages',
            'body' => [
                'from' => 'TaskMonkey <taskmonkey@mg.example.com>',
                'to' => '{to}',
                'subject' => '{subject}',
                'html' => '{html}',
            ],
            'mapping' => [
                'id' => 'id',
                'message' => 'message',
            ],
        ],
    ],
];

5. Workflow-Tool (orchestriert alles)

tools/workflows/dailyOrderReport.php:

<?php
return [
    'tools' => [
        'dailyOrderReport' => [
            'description' => 'Report des Vortags bauen und an die GL verschicken.',
            'parameters' => [
                'type' => 'object',
                'properties' => [
                    'recipient' => ['type' => 'string'],
                ],
                'required' => ['recipient'],
            ],
            'handler' => function (array $results, array $args, array $ctx): array {
                $data = $ctx->runTool('getYesterdayOrders', []);

                if ($data['count'] === 0) {
                    return ['sent' => false, 'reason' => 'Keine Bestellungen am Vortag.'];
                }

                $report = $ctx->runTool('buildOrderReport', [
                    'date' => $data['date'],
                    'orders' => $data['orders'],
                ]);

                $mail = $ctx->runTool('sendMail', [
                    'to' => $args['recipient'],
                    'subject' => "Bestell-Report {$data['date']} — {$data['count']} Orders",
                    'html' => $report['html'],
                ]);

                return [
                    'sent' => true,
                    'date' => $data['date'],
                    'count' => $data['count'],
                    'total' => $data['total'],
                    'messageId' => $mail['id'],
                ];
            },
        ],
    ],
];

6. Scheduled Task einrichten

scheduled.php:

<?php
return [
    'scheduled' => [
        'daily_order_report' => [
            'enabled' => true,
            'tool' => 'dailyOrderReport',
            'interval' => '09:00',
            'args' => ['recipient' => 'chef@kunde.de'],
        ],
    ],
];

7. Testen

# Dry-Run — baut Report, schickt aber keine Mail (dank --dry-run)
tm test-tool dailyOrderReport recipient=test@kunde.de --dry-run

# Echter Test (schickt dir die Mail!)
tm test-tool dailyOrderReport recipient=deine@mail.de

8. Live gehen

tm sync
tm monitor   # morgen früh um 9:00 den ersten Lauf beobachten

Erweiterungen

Was du als nächstes einbauen könntest:

  • PDF statt HTML: PDF-Tool einbauen und als Mail-Attachment
  • Mehrere Empfänger: recipient als Array, im Handler-Loop versenden
  • Schwellenwerte: Nur versenden, wenn count > 10 oder total > 1000
  • Datum-Range: Wöchentliche / Monatliche Varianten als weitere Scheduled Tasks
  • Slack-Benachrichtigung parallel zur Mail
Zuletzt aktualisiert: 2026-04-19