API-Tutorial

Stellen Sie noch heute Ihre eBills mit Hilfe unserer leistungsstarken API zu.

Die Dibito-REST-API erlaubt eine vollständige Integration in Ihr Buchhaltungssystem. Folgen Sie diesem Tutorial, um einen Einblick in die Möglichkeiten zu erhalten.

Voraussetzungen

  • Sie haben curl oder ein vergleichbares Tool lokal installiert.
  • Sie haben Ihre Organisation erfolgreich bei Dibito als Rechnungssteller verifiziert.

Für weitere Programmiersprachen wie Python, Java, C#, Go etc. finden Sie Programmierbeispiele in der API-Dokumentation.

API-Schlüssel generieren

Gehen Sie in Ihrem Dibito-Konto auf Dibito -> API-Schlüssel und klicken Sie auf «Schlüssel generieren».

API-Schlüssel generieren

Geben Sie dem Schlüssel einen Namen und notieren Sie sich den generierten Schlüssel. Dieser wird für alle API-Anfragen benötigt.

Sie können jederzeit neue Schlüssel generieren oder bestehende löschen.

Beispielrechnung erstellen

Vorsicht: Diese Testrechnungen werden im produktiven eBill-Portal zugestellt. Es fallen Transaktionsgebühren an. Verwenden Sie als eBill-Empfänger sich selber oder eine Person welche über die Tests informiert ist.

In einem ersten Schritt benötigen Sie ein Beispielrechnung, um die API zu testen. Sie können eine passende Testrechnung für einen beliebigen eBill-Empfänger direkt in Dibito unter dem Menupunkt «Beispiele» generieren. Jede der drei Dokumente-Varianten funktioniert mit der API:

Beispielrechnungen generieren in Dibito

Alternativ können Sie auch eine beliebige Rechnung mit unserem QR-Rechnungsgenerator erstellen. Benutzen Sie dabei die QR-IBAN Ihres Kontos, setzen Sie eine QR-Referenznummer und einen gültigen eBill-Empfänger.

Speichern Sie die generierte QR-Rechnung als PDF bei Ihnen ab.

Hinweis: Jede Referenznummer kann nur einmal ins eBill-Portal eingeliefert werden. Für weitere Versuche müssen Sie neue Rechnungen generieren.

Rechnung als eBill einliefern

Um eine Rechnung im PDF-Format ins eBill-Portal einzuliefern, genügt der folgenden curl-Befehl:

curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases?processingMode=STAGE' \
  -H 'Content-Type: application/pdf' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -H 'x-filename: qr-invoice.pdf' \
  --data-binary '@/path/to/your/qr-invoice.pdf'

Hinweis: Bei curl ist in diesem Fall das @ vor dem Dateipfad wichtig, um die Datei als Binärdaten zu senden.

Im Erfolgsfall befindet sich Ihre Rechnung jetzt in Dibito unter den bereitgestellten Geschäftsfällen.

Wünschen Sie die Rechnung nach der Validierung durch Dibito direkt ans eBill-Portal einzuliefern, so ändern Sie den Parameter processingMode zu DELIVER:

curl -i -X POST \
  'https://app.dibito.ch/api/v1/business-cases?processingMode=DELIVER' \
  -H 'Content-Type: application/pdf' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -H 'x-filename: qr-invoice.pdf' \
  --data-binary '@/path/to/your/qr-invoice.pdf'

In diesem Fall ist kein manueller Schritt zur Freischaltung mehr notwendig.

API-Dokumentation business-cases öffnen…

Rechnungsempfänger suchen

Um einem Empfänger eine Rechnung zustellen zu dürfen, ist eine gültige Anmeldung des Empfängers im System notwendig. Sie können folgendermassen eine Anmeldung mit einer E-Mail-Adresse überprüfen:

curl -i -X POST \
https://app.dibito.ch/api/v1/bill-recipients/search \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-d '{
  "items": [
    {
      "emailAddress": "hans.muster@example.org"
    }
  ]
}'
Wie finde ich die eBill-Identifikation meiner Kontakte?

Für Privatpersonen ist die eBill-Identifikation die E-Mail-Adresse. Beachten Sie, dass jede private Person im eBill-Portal nur eine einzige E-Mail-Adresse hinterlegen kann. Unter Umständen entspricht diese E-Mail-Adresse nicht der primären E-Mail-Adresse des Kontakts.

Für Unternehmen ist es die Unternehmens-Identifikationsnummer (UID). Sie finden die UID jedes Schweizer Unternehmens im UID-Register des Bundes. (Beispiel: CHE-428.851.403).

Ob Sie einer Person oder einem Unternehmen eine eBill-Rechnung zustellen können, finden Sie im Dibito-Interface unter dem Menupunkt «Empfänger» heraus. Dort finden Sie auch die 17-stellige Empfänger-ID aus dem eBill-Portal. Diese bleibt konstant, auch wenn z.B. eine Privatperson ihre E-Mail-Adresse ändert.

Die Antwort im JSON-Format:

{
  "items": [
    {
      "emailAddress": "hans.muster@example.org",
      "billRecipientSixId": "41234567890123456",
      "activeSubscription": true,
      "enterpriseIdentificationNumber": null,
      "submissionStatus": "ALLOWED"
    }
  ]
}

Erläuterung: Der Empfänger wurde gefunden und mit allen verfügbaren Informationen zurückgegeben (In diesem Fall seine E-Mail-Adresse und seine eindeutige fixe ebillRecipientId.)

Das Flag activeSubscription ist wahr, d.h. es besteht bereits eine Anmeldung dieses Empfängers an Ihren Rechnungssteller.

Der submissionStatus ist ALLOWED. Sie können diesem Empfänger eBills zustellen. Dieser Status kann auch ohne Anmeldung auf ALLOWED stehen, wenn der Empfänger allgemeine Zustellung von eBills erlaubt und dies so in seinem eBill-Portal eingestellt hat.

API-Dokumentation bill-recipients öffnen…

Weitere Möglichkeiten

Die Dibito-API verfügt über weitere Funktionen:

Haben Sie noch weitere Fragen? Kontaktieren Sie uns.