ProSonata API

Fremdkosten

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

• GET: Ressource lesen
• POST: Ressource erstellen
• PUT: Ressource bearbeiten

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

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:

* 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.