Zum Hauptinhalt springen
API docs by Redocly

Westarp Verlagsservice (2.0)

Westarp Verlagsservice GmbH: info@westarp.de URL: https://www.westarp-vs.de

Dies ist die API des Verlagsportals der Westarp Verlagsservice GmbH. Sie ermöglicht es Kunden, Partnern und Mandanten, ihre eigene Software an das Verlagsportal anzubinden. Hierfür stehen verschiedene Endpunkte zur Verwaltung von Buchtiteln, Bestellungen und Berichten zur Verfügung.

Allgemeines

Verwendung der Dokumentation

Diese Dokumentation soll einen Einstieg in die Verwendung der API geben und erklären, wie bestimmte Fälle abgedeckt und umgesetzt werden. Links sehen Sie ein Menü, über das Sie jederzeit zum gewünschten Thema der API navigieren können. In der mittleren Spalte finden Sie die jeweilige Erklärung. Rechts finden Sie Beispiele zu Anfragen und deren jeweiligen Antworten.

Authentifizierung

Die Authentifizierung an der API erfolgt über einen HTTP Bearer Token. Diesen können Sie für Ihren Verlag in unserer Booxboo.de App unter app.booxboo.de generieren. Gehen Sie hierzu bitte in den Bereich Einstellungen → API Schlüssel und erstellen Sie einen neuen API Schlüssel. Achten Sie bitte auch darauf, Ihrem neuen API Schlüssel nur die nötigsten Berechtigungen für Ihre Anwendung zu geben.

API Schlüssel verwalten →

Den generierten Token müssen Sie bei jeder Anfrage an die API im Header mitgeben. Hierfür nutzen Sie bitte den HTTP-Header Authorization mit dem Wert Bearer <token>. Der Token ist dann für alle Anfragen an die API gültig, bis Sie ihn in der Booxboo-App löschen.

Achtung!

Bitte achten Sie darauf, dass Sie den API Token nicht öffentlich zugänglich machen. Der Token ist wie ein Passwort und sollte daher auch nicht in öffentlich zugänglichen Repositories oder ähnlichem gespeichert werden!

Verlage

Als angemeldeter Nutzer an der API der Westarp Verlaggsoftware haben Sie Zugriff auf die Daten entweder eines oder mehrerer Verlage – auch Mandanten genannt. Jeder Verlag hält dabei seine eigenen Buchtitel, Bestellungen, Lieferungen, etc. und wird durch eine Verlags-ID (publisher_id) identifiziert.

Möchten Sie sich eine Liste der neuesten Bestellungen über die API abrufen, kann es daher z.B. hilfreich sein, diese nach der Verlags-ID zu filtern. Hinweise hierzu finden Sie in den entsprechenden Request-Beschreibungen.

Alle Verlage abrufen

Mit dieser Anfrage rufen Sie alle Ihnen zugeordneten Verlage ab.

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Bücher

Mit den folgenden Endpunkten haben Sie die Möglichkeit, Ihre Buchtitel abzurufen, anzulegen und zu bearbeiten. Wir empfehlen jedoch, Änderungen an Ihren Buchttieln über die Booxboo-App unter app.booxboo.de vorzunehmen.

Alle Bücher abrufen

Ruft eine Liste aller eingetragenen Bücher ab. Sie können die Liste der Bücher mittels der folgenden Request Parameter filtern, beispielsweise um nur Titel eines bestimmten Verlages abzurufen.

Die Antwort des Servers wird als Pagination ausgegeben. Das bedeutet, es können immer nur 25 Ergebnisse bei einem Request abgerufen werden. Innerhalb der Response finden Sie Seitenzahlen und direkte Links zu den einzelnen Ergebnisseiten.

Authorizations:
bearer
query Parameters
publisher_id
integer

Mandanten-ID

status
string
Enum: "available" "shortage" "out_of_stock" "planned" "nonweb" "discontinued" "blocked" "reprint" "new_edition" "available_without_vlb" "pending"

Veröffentlichungs-Lieferstatus

author
string

Autor (ID oder Name)

isbn
string

ISBN10 oder ISBN13 – auch ISBN-Teile

term
string

