Dokumentenmodell

Ein Dokument in xTool ist die zentrale Entität für eine Rechnung oder Gutschrift. Es hat eine Richtung, ein Format, einen Status und optional Metadaten und Inhalt. Mehr zu verwandten Begriffen: Formate, Transaktionen und Status-Lebenszyklus.

Richtung

Eingehend — das Dokument wurde empfangen (z. B. über Peppol).
Ausgehend — das Dokument wurde von Ihnen erstellt oder hochgeladen und kann versendet werden.

Die Richtung wird bei der Erstellung des Dokuments gesetzt und ändert sich nicht. In der Webanwendung werden eingehende und ausgehende Dokumente unter Dokumente → Eingehend und Dokumente → Ausgehend angezeigt. In der API können Sie die Dokumentenliste nach Richtung filtern (Parameter direction). Siehe Empfang per Peppol und Dokumente erstellen.

Format

Jedes Dokument hat ein Format (z. B. Peppol BIS Invoice UBL, XRechnung, Factur-X, SAP IDoc). Das Format legt fest, welche Validierungs- und Konvertierungsregeln gelten. Die vollständige Liste der Formate steht in Formate. So validieren und konvertieren Sie Dokumente: Validieren und konvertieren.

Status

Der Status des Dokuments spiegelt den aktuellen Schritt im Lebenszyklus wider. Jeder Schritt kann in einem von drei Zuständen sein: processing, completed oder failed. Zu den Schritten zählen:

create — Dokument erstellt (z. B. aus Formular oder Modell).
upload — Dokument hochgeladen (z. B. XML-Datei).
import — Dokument importiert (z. B. aus einer Integration).
receive — Dokument empfangen (z. B. über Peppol).
send — Dokument versendet (Peppol oder E-Mail).
delete — Dokument gelöscht.

Beispielcodes: upload.completed, send.processing, send.failed. Das Statusprotokoll ist eine Liste von Einträgen (Code, Details, Zeit), die die Geschichte der Statusänderungen zeigt. Sie können es in der Dokumentenkarte in der Webanwendung und in den API-Antworten einsehen. Mehr zu Schritten und Übergängen: Status-Lebenszyklus.

Metadaten

Sofern vorhanden, enthält das Dokument Metadaten wie:

number, issue_date
sender_name, sender_email, sender_id
receiver_name, receiver_email, receiver_id

Metadaten werden aus der XML oder dem Modell beim Erstellen oder Aktualisieren des Dokuments gefüllt. Sie werden in der Dokumentenkarte in der Webanwendung angezeigt und von der API beim Abruf eines Dokuments zurückgegeben.

Duplikate

Erkennt das System, dass ein Dokument ein Duplikat sein könnte (z. B. gleicher Geschäftsschlüssel wie ein anderes Dokument), kann es zugehörige Dokument-IDs zurückgeben (z. B. das Feld duplicate_ids in der API). So wird vermieden, dieselbe Rechnung zweimal zu senden. In der Webanwendung können Duplikat-Hinweise in einer Benachrichtigung oder auf der Dokumentenkarte erscheinen.

Erstellen, Aktualisieren, Löschen

Erstellen — Modell oder XML über die API oder die Webanwendung hochladen (Formular „Erstellen“ oder „Hochladen“). Siehe Dokumente erstellen.
Aktualisieren — Inhalt über die API (Modell oder XML aktualisieren) oder durch Bearbeiten in der Webanwendung ersetzen. Auf den neuen Inhalt wird die Validierung angewendet.
Löschen — Dokument über die API oder die Webanwendung löschen.

Bezug zu Transaktionen

Jeder Versand- oder Empfangsvorgang erzeugt eine Transaktion (z. B. send.peppol, send.email, receive.peppol). Dokumentstatus und Transaktionsstatus hängen zusammen: Bei Abschluss oder Fehler des Versands wechselt der Dokumentstatus zu send.completed oder send.failed. Ein Dokument kann mehrere Transaktionen haben (z. B. mehrere Versandversuche). Siehe Transaktionen.