BlotPrints API

Al onze producten kun je bestellen via onze API. Gemaakt voor developers en voor AI-agents.

Introductie

De basis-URL is:

https://www.blotprints.com/api/v1

• Requests en responses zijn JSON (Content-Type: application/json).
• Je hebt geen API-key nodig. Per IP-adres geldt een limiet op het aantal calls (zie Limieten).
• Datums en tijden zijn in ISO 8601, in UTC, zoals 2026-10-25T12:00:00Z.
• Er is geen testmodus: een offerte is gratis en verandert niets, en een bestelling wordt pas echt als hij betaald is.

Voorbeeldbestelling

Een hardcover boek bestellen uit pdf’s die online staan.

1. Vraag een offerte aan

curl -X POST https://www.blotprints.com/api/v1/quotes \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{
      "product": "hardcover",
      "size": "a5-portrait",
      "options": { "cover": "matte", "paper": "matte_standard" },
      "quantity": 1,
      "files": {
        "interior": { "url": "https://example.com/book-interior.pdf" },
        "cover": { "url": "https://example.com/book-cover.pdf" }
      }
    }],
    "shipping": { "country": "NL", "method": "standard" }
  }'

2. Plaats de bestelling, met de quoteId uit het antwoord. Heeft de offerte waarschuwingen, zet er dan "acceptWarnings": true bij (zie 3. Offerte aanvragen).

curl -X POST https://www.blotprints.com/api/v1/orders \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f1c2d3e-my-unique-key" \
  -d '{
    "quoteId": "quo_8hQ2kV7xLm3pR9tY",
    "acceptTerms": true,
    "email": "[email protected]",
    "shippingAddress": {
      "name": "Jane Doe",
      "line1": "Keizersgracht 123",
      "postalCode": "1015 CJ",
      "city": "Amsterdam",
      "country": "NL"
    }
  }'

3. Betaal de bestelling: open de paymentUrl uit het antwoord in een browser.

Een bestelling plaatsen

1. Product kiezen

In de producten zie je wat je kunt bestellen: per product de formaten, opties en prijzen, en welke bestanden we nodig hebben. Gebruik de namen die je hier vindt (product, size, de waarden van de opties) in je offerte.

Alle producten

GET https://www.blotprints.com/api/v1/products

Alles wat je kunt bestellen, met formaten, opties en prijzen.

{
  "products": [
    {
      "product": "hardcover",
      "name": "Hardcover book",
      "sizes": [
        {
          "size": "a5-portrait",
          "width": 148,
          "height": 210,
          "pages": { "min": 24, "max": 400, "step": 2 },
          "files": {
            "interior": { "fileTypes": ["pdf"], "width": 154, "height": 216, "bleed": 3 },
            "cover": { "fileTypes": ["pdf", "jpg", "png"], "width": 354, "height": 255, "bleed": 19 }
          },
          "price": { "base": 15.99, "perExtraPage": 0.40 },
          "options": {
            "cover": {
              "values": [
                { "value": "matte", "name": "Hardcover matte", "price": 5.99 },
                { "value": "glossy", "name": "Hardcover glossy", "price": 0 }
              ],
              "default": "matte"
            },
            "paper": {
              "values": [
                { "value": "matte_standard", "name": "Standard matte", "price": 0, "perExtraPage": 0 },
                { "value": "matte_heavy", "name": "Heavy matte", "price": 1.44, "perExtraPage": 0.07 }
              ],
              "default": "matte_standard"
            }
          }
        },
        {
          "size": "a5-landscape",
          "width": 210,
          "height": 148,
          "pages": { "min": 24, "max": 400, "step": 2 },
          "files": {
            "interior": { "fileTypes": ["pdf"], "width": 216, "height": 154, "bleed": 3 },
            "cover": { "fileTypes": ["pdf", "jpg", "png"], "width": 470, "height": 193, "bleed": 19 }
          },
          "price": { "base": 15.99, "perExtraPage": 0.40 },
          "options": {
            "cover": {
              "values": [
                { "value": "matte", "name": "Hardcover matte", "price": 5.99 },
                { "value": "glossy", "name": "Hardcover glossy", "price": 0 }
              ],
              "default": "matte"
            },
            "paper": {
              "values": [
                { "value": "matte_standard", "name": "Standard matte", "price": 0, "perExtraPage": 0 },
                { "value": "matte_heavy", "name": "Heavy matte", "price": 1.44, "perExtraPage": 0.07 }
              ],
              "default": "matte_standard"
            }
          }
        }
      ]
    }
  ]
}

Eén product

GET https://www.blotprints.com/api/v1/products/{product}

Hetzelfde als één product uit de lijst.

2. Bestanden toevoegen

Je bestanden zijn wat we drukken: het ontwerp van een poster of paneel, of het binnenwerk en de omslag van een boek, als pdf, jpg of png. Welke bestanden een formaat nodig heeft, staat in zijn files (zie 1. Product kiezen). Elk bestand kun je op twee manieren aanleveren: als link waar wij het downloaden, of door het naar ons te uploaden.

