Angebote in CentralStationCRM

API Navigation

Allgemeines: Grundlagen Authentifizierung Fehlerbehandlung Datenstruktur

Hauptmodelle: Personen Firmen Angebote Projekte Aufgaben

Sonstiges: Anschriften Kontaktdaten Wichtige Daten Individuelle Felder Positionen Notizen Dateianhänge Tags

Die Kür: Webhooks Nutzer Aktivitäten Filter Gruppen Individuelle Feld Typen

Angebote verhalten sich von den Actions (index, show, create, update, delete) her wie die Personen. Die Dokumentation zu den Actions der Personen ist ausführlicher und enthält einige Beispiele. Bei den Angeboten stehen folgende Felder zur Verfügung:

Feldname Feldtyp Beschreibung
id INTEGER ID des Angebotes (Read only)
account_id INTEGER ID des Accounts (Read only)
user_id INTEGER ID des verantwortlichen Nutzers
company_id INTEGER ID der zugehörigen Firma
name VARCHAR(120) Name des Angebotes (Pflichtfeld)
description TEXT Hintergrundinformationen zum Angebot
value DECIMAL Wert des Angebotes (Pflichtfeld)
value_type VARCHAR(20) Typ der Abrechnung. Optionen: Total, Monatlich, Tagessatz, Stundensatz (Pflichtfeld)
value_count INTEGER Anzahl; Nur relevant, wenn der value_type nicht Total ist (z.B. 5 x Stundensatz á 75 Euro) (Pflichtfeld)
currency VARCHAR(3) Währung der Angebotssumme (z.B. EUR), Default: EUR.
target_date DATE Zieldatum des Angebotes (Pflichtfeld)
finished_at TIMESTAMP Zeitpunkt des Angebotsabschlusses (Status wurde auf "won" oder "lost" gesetzt)
current_state VARCHAR(20) Status des Angebots (open_0, open_25, open_50, open_75, won, lost)
created_at TIMESTAMP Zeitpunkt der Erstellung (automatisch gesetzt, read only)
updated_at TIMESTAMP Zeitpunkt des letzten Updates (automatisch gesetzt, read only)
person_ids_set STRING (komma getrennte IDS) IDs der am Angebot beteiligten Personen (nur schreibend)

Bei dem Anlegen eines Angebotes können IDs der Ansprechpartner auf Kundenseite (people) mit übergeben werden. In dem Parameter person_ids_set können mehrere Personen IDs als kommagetrennter String übergeben werden.

Angebote verfügen außerdem über die folgenden verschachtelten Attribute. Der Aufruf dieser verschachtelten Attribute wird bei den Personen beispielhaft beschrieben.

Action: Index

GET /deals.json
Die Sortierung kann mit dem Parameter order beeinflusst werden. Möglich sind zum Beispiel "created_at-asc" (Erstellzeitpunkt), "activity-asc" (letzte Aktivität im Verlauf der Seite), oder "updated_at-desc" (letzte Bearbeitung). Wenn das order Statement übergeben wird, sollte sowohl das Sortierkriterium, als auch die Sortierrichtung (asc oder desc) übergeben werden, da wir je nach Kriterium unterschiedliche Standard-Sortierungen wählen (zB. aufsteigend bei der Sortierung nach Alphabet und absteigend bei der Sortierung nach dem Erstelldatum). Standard ist asc (aufsteigend) nach name (Alphabet).

Verschachtelte Unterobjekte (optional)
Bei dem Aufruf der Index Funktion können die Unterobjekte über den includes Parameter im Format includes:'people company' direkt mit ausgeliefert werden. Mögliche Optionen sind: tags people company custom_fields. Um alle genannten Optionen zu bekommen kann includes:'all' gesetzt werden.

Methods (optional)
Über den methods Parameter können einzelne Daten direkt in den JSON Hash eingebunden werden. Möglich ist methods=responsible_user_natural_name für den vollen Namen des verantwortlichen Nutzers.

Einschränkung nach beliebigem Feld (optional)
Die Liste kann nach jedem der Felder eingeschränkt werden. Beispiele für den filter Parameter sind:

Einschränkung nach Tags (optional)
Durch Übergabe des Parameters tag_id können alle Objekte mit dem gleichen Namen des jeweiligen Tags abgefragt werden. Bei Übergabe des tag_name werden alle Objekte zurückgegeben, die mit dem entsprechenden Tag versehen sind.

