List all credit notes

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>

You can filter the result by parameters:

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

Lists all credit notes with “GS123” in the credit note number. Upper and lower case are ignored.
The following filter parameters are available:

Parameter Description
client_id ID oft he client
contact_id ID of the contact
credit_note_number Credit note number
status Status (DRAFT, OPEN, PAID). More than one statuses could be given as a comma separated list. Theses statuses will be logically OR-connected.
from Only show credit notes since this date (format YYYY-MM-DD)
to Only show credit notes up to this date (format YYYY-MM-DD)
label Free text search in label text
intro Free text search in introductory text
note Free text search in explanatory notes
tags Comma separated list of tags
article_id ID of an article

Aggregated list of invoices

GET /api/credit-notes?group_by=client

Credit notes can also be found grouped together. The above example all credit notes grouped by client.
The following values are for parameter group_by are available:

Value Description
client client
status status of the credit note
day day
week week (starts with monday)
month month
year year

It can also be grouped according to several criteria. The desired values are simply concatenated by commas (?group_by=client,year). The order of values determines the order of aggregation.
The grouping parameters can also be combined with the other filters.

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

Get a single credit note

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>
</credit-note>

status can have the following values:
– DRAFT
– OPEN
– PAID
net_gross can have the following values:
– NET
– GROSS
In addition to the credit note combined taxes (taxes) will be returned.
items, comments and payments can be accessed separately.

Create credit note

POST /api/credit-notes
XML element Description Type Default value Mandatory
client_id ID of the client INT yes
contact_id ID of the contact INT
address the address ALNUM Client’s address
number_pre Prefix ALNUM Value taken from the settings
number Serial number INT next free numberr
number_length Minimum length of the invoice number (to be filled with leading zeros) INT Value taken from the settings
date Credit note date DATE today
title Title of the document ALNUM
label Label text to describe the project ALNUM
intro Introductory text ALNUM default value taken from the settings
note Explanatory notes ALNUM default value taken from the settings
reduction Reduction (absolute or percent: 10/10%) ALNUM
currency_code Currency ISO currency code Default currency
net_gross Price basis (gross or net prices) ALNUM (“NET”, “GROSS”) Default value taken from the settings
quote Currency quote (for conversion into standard currency) FLOAT 1.0000
invoice_id The ID of the invoice, if the credit note was created from an invoice. INT
free_text_id The ID of the free text to set title, label, intro and note. INT
template_id The ID of the template to be used to complete the credit note. INT ID of the default template

status at creation is always DRAFT.
The remaining properties of the credit note are automatically calculated.
Credit note items (credit-note-items) can be specified directly at creation. Please find a documentation of the XML elements at Create credit note items, but the XML element credit_note_id need not be specified with.

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

Edit credit note

PUT /api/credit-notes/{id}

A credit note can basically be edited in draft status (DRAFT) only.
Credit note items and comments could not be edited at the credit note. Please use the appropriate resource instead.

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

Delete credit note

DELETE /api/credit-notes/{id}

Deletes a credit note with all documents (PDFs), Credit note items and comments.

Complete credit note

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

Completes a credit note in the draft status (DRAFT). Here, the status of open (OPEN) or overdue (OVERDUE) is set and a PDF is generated and stored in the file system.

The optional parameter template_id determines which template is used to create a pdf.

If this parameter is not specified, the template specified at the credit note or the default template is used.

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

Open pdf of a credit note

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

At this point, the parameter format=pdf can also be used to open the PDF directly with MIME type “application/pdf”.
With the optional parameter type=print you can request the PDF without background. Note that the setting print_version must have been activated.

<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 encoded PDF}</base64file>
</pdf>

Updoad a digital signature for a given credit note

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

Updoads a digital signature for a given credit note.
The status of the credit note may not be DRAFT.

XML element Description Type Default value Mandatory
base64file Base64 encoded PDF with digital signature BASE64FILE yes

Note: A (qualitfied) digital signature can NOT be created by the billomat[API] directly. We recommend that you use this function directly on the PixelLetter interface or another service.

<signature>
    <base64file>{base64 encoded PDF}</base64file>
</signature>

Send credit note by e-mail

POST /api/credit-notes/{id}/email
XML element Description Type Default value Mandatory
email_template_id ID of the e-mail template INT
from Sender EMAIL Default email from the settings
recipients Recipients of the e-mail. There must be at least one xml node for “to”, “cc” and/or “bcc”. XML node/EMAIL ja
subject Subject of the e-mail (may include placeholders) ALNUM Value taken from the (default) e-mail template
body Text of the e-mail (may include placeholders) ALNUM Value taken from the (default) e-mail template
filename Name of the PDF file (without .pdf) ALNUM invoice_{id}
attachments Further files. Attachments can contain as many nodes on the “attachment” with the elements “filename”, “mimetype” and “base64file”. XML node
<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>

Send credit note by mail

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

Sends a credit note by mail. Pixelletter has to be configured as add on for usage.

XML element Description Type Default value Mandatory
color Determines whether to use color printing. BOOL 0
duplex Determines whether to use duplex printing. BOOL 1
paper_weight Determines the paper weight in grams. Possible values are 80 or 90. INT 90
attachments Further PDF files. Attachments can contain as many nodes on the “attachment” with the elements “filename”, “mimetype” and “base64file”. XML node
<mail>
    <color>0</color>
    <duplex>1</duplex>
    <paper_weight>90</paper_weight>
    <attachments>
        <attachment>
            <filename>drawing.pdf</filename>
            <mimetype>application/pdf</mimetype>
            <base64file>{base64 encoded file}</base64file>
        </attachment>
    </attachments>
</mail>

Cancel credit note

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

Undo cancellation

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