De API: bestellen vanuit je eigen systeem

Hoe maak en beheer je een API-sleutel?

Elke aanroep van de API gebruikt een sleutel. Er zijn twee soorten: een live sleutel (begint met prk_live_) plaatst echte orders die worden afgerekend en geproduceerd, een testsleutel (begint met prk_test_) werkt in de sandbox: orders worden aangemaakt, maar niets wordt afgerekend of geproduceerd.

1. 1

   Open het tabblad

   Ga in je dashboard naar API-sleutels.

2. 2

   Geef de sleutel een naam

   Vul bij Naam van de sleutel een herkenbare naam in, bijvoorbeeld de naam van je webshop of server. Zo weet je later welke sleutel waar gebruikt wordt.

3. 3

   Kies test of live

   Vink Testsleutel aan voor een sandboxsleutel (prk_test_). Laat het vakje leeg voor een live sleutel (prk_live_). Kies daarna bij Rechten (scopes) wat de sleutel mag; laat je alles aangevinkt, dan heeft hij alle rechten.

4. 4

   Maak de sleutel

   Klik op Sleutel maken. De volledige sleutel verschijnt één keer, met de melding Kopieer deze sleutel nu. Je ziet hem maar één keer.

5. 5

   Kopieer en bewaar hem

   Klik op Kopiëren en zet de sleutel direct op een veilige plek, zoals een omgevingsvariabele op je server of een wachtwoordkluis. Daarna zie je in de lijst alleen nog het begin van de sleutel en wanneer hij Laatst gebruikt is.

De API kent rechten (scopes) per sleutel. Een sleutel zonder scopes heeft alle rechten. In het dashboard kies je ze bij Rechten (scopes) als je de sleutel maakt. Laat je alles aangevinkt, dan krijgt de sleutel alle rechten, ook rechten die later bijkomen. In de lijst zie je per sleutel welke rechten hij heeft. Wil je de rechten van een sleutel wijzigen, maak dan een nieuwe sleutel en trek de oude in.

Base URL, authenticatie en limieten

• Base URL: https://www.printen.eu/api/reseller/v1. Alle paden in dit artikel zijn relatief daaraan.
• Authenticatie: stuur bij elk verzoek de header Authorization: Bearer prk_live_... of Authorization: Bearer prk_test_....
• Formaat: verzoeken en antwoorden zijn JSON. Een geslaagd antwoord staat altijd in een data-veld; lijsten hebben daarnaast nextCursor om de volgende pagina op te halen.
• Bedragen: altijd in eurocenten. 2873 betekent dus € 28,73.
• Limiet: maximaal 120 verzoeken per minuut per sleutel. Offertes (POST /quotes) en nieuwe orders hebben daarnaast een eigen limiet per account, die voor nieuwe accounts lager is. Elk antwoord bevat RateLimit-Limit, RateLimit-Remaining en RateLimit-Reset (seconden) voor de limiet die het eerst op is. Daarboven krijg je status 429 met een Retry-After-header.
• Specificatie: de volledige OpenAPI-specificatie staat op https://www.printen.eu/reseller-api/openapi.json. Je kunt die importeren in Postman, Insomnia of een codegenerator.

Test je sleutel met een eenvoudige aanroep, bijvoorbeeld het saldo opvragen. Krijg je JSON terug met data, dan werkt je sleutel.

curl https://www.printen.eu/api/reseller/v1/wallet \
  -H "Authorization: Bearer prk_test_..."

Hoe vraag je de catalogus en de opties op?

Met GET /products zoek je in de catalogus. Gebruik q als zoekterm, category voor een categorie, lang voor de taal van namen en opties (nl, en, de of fr), en limit (maximaal 100) en cursor om door de pagina’s te bladeren.

curl "https://www.printen.eu/api/reseller/v1/products?q=poster&lang=nl&limit=5" \
  -H "Authorization: Bearer prk_test_..."

Met het id uit die lijst haal je één product op met alle opties en de bestandseisen.

curl "https://www.printen.eu/api/reseller/v1/products/PRODUCT_ID?lang=nl" \
  -H "Authorization: Bearer prk_test_..."

{
  "data": {
    "id": "PRODUCT_ID",
    "slug": "poster",
    "name": "Poster",
    "options": [
      {
        "key": "size",
        "label": "Formaat",
        "type": "select",
        "values": [
          { "value": "A3", "label": "A3" },
          { "value": "A2", "label": "A2" }
        ]
      }
    ],
    "quantities": [1, 5, 10],
    "fileRequirements": {
      "required": true,
      "formats": ["pdf", "png", "jpg"],
      "minDpi": 300,
      "colorProfile": "CMYK",
      "bleedMm": 3,
      "fileUrlMustBeHttps": true
    }
  }
}