Suchbegriff (Titel, Untertitel, etc.)

Responses

Response samples

Content type
{}

Buch anlegen

Legt ein neues Buch an.

Authorizations:
bearer
Request Body schema:
required

Daten des neu anzulegenden Titels

publisher_id
required
integer

ID des Verlages, dem der Titel angehört

title
required
string

Der Titel des Buches

status
required
string

Veröffentlichungsstatus Ihres Titels

  • shortage: 'fehlt kurzfristig - Bestellung notiert'
  • out_of_stock: 'vergriffen -> Bestellung abggt'
  • planned: 'in Planung - interne Daten'
  • non_web: 'nonweb - interne Daten'
  • discontinued: 'erscheint nicht - Titel eingestellt'
  • blocked: 'Auslieferung gestoppt - Titel gesperrt'
  • available: 'lieferbar'
  • reprint: 'Nachdruck ohne Termin - vorgemerkt
  • new_edition: 'vergriffen --> siehe Neuaflage'
  • available_without_vlb: 'Lieferbar - ohne VLB-Eintrag'
  • pending: 'in Vorbereitung - Bestellung notiert'
sub_title
string or null

Untertitel

short_title
string or null

Kurztitel

isbn10
string

ISBN10

isbn13
string

ISBN13

ean
string or null

EAN (European Article Number)

edition
integer or null

Auflage

published_at
string

Veröffentlichungsdatum

type
any or null

Die Art des Buches

Array of objects

Mitwirkende an dem

object

Details zu dem Buch

costs
Array of objects
object
Array of objects
Array of objects
object
object
object
contracts
Array of objects
Array of objects

Responses

Request samples

Content type
{
  • "publisher_id": 78,
  • "title": "Die verlorenen Träume",
  • "isbn10": "0-246810-14-2",
  • "isbn13": "978-0-246810-14-5",
  • "ean": "9780246810145",
  • "published_at": "2023-11-10 08:17:36",
  • "status": "available",
  • "type": "new_edition",
  • "contributors": [
    ],
  • "details": {
    },
  • "descriptions": {
    },
  • "prices": [
    ]
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "legacy_id": 0,
  • "publisher_id": 0,
  • "title": "string",
  • "sub_title": "string",
  • "short_title": null,
  • "isbn10": "string",
  • "isbn13": "string",
  • "ean": "string",
  • "edition": 0,
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "shortage",
  • "collections": [
    ],
  • "type": "reprint",
  • "contributors": [
    ],
  • "details": {
    },
  • "costs": [
    ],
  • "descriptions": {
    },
  • "files": [
    ],
  • "prices": [
    ],
  • "current_retail_price": {
    },
  • "royalty": {
    },
  • "vlb": {
    },
  • "contracts": [
    ],
  • "stocks": [
    ]
}

Buch abrufen

Mit dieser Anfrage rufen Sie alle Details zu einem bestimmten Titel ab.

Authorizations:
bearer
path Parameters
bookId
required
string

Die ID des Buches

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "legacy_id": 0,
  • "publisher_id": 0,
  • "title": "string",
  • "sub_title": "string",
  • "short_title": null,
  • "isbn10": "string",
  • "isbn13": "string",
  • "ean": "string",
  • "edition": 0,
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "shortage",
  • "collections": [
    ],
  • "type": "reprint",
  • "contributors": [
    ],
  • "details": {
    },
  • "costs": [
    ],
  • "descriptions": {
    },
  • "files": [
    ],
  • "prices": [
    ],
  • "current_retail_price": {
    },
  • "royalty": {
    },
  • "vlb": {
    },
  • "contracts": [
    ],
  • "stocks": [
    ]
}

Buch löschen

Löscht ein Buch.

Achtung: Diese Anfrage sollte nur mit äußerster Vorsicht ausgeführt werden, da sie zur sofortigen Stornierung aller Bestellungen, sowie zur Entlistung in Shops, bei Amazon und den Barsortimenten führt. Bitte führen Sie diese Anfrage daher nur aus, wenn Sie genau wissen, was Sie tun.

Authorizations:
bearer
path Parameters
bookId
required
string

Die ID des Buches

Responses

Response samples

