Angebote | Billomat

Alle Angebote auflisten

GET /api/offers

<?xml version="1.0" encoding="UTF-8"?>
<offers type="array" page="1" per_page="100" total="2">
<offer>
…
</offer>
<offer>
…
</offer>
</offers>

Über Parameter kann gefiltert werden:

GET /api/offers?offer_number=AN123

Listet alle Angebote auf, die „AN123“ in der Angebotsnummer haben. Groß- und Kleinschreibung wird ignoriert.
Folgende Parameter stehen zur Verfügung:

Parameter	Beschreibung
client_id	ID des Kunden
contact_id	ID des Kontakts
offer_number	Angebotsnummer
status	Angebotsstatus (DRAFT, OPEN, WON, LOST, CANCELED, CLEARED). Mehrere Stati können per Komma getrennt werden.
from	Nur Angebote ab diesem Datum (Format YYYY-MM-DD)
to	Nur Angebote 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

Einzelnes Angebot aufrufen

GET /api/offers/{id}

<?xml version="1.0" encoding="UTF-8"?>
<offer>
<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>
<offer_number>AN123</offer_number>
<number type="integer">123</number>
<number_pre>AN</number_pre>
<number_length type="integer">0</number_length>
<status>OPEN</status>
<date type="date">2010-10-01</date>
<address>Billomat GmbH &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 drüfen:</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/offers/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>
<validity_date>2010-10-31</validity_date>
<validity_days>30</validity_days>
<template_id></template_id>
</offer>

status kann folgende Werte haben:

DRAFT (Entwurf)
OPEN (offen)
WON (gewonnen)
LOST (lost)
CANCELED (storniert)
CLEARED (abgerechnet)
net_gross kann folgende Werte haben:
NET (Netto-Preise)
GROSS (Brutto-Preise)
Zusätzlich zum eigentlichen Angebot werden noch die zusammengefassten Steuern (taxes) mit zurückgegeben.
Die Angebotspositionen und Angebotskommentare können gesondert abgerufen werden.

Angebot erstellen

POST /api/offers

Erstellt ein neues Angebot.

XML-Element	Beschreibung	Typ	Default-Wert	Pflichtfeld
client_id	ID des Kunden	INT		ja
contact_id	ID des Kontakts	INT
address	komplette Angebotsadresse	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 Angebotsnummer (wird mit führenden Nullen aufgefüllt)	INT	Wert aus Einstellungen
date	Angebotsdatum	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
validity_days	Gültigkeitstage	INT	Gültigkeitstage aus Einstellungen
validity_date	Gültigkeitsdatum	DATE	date + validity_days
free_text_id	Die ID des Freitextes zur Belegung von title, label, intro und note.	INT
template_id	Die ID der Vorlage, mit der das Angebot abgeschlossen werden soll.	INT	ID der Standardvorlage

status ist bei der Erstellung immer DRAFT.

Bei der initialen Erstellung im DRAFT-Status wird die offer_number als leere Response zurückgegeben. Erst bei Abschluss eines Angebotes wird die Angebotsnummer berechnet und erhält einen Wert.

Die übrigen Eigenschaften des Angebotes werden automatisch berechnet.

Angebotspositionen (offer-items) können bei der Erstellung direkt mit angegeben werden. Es gelten die gleichen XML-Elemente wie unter Angebotsposition erstellen. Nur das XML-Element offer_id muss nicht mit angegeben werden.

<offer>
<client_id>5</client_id>
<date>2009-11-17</date>
<offer-items>
<offer-item>
<unit>Stück</unit>
<unit_price>1.23</unit_price>
<quantity>1.5</quantity>
<title>Muster</title>
</offer-item>
<offer-item>
<unit>Stück</unit>
<unit_price>1.23</unit_price>
<quantity>5</quantity>
<title>Muster 2</title>
</offer-item>
</offer-items>
</offer>

<?xml version="1.0" encoding="UTF-8"?>
<offer>
<id type="integer">1234</id>
<client_id type="integer">5</client_id>
<created type="datetime">2007-12-13T12:12:00+01:00</created>
<offer_number>AN124</offer_number>
<number type="integer">124</number>
<number_pre>AN</number_pre>
<number_length type="integer">0</number_length>
<date type="date">2009-11-17</date>
…
</offer>

Angebot bearbeiten

PUT /api/offers/{id}

Aktualisiert ein Angebot mit den übergebenen Parametern.
Ein Angebot kann grundsätzlich nur im Entwurfs-Status (DRAFT) bearbeitet werden.
Angebotspositionen und Kommentare können nicht direkt über das Angebot bearbeitet werden. Bitte dafür über die entsprechende Ressource gehen.

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

Angebot löschen

DELETE /api/offers/{id}

Löscht ein Angebot inkl. aller dazugehöriger Dokumente (PDFs), Angebotspositionen und Kommentare.

Angebot abschließen

PUT /api/offers/{id}/complete

Schließt ein Angebot 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 am Angebot hinterlegte Vorlage oder die eingestellte Standardvorlage benutzt.

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

PDFs eines Angebotes aufrufen

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

Angebot per E-Mail versenden

POST /api/offers/{id}/email

Versendet ein Angebot per E-Mail.

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	offer_{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>Ihr Angebot</subject>
<body>Sehr geehrte Damen und Herren, ….</body>
<filename>angebot</filename>
<attachments>
<attachment>
<filename>zeichnung.pdf</filename>
<mimetype>application/pdf</mimetype>
<base64file>{base64-kodierte Datei}</base64file>
</attachment>
</attachments>
</email>

Angebot per Brief versenden

POST /api/offers/{id}/mail

Versendet ein Angebot 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>

Angebot stornieren

PUT /api/offers/{id}/cancel

Stornieren rückgängig machen

PUT /api/offers/{id}/uncancel

Angebot als gewonnen markieren

PUT /api/offers/{id}/win

Angebot als verloren markieren

PUT /api/offers/{id}/lose

Angebot als abgerechnet markieren

PUT /api/offers/{id}/clear

Angebot als nicht abgerechnet markieren

PUT /api/offers/{id}/unclear