Sie haben zwei Möglichkeiten, Belegdaten zur weiteren Verarbeitung aus d.velop invoices zu empfangen: per Webhook oder über die API zum Abholen von ausstehenden Transfers. Wenn Sie die Verarbeitung über einen Webhook wählen, ruft d.velop invoices einen von Ihnen implementierten Webservice mit den Daten des zu übertragenden Belegs auf. Bei der Verarbeitung per Abholung ist Ihre Anwendung dafür zuständig, regelmäßig innerhalb eines einstellbaren Zeitfensters die ausstehenden Belege abzuholen, zu verarbeiten, und Erfolg oder Misserfolg an d.velop invoices zu melden.

Wann bietet sich ein Webhook und wann das Abholen per API an? 

Das Abholen von Daten per API und der Empfang der Daten über einen Webhook bieten grundsätzlich den gleichen Funktionsumfang. Sie erhalten bei beiden Varianten die gleichen Belegdaten und müssen bei beiden Varianten zurückmelden, ob die Verarbeitung erfolgt oder nicht erfolgt ist. Wann sollten Sie also das Abholen per API und wann den Empfang über einen Webhook wählen?

Ein Webhook bietet Ihnen die Möglichkeit schneller auf Belegdaten zu reagieren, da d.velop invoices Ihre Anwendung aktiv kontaktiert, sobald es Daten zu verarbeiten gibt. Sie haben unmittelbar die Möglichkeit, die Daten beispielsweise auf Gültigkeit zu prüfen und eine Rückmeldung zu geben. Wenn Sie die Daten per API abholen, dann prüft Ihre Anwendung in regelmäßigen Intervallen, ob neue Daten zur Verfügung stellen. Erfolgt diese Prüfung beispielsweise einmal in der Stunde werden auch nur einmal in der Stunde Daten durch Ihre Anwendung an das externe System übertragen. Kommt es dabei zu Fehlern und Sie melden einen Misserfolg, erfahren die Anwender davon auch erst mit dieser Verzögerung.

Wenn Sie die Belegdaten über die API abrufen, muss Ihre Anwendung die API von d.velop invoices erreichen können. Nutzen Sie die Cloudversion von d.velop invoices, muss ihre Anwendung dementsprechend Internetzugriff haben. Damit Sie die Daten über einen Webhook empfangen können, muss d.velop invoices Ihre Anwendung erreichen können. Nutzen Sie die Cloudversion von d.velop invoices, dann muss Ihre Anwendung aus dem Internet erreichbar sein.

Format der Belegdaten 

Die Belegdaten werden Ihnen über beide Wege in einem einheitlichen Format bereitgestellt.