Content type
application/json
{
  • "message": "Unauthenticated."
}

Buch aktualisieren

Aktualisiert die Daten eines Titels.

Authorizations:
bearer
path Parameters
bookId
required
string

Die ID des Buches

Request Body schema: application/json
required

Updated Book information.

id
string

Eindeutige Buch-ID

legacy_id
integer or null
Deprecated

ID innerhalb des Legacy-Systems (nur intern verwendet)

publisher_id
integer

ID des zugehörigen Verlages

title
string

Titel des Buches

sub_title
string

Untertitel

short_title
any or null

Kurztitel

isbn10
string

ISBN-10

isbn13
string

ISBN-13

ean
string

EAN (European Article Number)

edition
integer

Auflage

published_at
string <date-time>

Veröffentlichungsdatum

status
string
Enum: "shortage" "out_of_stock" "planned" "non_web" "discontinued" "blocked" "available" "reprint" "new_edition" "available_without_vlb" "pending"

Veröffentlichungsstatus Ihres Titels

  • shortage: 'fehlt kurzfristig - Bestellung notiert'
  • out_of_stock: 'vergriffen -> Bestellung abggt'

planned: 'in Planung - interne Daten'

non_web: 'nonweb - interne Daten'

discontinued: 'erscheint nicht - Titel eingestellt'

blocked: 'Auslieferung gestoppt - Titel gesperrt'

available: 'lieferbar'

reprint: 'Nachdruck ohne Termin - vorgemerkt'

new_edition: 'vergriffen --> siehe Neuauflage'

available_without_vlb: 'Lieferbar - ohne VLB-Eintrag'

pending: 'in Vorbereitung - Bestellung notiert'

collections
Array of objects

Buchreihen

type
string or null
Enum: "reprint" "print_on_demand" "first_edition" "new_edition" "revised_edition" "non_book" "ebook" "dvd" "video"

Die Art des Buches

Array of objects

Mitwirkende des Titels

object
costs
Array of objects
object
Array of objects
Array of objects
object
object
object
contracts
Array of objects
Array of objects

Responses

Request samples

Content type
application/json
{
  • "id": "string",
  • "legacy_id": 0,
  • "publisher_id": 0,
  • "title": "string",
  • "sub_title": "string",
  • "short_title": null,
  • "isbn10": "string",
  • "isbn13": "string",
  • "ean": "string",
  • "edition": 0,
  • "published_at": "2019-08-24T14:15:22Z",
  • "status": "shortage",
  • "collections": [
    ],
  • "type": "reprint",
  • "contributors": [
    ],
  • "details": {
    },
  • "costs": [
    ],
  • "descriptions": {
    },
  • "files": [
    ],
  • "prices": [
    ],
  • "current_retail_price": {
    },
  • "royalty": {
    },
  • "vlb": {
    },
  • "contracts": [
    ],
  • "stocks": [
    ]
}

Response samples

Content type
application/json
{
  • "message": "Unauthenticated."
}

Lagerbestände

Der stocks Endpunkt dient Ihnen zum Abruf der aktuellen Lagerbestände Ihres Titels.

Lagerbestände abrufen

Ruft eine Lister aller Lagerbestände ab. Mittels der Query Parameter können die Lagerbestände nach Lager, Platz oder auch Buch durchsucht werden.

Authorizations:
bearer
query Parameters
storage_id
number

Lagerbestände nach einem bestimmten Lager filtern

book_id
string

Alle Lagerbestände eines Buches nach Buch-ID abrufen

place
string

Lagerbestände nach Lagerplatz suchen

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Bestellungen

Über diesen Endpunkt haben Sie Zugriff auf alle Bestellungen Ihres Verlages.

Bestellungen abrufen

Ruft eine Liste von Bestellungen ab, die neuesten Bestellungen zuerst. Mittels der Query Parametern können Sie die Bestellungen nach Status, Verlag, Art, Buch oder Kunden filtern.

Die Liste der Bestellungen ist paginated, nach Bestelldatum abwärts sortiert und auf einen Abruf von 50 Bestellungen pro Seite begrenzt.

Authorizations:
bearer
query Parameters
status
string
Enum: "pending" "processing" "completed" "cancelled"

