API docs by Redocly

BoekwinkeltjesVerkoperApi (2.4)

Download OpenAPI specification:

Boekwinkeltjes: info@boekwinkeltjes.nl URL: boekwinkeltjes.nl

API voor Boekwinkeltjes.nl

Test omgeving (endpoint): https://api-zandbak.boekwinkeltjes.nl/webservice/v1/

Live omgeving (endpoint): https://www.boekwinkeltjes.nl/webservice/v1/

  • Requests zijn rate-limited
  • De API en configuratie worden gebouwd in boekwinkeltjes.nl
  • Boeken die worden toegevoegd/gewijzigd/gedelete worden in een queue gezet en verwerkt door de uploadfunctie
  • Boeken via bestaande IdentityMap
  • webhook melding bij betaling

orders

Get orders

Retrieve all orders

Authorizations:
api-key
query Parameters
page
number >= 0
Example: page=1

Page number

query
string

Search query

sort
string
Example: sort=+title

Sorting

status
string

Filter the orders on status

Responses

Response samples

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

Create order

Create new order

Authorizations:
api-key

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Get single order

Get single order

Authorizations:
api-key
path Parameters
orderId
required
string

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Patch order

Patch single order

Authorizations:
api-key
path Parameters
orderId
required
string
Request Body schema: application/json
status
string
Enum: "new_order" "wait_for_customer" "wait_for_payment" "wait_for_shipping" "wait_for_pickup" "shipped_wait_for_payment" "shipped_paid" "picked_up_paid" "sold_or_unavailable" "no_response" "paymentlink_mailed" "return_received" "lost_in_transit"
onlinePaymentStatus
string
Enum: "paid" "open" "refunded"
object (Book)

Book model

object (Buyer)

Buyer model

Responses

Request samples