{
  "event_type": "integration.export",
  "_links": {
    "dmsobject": {
      "href": "https://example.d-velop.cloud/dms/r/21b9b52f-19e3-4b3d-8ac6-b32d991f83e0/o2/P000000001"
    }
  },
  "workflow": {
    "voucher": {
      "doc_id": "P000000001",
      "company": {
        "nr": "01",
        "name": "docures AG"
      },
      "vendor": {
        "nr": "50001",
        "name": "Schrauben Meier GmbH"
      },
      "vendor_bank_account":  {
        "id":  "",
       "iban":  ""
      },
      "currency": {
        "id": "EUR",
        "name": "Euro",
        "code": "EUR"
      },
      "net_amount": 100.0,
      "gross_amount": 119.0,
      "pay_amount":  null,
      "vat_amount": 19.0,
      "document_date": "2020-05-05T00:00:00+00:00",
      "internal_number": "INT010291",
      "external_number": "INV12310",
      "payment_date": "2020-05-10T00:00:00+00:00",
      "date_of_supply": "2020-05-05T00:00:00+00:00"
      "financially_correct":  false,
      "document_type": {
        "id": "inv",
        "name": "Invoice",
        "credit_note": false
      },
      "payment_terms": {
        "id": "NET30",
        "net_days": 30,
        "cashback_days1": 10,
        "cashback_percentage1": 2.5
      },
      "posting_period": "2020-05-09",
      "posting_date":  "2020-05-09T00:00:00+00:00",
      "posting_text": "M3x3mm screws",
      "barcode": "BC1234",
      "custom1": "Sales"
      "line_items": {
        "5afe1329-83cd-4ccc-b806-f9ee458522b7": {
          "internal_id": "5afe1329-83cd-4ccc-b806-f9ee458522b7",
          "line_no": 1,
          "verified": true,
          "verifier": {
            "type": "user",
            "name": "mmus",
            "display_name": "Max Mustermann"
          },
          "verified_by": {
            "type": "user",
            "id": "257659",
            "name": "mmus",
            "display_name": "Max Mustermann"
          },
          "verified_at": "2020-05-05T10:25:00+01:00",
          "gl_account": {
            "nr": "6300"
          },
          "cost_center": {
            "nr": "1000"
          },
          "cost_unit": {
            "nr": "PJ0001"
          },
          "net_amount": 100.0,
          "gross_amount": 119.0,
          "pay_amount": null,
          "vat_amount": 19.0,
          "tax_code": {
            "id": "DE_S",
            "name": "Vorsteuer 19%",
            "percentage": 19.0
          },
          "order_number": "PO001",
          "order_line": 1,
          "order_id": "PO_001",
          "order_line_id": "PO_001_1",
          "quantity": {
            "invoiced": 2
          },
          "unit": "Pcs.",
          "unit_price": 50.0,
          "description": "Schraubendreher",
          "item_number": "4711",
          "discount_absolute": 0,
          "discount_per_unit": 0,
          "discount_percent": 0,
          "discount2_percent": 0,
          "discount3_percent": 0,
          "discount4_percent": 0,
          "discount5_percent": 0,
          "custom1": "Neubau"
        }
      }
    },
    "step": {
      "id": "64576949-ff8e-4e45-b0ec-7b4e25436331",
      "title": "Verification"
    }
  },
  "connection": {
    "from_step": {
      "id": "9080a8d4-6698-4613-b5c1-6c1ca103daab",
      "title": "Verification"
    },
    "to_step": {
      "id": "fd51ab72-aceb-4c1d-b775-ea3d411c9284",
      "title": "Approval"
    },
    "end_mode": null
  }
}

Auf oberster Ebene erhalten Sie folgende Daten:

Informationen zur Schrittverbindung 

Ein Export (Ereignistyp integration.export) wird immer im Kontext einer Verbindung zwischen zwei Workflowschritten ausgelöst. Diese Informationen helfen Ihnen beispielsweise zu ermitteln, ob der Workflow mit dem Transfer endet.

Informationen zum aktuellen Workflowstatus (Workflow-Objekt) 

Kopfdaten des Belegs (Voucher-Objekt) 

Sämtliche Kopfdaten des Belegs sind in diesem Objekt zusammengefasst.

Informationen zu Belegpositionen (Line Item-Objekt) 

Jede einzelne Belegposition unterstützt die folgenden Eigenschaften:

Empfangen der Daten über einen Webhook 

Mit Hilfe von Webhooks können Sie Belegdaten aus d.velop smart invoice per HTTP in einem externen System empfangen. Hierzu können Sie eine Integration nutzen, in der Sie einen HTTP-Endpunkt speichern.

Was sind Webhooks? 

Über Webhooks kann d.velop smart invoice eine externe Anwendung, zum Beispiel ein ERP-System, beim Eintreten bestimmter Ereignisse informieren. Die externe Anwendung kann dann auf dieses Ereignis reagieren, zum Beispiel indem Sie einen Buchungsvorschlag erzeugt.