Downloadlink

Geef een URL op die we kunnen downloaden, met https. Handig voor bestanden die al online staan.

{ "url": "https://example.com/book-interior.pdf" }

De link moet werken zonder in te loggen op het moment dat je de offerte aanvraagt: dan downloaden we het bestand. Links die na een tijdje verlopen (zoals presigned links van een opslagdienst) zijn prima.

Een bestand uploaden

Voor bestanden op je eigen computer (of die van een agent) vraag je een uploadadres aan, en stuur je het bestand daarheen.

POST https://www.blotprints.com/api/v1/uploads

Je hoeft geen body mee te sturen. Het antwoord:

{
  "uploadId": "upl_3vN8qR2xKt5mW7yZ",
  "uploadUrl": "https://…",
  "expiresAt": "2026-10-25T14:30:00Z"
}

Stuur dan het bestand:

curl -T book-interior.pdf "<uploadUrl>"

En gebruik de upload in je offerte:

{ "uploadId": "upl_3vN8qR2xKt5mW7yZ" }

• Bestandstypen: pdf, jpg en png, voor zover het product ze toestaat. We kijken naar wat er echt in het bestand zit, niet naar de naam of extensie: al het andere weigeren we (unsupported_file_type).
• Maximaal 200 MB per bestand.
• Een upload die we weigeren (een ander type, of te groot) verwijderen we meteen: upload dan het juiste bestand opnieuw.
• Een uploadadres werkt een uur; een upload bewaren we een dag.

3. Offerte aanvragen

Een offerte is de stap vóór een bestelling: je stuurt wat je wilt laten drukken, met de bestanden, en wij controleren de bestanden en vertellen je wat het kost, inclusief verzending. Er is dan nog niets besteld of betaald. Ziet het er goed uit, dan plaats je de bestelling met de offerte.

POST https://www.blotprints.com/api/v1/quotes

{
  "items": [
    {
      "product": "poster",
      "size": "a3-landscape",
      "options": { "paper": "matte", "hanging": "photo_frame_black" },
      "quantity": 2,
      "files": { "design": { "uploadId": "upl_3vN8qR2xKt5mW7yZ" } }
    }
  ],
  "shipping": { "country": "NL", "method": "standard" }
}

Het antwoord:

{
  "quoteId": "quo_8hQ2kV7xLm3pR9tY",
  "expiresAt": "2026-10-26T12:00:00Z",
  "previewUrl": "https://www.blotprints.com/preview/quo_8hQ2kV7xLm3pR9tY",
  "items": [
    {
      "product": "poster",
      "size": "a3-landscape",
      "options": { "paper": "matte", "hanging": "photo_frame_black" },
      "quantity": 2,
      "unitPrice": 25.98,
      "price": 51.96,
      "vat": 9.02,
      "warnings": [
        {
          "code": "design_adjusted",
          "file": "design",
          "message": "The design is a different size or shape than the size needs. We zoom it in to fit, so 9.1% is cut off at the edges. Check the preview.",
          "values": { "cutOffPercent": 9.1 }
        }
      ],
      "previews": [
        {
          "file": "design",
          "url": "https://www.blotprints.com/api/v1/quotes/quo_8hQ2kV7xLm3pR9tY/previews/0-design.jpg",
          "width": 1200,
          "height": 853,
          "description": "The design as it's printed. The red line is where it's cut."
        }
      ]
    }
  ],
  "shipping": {
    "method": "standard",
    "price": 5.00,
    "vat": 0.87,
    "estimatedDelivery": { "from": "2026-10-28", "to": "2026-10-29" },
    "note": null
  },
  "shippingOptions": [
    {
      "method": "standard",
      "price": 5.00,
      "vat": 0.87,
      "estimatedDelivery": { "from": "2026-10-28", "to": "2026-10-29" }
    },
    {
      "method": "express",
      "price": 12.50,
      "vat": 2.17,
      "estimatedDelivery": { "from": "2026-10-27", "to": "2026-10-27" }
    }
  ],
  "total": 56.96,
  "vat": 9.89,
  "currency": "EUR",
  "termsUrl": "https://www.blotprints.com/terms"
}

Een bestand dat we niet kunnen drukken (verkeerd type, te weinig pagina’s, onleesbaar) geeft een foutmelding: de offerte mislukt met 422, en problems noemt elk probleem van elk bestand, zodat je ze in één keer kunt oplossen. Zie Foutmeldingen.

Een offerte kun je één keer bestellen. Voor een volgende bestelling vraag je een nieuwe offerte aan.

4. Bestelling plaatsen

Een bestelling is een offerte die je hebt besloten te kopen, met het adres waar hij heen moet. Je krijgt een betaallink: zodra er betaald is, drukken en versturen we hem, en kun je de status volgen tot hij aankomt.

POST https://www.blotprints.com/api/v1/orders

