Alle Gutschriften auflisten

GET /api/credit-notes
<?xml version="1.0" encoding="UTF-8"?>
<credit-notes type="array" page="1" per_page="100" total="2">
    <credit-note>
        ...
    </credit-note>
    <credit-note>
        ...
    </credit-note>
</credit-notes>

Über Parameter kann gefiltert werden:

GET /api/credit-notes?credit-note_number=GS123

Listet alle Gutschriften auf, die „GS123“ in der Gutschriftennummer haben. Groß- und Kleinschreibung wird ignoriert.
Folgende Filter-Parameter stehen zur Verfügung:

Parameter Beschreibung
client_id ID des Kunden
contact_id ID des Kontakts
credit_note_number Gutschriftennummer
status Gutschriftenstatus (DRAFT, OPEN, PAID). Mehrere Stati können per Komma getrennt werden.
from Nur Gutschriften ab diesem Datum (Format YYYY-MM-DD)
to Nur Gutschriften bis zu diesem Datum (Format YYYY-MM-DD)
label Freitextsuche in der Bezeichnung
intro Freitextsuche im Einleitungstext
note Freitextsuche im Anmerkungstext
tags Kommaseparierte Liste der Schlagworte
article_id ID eines Artikels, der enthalten ist

Gutschriften aggregiert auflisten

GET /api/credit-notes?group_by=client

Gutschriften können auch gruppiert abgerufen werden. Obiges Beispiel gruppiert alle Gutschriften nach Kunde.
Folgende Werte stehen für den Parameter group_by zur Verfügung:

Wert Beschreibung
client Kunde
status Gutschriftenstatus
day Tag
week Woche (beginnt mit Montag)
month Monat
year Jahr

Es kann auch nach mehreren Kriterien gruppiert werden. Dabei werden die gewünschten Werte einfach per Komma aneinandergehängt (?group_by=client,year). Die Reihenfolge der Werte bestimmt dabei die Reihenfolge der Aggregation.
Der Gruppierungs-Parameter kann auch mit den restlichen Filtern kombiniert werden.

<?xml version="1.0" encoding="UTF-8"?>
<credit-note-groups type="array" currency_code="USD">
    <credit-note-group>
        <total_gross type="float">347.28</total_gross>
        <total_net type="float">291.83</total_net>
        <client_id type="integer">476</client_id>
        <credit-note-params>
            <client_id type="integer">476</client_id>
        </credit-note-params>
    </credit-note-group>
    <credit-note-group>
        <total_gross type="float">1127.53</total_gross>
        <total_net type="float">947.50</total_net>
        <client_id type="integer">477</client_id>
        <credit-note-params>
            <client_id type="integer">477</client_id>
        </credit-note-params>
    </credit-note-group>
</credit-note-groups>

Einzelne Gutschrift aufrufen

GET /api/credit-notes/{id}
<?xml version="1.0" encoding="UTF-8"?>
<credit-note>
    <id type="integer">1</id>
    <client_id type="integer">123</client_id>
    <contact_id type="integer"></contact_id>
    <created type="datetime">2007-12-13T12:12:00+01:00</created>
    <credit_note_number>GS123</credit_note_number>
    <number type="integer">123</number>
    <number_pre>RE</number_pre>
    <number_length type="integer">0</number_length>
    <status>OPEN</status>
    <date type="date">2009-10-14</date>
    <address>Billomat GmbH &amp;amp;amp; Co. KG
Hollertszug 26
57562 Herdorf
Deutschland</address>
    <title></title>
    <label>Projekt 123</label>
    <intro>Wir schreiben Ihnen folgende Positionen gut:</intro>
    <note>Vielen Dank!</note>
    <total_gross type="float">107.1</total_gross>
    <total_net type="float">90.0</total_net>
    <net_gross>NET</net_gross>
    <reduction>10</reduction>
    <total_gross_unreduced type="float">119.0</total_gross_unreduced>
    <total_net_unreduced type="float">100.0</total_net_unreduced>
    <currency_code>EUR</currency_code>
    <quote type="float">1.0000</quote>
    <customerportal_url>https://mybillomatid.billomat.net/customerportal/creditnotes/show/entityId/123?hash=123456789aabbcc</customerportal_url>
    <taxes type="array">
        <tax>
            <name>MwSt</name>
            <rate type="float">19.0</rate>
            <amount type="float">19.0</amount>
        </tax>
    </taxes>
    <invoice_id></invoice_id>
    <template_id></template_id>
</credit-note>