Je eerste offerte: wat kost een order?

Met POST /quotes bereken je de prijs van één of meer regels voor een bestemmingsland, inclusief je korting, verzending en btw. Er wordt niets besteld of afgerekend. Een regel bevat een resellerSku (je eigen product) of een productId met options, plus een quantity.

curl -X POST https://www.printen.eu/api/reseller/v1/quotes \
  -H "Authorization: Bearer prk_test_..." -H "Content-Type: application/json" \
  -d '{"country":"NL","lines":[{"resellerSku":"POSTER-A2","quantity":1}]}'

{
  "data": {
    "lines": [
      {
        "productId": "PRODUCT_ID",
        "productName": "Poster",
        "options": { "size": "A2" },
        "quantity": 1,
        "retailNetCents": 2000,
        "netCents": 1800,
        "resellerProductId": "RESELLER_PRODUCT_ID"
      }
    ],
    "discountPercent": 10,
    "subtotalNetCents": 1800,
    "shippingNetCents": 574,
    "vatRate": 21,
    "vatTreatment": "domestic-business",
    "vatCents": 499,
    "totalCents": 2873,
    "currency": "EUR"
  }
}

Je eerste order plaatsen (met Idempotency-Key)

1. 1

   Kies een unieke sleutel

   Bedenk per order een unieke Idempotency-Key, bij voorkeur je eigen ordernummer (bijvoorbeeld shop-order-1001). Deze header is verplicht.

2. 2

   Stel de regels samen

   Gebruik per regel een resellerSku en een quantity. Heeft je product nog geen ontwerp, stuur dan een fileUrl (https) mee.

3. 3

   Vul de ontvanger in

   Verplicht zijn name, address1, postalCode, city en country (ISO-2, bijvoorbeeld NL). Optioneel: company, email, phone, address2 en state.

4. 4

   Voeg je eigen kenmerken toe

   Met externalOrderId en externalOrderNumber koppel je de order aan je eigen systeem; die komen terug in elke webhook. reference is je eigen kenmerk.

5. 5

   Verstuur het verzoek

   Een nieuwe order geeft status 201. Controleer state in het antwoord: SUBMITTED betekent betaald en onderweg naar productie.

curl -X POST https://www.printen.eu/api/reseller/v1/orders \
  -H "Authorization: Bearer prk_test_..." -H "Content-Type: application/json" \
  -H "Idempotency-Key: shop-order-1001" \
  -d '{"externalOrderId":"1001","lines":[{"resellerSku":"POSTER-A2","quantity":1}],
       "recipient":{"name":"Anna de Vries","address1":"Dorpsstraat 1","postalCode":"1234 AB","city":"Utrecht","country":"NL"}}'

{
  "data": {
    "id": "ORDER_ID",
    "resellerOrderId": "RESELLER_ORDER_ID",
    "orderNumber": "RS-3F9A1C7B2E",
    "state": "SUBMITTED",
    "totalCents": 2873,
    "chargedCents": 0,
    "duplicate": false,
    "test": true
  }
}

Waarom een Idempotency-Key? Netwerken zijn onbetrouwbaar: een time-out betekent niet dat je order niet is aangekomen. Met een Idempotency-Key kun je een verzoek veilig herhalen. Stuur je dezelfde sleutel nog een keer, dan krijg je de bestaande order terug met "duplicate": true en status 200. Er ontstaat nooit een tweede order.

{
  "data": {
    "id": "ORDER_ID",
    "resellerOrderId": "RESELLER_ORDER_ID",
    "orderNumber": "RS-3F9A1C7B2E",
    "state": "SUBMITTED",
    "totalCents": 2873,
    "chargedCents": 0,
    "duplicate": true,
    "test": true
  }
}

• Gebruik één sleutel per order, en altijd dezelfde sleutel als je die order opnieuw probeert.
• Met een bestaande sleutel krijg je altijd de oorspronkelijke order terug, ook als de inhoud van je verzoek anders is. Wil je echt een nieuwe order, gebruik dan een nieuwe sleutel.
• Een sleutel is maximaal 200 tekens (zichtbare ASCII-tekens).
• Live sleutels en testsleutels hebben elk hun eigen verzameling. Een testorder met shop-order-1001 blokkeert dus geen live order met dezelfde sleutel.

Eigen producten beheren via de API

Een eigen product is een catalogusproduct met vaste opties, jouw SKU, je ontwerpbestand, een titel en optioneel je verkoopprijs. Via POST /reseller-products maak je er een aan; daarna bestel je het met resellerSku.

