Template für cloudfähige Debitor Schnittstellen

Es gibt eine Beispiel-Debitoren-Schnittstelle, welche zeigt, was man implementieren muss, um eine lauffähige cloudfähige Fibu-Schnittstelle zu erstellen. Sie kann als Basis für neue Schnittstellen verwendet werden.

Um die Beispiel-Schnittstelle zu implementieren bzw. den Code einzusehen, erstellen Sie in Vertec im Ordner Einstellungen > Schnittstellen > Extensions eine neue Extension.

Als Extension-ID geben Sie eine der folgenden Referenzen an:

• Online-Schnittstelle: FibuExampleExtension.ExampleOnlineDebiExtension. Dies ist das Beispiel einer Schnittstelle, welche online und mit requests arbeitet. Ein Beispiel dafür ist die Run my Accounts Debitoren Schnittstelle.
• Offline-Schnittstelle: FibuExampleExtension.ExampleOfflineDebiExtension. Dies ist das Beispiel einer Schnittstelle, welche beim Buchen oder Stornieren jeweils eine Textdatei erstellt und diese zum Download liefert. Diese Textfiles werden dann in den Buchhaltungssystemen eingelesen. Beispiele dafür sind die Datev Debitoren Schnittstelle und die BMD Debitoren Schnittstelle.

Sobald Sie die Extension-ID eingegeben haben, können Sie über den Button mit den drei Punkten den Code öffnen:

Der Code für beide Schnittstellen befindet sich im selben File, es kann jedoch pro Extension jeweils nur die eine oder die andere registriert werden.

Online-Schnittstelle

Die Klasse für Online Debitor Schnittstellen heisst ExampleOnlineDebiExtension und enthält folgende Einstiegspunkte:

TryPostInvoiceBookings(self, invoiceList)

Diese Methode wird direkt von Vertec aufgerufen und dient dazu, die Rechnungen in der Buchhaltung zu buchen. Bei diesem Vorgang wird auch die Debitoradresse geschrieben.

Ihr Argument ist eine Liste von Vertec Rechnungsobjekten. Die Liste enthält nur gültige Rechnungen. Die Konsistenzprüfung wird vor dem Aufruf dieser Methode durchgeführt.

def TryPostInvoiceBookings(self, invoiceList):
    response = [""] * len(invoiceList)
    for i in range(len(invoiceList)):
        try:
            self.CreateOrUpdateDebitor(invoiceList[i])
            self.BookInvoice(invoiceList[i])
        except Exception as e :
            errortext = translate('The invoice with the number %s reports:') % str(invoiceList[i].nummer)
            errortext += '\n'
            errortext += str(e)
            response[i] = errortext.replace('\n', "\n \t")
    return response

Es muss eine Liste von Strings zurückgegeben werden, mit der gleichen Länge wie die Liste der Rechnungen.

• Jeder String ist mit der Rechnung auf dem gleichen Index verknüpft.
• Ist die Zeichenkette leer, wird die Rechnung von Vertec als gebucht betrachtet.
• In jedem anderen Fall muss die Fehlermeldung in den String geschrieben werden.

Beispiel

        invoicelist[0] - response[0] = ""
        invoicelist[1] - response[1] = ""
        invoicelist[2] - response[2] = "Ein erster Fehler ist aufgetreten"
        invoicelist[3] - response[3] = "Es ist ein zweiter Fehler aufgetreten"
        invoicelist[4] - response[4] = ""

Die Rechnungen mit dem Index 0,1 und 4 werden in Vertec verbucht. Die anderen Rechnungen werden nicht verbucht.

Zusätzlich wird dem Benutzer der erste Fehler als Fehlermeldung angezeigt: "Ein erster Fehler ist aufgetreten". Es wird jeweils nur der erste Fehler angezeigt.

TryCancelInvoiceBookings(self, invoiceList)

Diese Methode wird direkt von Vertec aufgerufen und dient dazu, Rechnungen in der Buchhaltung zu stornieren.

Ihr Argument ist eine Liste von Vertec Rechnungsobjekten. Die Liste enthält nur gültige Rechnungen. Die Konsistenzprüfung wird vor dem Aufruf dieser Methode durchgeführt.

def TryCancelInvoiceBookings(self, invoiceList):
    response = [""] * len(invoiceList)
    for i in range(len(invoiceList)):
        try:
            self.CancelInvoice(invoiceList[i])
        except Exception as e :
            errortext = translate('The invoice with the number %s reports:') % str(invoiceList[i].nummer)
            errortext += '\n'
            errortext += str(e)
            response[i] = errortext.replace('\n', "\n \t")
    return response

Es muss eine Liste von Strings zurückgegeben werden, mit der gleichen Länge wie die Liste der Rechnungen.

• Jeder String ist mit der Rechnung auf dem gleichen Index verknüpft.
• Ist die Zeichenkette leer, wird die Rechnung von Vertec als gebucht betrachtet.
• In jedem anderen Fall muss die Fehlermeldung in den String geschrieben werden.

 Beispiel

        invoicelist[0] - response[0] = ""
        invoicelist[1] - response[1] = ""
        invoicelist[2] - response[2] = "Ein erster Fehler ist aufgetreten"
        invoicelist[3] - response[3] = "Es ist ein zweiter Fehler aufgetreten"
        invoicelist[4] - response[4] = ""

Die Rechnungen mit dem Index 0,1 und 4 werden in Vertec storniert. Die anderen Rechnungen werden nicht storniert.

Zusätzlich wird dem Benutzer der erste Fehler als Fehlermeldung angezeigt: "Ein erster Fehler ist aufgetreten". Es wird jeweils nur der erste Fehler angezeigt.