status kann folgende Werte haben:
– DRAFT (Entwurf)
– OPEN (offen)
– PAID (bezahlt)
net_gross kann folgende Werte haben:
– NET (Netto-Preise)
– GROSS (Brutto-Preise)
Zusätzlich zu der eigentlichen Gutschrift werden noch die zusammengefassten Steuern (taxes) mit zurückgegeben.
Die Gutschriftenpositionen, Gutschriftenkommentare und Zahlungen können gesondert abgerufen werden.

Gutschrift erstellen

POST /api/credit-notes
XML-Element Beschreibung Typ Default-Wert Pflichtfeld
client_id ID des Kunden INT ja
contact_id ID des Kontakts INT
address komplette Gutschriftenadresse ALNUM Adresse des Kunden
number_pre Präfix ALNUM Wert aus Einstellungen
number lfd. Nummer INT nächste freie Nummer
number_length Mindestlänge der Gutschriftennummer (wird mit führenden Nullen aufgefüllt) INT Wert aus den Einstellungen
date Gutschriftendatum DATE heute
title Dokumentenüberschrift ALNUM
label Bezeichnung ALNUM
intro Einleitungstext ALNUM Wert aus Einstellungen
note Anmerkungstext ALNUM Wert aus Einstellungen
reduction Rabatt (Absolut oder als Prozentwert: 10/10%) ALNUM
currency_code Währung ISO-Währungscode Standard-Währung
net_gross Preisbasis (Brutto- oder Netto-Preise) ALNUM („NET“, „GROSS“) Wert aus den Einstellungen
quote Währungskurs (für Umrechnung in Standard-Währung) FLOAT 1.0000
invoice_id Die ID der Rechnung, wenn die Gutschrift aus einer Rechnung erstellt wurde. INT
free_text_id Die ID des Freitextes zur Belegung von title, label, intro und note. INT
template_id Die ID der Vorlage, mit der die Gutschrift abgeschlossen werden soll. INT ID der Standardvorlage

status ist bei der Erstellung immer DRAFT.
Die übrigen Eigenschaften der Gutschrift werden automatisch berechnet.
Gutschriftenpositionen (credit-note-items) können bei der Erstellung direkt mit angegeben werden. Es gelten die gleichen XML-Elemente wie unter Gutschriftenposition erstellen. Nur das XML-Element credit_note_id muss nicht mit angegeben werden.

<credit-note>
    <client_id>1</client_id>
    <date>2009-11-18</date>
    <note>Wir schreiben Ihnen gut:</note>
    <credit-note-items>
        <credit-note-item>
            <unit>Stück</unit>
            <unit_price>1.23</unit_price>
            <quantity>1.5</quantity>
            <title>Muster</title>
        </credit-note-item>
        <credit-note-item>
            <unit>Stunde</unit>
            <unit_price>90</unit_price>
            <quantity>8</quantity>
            <title>Arbeiten</title>
        </credit-note-item>
    </credit-note-items>
</credit-note>

<?xml version="1.0" encoding="UTF-8"?>
<credit-note>
    <id type="integer">1234</id>
    <client_id type="integer">1</client_id>
    <created type="datetime">2007-12-13T12:12:00+01:00</created>
    <credit_note_number>RE124</credit_note_number>
    <number type="integer">124</number>
    <number_pre>RE</number_pre>
    <number_length type="integer">0</number_length>
    <date type="date">2009-11-18</date>
    ...
</credit-note>

Gutschrift bearbeiten

PUT /api/credit-notes/{id}

Eine Gutschrift kann grundsätzlich nur im Entwurfs-Status (DRAFT) bearbeitet werden.
Gutschriftenpositionen und Kommentare können nicht direkt über die Gutschrift bearbeitet werden. Bitte dafür über die entsprechende Ressource gehen.

<credit-note>
    <date>2009-10-13</date>
</credit-note>

Gutschrift löschen

DELETE /api/credit-notes/{id}

Löscht eine Gutschrift inkl. aller dazugehöriger Dokumente (PDFs), Gutschriftenositionen und Kommentare.

Gutschrift abschließen

PUT /api/credit-notes/{id}/complete

Schließt eine Gutschrift im Entwurfsstatus (DRAFT) ab. Dabei wird der Status auf offen (OPEN) gesetzt, ein PDF erzeugt und im Dateisystem abgelegt.

Welche Vorlage für die PDF-Erzeugung benutzt wird, steuert der optionale Parameter template_id.

Wird dieser Parameter nicht angegeben, wird entweder die an der Gutschrift hinterlegte Vorlage oder die eingestellte Standardvorlage benutzt.

<complete>
    <template_id>123</template_id>
</complete>



PDFs einer Gutschrift aufrufen


GET /api/credit-notes/{id}/pdf


Als optionaler Parameter kann type=signed verwendet werden, um das digital signierte PDF aufzurufen.

