Zum Hauptinhalt gehen

Artikel (articles) – inkl. Attribute & Schlagworte

Svenja Jacobs
Aktualisiert

Über die Ressource /api/articles verwaltest du deinen Artikelstamm – Produkte und Dienstleistungen mit Preisen, Steuersätzen, Einheiten und mehr.

 

Basis-Endpunkt

https://{deineBillomatID}.billomat.net/api/articles

 

 

Alle Artikel abrufen

Request:

GET /api/articles

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/articles?format=json

Response (200 OK):

{
  "articles": {
    "@page": "1",
    "@per_page": "100",
    "@total": "2",
    "article": [
      { "id": "1", "article_number": "ART001", "title": "Bildbearbeitung", ... },
      { "id": "2", "article_number": "ART002", "title": "Retusche", ... }
    ]
  }
}

Verfügbare Filterparameter:

Parameter Beschreibung
article_number Artikelnummer (Teilsuche)
title Bezeichnung des Artikels (Teilsuche, case-insensitive)
description Beschreibung des Artikels
currency_code Währungscode nach ISO
unit_id ID der zugewiesenen Einheit
tags Kommaseparierte Schlagworte
supplier_id ID des zugewiesenen Lieferanten

 

Beispiel: Alle Artikel, deren Titel „bildbearbeitung" enthält:

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/articles?title=bildbearbeitung&format=json

 

 

Einzelnen Artikel abrufen

Request:

GET /api/articles/{id}

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/articles/1?format=json

Response (200 OK) – vollständiges Datenobjekt:

{
  "article": {
    "id": "1",
    "created": "2007-12-13T12:12:00+01:00",
    "article_number": "ART123",
    "number": "123",
    "number_pre": "ART",
    "number_length": "0",
    "title": "Bildbearbeitung",
    "description": "Das ist eine Beschreibung",
    "sales_price": "123.45",
    "sales_price2": "110.45",
    "sales_price3": "99.99",
    "sales_price4": "",
    "sales_price5": "",
    "currency_code": "EUR",
    "unit_id": "123",
    "tax_id": "1",
    "purchase_price": "",
    "purchase_price_net_gross": "NET",
    "supplier_id": "1",
    "type": "SERVICE"
  }
}

 

 

Neuen Artikel anlegen

Kein Feld ist Pflichtfeld – alle Angaben sind optional.

Request:

POST /api/articles

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{
    "article": {
      "title": "Retusche",
      "sales_price": "12.34",
      "currency_code": "EUR",
      "unit_id": "123",
      "tax_id": "1",
      "type": "SERVICE"
    }
  }' \
  https://{deineBillomatID}.billomat.net/api/articles

Response (201 Created):

{
  "article": {
    "id": "1234",
    "created": "2024-06-01T10:00:00+02:00",
    "article_number": "ART1235",
    "number": "1235",
    "number_pre": "ART",
    "number_length": "0",
    "title": "Retusche",
    "description": "",
    "sales_price": "12.34",
    "currency_code": "EUR",
    "unit_id": "123",
    "tax_id": "1",
    "type": "SERVICE"
  }
}

Alle verfügbaren Felder beim Anlegen:

Feld Typ Pflicht Beschreibung
number_pre ALNUM — Artikelnummer-Präfix (Standard: Wert aus Einstellungen)
number INT — Laufende Nummer (Standard: nächste freie Artikelnummer)
number_length INT — Mindestlänge der Artikelnummer (wird mit führenden Nullen aufgefüllt)
title ALNUM — Bezeichnung des Artikels
description ALNUM — Beschreibung
sales_price FLOAT — Normalpreis (Standard: 0.0)
sales_price2 FLOAT — Preis für Kunden der Preisgruppe 2 (leer = Normalpreis)
sales_price3 FLOAT — Preis für Kunden der Preisgruppe 3 (leer = Normalpreis)
sales_price4 FLOAT — Preis für Kunden der Preisgruppe 4 (leer = Normalpreis)
sales_price5 FLOAT — Preis für Kunden der Preisgruppe 5 (leer = Normalpreis)
currency_code ISO — Währung (Standard: Account-Währung)
unit_id INT — ID der verknüpften Einheit (aus Einstellungen)
tax_id INT — ID des verknüpften Steuersatzes (aus Einstellungen)
purchase_price FLOAT — Einkaufspreis
purchase_price_net_gross NET / GROSS — Preisbasis des Einkaufspreises (Standard: NET)
supplier_id INT — ID des verknüpften Lieferanten
type PRODUCT / SERVICE — Typ: Produkt oder Dienstleistung

