Inhaltsverzeichnis

  1. Einführung

  2. Gutschriften in Dolibarr verstehen

  3. Warum Rückerstattungen über die REST-API automatisieren?

  4. API-Voraussetzungen und Authentifizierung

  5. Übersicht über Dolibarrs REST-API

  6. Gutschriftstruktur in der API

  7. Schritt-für-Schritt-Anleitung: Abwicklung einer Rückerstattung per API

  8. Handhabung von teilweisen vs. vollständigen Rückerstattungen

  9. Anwendungsfälle und Automatisierungsszenarien

  10. Sicherheitsüberlegungen

  11. Häufige Fehler und Tipps zur Fehlerbehebung

  12. Erweitern der Funktionalität mit benutzerdefinierten Endpunkten

  13. Best Practices für API-basierte Finanztransaktionen

  14. Fazit

1. Einleitung

Dolibarr ERP/CRM ist eine modulare Open-Source-Softwaresuite, die Tausende kleiner und mittlerer Unternehmen zur Verwaltung ihrer täglichen Abläufe nutzen. Zu den wichtigsten Finanzfunktionen gehört die Verwaltung von Gutschriften (auf Französisch auch „avoir“ genannt), die für Rückerstattungen oder die Stornierung von Rechnungen verwendet werden.

Mit zunehmender Automatisierung ist die Integration der REST-API zur programmgesteuerten Verwaltung dieser Gutschriftenrückerstattungen unerlässlich. Dieser Artikel bietet eine umfassende Anleitung zur Konfiguration, Implementierung und Verwendung der REST-API von Dolibarr zur Ausstellung von Rückerstattungen im Zusammenhang mit Gutschriften.

2. Gutschriften in Dolibarr verstehen

Gutschriften sind Buchhaltungsdokumente, die ausgestellte Rechnungen stornieren oder korrigieren. Sie werden typischerweise verwendet:

  • Wenn ein Kunde Waren zurücksendet.

  • Wenn eine Rechnung Fehler enthält.

  • Um nach der Rechnungsstellung einen Rabatt oder eine Korrektur anzuwenden.

In Dolibarr sind Gutschriften mit Originalrechnungen verknüpft. Sie reduzieren den Gesamtbetrag und können manuell oder automatisch in Rückerstattungen umgewandelt werden.

3. Warum Rückerstattungen über die REST-API automatisieren?

Die manuelle Bearbeitung von Rückerstattungen kann zeitaufwändig, fehleranfällig und inkonsistent sein. Die Automatisierung dieses Prozesses über die REST-API bietet:

  • Geschwindigkeit: Sofortige Rückerstattung, wenn bestimmte Bedingungen erfüllt sind.

  • Genauigkeit: Vermeiden Sie menschliche Fehler bei der Berechnung von Rückerstattungen.

  • Skalierbarkeit: Große Transaktionsmengen programmgesteuert verarbeiten.

  • Integration: Synchronisierung mit anderen Plattformen wie E-Commerce, CRM oder Banksystemen.

4. API-Voraussetzungen und Authentifizierung

Stellen Sie vor der Verwendung der REST-API Folgendes sicher:

  • Das REST-API-Modul ist in Dolibarr aktiviert (über die Admin-Oberfläche).

  • Sie haben einen API-Schlüssel oder ein Token für einen autorisierten Benutzer generiert.

  • Für eine sichere Kommunikation ist HTTPS aktiviert.

Die Authentifizierung erfolgt normalerweise über HTTP-Header:

GET /api/index.php/invoices/ HTTP/1.1
DOLAPIKEY: your_api_key_here
Host: dolibarr.example.com

5. Übersicht über Dolibarrs REST-API

Dolibarr bietet RESTful-Endpunkte für die meisten großen Unternehmen, darunter:

  • Dritte (/thirdparties)

  • Rechnungen (/invoices)

  • Gutschriften (/suppliercreditnotes, /invoices mit negativen Summen)

  • Zahlungen (/payments, /paymentinvoices)

Um Rückerstattungen im Zusammenhang mit Gutschriften abzuwickeln, interagieren Sie im Allgemeinen mit:

  • /invoices für die Originalrechnung

  • /invoices or /suppliercreditnotes für die Gutschrift

  • /paymentinvoices zur Registrierung von Rückerstattungen

6. Gutschriftstruktur in der API

Eine Gutschrift ähnelt einer Rechnung, weist jedoch einen negativen Gesamtbetrag auf. Hier ist ein Beispiel für die Nutzlast:

{
  "socid": 5,
  "type": 2, // Indicates credit note
  "date": "2024-12-01",
  "lines": [
    {
      "desc": "Refunded Product",
      "subprice": -100,
      "qty": 1
    }
  ]
}

Wichtige Hinweise:

  • type: 2 zeigt eine Gutschrift an.

  • Die Beträge sind negativ.

  • Muss mit dem richtigen Mandanten verknüpft sein (socid).

