Vorgio
DE EN

Erste Schritte

Fünf Minuten von Null bis zu einer Vorgio-Rechnung in Ihrem Test-Postfach.

#1. Ein API-Token ausstellen

Gehen Sie in den Einstellungen Ihres Vorgio-Teams zu API-Tokens (/{your-team}/api-tokens). Klicken Sie auf den Preset-Button „Payment-Provider-Integration" — er wählt die vier Abilities, die Sie benötigen, automatisch aus:

  • checkouts:write — Checkouts erstellen
  • invoices:read — Rechnungsstatus abfragen
  • invoices:mark-paid — wird benötigt, wenn Ihr Shop Rechnungen als bezahlt markiert (z. B. wenn der eigene Processor eine Überweisung bestätigt)
  • webhooks:manage — Ihren Webhook-Endpoint registrieren

Geben Sie dem Token einen Namen („Acme Shop Production"), belassen Sie das Rate Limit vorerst beim Default 60/min und klicken Sie auf Token erstellen.

Kopieren Sie das Token sofort. Es wird nur einmal angezeigt — danach nie wieder. Das Format lautet act_{your-team-slug}_{random40chars}, dem die numerische Token-ID vorangestellt ist, etwa:

 142|act_acme_shop_aB3xZ4kL...

Der gesamte String ist Ihr Authorization: Bearer …-Wert.

#2. Einen Webhook-Endpoint registrieren

Gehen Sie in Ihren Team-Einstellungen zu Webhooks. Fügen Sie eine Endpoint-URL hinzu, an die Vorgio Events per POST senden soll:

  • URL: https://your-shop.example/webhooks/vorgio
  • Events: aktivieren Sie invoice.sent und invoice.paid

Klicken Sie auf Webhook erstellen. Das Signing-Secret wird nur einmal angezeigt — kopieren Sie es jetzt. Sie benötigen es, um Webhook-Signaturen zu verifizieren (siehe Webhooks).

Für die lokale Entwicklung machen Sie Ihren Dev-Server mit ngrok http 3000 (oder ähnlich) öffentlich erreichbar und verwenden die öffentliche URL.

Tipp: Führen Sie bei Laravel jetzt php artisan vorgio:doctor --test-webhook aus, um Token, Abilities und Webhook zu bestätigen, bevor Sie Code schreiben. Siehe Verbindung prüfen.

#3. Ihr erster Aufruf

Dieser einzelne Aufruf legt einen Vorgio-Client an, stellt eine nummerierte Rechnung aus und versendet sie per E-Mail an den Kunden:

 1curl -X POST https://app.vorgio.example/api/v1/checkouts \
 2  -H "Authorization: Bearer 42|act_acme_shop_aB3xZ4kL..." \
 3  -H "Content-Type: application/json" \
 4  -H "Idempotency-Key: order-1234-checkout" \
 5  -d '{
 6    "client": {
 7      "external_id": "shop_customer_42",
 8      "name": "Erika Mustermann",
 9      "address": "Musterstraße 1",
10      "zip": "10115",
11      "city": "Berlin",
12      "country": "DE",
13      "email": "erika@example.com",
14      "language": "de",
15      "rate": 0,
16      "vat": 19.0,
17      "default_position_mode": "fixed"
18    },
19    "invoice": {
20      "tax_rate": 19.0,
21      "due_offset_days": 14,
22      "subject": "Order #1234",
23      "positions": [
24        {
25          "id": "0193f7b0-1b8a-7b7d-9ad0-0c7b5b1d5f3e",
26          "date": "2026-05-10",
27          "mode": "fixed",
28          "description": "1× Widget Pro",
29          "amount_cents": 4990
30        }
31      ]
32    },
33    "send": {
34      "subject": "Your invoice from Acme Shop",
35      "body": "Hi {client.name}, please find your invoice attached. — Acme Shop"
36    },
37    "metadata": {
38      "shop_order_id": "1234"
39    }
40  }'

Erwartete Response: 201 Created mit einem Body in folgender Form:

 1{
 2  "data": {
 3    "client_id": "0193f7b0-1b8a-7b7d-9ad0-0c7b5b1d5f3e",
 4    "invoice": { "id": "...", "number": "1", "amount_total": 5938, "...": "..." },
 5    "mail_event_id": "1"
 6  }
 7}

Wenige Sekunden später trifft die E-Mail mit angehängtem PDF in erika@example.com ein. Wenige Sekunden danach erhält Ihr Webhook-Endpoint ein invoice.sent-Event mit derselben metadata.shop_order_id zurück.

#4. Den Webhook verarbeiten

Ihr Endpoint erhält einen POST wie diesen:

 1POST /webhooks/vorgio HTTP/1.1
 2Content-Type: application/json
 3Vorgio-Signature: t=1715342400,v1=4f8d2c...
 4Vorgio-Event: invoice.sent
 5
 6{ "id": "evt_...", "type": "invoice.sent", "data": { "invoice": {...}, "client": {...} }, "metadata": {"shop_order_id": "1234"} }

Der Vorgio-Signature-Header ist HMAC-SHA256 über <unix>.<json>, gekeyt mit Ihrem Webhook-Secret. Verifizieren Sie immer, bevor Sie dem Payload vertrauen — siehe Webhooks für die Verifizierungs-Snippets in PHP, JavaScript und Python.

#Wie geht's weiter

Sie haben nun den vollständigen Happy Path am Laufen. Als Nächstes:

  • Lesen Sie die vollständige /v1/checkouts-Referenz für alle optionalen Felder und Beispiele pro Sprache.
  • Lesen Sie Webhooks für Signatur-Verifizierung, die Retry-Policy und das Verhalten, wenn Ihr Endpoint ausfällt.
  • Wenn Sie in WooCommerce integrieren, springen Sie direkt zum WooCommerce-Plugin — es verdrahtet alles oben Genannte für Sie.
  • Bevor Sie auf Produktion umstellen, arbeiten Sie Go-Live durch.