ProSonata API

Fremdkosten

Folgende HTTP-Methoden stehen für Fremdkosten zur Verfügung:

Zugriff ab Benutzergruppe Teamleiter und für Fremdkostenerfasser.

alle Fremdkosten auflisten

GET /api/v1/externalcosts

Antwort:

{
  "meta": {
    "status": 200,
    "perPage": 100,
    "page": 1,
    "totalCount": 64,
    "requestUserID": 1,
    "requestUsername": "Admin1",
    "usergroupName": "Administrator",
    "apiLimitRemaining": 428,
    "apiLimitReset": 793
  },
  "data": [
    {
      "documentID": 119,
      "addressID": 43,
      "name1": "Repro Schmidt GbR",
      "type": 1,
      "projectID": 172,
      "projectNo": "17-18-001",
      "projectName": "Käsebroschüre",
      "customerName": "Käserei Gouda",
      "costName": "Broschüre Proofs",
      "documentNo": "R513213",
      "documentDate": "2019-10-23",
      "paymentTarget": 0,
      "paymentType": null,
      "receiptDate": "2019-10-23",
      "recurringDoc": 0,
      "createdByUserID": 2,
      "quantity": null,
      "unitPrice": null,
      "unit": "",
      "netValue": 100,
      "grossValue": 119,
      ...
    },
    ...
  ]
}

Filterung/Suche

Über Parameter kann gefiltert werden:

GET /api/v1/externalcosts?projectName=Testprojekt
Parameter Beschreibung
addressID ID der Lieferantenadresse
name1 Firmierung des Lieferanten (Zeile 1 der Adresse)
type Dokumenttyp
0 = Angebot
1 = Rechnung
projectID ID des Projekts
projectNo Projektnummer
projectName Bezeichnung des Projekts
customerID ID des Kunden (Firma/Gruppe)
customerName Bezeichnung des Kunden (Firma/Gruppe)
costName Bezeichnung des Fremdkostendokuments
documentNo Nummer des Dokuments
documentDate Datum des Dokuments
durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen
receiptDate Eingangsdatum des Dokuments
durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen
paymentType Zahlmethode:
1 = Banküberweisung
2 = Lastschrift
3 = Kreditkarte
4 = Dauerauftrag
5 = Kasse
6 = Vorkasse
7 = Paypal
8 = Scheck
9 = Gutschrift
10 = Verrechnung
11 = EC-Karte
recurringDoc wiederkehrendes Projekt:
0 = nicht wiederkehrend
1 = monatlich
2 = zweimonatlich
3 = quartalsweise
4 = halbjährlich
5 = jährlich
6 = zweijährlich
7 = mit Projekt kopieren
createdByUserID Dokument angelegt von Benutzer ID
currency Währung:
0 = Euro
1 = CHF
2 = USD
3 = GBP
4 = CAD
reverseCharge Reverse Charge (Rechnungsempfänger ist steuerpflichtig):
0 = nein
1 = ja
paymentDate Bezahldatum des Dokuments
durch Angabe von > oder < vor dem Datum kann eine Suche ab dem bzw. bis zum Datum erfolgen
notInvoiceable nicht weiterberechenbar:
0 = nein
1 = ja
kskMember Dokument ist relevant für Künstler Sozialkasse:
0 = nein
1 = ja
useForCalculation in Projektkalkulation einbezogen (relevant für Angebote):
0 = nein
1 = ja
serviceCategory ID der Leistungskategorie
datevExport FiBu Export ist erfolgt:
0 = nein
1 = ja

 

Sortierung

Nach folgenden Parametern kann sortiert werden (Sortierrichtung ggf. mit ASC bzw. DESC ergänzen):

documentID, projectID, addressID, documentNo, documentDate, receiptDate, grossValue

ein Fremdkostendokument aufrufen

GET /api/v1/externalcosts/{id}

Antwort:

{
  "meta": {
    "status": 200,
    "requestUserID": 1,
    "requestUsername": "Admin1",
    "usergroupName": "Administrator",
    "apiLimitRemaining": 491,
    "apiLimitReset": 493
  },
  "data": {
    "documentID": 86,
    "addressID": 41,
    "name1": "Druckerei Schnell GmbH",
    "type": 1,
    "projectID": 172,
    "projectNo": "17-18-001",
    "projectName": "Käsebroschüre",
    "customerID": 18,
    "customerName": "Käserei Gouda",
    "costName": "Druck Broschüre",
    "documentNo": "R23424",
    "documentDate": "2017-02-18",
    "paymentTarget": 14,
    "paymentType": null,
    "receiptDate": "2017-02-18",
    "recurringDoc": 0,
    "createdByUserID": 1,
    "quantity": 1,
    "unitPrice": 1100,
    "unit": "",
    "comments": "erste Position des Dokuments",
    "netValue": 1500,
    "grossValue": 1785,
    "currency": 0,
    "tax": 19,
    "multipleTaxes": 0,
    "reverseCharge": 0,
    "multiplePositions": 1,
    "cashDiscountRate": 0,
    "paymentDate": null,
    "paidCashDiscount": 0,
    "additionalCharge": 0,
    "additionalCharge2": 0,
    "notInvoiceable": 0,
    "kskMember": 0,
    "useForCalculation": 0,
    "serviceCategory": 4,
    "categoryName": "Produktion",
    "fibuExpenseAccount": "",
    "fibuInputTaxAccount": "",
    "datevTaxKey": 9,
    "approvedByUsers": "",
    "datevExport": 0,
    "documentViaApi": 0,
    "additionalPositions": [
      {
        "detailID": 23,
        "detail": "zweite Position des Dokuments",
        "quantity": 2,
        "unit": "Stck.",
        "netValue": 200,
        "taxSwitch": 0,
        "tax": 0,
        "fibuInputTaxAccount": "",
        "datevTaxKey": null
      }
    ]
  }
}

ein Fremdkostendokument erstellen

POST /api/v1/externalcosts

Übergebene Werte (z.B. netValue, grossValue = Gesamtpreis des Dokuments) werden bei der Speicherung nicht auf korrekte Berechnung überprüft! Eine Validierung muss vorab erfolgen.

Im einfachsten Fall kann ein zu erfassendes Dokument einen Gesamtpreis und die Zuordnung zum Projekt und Lieferanten erhalten. Ergänzend können hier die Parameter quantity und unitPrice genutzt werden, um eine Menge und einen Einzelpreis (für die erste Position) zu erfassen. Falls weitere Positionen vorhanden sind, können diese als Array mit dem Parameter additionalPositions übergeben werden.

Optional – und wenn ein FTP Webspace als Dateiablage konfiguriert ist – kann eine Datei hochgeladen werden. Die Datei muss dabei base64 codiert im entsprechenden Feld file übertragen werden.

Falls die addressID und/oder die projectID nicht bekannt sind, kann der Datensatz in die Inbox gespeichert werden (Parameter useInbox = 1). In einem zweiten Schritt kann in ProSonata (Menüpunkt > Faktura > Fremdkosten) der Datensatz nach Zuordnung der fehlenden Parameter als neues Fremdkostendokument übernommen werden.

Notwendige und mögliche Parameter im Body:

Parameter Beschreibung Typ Default-Wert Pflichtfeld
projectID ID des Projekts Int   ja*
projectNo Nummer des Projekts (bei Nutzung der Inbox, ansonsten hat die projectID Vorrang) String    
addressID ID der Lieferantenadresse Int   ja*
supplierName Firmierung des Lieferanten (bei Nutzung der Inbox, ansonsten hat die addressID Vorrang) String    
type Dokumenttyp
0 = Angebot
1 = Rechnung
Int 1  
costName Bezeichnung des Fremdkostendokuments String    
documentNo Nummer des Dokuments String    
documentDate Datum des Dokuments Date aktueller Tag  
paymentTarget Zahlungsziel (in Tagen) Int 0  
paymentType Zahlmethode:
1 = Banküberweisung
2 = Lastschrift
3 = Kreditkarte
4 = Dauerauftrag
5 = Kasse
6 = Vorkasse
7 = Paypal
8 = Scheck
9 = Gutschrift
10 = Verrechnung
11 = EC-Karte
  null  
receiptDate Eingangsdatum des Dokuments Date aktueller Tag  
recurringDoc wiederkehrendes Projekt:
0 = nicht wiederkehrend
1 = monatlich
2 = zweimonatlich
3 = quartalsweise
4 = halbjährlich
5 = jährlich
6 = zweijährlich
7 = mit Projekt kopieren
  0  