Status der Bestellung

book_id
string

Buch-ID

publisher_id
integer

Verlags-ID

Responses

Response samples

Content type
{}

Bestellung anlegen

Um eine neue Bestellung anzulegen, müssen einige wichtige Daten angegeben werden, welche nachfolgend aufgeschlüsselt sind.

Nachdem eine Bestellung angelegt wurde, erhalten Sie diese noch einmal mit allen Details zurück. Sollten Sie in Ihrem API-Zugang mehrere Verlage verwalten, haben Sie auch die Möglichkeit, Titel verschiedener Verlage zu bestellen. Die Bestellung wird dann aufgeteilt. Daher antwortet die API bei erfolgreichem Speichern mit einem data Array angelegter Bestellungen und deren Details. In diesen Details ist auch die Bestell-ID enthalten, mit der Sie jederzeit den Status der Bestellung abrufen können.

Authorizations:
bearer
Request Body schema: application/json
code
required
string

Das Bestellzeichen Ihrer Bestellung

type
required
string
Enum: "email" "shop" "phone" "fax" "post"

Art der Bestellung

required
object

Angaben zum Besteller

required
object

Rechnungsadresse

required
object

Versandadresse

payment_method_id
required
integer
Enum: 1 3 6 8 9

Zahlungsart:

  • 1: BAG-Einzug: Kunde erhält eine Rechnung und der Betrag wird über die BAG eingezogen
  • 3: Überweisung: Kunde erhält mit der Ware eine Rechnung
  • 6: Vorkasse: Kunde erhält eine Rechnung per E-Mail. Die Ware wird nach bezahlung ausgeliefert
  • 8: PayPal: Betrag wurde bereits mit PayPal bezahlt
  • 9: Stripe: Betrag wurde bereits mit Stripe bezahlt
shipping_method_name
required
string

Name der gewünschten Versandart auf der Rechnung, z.B. "Standard-Versand"

shipping_cost
required
number <float>

Versandkosten, die Sie dem Kunden in Rechnung stellen

required
Array of objects

Bestell-Positionen

delivery_date
string or null <date>

Versanddatum

Achtung: Wenn Sie ein Versanddatum angeben, wird die Bestellung nicht vor dem gewählten Datum ausgeliefert!

notes
string

Notizen zu der Bestellung (nur für interne Zwecke, erscheinen nicht beim Kunden)

created_at
string <date-time>

Bestelldatum

Responses

Request samples

Content type
application/json
{
  • "code": "545515 8884 AAZ",
  • "type": "email",
  • "person": {
    },
  • "payment_address": {
    },
  • "shipping_address": {
    },
  • "delivery_date": "2019-08-24",
  • "payment_method_id": 3,
  • "shipping_method_name": "Standard-Versand",
  • "shipping_cost": 3.5,
  • "items": [
    ]
}

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Bestellung abrufen

Ruft eine einzelne Bestellung mit allen Details ab.

Authorizations:
bearer
path Parameters
orderId
required
string
Example: 76.2944

Die ID der Bestellung

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Versandarten

Die Versandarten sind die verschiedenen Möglichkeiten, wie Sie Ihre Bestellungen an Ihre Kunden versenden können. Sie können bei der Erfassung Ihrer Bestellungen eigene Versandkosten angeben oder auf unsere Versandkostentabelle zurückgreifen. Sollten Sie unsere Versandarten nutzen wollen, geben Sie einer Bestellung bitte die id der Versandart in dem Feld shipping_method_id an. Mehr dazu finden Sie im API-Abschnitt zur Bestellerfassung.

Es gibt verschiedene Arten der Preisberechnung bei den Versandarten:

  • weight - Staffelung nach Gewicht (g): Die Staffelung wird im Feld rates angegeben. Jeder Array-Key gibt das nächste Staffelgewicht an, der Array-Value den Netto-Preis.
  • fixed - Versandkostenpauschale: Der Preis wird im Feld price angegeben und ist unabängig vom Gewicht.
  • linear - Preis je Kilogramm: Der Preis wird im Feld price angegeben und wird pro angefangenem Kilogramm berechnet.

Versandarten abrufen

Authorizations:
bearer

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]