ImportPayments(self, invoiceList)

Diese Methode wird direkt von Vertec aufgerufen und dient dazu, Zahlungen aus der Buchhaltung ins Vertec zu importieren.

Ihr Argument ist eine Liste von Vertec Rechnungsobjekten. Die Liste enthält nur gültige Rechnungen. Die Konsistenzprüfung wird vor dem Aufruf dieser Methode durchgeführt.

def ImportPayments(self, invoiceList):
    for invoice in invoiceList:

        # get payments from fibu
        amount = 9.95
        date = datetime.date.today()

        # get paymenttyp from vertec
        zahltyp = vtcapp.evalocl("zahlungstyp->select(code='AUTO')->first")
        if not zahltyp:
            self.Log('No Paymenttyp with code "AUTO" found, will be created.')
            zahltyp = vtcapp.createobject('Zahlungstyp')
            zahltyp.Code = "AUTO"
            zahltyp.Bezeichnung = translate("automatically created through synchronization of payment")
            zahltyp.Aktiv = True

        # create vertec payment
        zahlobj = vtcapp.createobject('Zahlung')
        zahlobj.rechnung    = invoice
        zahlobj.typ         = zahltyp
        zahlobj.betrag      = amount
        zahlobj.datum       = date
        zahlobj.text        = "This payment was done by the example fibu extension"
        # Mark invoice as payed, if no open fees left.
        if invoice.betragoffen == 0:
            invoice.bezahlt = True

        print("Imported payments for invoice with number "+str(invoice.nummer))

Es gibt drei Fälle:

1. Zahlungsimport auf einer einzelnen Rechnung ausgeführt: Die Liste enthält nur eine Rechnung.
2. Zahlungsimport auf einer Liste von Rechnungen ausgeführt: Die Liste enthält alle Rechnungen der Liste.
3. Zahlungsimport global aufgerufen: Die Liste enthält alle Rechnungen, die nicht bezahlt sind.

Es müssen in Vertec Zahlungen erstellt und der Rechnung zugeordnet werden. 

Wenn in Vertec kein Zahlungstyp mit dem Code AUTO vorhanden ist, wird einer erstellt.

Ausserdem muss die Rechnung als bezahlt markiert werden, wenn sie vollständig bezahlt wurde.

In der Beispiel-Extension wird der Rechnung eine Zahlung von 9.95 hinzugefügt. Ausserdem wird beim Buchen die Personenkontonummer auf Adressen auf 1 gesetzt. Diese Nummer muss von der Fibu kommen, bitte Kommentar im Code beachten.

 def PostInvoiceBookings(self, invoiceList):

    zipContentList = []
    for invoice in invoiceList:
        content_address = self.CreateOrUpdateDebitor(invoice)
        content_invoice = self.BookInvoice(invoice)
        zipContentList.append(content_address)
        zipContentList.append(content_invoice)
    
    zipFileAsBytes = ziputils.createzip(zipContentList)

    return ("FileNameForBookedInvoices.zip", zipFileAsBytes)

def CancelInvoiceBookings(self, invoiceList):

    zipContentList = []
    for invoice in invoiceList:
        content = self.CancelInvoice(invoice)
        zipContentList.append(content)
    
    zipFileAsBytes = ziputils.createzip(zipContentList)

    return ("FileNameForCanceledInvoices.zip", zipFileAsBytes)

 def ImportPayments(self, invoiceList):

    # show file selection dialog
    filename, content = vtcapp.requestfilefromclient("Import payments file", '', '*.txt')

    # here we would process the payments file content....

    # as an example, we just add a payment to all the invoices
    for invoice in invoiceList:

        # get payments from fibu
        amount = 9.95
        date = datetime.date.today()

        # get paymenttyp from vertec
        zahltyp = vtcapp.evalocl("zahlungstyp->select(code='AUTO')->first")
        if not zahltyp:
            self.Log('No Paymenttyp with code "AUTO" found, will be created.')
            zahltyp = vtcapp.createobject('Zahlungstyp')
            zahltyp.Code = "AUTO"
            zahltyp.Bezeichnung = translate("automatically created through synchronization of payment")
            zahltyp.Aktiv = True

        # create vertec payment
        zahlobj = vtcapp.createobject('Zahlung')
        zahlobj.rechnung    = invoice
        zahlobj.typ         = zahltyp
        zahlobj.betrag      = amount
        zahlobj.datum       = date
        zahlobj.text        = "This payment was done by the example fibu extension"
        # Mark invoice as payed, if no open fees left.
        if invoice.betragoffen == 0:
            invoice.bezahlt = True

        print("Imported payments for invoice with number "+str(invoice.nummer))

Folgende Hinweise sollten beachtet werden beim Implementieren einer neuen Schnittstelle:

Folgendes darf von der Schnittstelle NICHT geschrieben werden:

• Der Zustand gebucht auf der Rechnung wird von der Vertec Business-Logik gesetzt und darf nicht separat von der Extension gesetzt werden.
• Dasselbe gilt für die persistenten Buchhaltungs-Attribute auf der Rechnung (die Werte mit bhXX), welche ebenfalls von Vertec automatisch beschrieben werden.

Folgendes MUSS von der Schnittstelle geschrieben werden:

• Die Belegnummer (rechnung.belegnr) muss von der Extension gesetzt werden, denn ohne eine Belegnummer kann nicht storniert werden. Bei Buchhaltungen, welche ohne Belegnummern arbeiten, kann einfach 0 hineingeschrieben werden.

Ausgabe

Es werden Prints in die Python Konsole geschrieben beim Buchen und Stornieren.