API revendeurs

Démarrage rapide

1. 1. Créez une clé API

   Une fois votre compte revendeur approuvé, créez une clé dans votre tableau de bord. Une clé prk_live_ passe de vraies commandes ; une clé prk_test_ est un bac à sable qui ne facture rien et ne produit rien. La clé complète n’est affichée qu’une seule fois.

2. 2. Demandez un prix

   POST /quotes avec les lignes et le pays de livraison renvoie votre prix, remise, TVA et livraison comprises.

3. 3. Passez une commande

   POST /orders avec un en-tête Idempotency-Key (par exemple votre propre numéro de commande). Une nouvelle tentative avec la même clé ne crée jamais une deuxième commande.

4. 4. Recevez des webhooks

   Enregistrez un point de terminaison https et recevez les changements de statut, par exemple « expédiée » avec le suivi.

# Product: customer options with defaults and allowed values (id or any slug)
curl https://www.printen.eu/api/reseller/v1/products/flyers?lang=en \
  -H "Authorization: Bearer prk_test_..." -H "User-Agent: MyShop-Integration/1.0"

# Prijs / quote: only customer options; omitted options get the product-page default.
# quantity = number of pieces (for run-priced products the run: here 1000 flyers)
curl -X POST https://www.printen.eu/api/reseller/v1/quotes \
  -H "Authorization: Bearer prk_test_..." -H "Content-Type: application/json" \
  -H "User-Agent: MyShop-Integration/1.0" \
  -d '{"country":"BE","lines":[{"productId":"<product id>","quantity":1000,"options":{"size":"a5","material":"135gr_gesatineerd_mc","printtype":"44"}},{"resellerSku":"POSTER-A2","quantity":1}]}'

# Order
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,"fileUrl":"https://example.com/design.pdf"}],
       "recipient":{"name":"Anna de Vries","email":"anna@example.com","phone":"+31612345678","address1":"Dorpsstraat 1","postalCode":"1234 AB","city":"Utrecht","country":"NL"}}'

# Webhook
curl -X POST https://www.printen.eu/api/reseller/v1/webhooks \
  -H "Authorization: Bearer prk_live_..." -H "Content-Type: application/json" \
  -d '{"url":"https://example.com/printen-webhook","events":["order.shipped","order.delivered"]}'

Authentification

Envoyez votre clé sous la forme Authorization: Bearer prk_live_... Les clés peuvent avoir des scopes ; une clé sans scope peut tout faire.

Avec une clé prk_test_, les commandes sont créées mais ni facturées ni envoyées en production.

Au maximum 120 requêtes par minute et par clé, plus des quotas par compte pour les devis et les commandes. Chaque réponse contient RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (secondes) pour la limite la plus stricte ; au-delà, vous recevez 429 avec un en-tête Retry-After.

Base URL: https://www.printen.eu/api/reseller/v1

Points de terminaison

Fonctionnement de l’API

Webhooks

Nous envoyons un POST JSON à votre point de terminaison, avec les en-têtes X-Printen-Event, X-Printen-Delivery, X-Printen-Timestamp et X-Printen-Signature. Répondez avec un statut 2xx dans les 10 secondes. En cas d’échec, nous réessayons pendant environ 24 heures. Un événement peut arriver plusieurs fois : dédupliquez sur le champ id.

Événements

• order.created
• order.submitted
• order.awaiting_funds
• order.payment_failed
• order.in_production
• order.shipped
• order.delivered
• order.cancelled
• order.file_problem

Vérifier la signature

X-Printen-Signature vaut v1= suivi du HMAC-SHA256 hexadécimal de « horodatage.corps brut » avec le secret de votre point de terminaison. Refusez les messages dont l’horodatage date de plus de 5 minutes.

Node.js

import crypto from 'node:crypto';

export function verifyPrintenWebhook(rawBody, headers, secret) {
  const timestamp = headers['x-printen-timestamp'];
  const signature = headers['x-printen-signature'] || '';
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
  const expected = 'v1=' + crypto.createHmac('sha256', secret)
    .update(`${timestamp}.${rawBody}`).digest('hex');
  return signature.length === expected.length
    && crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

PHP

<?php
function verify_printen_webhook(string $rawBody, string $timestamp, string $signature, string $secret): bool {
    if (abs(time() - (int) $timestamp) > 300) return false;
    $expected = 'v1=' . hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    return hash_equals($expected, $signature);
}

Python

import hashlib, hmac, time

def verify_printen_webhook(raw_body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    expected = "v1=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature)

Erreurs

Chaque erreur a la forme {"error": {"code": "...", "message": "...", "details": [...]}}. 400 = requête mal formée ; 422 = requête valide qui ne peut pas être exécutée (voir details) ; 401, 403, 404, 409 et 429 comme d’habitude ; 500 uniquement en cas d’erreur de notre côté. Les montants sont toujours en centimes d’euro.