Gutschriften

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:

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:

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; 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

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.

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

<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.

<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