Technisch kann ein Webhook in jeder beliebigen Technologie erstellt werden, solange die Anwendung einen HTTP-Endpunkt bereitstellt, der POST-Anfragen in einem von d.velop smart invoice spezifizierten Format entgegennehmen kann.

Implementieren eines Webhook-Endpunkts 

Um einen Webhook-Endpunkt zu implementieren, müssen Sie zunächst einen neuen Endpunkt in Ihrer Anwendung bereitstellen. Die Art auf die dies geschieht, hängt von der Technologie ab, die Sie verwenden: in einer PHP-Anwendung, kann es zum Beispiel eine neue .php-Datei sein, in Microsoft .NET ASP MVC eine neue Route.

Die Aufgabe des Endpunkts ist es dann, das JSON aus der POST-Anfrage zu extrahieren und zu verarbeiten. Am Ende der Verarbeitung müssen Sie einen HTTP-Statuscode zurückgeben, mit dem Sie d.velop smart invoice signalisieren, ob die Verarbeitung erfolgreich war.

Die Daten, die d.velop smart invoice an den Endpunkt schickt, entsprechen dem Event-Objekt aus der API.

Zusätzlich sollten Sie die eingehenden Anfragen authentifizieren, um sicher zu stellen, dass sie tatsächlich von d.velop smart invoice stammen.

Statuscodes und Rückgabewerte 

Wenn Sie die Webhook-Anfrage korrekt verarbeiten konnten, sollten Sie mit dem HTTP-Statuscode 200 antworten. Falls Fehler aufgetreten sind, sollten Sie mit dem Statuscode 500 antworten, falls es ein Programmfehler auf Ihrer Seite ist.

Sind ungültige Angaben, zum Beispiel ein nicht existierendes Sachkonto, die Ursache, sollten Sie mit dem Fehler 400 antworten. In diesem Fall haben Sie zusätzlich die Möglichkeit, eine Fehlermeldung in der Antwort anzugeben. Diese Fehlermeldung wird dem Anwender in d.velop smart invoice angezeigt. Sie müssen die Fehlermeldung in den Sprachen Deutsch und Englisch angeben.

Zum Beispiel:

{
  "error": {
    "de": "Die Buchungsperiode wurde bereits geschlossen.",
    "en": "The posting period has already been closed."
  }
}

Authentifizieren von Anfragen 

Wenn Sie einen Webhook-Endpunkt implementieren, müssen Sie sicherstellen, dass eingehende Anfragen auch tatsächlich von d.velop smart invoice stammen. Hierzu enthält jede Anfrage eine Signatur im Header X-Smart-Invoice-Signature. Um die Signatur zu verifizieren, benötigen Sie das Secret aus den Einstellungen der Webhook-Integration. Das Secret ist je Integration verschieden.

Der Header X-Smart-Invoice-Signature enthält die Signatur sowie einen Zeitstempel. Dieser Zeitstempel ist im Schlüssel t als Unix-Timestamp angegeben. Die Signatur finden Sie im Schlüssel v1.

X-Smart-Invoice-Signature: t=12839891289,v1=38941389418903890128930jaskldjl221

Die Signatur wird von d.velop smart invoice nach dem HMAC-SHA256-Verfahren erzeugt. Sie können wie folgt vorgehen, um die Signatur zu prüfen:

GET /smartinvoice/api/v1/transfers?integration_key=abc
Accept: application/json

{
  "_links": {
    "next": {
      "href": "https://test.d-velop.cloud/smartinvoice/api/v1/transfers/..."
    },
    "previous": {
      "href": "https://test.d-velop.cloud/smartinvoice/api/v1/transfers/..."
    },
  },
  "transfers": [
    {
      "_links": { ... },
      "workflow": {
        ...
      }
    }
  ]
}

POST /smartinvoice/api/v1/transfers/:id
Content-Type: application/json

{
  "successful": false,
  "error": {
    "de": "Transfer fehlgeschlagen.",
    "en": "Transfer failed."
  }
}