7. Schritt-für-Schritt-Anleitung: Rückerstattung per API abwickeln

Schritt 1: Originalrechnung abrufen

Verwenden Sie den Endpunkt:

GET /api/index.php/invoices/{id}

Schritt 2: Gutschrift erstellen

POST an:

POST /api/index.php/invoices

mit einer Nutzlast ähnlich dem Beispiel in Abschnitt 6.

Schritt 3: Gutschrift validieren

POST /api/index.php/invoices/{id}/validate

Schritt 4: Registrieren Sie die Rückerstattung

POST /api/index.php/paymentinvoices

Beispiel-Nutzlast:

{
  "datepaye": "2024-12-02",
  "amounts": {
    "CREDIT_NOTE_ID": 100
  },
  "accountid": 1,
  "paymenttype": 2,
  "ref": "Refund via API"
}

8. Umgang mit teilweisen vs. vollständigen Rückerstattungen

Beim Erstellen von Gutschriften können Sie die Menge bzw. den Betrag der Artikel anpassen. Bei Teilrückerstattungen:

  • Positiv verwenden qty aber anpassen subprice um Teilbeträge abzubilden.

  • Stellen Sie sicher, dass der Gesamtbetrag der beabsichtigten Rückerstattung entspricht.

Beispiel für eine 50%ige Rückerstattung:

{
  "lines": [
    {
      "desc": "Partial refund",
      "subprice": -50,
      "qty": 1
    }
  ]
}

9. Anwendungsfälle und Automatisierungsszenarien

  • E-Commerce-Retouren: Automatische Ausstellung von Gutschriften und Rückerstattungen bei Online-Bearbeitung einer Rücksendung.

  • Rechnungskorrekturen: Erstellen und veranlassen Sie Rückerstattungen, wenn eine Überberechnung festgestellt wird.

  • Abonnementverwaltung: Anteilige Rückerstattungen für gekündigte Abonnements.

Alle diese können mithilfe von Webhook-Listenern oder Cron-Jobs ausgelöst werden, die nach bestimmten Auslösern suchen.

10. Sicherheitsüberlegungen

Bei der Automatisierung von Finanztransaktionen:

  • Verwenden Sie immer HTTPS.

  • Beschränken Sie API-Schlüssel auf bestimmte Rollen.

  • Protokollieren Sie alle Rückerstattungstransaktionen.

  • Überwachen Sie die API-Nutzung mit Ratenbegrenzungen.

Validieren Sie außerdem alle Rückerstattungsanfragen intern, bevor Sie API-Aufrufe durchführen.

11. Häufige Fehler und Tipps zur Fehlerbehebung

  • Ungültiger Rechnungstyp: Stellen Sie sicher, dass Sie type: 2 für Gutschriften.

  • Falsche Gesellschaft: Die Client-ID muss übereinstimmen.

  • Rundungsprobleme: Überprüfen Sie die Summen doppelt, um Gleitkommafehler zu vermeiden.

  • Validierungsfehler: Gutschriften müssen vor der Zahlung validiert werden.

Verwenden Sie die API-Protokolle und Webserver-Protokolle von Dolibarr, um fehlgeschlagene Anrufe zu verfolgen.

12. Erweiterung der Funktionalität mit benutzerdefinierten Endpunkten

Fortgeschrittene Benutzer dürfen:

  • Erstellen Sie Module, die die Rückerstattungslogik umschließen.

  • Stellen Sie benutzerdefinierte Endpunkte bereit, um mehrere API-Schritte zu konsolidieren.

  • Integrieren Sie Rückerstattungs-Workflows mit externen Plattformen (z. B. Stripe, PayPal).

Dies kann das Überschreiben des Dolibarr-Kerns oder die Verwendung des api_extra Haken.

13. Best Practices für API-basierte Finanztransaktionen

  • Implementieren Sie Transaktionsprotokolle.

  • Gleichen Sie Rückerstattungen regelmäßig mit Bankkonten ab.

  • Verwenden Sie Sandbox-/Testumgebungen vor der Produktionsbereitstellung.

  • Informieren Sie Kunden per automatisierter E-Mail, wenn eine Rückerstattung erfolgt.

14. Fazit

Die REST-API von Dolibarr ermöglicht die vollständige Automatisierung der Gutschriftsrückerstattung, optimiert Abläufe, verbessert die Genauigkeit und reduziert den Verwaltungsaufwand. Mit sorgfältiger Konfiguration, sicherer Implementierung und klaren Geschäftsregeln können Unternehmen die API nutzen, um ihren Kunden ein schnelleres und professionelleres Erlebnis zu bieten und gleichzeitig die volle Kontrolle über ihre Finanzabläufe zu behalten.

Unabhängig davon, ob Sie E-Commerce-Transaktionen mit hohem Volumen oder gelegentliche Kundenrückerstattungen abwickeln, ist diese API-Integration eine leistungsstarke Bereicherung für Ihr Dolibarr-Toolkit.