{
  "quoteId": "quo_8hQ2kV7xLm3pR9tY",
  "acceptTerms": true,
  "acceptWarnings": true,
  "reference": "SHOP-2026-0042",
  "email": "[email protected]",
  "shippingAddress": {
    "name": "Jane Doe",
    "line1": "Keizersgracht 123",
    "line2": "",
    "postalCode": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL"
  }
}

Het antwoord (201):

{
  "orderId": "1042-x7Kq2mV9pL4tR8wN3bY6zA",
  "reference": "SHOP-2026-0042",
  "status": "awaiting_payment",
  "paymentUrl": "https://www.blotprints.com/pay/1042-x7Kq2mV9pL4tR8wN3bY6zA",
  "total": 56.96,
  "currency": "EUR"
}

5. Betalen

Open de paymentUrl in een browser. Daar staat de bestelling, en wordt er gevraagd om te betalen (iDEAL, kaart en de andere betaalmethoden van het land). Zodra er betaald is, gaan we drukken. Een bestelling die niet binnen 7 dagen betaald is, vervalt.

6. Bestelling volgen

GET https://www.blotprints.com/api/v1/orders/{orderId}

{
  "orderId": "1042-x7Kq2mV9pL4tR8wN3bY6zA",
  "reference": "SHOP-2026-0042",
  "status": "shipped",
  "createdAt": "2026-10-25T12:00:00Z",
  "paidAt": "2026-10-25T12:05:00Z",
  "items": [
    {
      "product": "poster",
      "size": "a3-landscape",
      "options": { "paper": "matte", "hanging": "photo_frame_black" },
      "quantity": 2,
      "unitPrice": 25.98,
      "price": 51.96,
      "vat": 9.02
    }
  ],
  "shipping": {
    "method": "standard",
    "price": 5.00,
    "vat": 0.87,
    "trackingUrl": "https://…"
  },
  "shippingAddress": {
    "name": "Jane Doe",
    "line1": "Keizersgracht 123",
    "line2": "",
    "postalCode": "1015 CJ",
    "city": "Amsterdam",
    "country": "NL"
  },
  "total": 56.96,
  "vat": 9.89,
  "currency": "EUR",
  "paymentUrl": null
}

status is een van:

Naslag

Foutmeldingen

Een foutmelding heeft een HTTP-status en een body zoals deze:

{
  "error": {
    "code": "file_check_failed",
    "message": "The interior has 18 pages. It needs at least 24. The cover isn't a file type we print.",
    "item": 0,
    "file": "interior",
    "problems": [
      {
        "item": 0,
        "file": "interior",
        "code": "too_few_pages",
        "message": "The interior has 18 pages. It needs at least 24.",
        "values": { "pageCount": 18, "min": 24 }
      },
      {
        "item": 0,
        "file": "cover",
        "code": "unsupported_file_type",
        "message": "The cover isn't a file type we print."
      }
    ]
  }
}

Idempotentie

Netwerken haperen, en scripts en agents proberen het dan opnieuw. Om zeker te weten dat een bestelling nooit twee keer geplaatst wordt, stuur je bij POST /orders een Idempotency-Key-header mee: een willekeurige unieke tekst, zoals een UUID.

Stuur je binnen 24 uur dezelfde key nog eens, dan krijg je dezelfde bestelling terug in plaats van een nieuwe. Gebruik voor elke nieuwe bestelling een nieuwe key.

Limieten

Per IP-adres:

Kom je boven een limiet, dan krijg je 429 met een Retry-After-header: het aantal seconden dat je moet wachten.

Voor AI-agents

Deze documentatie staat ook als platte Markdown op /api/docs.md, in het Engels: lees die om de API te leren kennen. AI-tools vinden hem ook via /llms.txt, met de tips hieronder.

MCP-server. AI-assistenten die het Model Context Protocol ondersteunen (Claude, ChatGPT, Copilot, …) kunnen BlotPrints toevoegen als connector, op:

https://www.blotprints.com/mcp

Inloggen is niet nodig. De assistent krijgt dan de stappen van deze pagina als tools: list_products, get_product, create_upload, get_quote, place_order en get_order.

OpenAPI. De API is ook beschreven in OpenAPI 3.1, op /api/openapi.json: voor tools die dat lezen, zoals codegenerators of de actions van een custom GPT.

Tips voor agents:

• Begin met GET /products om te zien wat er kan, en kies formaten en opties daaruit: gok geen namen.
• Gebruik voor bestanden op de computer van de gebruiker een upload: curl -T bestand.pdf "<uploadUrl>".
• Laat de gebruiker het voorbeeld van de offerte (previewUrl), de prijs, de waarschuwingen en de voorwaarden (termsUrl) zien voordat je de bestelling plaatst, en vraag of het voorbeeld klopt.
• Geef de gebruiker de paymentUrl om te betalen: zelf betalen kun je niet.
• Bewaar de orderId, om de bestelling later op te vragen.

Veelgestelde vragen