An dieser Stelle kann außerdem der Parameter format=pdf verwendet werden, um das PDF direkt mit Mimetype „application/pdf“ aufzurufen. Über den optionalen Parameter type=print kann das PDF ohne Hintergrund angefordert werden. Bitte beachte, dass zum Zeitpunkt der Erstellung die Einstellung print_version bei den Settings aktiviert gewesen sein muss.


<pdf>
    <id type="integer">4882</id>
    <created type="datetime">2009-09-02T12:04:15+02:00</created>
    <credit_note_id type="integer">240</credit_note_id>
    <filename>credit-note_123.pdf</filename>
    <mimetype>application/pdf</mimetype>
    <filesize>70137</filesize>
    <base64file>{base64-kodiertes PDF}</base64file>
</pdf>



Signiertes PDF zu einer Gutschrift hochladen


PUT /api/credit-notes/{id}/upload-signature


Lädt ein PDF mit einer digitalen Signatur zur angegebenen Gutschrift hoch.

Die Gutschrift darf sich nicht mehr im Entwurfs-Status (DRAFT) befinden.






XML-Element
Beschreibung
Typ
Default-Wert
Pflichtfeld




base64file
Base64-kodiertes PDF mit digitaler Signatur
BASE64FILE

ja






Hinweis: Eine (qualifizierte) digitale Signatur kann NICHT direkt über die billomat[API] erstellt werden. Wir empfehlen, für diese Funktion direkt auf die PixelLetter-Schnittstelle oder einen anderen Dienst zurück zu greifen.


<signature>
    <base64file>{base64-kodiertes PDF}</base64file>
</signature>





Gutschrift per E-Mail versenden


POST /api/credit-notes/{id}/email






XML-Element
Beschreibung
Typ
Default-Wert
Pflichtfeld




email_template_id
ID der E-Mail-Vorlage
INT






from
Absender
EMAIL
Standard-E-Mail aus Einstellungen





recipients
Empfänger der E-Mail. Muss mindestens einen XML-Knoten „to“, „cc“ und/oder „bcc“ mit den gewünschten E-Mail-Adressen enthalten
XML-Knoten/EMAIL

ja




subject
Betreff der E-Mail, kann Platzhalter enthalten
ALNUM
Wert aus der (Standard-)E-Mail-Vorlage





body
Text der Mail, kann Platzhalter enthalten
ALNUM
Wert aus der (Standard-)E-Mail-Vorlage





filename
Dateiname der PDF-Gutschrift (ohne .pdf)
ALNUM
credit-note_{id}





attachments
Weitere Dateianhänge. Kann beliebig viele Dateianhänge über die Knoten „attachment“ mit den Elementen „filename“, „mimetype“ und „base64file“ enthalten
XML-Knoten








<email>
    <from>info@billomat.com</from>
    <recipients>
        <to>info@billomat.com</to>
        <cc>mail@example.com</cc>
    </recipients>
    <subject>Ihre Gutschrift</subject>
    <body>Sehr geehrte Damen und Herren, ....</body>
    <filename>gutschrift</filename>
    <attachments>
        <attachment>
            <filename>zeichnung.pdf</filename>
            <mimetype>application/pdf</mimetype>
            <base64file>{base64-kodierte Datei}</base64file>
        </attachment>
    </attachments>
</email>



 Gutschrift per Brief versenden


POST /api/credit-notes/{id}/mail


Versendet eine Gutschrift per Brief. Dazu muss Pixelletter als Add-On eingerichtet sein.






XML-Element
Beschreibung
Typ
Default-Wert
Pflichtfeld




color
Zeigt an, ob ein Farbdruck beauftragt werden soll.
BOOL
0





duplex
Zeigt an, ob Duplexdruck beauftragt werden soll.
BOOL
1





paper_weight
Welche Papierstärke in Gramm soll das Papier haben? Mögliche Werte sind 80 oder 90.
INT
90





attachments
PDF Dateien, die zusätzlich mit gedruckt werden sollen. Kann beliebig viele Dateien über die Knoten „attachment“ mit den Elementen „filename“, „mimetype“ und „base64file“ enthalten.
XML-Knoten








<mail>
    <color>0</color>
    <duplex>1</duplex>
    <paper_weight>90</paper_weight>
    <attachments>
        <attachment>
            <filename>zeichnung.pdf</filename>
            <mimetype>application/pdf</mimetype>
            <base64file>{base64-kodierte Datei}</base64file>
        </attachment>
    </attachments>
</mail>



 Gutschrift stornieren


PUT /api/credit-notes/{id}/cancel


 Stornieren rückgängig machen


PUT /api/credit-notes/{id}/uncancel