Mahnungen | Billomat

Alle Mahnungen auflisten

GET /api/reminders

<!--?xml version="1.0" encoding="UTF-8"?-->
<reminders type="array" page="1" per_page="100" total="2">
<reminder>
...
</reminder>
<reminder>
...
</reminder>
</reminders>

Über Parameter kann gefiltert werden:

GET /api/reminders?invoice_number=RE123

Listet alle Mahnungen für die Rechnung „RE123“. Groß- und Kleinschreibung wird ignoriert.
Folgende Filter-Parameter stehen zur Verfügung:

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

Einzelne Mahnung aufrufen

GET /api/reminders/{id}

<!--?xml version="1.0" encoding="UTF-8"?-->
<reminder>
<id type="integer">1</id>
<created type="datetime">2007-12-13T12:12:00+01:00</created>
<status>OPEN</status>
<invoice_id>7</invoice_id>
<contact_id type="integer"></contact_id>
<reminder_text_id type="integer">123</reminder_text_id>
<reminder_level type="integer">1</reminder_level>
<reminder_level_name>Erste Stufe</reminder_level_name>
<date type="date">2009-10-01</date>
<label>Projekt 123</label>
<subject>Zahlungserinnerung</subject>
<intro>Sicherlich haben Sie nur vergessen, zu zahlen...</intro>
<note>Bitte zahlen Sie bis zum....</note>
<due_date type="date">2010-10-31</due_date>
<due_days>30</due_days>
<total_gross type="float">119</total_gross>
    <paid_amount type="float">0</paid_amount>
    <open_amount type="float">119</open_amount>
<is_old>0</is_old>
<customerportal_url>https://mybillomatid.billomat.net/customerportal/reminders/show/entityId/123?hash=123456789aabbcc</customerportal_url>
<template_id></template_id>
</reminder>

status kann folgende Werte haben:
– DRAFT (Entwurf)
– OPEN (offen)
– OVERDUE (überfällig)
– PAID (bezahlt)
– CANCELED (storniert)
Die Mahnungspositionen können gesondert abgerufen werden.

Mahnung erstellen

POST /api/reminders

XML-Element	Beschreibung	Typ	Default-Wert	Pflichtfeld
invoice_id	ID der überfälligen Rechnung	INT		ja
contact_id	ID des Kontakts	INT
address	komplette Mahnungsadresse	ALNUM	Adresse aus der Rechnung
date	Mahnungssdatum	DATE	heute
due_days	Tage bis Fälligkeit	INT	Fälligkeit in Tagen aus Einstellungen
due_date	Fälligkeitsdatum	DATE	date + due_days
subject	Betreff	ALNUM	Betreff der nächsten Mahnstufe (falls vorhanden)
label	Bezeichnung	ALNUM
intro	Einleitungstext	ALNUM	Einleitungstext der nächsten Mahnstufe (falls vorhanden)
note	Anmerkungstext	ALNUM	Anmerkungstext der nächsten Mahnstufe (falls vorhanden)
template_id	Die ID der Vorlage, mit der die Mahnung abgeschlossen werden soll.	INT	ID der Standardvorlage

status ist bei der Erstellung immer DRAFT.
Mahnungspositionen (reminder-items) können bei der Erstellung direkt mit angegeben werden. Es gelten die gleichen XML-Elemente wie unter Mahnungsposition erstellen. Nur das XML-Element reminder_id muss nicht mit angegeben werden.

<reminder>
<invoice_id>56610</invoice_id>
<reminder_level type="integer">1</reminder_level>
<date type="date">2009-10-14</date>
<subject>Zahlungserinnerung</subject>
<intro>Sicherlich haben Sie nur vergessen, zu zahlen...</intro>
<note>Bitte zahlen Sie bis zum....</note>
<due_date type="date">2011-04-12</due_date>
<reminder-items>
<reminder-item>
<unit></unit>
<unit_price>2</unit_price>
<quantity>1</quantity>
<title>Verzugszinsen</title>
</reminder-item>
<reminder-item>
<unit></unit>
<unit_price>10</unit_price>
<quantity>1</quantity>
<title>Mahngebühren</title>
</reminder-item>
</reminder-items>
</reminder>

<reminder>
<id type="integer">9</id>
<created type="datetime">2011-02-11T11:33:05+01:00</created>
<status>DRAFT</status>
<invoice_id type="integer">56610</invoice_id>
<reminder_text_id type="integer">
<reminder_level type="integer">1</reminder_level>
<reminder_level_name>
<date type="date">2009-10-14</date>
<subject>Zahlungserinnerung</subject>
...
</reminder_level_name></reminder_text_id></reminder>

Mahnung bearbeiten

PUT /api/reminders/{id}

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

<reminder>
<date>2009-10-13</date>
</reminder>

Mahnung löschen

DELETE /api/reminders/{id}

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

Mahnung abschließen

PUT /api/reminders/{id}/complete

Schließt eine Mahnung im Entwurfsstatus (DRAFT) ab. Dabei wird der Status auf offen (OPEN) bzw. überfällig (OVERDUE) gesetzt und 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 Mahnung hinterlegte Vorlage oder die eingestellte Standardvorlage benutzt.

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

PDFs einer Mahnung aufrufen

GET /api/reminders/{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>
<reminder_id type="integer">240</reminder_id>
<filename>reminder_123.pdf</filename>
<mimetype>application/pdf</mimetype>
<filesize>70137</filesize>
<base64file>{base64-kodiertes PDF}</base64file>
</pdf>

Signiertes PDF zu einer Mahnung hochladen

PUT /api/reminders/{id}/upload-signature

Lädt ein PDF mit einer digitalen Signatur zur angegebenen Mahnung hoch.
Die Mahnung 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>

Mahnung per E-Mail versenden

POST /api/reminders/{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-Rechnung (ohne .pdf)	ALNUM	reminder_{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>Mahnung</subject>
Sehr geehrte Damen und Herren, ....
<filename>mahnung</filename>
<attachments>
<attachment>
<filename>zeichnung.pdf</filename>
<mimetype>application/pdf</mimetype>
<base64file>{base64-kodierte Datei}</base64file>
</attachment>
</attachments>
</email>

Mahnung per Brief versenden

POST /api/reminders/{id}/mail

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

XML-Element	Beschreibung	Typ	Default-Wert
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>

Mahnung stornieren

PUT /api/reminders/{id}/cancel

Stornieren rückgängig machen

PUT /api/reminders/{id}/uncancel