Hinweis zu Preisgruppen:
Die Felder sales_price2 bis sales_price5 entsprechen den Preisgruppen 2–5. Welcher Preis einem Kunden angezeigt wird, hängt von der am Kunden hinterlegten price_group ab. Ist kein gruppenspezifischer Preis gesetzt, gilt automatisch der Normalpreis (sales_price).

 

 

Artikel bearbeiten

Es müssen nur die zu ändernden Felder mitgeschickt werden.

Request:

PUT /api/articles/{id}

curl -X PUT \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{"article": {"description": "Exessive Photoshop-Manipulationen"}}' \
  https://{deineBillomatID}.billomat.net/api/articles/1

Response (200 OK) – vollständiger aktualisierter Datensatz.

 

 

Artikel löschen

Request:

DELETE /api/articles/{id}

curl -X DELETE \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/articles/1

Response (200 OK) – kein Body.

 

 

Teil 2: Benutzerdefinierte Attribute

Auch Artikel können mit eigenen Attributen versehen werden – z.B. Farbe, Material oder Lagerort. Die Attributdefinitionen werden unter Einstellungen > Artikel-Attribute angelegt, die Werte über /api/article-property-values verwaltet.

 

Alle Attributwerte auflisten

Request:

GET /api/article-property-values

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/article-property-values?format=json

Filterparameter:

Parameter Beschreibung
article_id Alle Attribute eines bestimmten Artikels
article_property_id Alle Werte eines bestimmten Attributs
value Wert des Attributs

 

Einzelnes Attribut abrufen

Request:

GET /api/article-property-values/{id}

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/article-property-values/1?format=json

Response (200 OK):

{
  "article-property-value": {
    "id": "1",
    "article_id": "2",
    "article_property_id": "3",
    "type": "TEXTFIELD",
    "name": "Farbe",
    "value": "blau"
  }
}

 

Attributwert setzen

Alle drei Felder sind Pflichtfelder.

Request:

POST /api/article-property-values

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{
    "article-property-value": {
      "article_id": "2",
      "article_property_id": "3",
      "value": "rot"
    }
  }' \
  https://{deineBillomatID}.billomat.net/api/article-property-values

Response (201 Created):

{
  "article-property-value": {
    "id": "1",
    "article_id": "2",
    "article_property_id": "3",
    "type": "TEXTFIELD",
    "name": "Farbe",
    "value": "rot"
  }
}

 

 

Teil 3: Schlagworte (Tags)

Schlagworte ermöglichen die freie Kategorisierung von Artikeln. Das Muster ist identisch mit Kunden- und Lieferanten-Tags – nur mit dem Endpunkt /api/article-tags.

 

Alle Schlagworte (Tagcloud) abrufen

Request:

GET /api/article-tags

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/article-tags?format=json

Response (200 OK):

{
  "article-tags": {
    "@total": "2",
    "article-tag": [
      { "id": "1", "name": "Fotografie", "count": "12" },
      { "id": "2", "name": "Retusche", "count": "7" }
    ]
  }
}

 

Schlagworte eines Artikels abrufen

article_id ist Pflichtparameter – Schlagworte können nur artikelbezogen abgerufen werden.

Request:

GET /api/article-tags?article_id={id}

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/article-tags?article_id=1&format=json

Response (200 OK):

{
  "article-tags": {
    "@total": "1",
    "article-tag": {
      "id": "5",
      "article_id": "1",
      "name": "Fotografie"
    }
  }
}

 

Einzelnes Schlagwort abrufen

Request:

GET /api/article-tags/{id}

curl -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/article-tags/5?format=json

Response (200 OK):

{
  "article-tag": {
    "id": "5",
    "article_id": "1",
    "name": "Fotografie"
  }
}

 

Schlagwort vergeben

Beide Felder sind Pflichtfelder.

Request:

POST /api/article-tags

curl -X POST \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  -H 'Content-Type: application/json' \
  -d '{"article-tag": {"article_id": "1", "name": "Fotografie"}}' \
  https://{deineBillomatID}.billomat.net/api/article-tags

Response (201 Created):

{
  "article-tag": {
    "id": "5",
    "article_id": "1",
    "name": "Fotografie"
  }
}

 

Schlagwort entfernen

Request:

DELETE /api/article-tags/{id}

curl -X DELETE \
  -H 'X-BillomatApiKey: {dein-api-schluessel}' \
  https://{deineBillomatID}.billomat.net/api/article-tags/5

Response (200 OK) – kein Body.

 

Verwandte Artikel

 

Verknüpfung mit

Kommentare

0 Kommentare

Zu diesem Beitrag können keine Kommentare hinterlassen werden.