curl -X POST https://www.printen.eu/api/reseller/v1/reseller-products \
  -H "Authorization: Bearer prk_test_..." -H "Content-Type: application/json" \
  -d '{"productId":"PRODUCT_ID","sku":"POSTER-A2-MAT","title":"Poster A2 mat",
       "options":{"size":"A2"},"fileUrl":"https://example.com/designs/poster-a2.pdf",
       "retailPriceCents":4995,"active":true}'

Met PATCH /reseller-products/{id} wijzig je een bestaand product. In plaats van het id mag je ook de SKU gebruiken. Je stuurt alleen de velden mee die je wilt veranderen, bijvoorbeeld een nieuw bestand, een andere prijs of mockupafbeeldingen in mockupUrls.

curl -X PATCH https://www.printen.eu/api/reseller/v1/reseller-products/POSTER-A2-MAT \
  -H "Authorization: Bearer prk_test_..." -H "Content-Type: application/json" \
  -d '{"mockupUrls":["https://example.com/mockups/poster-a2-living-room.jpg",
                     "https://example.com/mockups/poster-a2-detail.jpg"],
       "retailPriceCents":4495}'

• productId, sku en title zijn verplicht bij het maken. Bedragen zoals retailPriceCents zijn in eurocenten.
• Een SKU moet uniek zijn in je account. Bestaat hij al, dan krijg je 409.
• Kloppen de opties niet voor dit product, dan krijg je 422.
• Met "active": false zet je een product op inactief. Orders met die SKU worden dan geweigerd.
• Met DELETE /reseller-products/{id} verwijder je een product. Is het nog gekoppeld aan een verbonden winkel, dan krijg je 409.

Welke orderstatussen zijn er, en wat moet je doen?

Elke order heeft een state: de status aan jouw kant (betaling en bestand). Zodra de order SUBMITTED is, volgt ook een productiestatus in status.

De productiestatus in status loopt van PAID via PROCESSING en PRINTING naar SHIPPED en DELIVERED. Bij SHIPPED vind je de trackingcode en de trackinglink in tracking. Een geannuleerde order krijgt CANCELLED of REFUNDED.

# Orders that are waiting for balance
curl "https://www.printen.eu/api/reseller/v1/orders?state=AWAITING_FUNDS" \
  -H "Authorization: Bearer prk_test_..."

# One order: by id, resellerOrderId or order number
curl https://www.printen.eu/api/reseller/v1/orders/RS-3F9A1C7B2E \
  -H "Authorization: Bearer prk_test_..."

Hoe annuleer je een order?

Met POST /orders/{id}/cancel annuleer je een order, zolang hij nog niet naar productie is gegaan. Als {id} mag je het order-id, het resellerOrderId of het ordernummer gebruiken.

curl -X POST https://www.printen.eu/api/reseller/v1/orders/RS-3F9A1C7B2E/cancel \
  -H "Authorization: Bearer prk_test_..."

• Lukt het, dan krijg je de order terug met state CANCELLED.
• Is de order al in productie, dan krijg je 409: annuleren kan dan niet meer.
• Betaald met saldo: het bedrag komt terug op je saldo en staat als Terugbetaling bij Mutaties.
• Betaald met je kaart: het bedrag gaat terug naar die kaart.
• Is er nog niets afgerekend (bijvoorbeeld bij AWAITING_FUNDS), dan wordt er ook niets terugbetaald.

Hoe test je veilig in de sandbox?

Met een testsleutel (prk_test_) bouw en test je je koppeling zonder risico. Je gebruikt dezelfde base URL en dezelfde aanroepen als live.

1. 1

   Test alles met prk_test_

   Controleer offertes, orders, herhaalde verzoeken met dezelfde Idempotency-Key, annuleren en je webhook-verwerking.

2. 2

   Maak een live sleutel

   Maak bij API-sleutels een sleutel zonder Testsleutel aan te vinken.

3. 3

   Wissel de sleutel

   Vervang in je configuratie de prk_test_-sleutel door de prk_live_-sleutel. Verder verandert er niets.

4. 4

   Controleer je betaalwijze

   Zorg voor genoeg saldo of een opgeslagen kaart bij Saldo & betalen, anders blijven live orders op AWAITING_FUNDS of PAYMENT_FAILED staan.

Wat betekent een foutmelding?

Elke fout heeft dezelfde vorm: een error-object met een korte code en een leesbare message. Kijk eerst naar de HTTP-status; de message vertelt je meestal precies wat er mis is.

{
  "error": {
    "code": "...",
    "message": "..."
  }
}