Auftragsbestätigungen

Alle Auftragsbestätigungen auflisten

GET /api/confirmations

?xml version="1.0" encoding="UTF-8"?>
<confirmations type=&quot;array&quot; page=&quot;1&quot; per_page=&quot;100&quot; total=&quot;2&quot;>
<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:

ParameterBeschreibung
client_idID des Kunden
contact_idID des Kontakts
confirmation_numberAuftragsbestätigungsnummer
statusAuftragsbestätigungsstatus (DRAFT, COMPLETED, CANCELED). Mehrere Stati können per Komma getrennt werden.
fromNur Auftragsbestätigungen ab diesem Datum (Format YYYY-MM-DD)
toNur Auftragsbestätigungen bis zu diesem Datum (Format YYYY-MM-DD)
labelFreitextsuche in der Bezeichnung
introFreitextsuche im Einleitungstext
noteFreitextsuche im Anmerkungstext
tagsKommaseparierte Liste der Schlagworte
article_idID eines Artikels, der enthalten ist

Einzelne Auftragsbestätigung aufrufen

GET /api/confirmations/{id}

<?xml version=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?>
<confirmation>
<id type=&quot;integer&quot;>1</id>
<client_id type=&quot;integer&quot;>123</client_id>
<contact_id type=&quot;integer&quot;></contact_id>
<created type=&quot;datetime&quot;>2007-12-13T12:12:00+01:00</created>
<confirmation_number>AB123</confirmation_number>
<number type=&quot;integer&quot;>123</number>
<number_pre>AB</number_pre>
<number_length type=&quot;integer&quot;>0</number_length>
<status>COMPLETED</status>
<date type=&quot;date&quot;>2010-10-01</date>
<address>Billomat GmbH &amp;amp;amp;amp;amp;amp; 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=&quot;float&quot;>107.1</total_gross>
<total_net type=&quot;float&quot;>90.0</total_net>
<net_gross>NET</net_gross>
<reduction>10</reduction>
<total_gross_unreduced type=&quot;float&quot;>119.0</total_gross_unreduced>
<total_net_unreduced type=&quot;float&quot;>100.0</total_net_unreduced>
<currency_code>EUR</currency_code>
<quote type=&quot;float&quot;>1.0000</quote>
<customerportal_url>https://mybillomatid.billomat.net/customerportal/confirmations/show/entityId/123?hash=123456789aabbcc</customerportal_url>
<taxes type=&quot;array&quot;>
<tax>
<name>MwSt</name>
<rate type=&quot;float&quot;>19.0</rate>
<amount type=&quot;float&quot;>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-ElementBeschreibungTypDefault-WertPflichtfeld
client_idID des KundenINTja
contact_idID des KontaktsINT
addresskomplette AdresseALNUMAdresse des Kunden
number_prePräfixALNUMWert aus Einstellungen
numberlfd. NummerINTnächste freie Nummer
number_lengthMindestlänge der Auftragsbestätungsnummer (wird mit führenden Nullen aufgefüllt)INTWert aus Einstellungen
dateAuftragsbestätigungsdatumDATEheute
titleDokumentenüberschriftALNUM
labelBezeichnungALNUM
introEinleitungstextALNUMWert aus Einstellungen
noteAnmerkungstextALNUMWert aus Einstellungen
reductionRabatt (Absolut oder als Prozentwert: 10/10%)ALNUM
currency_codeWährungISO-WährungscodeStandard-Währung
net_grossPreisbasis (Brutto- oder Netto-Preise)ALNUM („NET“, „GROSS“)Wert aus den Einstellungen
quoteWährungskurs (für Umrechnung in Standard-Währung)FLOAT1.0000
offer_idDie ID des Angebots, wenn die Auftragsbestätigung aus einem Angebot erstellt wurde.INT
free_text_idDie ID des Freitextes zur Belegung von title, label, intro und note.INT
template_idDie ID der Vorlage, mit der die Auftragsbestätigung abgeschlossen werden soll.INTID der Standardvorlage

status ist bei der Erstellung immer DRAFT.

Bei der initialen Erstellung im DRAFT-Status wird die confirmation_number als leere Response zurückgegeben. Erst bei Abschluss einer Auftragsbestätigung wird die Auftragsbestätigungsnummer berechnet und erhält einen Wert.


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=&quot;1.0&quot; encoding=&quot;UTF-8&quot;?>
<confirmation>
<id type=&quot;integer&quot;>1234</id>
<client_id type=&quot;integer&quot;>5</client_id>
<created type=&quot;datetime&quot;>2007-12-13T12:12:00+01:00</created>
<confirmation_number>AB124</confirmation_number>
<number type=&quot;integer&quot;>124</number>
<number_pre>AB</number_pre>
<number_length type=&quot;integer&quot;>0</number_length>
<date type=&quot;date&quot;>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=&quot;integer&quot;>4882</id>
<created type=&quot;datetime&quot;>2009-09-02T12:04:15+02:00</created>
<confirmation_id type=&quot;integer&quot;>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-ElementBeschreibungTypDefault-WertPflichtfeld
email_template_idID der E-Mail-VorlageINT
fromAbsenderEMAILStandard-E-Mail aus Einstellungen
recipientsEmpfänger der E-Mail. Muss mindestens einen XML-Knoten „to“, „cc“ und/oder „bcc“ mit den gewünschten E-Mail-Adressen enthaltenXML-Knoten/EMAILja
subjectBetreff der E-Mail, kann Platzhalter enthaltenALNUMWert aus der (Standard-)E-Mail-Vorlage
bodyText der Mail, kann Platzhalter enthaltenALNUMWert aus der (Standard-)E-Mail-Vorlage
filenameDateiname der PDF-Auftragsbestätigung (ohne .pdf)ALNUMconfirmation_{id}
attachmentsWeitere Dateianhänge. Kann beliebig viele Dateianhänge über die Knoten „attachment“ mit den Elementen „filename“, „mimetype“ und „base64file“ enthaltenXML-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-ElementBeschreibungTypDefault-WertPflichtfeld
colorZeigt an, ob ein Farbdruck beauftragt werden soll.BOOL0
duplexZeigt an, ob Duplexdruck beauftragt werden soll.BOOL1
paper_weightWelche Papierstärke in Gramm soll das Papier haben? Mögliche Werte sind 80 oder 90.INT90
attachmentsPDF 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

Rechnung aus Auftragsbestätigung erstellen

Im ersten Schritt muss man sich über die Preset-Funktion zur entsprechenden Auftragsbestätigung (confirmation_id) einen Payload der Rechnung beschaffen.

GET /api/invoices/preset?confirmation_id={id}

Diesen erhaltenen Payload übergibt man vollständig an die Rechnungs-Erstellen-API:

POST /api/invoices

<invoice>
...
</invoice>