Content type
application/json
{
  • "status": "new_order",
  • "onlinePaymentStatus": "paid",
  • "book": {
    },
  • "buyer": {
    }
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

books

Retrieve books

Get all books

Authorizations:
api-key
query Parameters
page
number >= 0
Example: page=1

Page number

per_page
integer [ 1 .. 500 ]
Default: 25

Number of books per page (default 25, values above 500 are capped at 500)

query
string

Search query

location
string

Book storage location (the plaats field, e.g. a shelf/box code); matched with a partial LIKE

for-sale-since-type
integer
Enum: 0 1 2

0 = before, 1 = after, 2 = on

for-sale-since
string <date>

Date

status
integer
Enum: 0 1 2

0 = all, 1 = available, 2 = sold

language
string = 2 characters
Example: language=NL

Country code

image
string
Enum: "0" "1" "2"

0 = all, 1 = without image, 2 = with image

price-from
number

from price

price-to
string

to price

Responses

Response samples

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

Add book

Add new book

Authorizations:
api-key
Request Body schema: application/json

Add book response body

bookNumber
integer
location
string
amount
integer
category1
string
Enum: "overig diverse" "detectives" "geschiedenis" "hobby" "kinderboeken" "literatuur" "literaire thriller" "psychologische thriller" "kunst" "romans" "jeugdroman" "science fiction fantasy" "strips" "studieboeken" "topografie" "toneel"
category2
string
category3
string
language
string
author
string
title
string
publisher
string
ean
number
shortDescription
string
longDescription
string
price
number <float> [ 0 .. 99999 ]
shippingCost
number <float> [ -1 .. 99999 ]
shippingCategory
integer
date
string
weblink
string

Responses

Request samples

Content type
application/json
{
  • "id": 1,
  • "bookNumber": 213124124124,
  • "location": "bw-doos 5",
  • "amount": 4,
  • "category1": "detectives",
  • "category2": "horror",
  • "category3": "avontuurlijk",
  • "language": "NL",
  • "author": "Beatles, The",
  • "title": "Let It Be",
  • "publisher": "string",
  • "ean": 1234567891234,
  • "shortDescription": "This is a short description",
  • "longDescription": "This is a long description, lorem ipsum dolor sit amet",
  • "price": 10.99,
  • "shippingCost": 6.99,
  • "shippingCategory": 1,
  • "date": "2023-05-22 11:45:22",
  • "weblink": "https://www.boekwinkeltjes.nl/b/202593063/De-cursus-Omgaan-met-teleurstellingen",
  • "imageurl": "https://www.images.nl/myimage"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Get book by id

Get single book

Authorizations:
api-key
path Parameters
bookId
required
integer <int32> >= 0
Example: 1

id of book

query Parameters
type
string
Default: "bookId"
Enum: "bookId" "bookNumber"

Type of id

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Patch book by id

Patch single book

Authorizations:
api-key
path Parameters
bookId
required
integer <int32> >= 0
Example: 1

id of book

Request Body schema: application/json

Add book response body

bookNumber
integer
location
string
amount
integer
category1
string
Enum: "overig diverse" "detectives" "geschiedenis" "hobby" "kinderboeken" "literatuur" "literaire thriller" "psychologische thriller" "kunst" "romans" "jeugdroman" "science fiction fantasy" "strips" "studieboeken" "topografie" "toneel"
category2
string
category3
string
language
string
author
string
title
string
publisher
string
ean
number
shortDescription
string
longDescription
string
price
number <float> [ 0 .. 99999 ]
shippingCost
number <float> [ -1 .. 99999 ]
shippingCategory
integer
date
string
weblink
string

Responses

Request samples

Content type
application/json
{
  • "id": 1,
  • "bookNumber": 213124124124,
  • "location": "bw-doos 5",
  • "amount": 4,
  • "category1": "detectives",
  • "category2": "horror",
  • "category3": "avontuurlijk",
  • "language": "NL",
  • "author": "Beatles, The",
  • "title": "Let It Be",
  • "publisher": "string",
  • "ean": 1234567891234,
  • "shortDescription": "This is a short description",
  • "longDescription": "This is a long description, lorem ipsum dolor sit amet",
  • "price": 10.99,
  • "shippingCost": 6.99,
  • "shippingCategory": 1,
  • "date": "2023-05-22 11:45:22",
  • "weblink": "https://www.boekwinkeltjes.nl/b/202593063/De-cursus-Omgaan-met-teleurstellingen",
  • "imageurl": "https://www.images.nl/myimage"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Delete book by id

Delete single book

Authorizations:
api-key
path Parameters
bookId
required
integer <int32> >= 0
Example: 1

id of book

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": { }
}

images

Get images for single book

Get images for single book

Authorizations:
api-key
path Parameters
bookId
required
integer <int32> >= 0
Example: 1

id of book

Responses

Response samples

Content type
application/json
{}

Add images to single book

Upload image (jpeg/png)

Authorizations:
api-key
path Parameters
bookId
required
integer <int32> >= 0
Example: 1

id of book

Request Body schema: image/*
string <binary>

Responses

Request samples

Content type
image/*
No sample

Response samples

Content type
application/json
{
  • "status": 201,
  • "data": { }
}

Add images to single book

Upload image url

Authorizations:
api-key
path Parameters
bookId
required
integer <int32> >= 0
Example: 1

id of book

Request Body schema: application/json
url
string

Responses

Request samples

Content type
application/json
{
  • "url": "string"
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": { }
}

Delete image by image id

Authorizations:
api-key
path Parameters
imageId
required
string

Responses

packages

Retrieve all packages

Retrieves all packages

Authorizations:
api-key
query Parameters
page
number >= 0
Example: page=1

Page number

orderId
integer >= 1
Example: orderId=4006

Filter packages by order ID. Returns all non-cancelled packages that were created for this order, newest first. The result is always complete, so pagination does not apply when this filter is used.

Responses

Response samples

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

Post new package

Posts new package (all types)

Authorizations:
api-key
Request Body schema: application/json
operator
required
string
Enum: "PostNL" "Dpd" "DHL" "MondialRelay"
packageID
string
type
required
string
Enum: "STANDARD" "MAILBOX" "SMALL"
name
string
required
object (Address)
weight
number
addressType
string
Enum: "P" "B"
email
string
phoneNumber
string
orderId
integer
rate
string
shopID
string <= 20 characters

Pickup point (parcel shop) code of the carrier, to deliver the package to a pickup point instead of a home address. Use the carrier's own code: the Mondial Relay relay number, PostNL location code, DHL parcel shop id or DPD parcel shop id. Codes can be looked up via GET /packages/parcel-shops. Required for MondialRelay (those shipments always go to a relay point), optional for the other carriers. When set, phoneNumber and email are required so the carrier can notify the recipient.

deliverySpeed
string
Default: "standard"
Enum: "standard" "prio"

PostNL brievenbus (type MAILBOX) only. 'prio' selects priority delivery (24h) with a surcharge; 'standard' is regular delivery (24-48h). Ignored for other operators or package types.

printOptions
integer
Enum: 0 1

DHL only (required for DHL). 1 = print the shipping label yourself (the label is a PDF); 0 = printless: the label is a QR-code image (image/png) that is scanned at the DHL parcel point.

Responses

Request samples

Content type
application/json
Example
{
  • "operator": "Dpd",
  • "packageID": "string",
  • "type": "SMALL",
  • "name": "Hans Pieterson",
  • "address": {
    },
  • "weight": 500,
  • "addressType": "P",
  • "email": "email@boekwinkeltjes.nl",
  • "phoneNumber": "+31612345678",
  • "orderId": 4006,
  • "rate": "2500",
  • "shopID": "2224234",
  • "printOptions": 1
}

Response samples

Content type
application/json
{
  • "status": 201,
  • "data": {
    }
}

Get single package

Get package by ID

Authorizations:
api-key
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "operator": "Dpd",
  • "packageID": "string",
  • "type": "SMALL",
  • "name": "Hans Pieterson",
  • "address": {
    },
  • "weight": 500,
  • "addressType": "P",
  • "email": "email@boekwinkeltjes.nl",
  • "phoneNumber": "+31612345678",
  • "orderId": 4006,
  • "rate": "2500",
  • "shopID": "2224234",
  • "printOptions": 1
}

Delete package

Delete a package by ID

Authorizations:
api-key
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": { }
}

Get shipping label

Retrieves the shipping label of a package as base64-encoded file content. Usually this is a PDF (contentType application/pdf); for DHL shipments with the printless option the label is a QR-code image (contentType image/png) that the sender scans at the DHL parcel point. Returns 404 when no label is available, e.g. because the carrier could not create one or the package was cancelled. The same label object is also included directly in the POST /packages response.

Authorizations:
api-key
path Parameters
packageId
required
integer

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Track package

Track package by package ID

Authorizations:
api-key
path Parameters
packageId
required
integer

Responses

Response samples

Content type
application/json
{
  • "packageID": 1234,
  • "operator": "PostNL",
  • "barcode": "3SABCD1234567",
  • "trackingUrl": "https://jouw.postnl.nl/track-and-trace/3SABCD1234567-nl-7654AA",
  • "statusName": "In transportation",
  • "statusHistory": [
    ]
}

Find parcel shops

Finds pickup points (parcel shops) of a carrier near a zip code. Results are retrieved live from the carrier, closest first. The returned shopID values can be used directly in the shopID field of POST /packages.

Authorizations:
api-key
query Parameters
operator
required
string
Enum: "PostNL" "Dpd" "DHL" "MondialRelay"

Carrier to search pickup points for

zip
required
string
Example: zip=7654AA

Zip code to search around

country
required
string
Example: country=NL

Uppercase ISO country code; must be a country the carrier ships to

city
string
Example: city=Nijverdal

Optional, improves the location search for some carriers

type
string
Default: "STANDARD"
Enum: "STANDARD" "MAILBOX" "SMALL"

Package type the shipment will use

limit
integer [ 1 .. 25 ]
Default: 3

Maximum number of pickup points to return

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Get Package Rates

Retrieve shipping costs from every operator

Authorizations:
api-key

Responses

Post Package Rate

Post Package rate

Authorizations:
api-key
Request Body schema: application/json
operator
required
string
Enum: "PostNL" "Dpd" "DHL" "MondialRelay"
packageID
string
type
required
string
Enum: "STANDARD" "MAILBOX" "SMALL"
name
string
required
object (Address)
weight
number
addressType
string
Enum: "P" "B"
email
string
phoneNumber
string
orderId
integer
rate
string
shopID
string <= 20 characters

Pickup point (parcel shop) code of the carrier, to deliver the package to a pickup point instead of a home address. Use the carrier's own code: the Mondial Relay relay number, PostNL location code, DHL parcel shop id or DPD parcel shop id. Codes can be looked up via GET /packages/parcel-shops. Required for MondialRelay (those shipments always go to a relay point), optional for the other carriers. When set, phoneNumber and email are required so the carrier can notify the recipient.

deliverySpeed
string
Default: "standard"
Enum: "standard" "prio"

PostNL brievenbus (type MAILBOX) only. 'prio' selects priority delivery (24h) with a surcharge; 'standard' is regular delivery (24-48h). Ignored for other operators or package types.

printOptions
integer
Enum: 0 1

DHL only (required for DHL). 1 = print the shipping label yourself (the label is a PDF); 0 = printless: the label is a QR-code image (image/png) that is scanned at the DHL parcel point.

Responses

Request samples

Content type
application/json
Example
{
  • "operator": "Dpd",
  • "packageID": "string",
  • "type": "SMALL",
  • "name": "Hans Pieterson",
  • "address": {
    },
  • "weight": 500,
  • "addressType": "P",
  • "email": "email@boekwinkeltjes.nl",
  • "phoneNumber": "+31612345678",
  • "orderId": 4006,
  • "rate": "2500",
  • "shopID": "2224234",
  • "printOptions": 1
}

payments

Get payments

Retrieves a list of all payments including their status and metadata.

Authorizations:
api-key

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Get payment details

Retrieves detailed information about a single payment by its ID.

Authorizations:
api-key
path Parameters
id
required
integer

ID of the payment

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Refund a payment

Initiates a refund for the payment with the specified ID.

Authorizations:
api-key
path Parameters
id
required
integer

ID of the payment to refund

Request Body schema: application/json
required
reason
required
string

Explanation for the refund

Responses

Request samples

Content type
application/json
{
  • "reason": "string"
}

Response samples

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

settings

Get settings

Authorizations:
api-key

Responses

Response samples

Content type
application/json
No sample

shipping-fees

Get shipping fees

Authorizations:
api-key

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Update shipping fee settings

Wijzigt de verzendkosten-instellingen van de verkoper.

  • type: none — geen verzendkosten; alle bestaande boeken worden omgezet naar € 0,00.
  • type: fixed — vast bedrag voor alle boeken; geef fee op, of free: true voor gratis verzending. Alle bestaande boeken worden omgezet naar het nieuwe bedrag.
  • type: variable — verzendkosten per categorie; beheer de categorieën daarna via POST /shipping-fees, PATCH /shipping-fees/{id} en DELETE /shipping-fees/{id}.

Het omzetten van bestaande boeken gebeurt door een achtergrondtaak. Het doorvoeren van veranderingen kan tot 5 uur nadat u een aanpassing heeft gedaan duren, dit is afhankelijk van het aantal boeken dat u heeft.

Authorizations:
api-key
Request Body schema: application/json
required
type
required
string
Enum: "none" "fixed" "variable"
fee
number <float> >= 0.01

Vast verzendkostenbedrag, verplicht bij type fixed (tenzij free true is)

free
boolean

Gratis verzending, alleen bij type fixed

Responses

Request samples

Content type
application/json
Example
{
  • "type": "fixed",
  • "fee": 4.95
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Add variable shipping fee category

Voegt een variabele verzendkostencategorie toe. Alleen mogelijk wanneer het verzendkostentype variable is (zie PUT /shipping-fees).

Geef fee op, of free: true voor een categorie met gratis verzending. Een bedrag van 0,00 of een bedrag dat al bij een andere categorie hoort is niet toegestaan.

Authorizations:
api-key
Request Body schema: application/json
required
name
required
string [ 1 .. 100 ] characters
fee
number <float> >= 0.01

Verplicht tenzij free true is

free
boolean

Gratis verzending voor deze categorie

Responses

Request samples

Content type
application/json
{
  • "name": "Brievenbuspakje",
  • "fee": 4.25
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Get shipping fee by Id

Authorizations:
api-key
path Parameters
id
required
integer
query Parameters
type
string
Enum: "bookId" "shippingId"

Which type of id

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Update variable shipping fee category

Wijzigt het bedrag van een variabele verzendkostencategorie. Alleen mogelijk wanneer het verzendkostentype variable is.

Met applyToExistingBooks: true worden ook de bestaande boeken in deze categorie omgezet naar het nieuwe bedrag. Dat gebeurt door een achtergrondtaak; het doorvoeren van veranderingen kan tot 5 uur nadat u een aanpassing heeft gedaan duren, dit is afhankelijk van het aantal boeken dat u heeft.

Authorizations:
api-key
path Parameters
id
required
integer
Request Body schema: application/json
required
fee
required
number <float> >= 0.01
applyToExistingBooks
boolean
Default: false

Bestaande boeken in deze categorie omzetten naar het nieuwe bedrag

Responses

Request samples

Content type
application/json
{
  • "fee": 4.5,
  • "applyToExistingBooks": true
}

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}

Delete variable shipping fee category

Verwijdert een variabele verzendkostencategorie. Alleen mogelijk wanneer het verzendkostentype variable is.

Met de queryparameter mergeInto worden de bestaande boeken in de verwijderde categorie omgezet naar de opgegeven categorie. Dat gebeurt door een achtergrondtaak; het doorvoeren van veranderingen kan tot 5 uur nadat u een aanpassing heeft gedaan duren, dit is afhankelijk van het aantal boeken dat u heeft. Zonder mergeInto behouden de boeken hun huidige verzendkosten.

Authorizations:
api-key
path Parameters
id
required
integer
query Parameters
mergeInto
integer

Id van de categorie waar de boeken uit de verwijderde categorie naartoe moeten

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": { }
}

questions

Get questions

Authorizations:
api-key

Responses

Response samples

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

Get question by id

Authorizations:
api-key
path Parameters
id
required
string

Responses

Response samples

Content type
application/json
{
  • "status": 200,
  • "data": {
    }
}