Alle Auftragsbestätigungen auflisten
GET /api/confirmations
<?xml version="1.0" encoding="UTF-8"?>
<confirmations type="array" page="1" per_page="100" total="2">
<confirmation>
...
</confirmation>
<confirmation>
...
</confirmation>
</confirmations>
Über Parameter kann gefiltert werden:
GET /api/confirmations?confirmation_number=AB123
Listet alle Auftragsbestätigungen auf, die „AB123“ in der Auftragsbestätigungesnummer haben. Groß- und Kleinschreibung wird ignoriert.
Folgende Parameter stehen zur Verfügung:
Parameter |
Beschreibung |
client_id |
ID des Kunden |
contact_id |
ID des Kontakts |
confirmation_number |
Auftragsbestätigungsnummer |
status |
Auftragsbestätigungsstatus (DRAFT, COMPLETED, CANCELED). Mehrere Stati können per Komma getrennt werden. |
from |
Nur Auftragsbestätigungen ab diesem Datum (Format YYYY-MM-DD) |
to |
Nur Auftragsbestätigungen 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 |
Einzelne Auftragsbestätigung aufrufen
GET /api/confirmations/{id}
<?xml version="1.0" encoding="UTF-8"?>
<confirmation>
<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>
<confirmation_number>AB123</confirmation_number>
<number type="integer">123</number>
<number_pre>AB</number_pre>
<number_length type="integer">0</number_length>
<status>COMPLETED</status>
<date type="date">2010-10-01</date>
<address>Billomat GmbH & Co. KG
Hollertszug 26
57562 Herdorf
Deutschland</address>
<title></title>
<label>Projekt 123</label>
<intro>Wir freuen uns, Ihnen folgende Positionen anbieten zu dürfen:</intro>
<note>Wir freuen und über Ihren Auftrag!</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/confirmations/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>
<offer_id></offer_id>
<template_id></template_id>
</confirmation>
status kann folgende Werte haben:
– DRAFT (Entwurf)
– COMPLETED (abgeschlossen)
– CANCELED (storniert)
– CLEARED (abgerechnet)
net_gross kann folgende Werte haben:
– NET (Netto-Preise)
– GROSS (Brutto-Preise)
Zusätzlich zur eigentlichen Auftragsbestätigung werden noch die zusammengefassten Steuern (taxes) mit zurückgegeben.
Die Positionen und Kommentare können gesondert abgerufen werden.
Auftragsbestätigung erstellen
POST /api/confirmations
XML-Element |
Beschreibung |
Typ |
Default-Wert |
Pflichtfeld |
client_id |
ID des Kunden |
INT |
|
ja |
contact_id |
ID des Kontakts |
INT |
|
|
address |
komplette Adresse |
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 Auftragsbestätungsnummer (wird mit führenden Nullen aufgefüllt) |
INT |
Wert aus Einstellungen |
|
date |
Auftragsbestätigungsdatum |
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 |
|
offer_id |
Die ID des Angebots, wenn die Auftragsbestätigung aus einem Angebot 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 Auftragsbestätigung abgeschlossen werden soll. |
INT |
ID der Standardvorlage |
|
status ist bei der Erstellung immer DRAFT.
Die übrigen Eigenschaften der Auftragsbestätigung werden automatisch berechnet.
Auftragsbestätigungspositionen (confirmation-items) können bei der Erstellung direkt mit angegeben werden. Es gelten die gleichen XML-Elemente wie unter Auftragsbestätigungsbestätigungspositionen erstellen. Nur das XML-Element confirmation_id muss nicht mit angegeben werden.
<confirmation>
<client_id>5</client_id>
<date>2009-11-17</date>
<confirmation-items>
<confirmation-item>
<unit>Stück</unit>
<unit_price>1.23</unit_price>
<quantity>1.5</quantity>
<title>Muster</title>
</confirmation-item>
<confirmation-item>
<unit>Stück</unit>
<unit_price>1.23</unit_price>
<quantity>5</quantity>
<title>Muster 2</title>
</confirmation-item>
</confirmation-items>
</confirmation>
<?xml version="1.0" encoding="UTF-8"?>
<confirmation>
<id type="integer">1234</id>
<client_id type="integer">5</client_id>
<created type="datetime">2007-12-13T12:12:00+01:00</created>
<confirmation_number>AB124</confirmation_number>
<number type="integer">124</number>
<number_pre>AB</number_pre>
<number_length type="integer">0</number_length>
<date type="date">2009-11-17</date>
...
</confirmation>
Auftragsbestätigung bearbeiten
PUT /api/confirmations/{id}
Eine Auftragsbestätigung kann grundsätzlich nur im Entwurfs-Status (DRAFT) bearbeitet werden.
Positionen und Kommentare können nicht direkt über die Auftragsbestätigung bearbeitet werden. Bitte dafür über die entsprechende Ressource gehen.
<confirmation>
<date>2009-10-13</date>
</confirmation>
Auftragsbestätigung löschen
DELETE /api/confirmations/{id}
Löscht eine Auftragsbestätigung inkl. aller dazugehöriger Dokumente (PDFs), Positionen und Kommentare.
Auftragsbestätigung abschließen
PUT /api/confirmations/{id}/complete
Schließt eine Auftragsbestätigung im Entwurfsstatus (DRAFT) ab. Dabei wird der Status auf offen (OPEN) 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 Auftragsbestätigung hinterlegte Vorlage oder die eingestellte Standardvorlage benutzt.
<complete>
<template_id>123</template_id>
</complete>
PDFs einer Auftragsbestätigung aufrufen
GET /api/confirmations/{id}/pdf
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>
<confirmation_id type="integer">240</confirmation_id>
<filename>confirmation_123.pdf</filename>
<mimetype>application/pdf</mimetype>
<filesize>70137</filesize>
<base64file>{base64-kodiertes PDF}</base64file>
</pdf>
Auftragsbestätigung per E-Mail versenden
POST /api/confirmations/{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-Auftragsbestätigung (ohne .pdf) |
ALNUM |
confirmation_{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>Bestätigung des Auftrags</subject>
<body>Sehr geehrte Damen und Herren, ....</body>
<filename>Auftragsbestätigung</filename>
<attachments>
<attachment>
<filename>zeichnung.pdf</filename>
<mimetype>application/pdf</mimetype>
<base64file>{base64-kodierte Datei}</base64file>
</attachment>
</attachments>
</email>
Auftragsbestätigung per Brief versenden
POST /api/confirmations/{id}/mail
Versendet eine Auftragsbestätigung 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>
Auftragsbestätigung stornieren
PUT /api/confirmations/{id}/cancel
Stornieren rückgängig machen
PUT /api/confirmations/{id}/uncancel
Auftragsbestätigung als abgerechnet markieren
PUT /api/confirmations/{id}/clear
Auftragsbestätigung als nicht abgerechnet markieren
PUT /api/confirmations/{id}/unclear