Rechnungsautomatisierung
Rechnungen GoBD-konform automatisch erstellen, versenden, verbuchen und korrigieren.
Voraussetzungen
- Ein API-Schlüssel mit den erforderlichen Bereichen
- Ein aktiver PlanDocket-Account
Schlüssel und Einstellungen vorbereiten
Erstellen Sie einen API-Schlüssel mit dem Scope "invoices:write" (zusätzlich "payments:write", um Zahlungen zu buchen). Firmendaten, Bankverbindung, Steuersätze und Nummernkreise kommen aus den Rechnungseinstellungen im Adminbereich: Die API arbeitet nach genau denselben Regeln wie der Adminbereich. Positionen dürfen nur die Steuersätze Ihrer Rechnungseinstellungen verwenden.
Entwurf anlegen
POST /api/v1/invoices legt einen Entwurf für einen Teilnehmer ("event_participant_id") oder einen Kontakt ("contact_id") an. Ohne "items" werden die offenen abrechenbaren Posten des Teilnehmers (Stände, Serviceaufträge, Formeln) übernommen. Entwürfe haben noch keine Rechnungsnummer ("display_number" zeigt "Entwurf #id") und lassen sich per PATCH noch ändern.
curl -X POST "https://ihr-mandant.plandocket.com/api/v1/invoices" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"event_participant_id": 7,
"items": [
{"description": "Booth area 12 m²", "quantity": 12, "unit_price": 75, "tax_rate": 19}
],
"include_billable_items": false
}'Ausstellen und versenden
POST /api/v1/invoices/{id}/send stellt den Entwurf aus (vergibt die nächste Nummer und das Rechnungsdatum und sperrt ihn) und schickt das PDF an die Rechnungsadresse oder an die Adressen in "to" (optional "cc", "bcc", "subject", "message"). POST /api/v1/invoices/{id}/issue stellt ohne E-Mail aus. Abkürzung: "issue": true oder "send": true schon beim Anlegen. Ausgestellte Rechnungen lassen sich nicht mehr bearbeiten.
curl -X POST "https://ihr-mandant.plandocket.com/api/v1/invoices/789/send" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"message": "Thank you for exhibiting with us."
}'PDF oder E-Rechnung herunterladen
GET /api/v1/invoices/{id}/pdf liefert das PDF (application/pdf). Für Rechnungen mit "e_invoice_format" xrechnung oder zugferd liefert GET /api/v1/invoices/{id}/e-invoice das XRechnung-XML bzw. das ZUGFeRD-PDF (E-Rechnung muss in den Einstellungen aktiviert sein).
curl -o invoice.pdf "https://ihr-mandant.plandocket.com/api/v1/invoices/789/pdf" \
-H "Authorization: Bearer YOUR_API_KEY"
curl -o invoice.xml "https://ihr-mandant.plandocket.com/api/v1/invoices/789/e-invoice?format=xrechnung" \
-H "Authorization: Bearer YOUR_API_KEY"Zahlungen buchen
POST /api/v1/payments mit "invoice_number" und "amount" bucht eine Zahlung. Der Status (teilweise bezahlt, bezahlt, überfällig) ergibt sich automatisch aus Zahlungen und Gutschriften und kann nicht von Hand gesetzt werden (PATCH mit "status": "paid" wird mit 422 abgelehnt). Webhooks: "payment.received" bei jeder Zahlung und "invoice.paid", sobald nichts mehr offen ist.
curl -X POST "https://ihr-mandant.plandocket.com/api/v1/payments" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"invoice_number": "RE-2027-000311",
"amount": 1071.00,
"payment_date": "2027-04-12"
}'Mit einer Gutschrift korrigieren
Ausgestellte Rechnungen werden nie geändert (GoBD). POST /api/v1/invoices/{id}/cancel mit einem "reason" storniert die Rechnung und erzeugt eine Gutschrift über den noch offenen Betrag. Gutschriften stehen unter GET /api/v1/credit-notes und haben ein eigenes PDF. Ein nie ausgestellter Entwurf wird einfach verworfen.
curl -X POST "https://ihr-mandant.plandocket.com/api/v1/invoices/789/cancel" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"reason": "Invoiced twice"
}'