Einschränkung nach dem Inhalt von individuellen Feldern (optional)
Die Liste kann anhand eines individuellen Felds eingeschränkt werden. Um die Filterung nach einem individuellen Feld durchzuführen können folgende Formate übergeben werden:
Übergabe der CustomFieldType ID sowie dem Wert, den das Feld enthalten soll:
custom_fields: {'custom_field_type_id' => '1', 'value' => '12345'}
Bsp. URL: /api/people.json?custom_fields[custom_field_type_id]=3&custom_fields[value]=0815

Übergabe des CustomFieldType Name sowie dem Wert, den das Feld enthalten soll:
custom_fields: {'custom_field_type_name' => 'kundennummer', 'value' => '0815'}
Bsp. URL: /api/people.json?custom_fields[custom_field_type_name]=kundennummer&custom_fields[value]=0815

Übergabe der CustomFieldType ID sowie des Wertes in Hash Form (für die Einschränkung nach mehreren CustomFieldTypes):
custom_fields: {'3' => '0815', '5' => 'meinWert', 'CustomFieldTypeID' => 'Suchwert'}
Bsp. URL: /api/people.json?custom_fields[3]=0815&custom_fields[5]=meinWert

Einschränkung auf die beobachteten Einträge eines speziellen Nutzers (optional)
Die Liste kann mit dem Parameter observer_user_id (z.B. observer_user_id=42) so eingeschränkt werden, dass nur die Einträge ausgegeben werden, die von dem angegebenen Benutzer beobachtet werden. Wird der Parameter übergeben, aber keine User ID übergeben, dann wird der Benutzer des API Schlüssels genommen.

Action: Create

POST /deals.json
Ein neues Angebot kann mit der Action create angelegt werden. Im positiven Fall liefert das System das neue Angebot zurück.

Beispiel
curl -v -H "Accept: application/json" -H "Content-type: application/json" 
-X POST -d '{"deal":{"name":"Prozessoptimierung","value_type":"Total",
"target_date":"12-03-2014", "value_count":"1","value":"10000",
"person_ids_set":":person_id, :person_id_2","description":"...","user_id":":user_id"}}'
https://accountname.centralstationcrm.net/api/deals.json

{"deal":{"id":66361,"account_id":21,"company_id":null,"user_id":64,
"name":"Prozessoptimierung","value":"10000.0","value_type":"Total",
"target_date":"2014-03-12","finished_at":null,"current_state":"open_0","value_count":"1.0",
"description":"...","created_at":"2015-07-20T13:55:20.873Z",
"updated_at":"2015-07-20T13:55:20.873Z","currency":"EUR"}}

Angebot Sonderfunktionen

Action: Search

GET /deals/search.json?name=Mäh
Um nach Angeboten zu suchen, kann der Parameter name übergeben werden. Der Parameter name ist Pflichtfeld. Die Rückgabe erfolgt in gleicher Form, wie bei der Index Funktion. Wenn keine Treffer gefunden wurden geben wir einen leeren Array zurück.

Beispiel
curl -X GET https://accountname.centralstationcrm.net/api/deals/search.json?name=Prozess

[
{"deal":{"id":11365,"account_id":21,"company_id":19510,"user_id":64,"name":"Prozessberatung Produktion",
"value":"14000.0","value_type":"Total","target_date":"2015-03-30",
"finished_at":"2014-08-27T07:05:19.000Z","current_state":"won","value_count":"1.0",
"description":"","created_at":"2013-07-04T07:52:50.000Z",
"updated_at":"2015-03-18T15:35:04.000Z","currency":"EUR"}},

{"deal":{"id":4814,"account_id":21,"company_id":987,"user_id":64,"name":"Prozessberatung Verwaltung",
"value":"7980.0","value_type":"Total","target_date":"2015-06-01",
"finished_at":"2015-03-18T16:30:28.000Z","current_state":"won","value_count":"1.0",
"description":"","created_at":"2012-12-14T16:48:16.000Z",
"updated_at":"2015-03-18T16:30:28.000Z","currency":"EUR"}}

...
]

Action: Stats

GET /deals/stats.json
Über die stats können reine Count oder Summenberechnungen für alle oder gefilterte Angebote abgefragt werden. Die Angebote können wie die index action gefiltert werden, also nach Tags oder beliebigen Feldern. total_entries enthält die absolute Zahl der Angebote, sum enthält die Summe der betroffenen Angebote (value * value_count) in der angegebenen currency.

Beispiel
curl -X GET https://accountname.centralstationcrm.net/api/deals/stats.json

{
total_entries: 40,
sum: 217408,
currency: "eur"
}