quantity Menge (Position 1) Dec null  
unitPrice Einzelpreis (Position 1) Dec null  
unit Einheit (Position 1) String    
comments Beschreibungstext (Position 1 oder allgemein zum Dokument) String    
netValue Gesamtpreis netto Dec 0.00 ja
grossValue Gesamtpreis brutto Dec 0.00 ja
currency Währung:
0 = Euro
1 = CHF (SFr)
2 = US$
3 = GBP
Int 0  
tax Steuersatz Dec 0.0 ja
multipleTaxes mehrere Steuersätze im Dokument vorhanden
0 = nein
1 = ja
Int 0  
reverseCharge Dokument unterliegt dem Reverse Charge Verfahren
0 = nein
1 = ja
Int 0  
multiplePositions mehrere Positionen im Dokument vorhanden
0 = nein
1 = ja
Int 0  
cashDiscountRate gewährter Skontosatz Dec 0.0  
paymentDate Dokument ist bezahlt (Eingabe Zahldatum) Date null  
paidCashDiscount Skonto wurde genutzt
0 = nein
1 = ja
Int 0  
additionalCharge geplanter prozentualer Aufschlag Dec 0.00  
additionalCharge2 geplanter Aufschlag als Festbetrag
– die Eingabe hat Vorrang vor einem prozentualen Aufschlag
– bei mehreren erfassten Positionen erfolgt der Aufschlag nur prozentual
Dec 0.00  
notInvoiceable nicht weiterberechenbare Rechnung
0 = nein
1 = ja
Int 0  
kskMember Rechnung ist relevant für Künstler Sozialkasse
0 = nein
1 = ja
Int    
useForCalculation Angebot wird in der Projektauswertung berücksichtigt
0 = nein
1 = ja
Int 1  
serviceCategory ID der Leistungskategorie Int null  
fibuExpenseAccount FiBu Aufwandskonto String    
fibuInputTaxAccount FiBu Vorsteuerkonto String    
datevTaxKey Vorsteuerschlüssel nach Datev Int null  
approvedByUsers Freigabetext (interne Freigabe) String    
datevExport FiBu Export ist erfolgt
0 = nein
1 = ja
Int 0  
additionalPositions

weitere Positionen des Dokuments speichern;
ein Array der Positionen kann übergeben werden:

detail: Beschreibung der Position

quantity: Menge

unit: Einheit

netValue: Einzelpreis

taxSwitch: Pos. hat einen eigenen Steuersatz
0 = nein (default)
1 = ja

tax: Steuersatz

fibuInputTaxAccount: FiBu Vorsteuerkonto

datevTaxKey: Vorsteuerschlüssel nach Datev

Array []
leeres Array
 
file base64 encodierte Daten der Datei (ein MIME-Type o.ä. darf nicht enthalten sein)
maximale Dateigröße ca. 5 MB
String   **
fileName Dateiname inkl. Dateiendung (.pdf, .jpg etc.) String   **
useInbox Nutzung der Inbox für die Dokumenterstellung
0 = nein
1 = ja
Int 0  

* Wird die Inbox genutzt, sind die Felder keine Pflichtfelder.

** Wird eine Datei im Feld file übertragen muss auch ein Dateiname übergeben werden.

Angabe von Dezimalwerten mit Punkt als Trennzeichen.

Beispiel:

{
    "addressID": 41,
    "type": 1,
    "projectID": 45,
    "costName": "eine kurze Bezeichnung",
    "documentNo": "R1234567-123",
    "documentDate": "2019-09-08",
    "paymentTarget": 14,
    "receiptDate": "2019-09-10",
    "quantity": 2,
    "unitPrice": 100.00,
    "unit": "Std.",
    "comments": "Beschreibung zur ersten Position",
    "netValue": 1320.00,
    "grossValue": 1496.40,
    "currency": 0,
    "tax": 19,
    "multipleTaxes": 0,
    "multiplePositions": 1,
    "cashDiscountRate": 2.0,
    "additionalPositions": [
      {
        "detail": "<p>Beschreibung der zweiten Position, mit Dokument Steuersatz 19 %</p>",
        "quantity": 5,
        "unit": "Std.",
        "netValue": 100
      },
      {
        "detail": "<p>Beschreibung der dritten Position, mit Steuersatz 7 %</p>",
        "quantity": 1,
        "unit": "Stck.",
        "netValue": 620,
        "taxSwitch": 1,
        "tax": 7
      }
    ]
}

ein Fremdkostendokument bearbeiten

PUT /api/v1/externalcosts/{id}

Es müssen nicht alle Parameter für eine Bearbeitung übergeben werden.

Es stehen die Parameter zum Erstellen der Ressource zur Verfügung (s.o.).

Ausnahmen:

  • Der Typ des Dokuments (type) kann nachträglich nicht verändert werden.
  • Es kann kein Dateiupload erfolgen.