Test-Modus

Jedes Vorgio-Team hat eine Live- und eine Test-Seite. Beide teilen sich dasselbe Login, dieselben Team-Einstellungen und dieselben API-Endpoints — die Daten sind jedoch streng voneinander getrennt, und Test-Mode-Requests sind von allen realen Nebenwirkungen befreit:

• Keine kundenseitigen E-Mails. Rechnungs-E-Mails an den Kunden werden als unterdrückt verbucht; nichts verlässt das Mail-Relay von Vorgio in Richtung Käufer. Interne Team-Benachrichtigungen (z. B. „Neue Rechnung über API erstellt") werden weiterhin an die Mitglieder Ihres Vorgio-Teams gesendet — so erkennen Sie, dass Ihr Test-Request angekommen ist.
• Eigene Rechnungsnummerierung. Test-Rechnungen verwenden einen unabhängigen Zähler und werden mit TEST- vorangestellt (z. B. TEST-1, TEST-2, …), sodass sie nie mit Live-Rechnungen verwechselt werden können.
• Webhooks werden trotzdem ausgelöst. Test-Mode-Events werden per POST an Ihre Test-Webhook-Endpoints gesendet — genauso wie Live-Events an Ihre Live-Endpoints. Genau das ist der Zweck: Sie können Ihren Webhook-Handler vollständig durchspielen, bevor Sie auf Produktion umstellen.
• PDFs tragen ein „TEST"-Wasserzeichen. Über jede Seite einer Test-Rechnungs-PDF wird diagonal ein leises „TEST" gedruckt.

Live- und Test-Daten sind vollständig isoliert. Eine Test-Rechnung erscheint nie in einer Live-Rechnungsliste; ein Test-Client nie in einer Live-Kundenliste; Live- und Test-Webhooks haben eigene URLs und eigene Signing Secrets.

#Wie ein Request in den Test-Modus geroutet wird

Der Modus ist an das Token gebunden. Beim Ausstellen eines API-Tokens in der Vorgio-UI wählen Sie Live oder Test — die Auswahl ist Pflicht, es gibt keinen Default. Das Token trägt diesen Modus für seine gesamte Lebensdauer; ein Umschalten von Live auf Test oder umgekehrt ist nicht möglich. Es gibt keinen Vorgio-Mode-Header, keinen ?mode=test-Query-Parameter und kein Per-Request-Override. Rufen Sie Vorgio mit einem Test-Token auf, läuft jede Aktion dieses Requests im Test-Modus; rufen Sie mit einem Live-Token auf, läuft jede Aktion im Live-Modus.

Das macht die Frage „In welchem Modus bin ich gerade?" für Ihren Shop trivial: in dem Modus, dessen Token Sie in Ihrer Umgebung hinterlegt haben.

 1# .env auf Ihrem lokalen / Staging-Server
 2VORGIO_TOKEN=42|act_acme_shop_test_aB3xZ4kL...   # Test-Token
 3
 4# .env auf Ihrem Produktiv-Server
 5VORGIO_TOKEN=7|act_acme_shop_live_p9QrTbN2...    # Live-Token

#Ein Test-Token ausstellen

1. Öffnen Sie in den Einstellungen Ihres Vorgio-Teams API-Tokens (/{your-team}/api-tokens).
2. Klicken Sie auf Token erstellen.
3. Wählen Sie im Formular die Radio-Option Test (neben Live).
4. Wählen Sie das zu Ihrer Integration passende Preset (siehe Tabelle unten), geben Sie dem Token einen Namen („Acme Shop Staging") und klicken Sie auf Token erstellen.
5. Kopieren Sie den Token-Wert — er wird genau wie ein Live-Token nur einmal angezeigt.

Das Formular listet darüber hinaus alle Ihre bestehenden Tokens nach Modus gruppiert auf; Sie können ein Live- und ein Test-Token problemlos nebeneinander halten.

#Welches Preset passt zu welcher Integration?

Die Token-Maske bietet zwei Presets, weil es zwei strukturell unterschiedliche Integrationsformen gibt:

POST /v1/checkouts akzeptiert auch wiederkehrende Felder (every, next_invoice_at) — so können SaaS-Apps eine Subscription ebenfalls in einem Aufruf starten. Wählen Sie Shop-Checkout, wenn Sie ausschließlich einmalige Bestellungen abwickeln; wählen Sie SaaS-Abrechnung, wenn Sie zusätzlich die subscriptions()-Helfer (Stop / Zyklus ändern) über die Einzel-Endpoints benötigen. Bei seltenen Mischfällen haken Sie die nötigen Berechtigungen einfach manuell zusätzlich an.

#Was sich im Test-Modus ändert

Die API-Oberfläche, Request-Strukturen, Response-Strukturen, Status-Codes, Header und Idempotenz-Semantik sind identisch zum Live-Modus. Die Unterschiede betreffen ausschließlich Nebenwirkungen und welche Daten persistiert werden.

#Rechnungen versenden (POST /v1/invoices/{id}/send und der implizite Versand in POST /v1/checkouts)

• Live-Modus: Es wird eine MailEvent-Zeile mit Status queued angelegt, ein SendInvoiceMail-Job wird dispatched, Mailgun stellt die E-Mail an den Kunden zu, das Datum Invoice.sent_on wird gesetzt, der Webhook invoice.sent wird ausgelöst.
• Test-Modus: Es wird eine MailEvent-Zeile mit Status suppressed_test angelegt, es wird kein Mail-Job an den Kunden dispatched, das Datum Invoice.sent_on wird exakt wie im Live-Modus gesetzt, der Webhook invoice.sent wird exakt wie im Live-Modus ausgelöst.

Interne Team-Benachrichtigungen (z. B. „Neue Rechnung über API erstellt" an Ihre Vorgio-Team-Mitglieder) werden auch im Test-Modus ausgelöst. Die Unterdrückung betrifft ausschließlich kundenseitige E-Mails.

Die JSON-Response von POST /v1/checkouts und POST /v1/invoices/{id}/send enthält am mail_event "status": "suppressed_test" statt "status": "queued". Alles andere — das Invoice-Payload, das Client-Payload, die Header — ist identisch. Falls Ihr Shop mail_event.status prüft, behandeln Sie suppressed_test äquivalent zu queued (der Test-Pfad bedeutet „als wäre versendet worden").

#Nummerierung

Test-Rechnungen verwenden einen unabhängigen Zähler pro Team und pro Typ. Live-Rechnung 5 und Test-Rechnung 5 können für dasselbe Team ohne Kollision existieren. Die sichtbare Nummer ist mit TEST- vorangestellt — z. B. TEST-1, TEST-2. Das ist Ihr Auf-einen-Blick-Signal in jeder UI oder jedem Log, dass Sie auf einen Test-Datensatz schauen.

#Webhooks

Test-Rechnungen lösen ausschließlich Test-Webhooks aus; Live-Rechnungen lösen ausschließlich Live-Webhooks aus. Es gibt keine Überkreuzung.

• Die Webhook-Konfigurationsseite in der Vorgio-UI hat zwei Tabs — Live-Webhooks und Test-Webhooks — mit jeweils eigener Liste von Endpoint-URLs und jeweils eigenen Signing Secrets.
• Der HTTP-Request, den Vorgio an Ihren Endpoint sendet, ist byte-identisch zwischen den Modi — es gibt keinen Vorgio-Mode-Header. Ihr Endpoint erkennt den Modus daran, welche URL getroffen wurde (Ihre Live-URL vs. Ihre Test-URL) und welches Signing Secret die Signatur verifiziert.
• Siehe Webhooks für die Payload-Struktur und das Signaturschema; alles dort Beschriebene gilt unverändert für beide Modi.

In der Praxis registrieren Sie in Ihrem Shop zwei URLs: z. B. https://shop.example/webhooks/vorgio für Live und https://shop.example/webhooks/vorgio-test (oder einen eigenen Staging-Host) für Test. Jede URL erhält ihr eigenes Secret in Ihrem Secrets-Store.

#/v1/checkouts und /v1/checkout-intents

Beide Endpoints verhalten sich im Test-Modus identisch — gleiche Validierung, gleiche Response, gleicher Webhook-Dispatch. Es gibt keine Simulation von Test-Kartennummern (Vorgio ist SEPA-only; es gibt keinen Karten-Flow zu simulieren). Das „Test"-Verhalten besteht ausschließlich aus dem unterdrückten E-Mail-Versand und der getrennten Datenhaltung.

#PDFs

Ein Aufruf von GET /v1/invoices/{id}/pdf für eine Test-Rechnung liefert eine echte PDF mit dem Layout, das Sie in Produktion sehen würden — jedoch mit einem schwachen, diagonal über jede Seite gedruckten „TEST"-Wasserzeichen (gerendert bei etwa 12 % Opazität). Das Wasserzeichen ist rein visuell — die PDF ist ansonsten byte-äquivalent zu einem Live-Rendering.

#Die interne Abrechnung bleibt unberührt

Vorgio rechnet die eigenen Händler über Subscriptions ab (das „Recht-zu-fakturieren" der Plattform). Diese Subscriptions sind immer live und werden nie über Test-Mode-Tokens angelegt. Sie können beliebig viele Test-Tokens ausstellen und wieder verwerfen, ohne die Abrechnung Ihres Vorgio-Accounts zu berühren.

#Auf Produktion umstellen

Wenn Sie von Test auf Produktion wechseln, ändert sich in Ihrem Code nur ein einziger Wert: das Token in Ihrer Umgebung. Alles andere — Endpoints, Request-Strukturen, Webhook-Handler, Signatur-Verifizierung — ist zwischen den Modi identisch.

Bevor Sie umstellen, arbeiten Sie die Go-Live-Checkliste durch. Die Checkliste setzt voraus, dass Sie die Integration bereits end-to-end mit einem Test-Token validiert haben.

#FAQ

Kann eine Test-Rechnung per SEPA bezahlt werden? Nein. Vorgio verarbeitet in keinem Modus Zahlungen — Zahlungen erfolgen out-of-band per Banküberweisung auf die IBAN des Händlers. Im Test-Modus erhält der Kunde die E-Mail erst gar nicht, hat also keinen Weg, die IBAN zu erfahren. Wenn Sie den Webhook invoice.paid für eine Test-Rechnung auslösen möchten, markieren Sie die Rechnung in der Vorgio-UI als bezahlt (oder per POST /v1/invoices/{id}/mark-paid) — der Webhook wird dann an Ihren Test-Endpoint gesendet.

Kann ich eine Test-Rechnung nach Live migrieren? Nein. Eine Test-Rechnung und der zugehörige Client sind dauerhaft an den Test-Modus gebunden. Das richtige Vorgehen lautet: Test-Daten unbesorgt verwerfen, anschließend mit dem Live-Token sauber neu anlegen, sobald Sie produktiv gehen.

Kann mein Staging-Shop versehentlich auf meine Live-Vorgio-Daten zugreifen? Nicht, solange Ihre Staging-Umgebung ein Test-Token hält. Das Token ist die Grenze; es gibt keinen Pfad, über den ein Test-Token Live-Daten lesen oder schreiben kann.

Sagt mir die Response, in welchem Modus ich bin? Nein — es gibt kein mode-Feld in den API-Responses und keinen Vorgio-Mode-Response-Header. Ihr Shop weiß ohnehin Bescheid: Es ist der Modus, dessen Token Sie konfiguriert haben. Falls Sie in der Admin-UI Ihres Shops einen sichtbaren Hinweis möchten, lesen Sie ihn aus Ihrer eigenen Umgebungsvariable — nicht aus der Vorgio-Response.