Credit Notes

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:

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:

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

status at creation is always DRAFT.

When initially created in DRAFT state, the credit_note_number is returned as an empty response. It is only on completion of a credit note that the credit note number is calculated and gets a value.

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.

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

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

<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