API docs by Redocly

BoekwinkeltjesVerkoperApi (2.8)

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 (per API-key). Boven de limiet volgt een 429 met een Retry-After-header. Het bestellingenoverzicht (GET /orders) mag 1x per 5 minuten per URL worden opgehaald, een losse bestelling (GET /orders/{orderId}) 1x per half uur. Gebruik voor nieuwe bestellingen en betalingen de webhook in plaats van pollen.
  • 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 nieuwe bestellingen, betalingen en berichten, zie het hoofdstuk webhook onderaan

orders

Get orders

Retrieve all orders. Rate limit: at most 1 request per 5 minutes per URL (so per combination of query, sort and status). Do not poll this endpoint for new orders, use the webhook instead.

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. Rate limit: at most 1 request per 30 minutes per order. New orders and payment updates are announced through the webhook, do not poll this endpoint.

Authorizations:
api-key
path Parameters
orderId
required
string

Responses

Response samples

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

Update order status

Changes the status of an order. Only status can be changed; other fields in the request body are ignored, so sending a complete Order object with a modified status also works.

The change is written to the status log of the order, like a status change in Mijn Boekwinkeltjes. Setting no_response cancels the order and makes the book available again (its amount is increased by one); changing a cancelled order to another status reverses that.

Authorizations:
api-key
path Parameters
orderId
required
string
Request Body schema: application/json
required
status
required
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" "return_received" "lost_in_transit" "sold_or_unavailable" "no_response"

The new status. webshop_order and paymentlink_mailed are set by the system and cannot be set here.

Responses

Request samples

Content type
application/json
{
  • "status": "shipped_paid"
}

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
shippingFormat
integer or null
Enum: 0 1 2 3 4
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,
  • "shippingFormat": 2,
  • "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
shippingFormat
integer or null
Enum: 0 1 2 3 4
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,
  • "shippingFormat": 2,
  • "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/avif) as raw request body; the Content-Type header must match the image type.

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. Printless adds a surcharge of € 0.10 (incl. VAT) to the shipping rate.

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. Printless adds a surcharge of € 0.10 (incl. VAT) to the shipping rate.

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": {
    }
}

webhook

Boekwinkeltjes kan je koppeling actief op de hoogte brengen van nieuwe bestellingen, afgeronde betalingen en nieuwe berichten. Gebruik de webhook in plaats van het periodiek ophalen van GET /orders: de webhook is sneller en de orders-endpoints zijn rate-limited.

Inschakelen. Geef je webhook-URL (https) door aan data@boekwinkeltjes.nl. Wij koppelen die aan je API-key. De ingestelde URL en het tijdstip van de laatste geslaagde melding zie je in Mijn Boekwinkeltje → Mijn gegevens en in GET /settings (webhookUrl).

Wat wij sturen. Een POST naar jouw URL met Content-Type: application/json en dit body:

{"object": "Order", "status": "new", "identifier": 123456, "bwID": 1234}
object status Wanneer identifier
Order new Een koper heeft een bestelling geplaatst Het bestelnummer, ophalen met GET /orders/{orderId}
Payment update Een online betaling is voltooid of terugbetaald Het betalings-id, ophalen met GET /payments/{id}
Message new Een koper stuurde een bericht terwijl je niet online was in het berichtencentrum Het bericht-id in het berichtencentrum (nog niet via de API op te halen)

bwID is altijd je eigen boekwinkelnummer. De melding bevat alleen deze vier velden, geen bestel- of betaalgegevens: haal die na ontvangst op met het genoemde endpoint. Voor een betaling kijk je naar status in het antwoord van GET /payments/{id} (3 = voltooid, 7 = terugbetaald).

Afleveren. De melding wordt via een wachtrij verstuurd en komt meestal binnen enkele seconden na de gebeurtenis aan. Antwoord met een HTTP-status 2xx, bij voorkeur direct en zonder zware verwerking in het request. Er is geen handtekening, authenticatie of herhaalde poging: controleer zelf of bwID jouw nummer is en gebruik een URL die niet te raden is. Een melding die bij jou niet aankomt wordt niet opnieuw aangeboden. Haal daarom bij het opstarten van je koppeling, of hooguit een paar keer per dag, GET /orders?status=new_order op als vangnet.

Webhook notification Webhook

Sent by Boekwinkeltjes to the webhook URL configured for your API key, with Content-Type: application/json. The body only identifies the object; fetch the details with GET /orders/{orderId} or GET /payments/{id}. Respond with a 2xx status. There is no signature and no retry, see the description of this section.

Authorizations:
api-key
Request Body schema: application/json
required
object
required
string
Enum: "Order" "Payment" "Message"

What the notification is about

status
required
string
Enum: "new" "update"

new for an Order or Message, update for a Payment (completed or refunded)

identifier
required
integer

Id of the object: the order id for Order (GET /orders/{orderId}), the payment id for Payment (GET /payments/{id}), the message id in the message centre for Message

bwID
required
integer

Your own Boekwinkeltjes seller number

Responses

Request samples

Content type
application/json
Example
{
  • "object": "Order",
  • "status": "new",
  • "identifier": 123456,
  • "bwID": 1234
}