L’API : commander depuis votre propre système

Comment créer et gérer une clé API ?

Chaque appel à l’API utilise une clé. Il en existe deux sortes : une clé live (commence par prk_live_) passe de vraies commandes, facturées et produites ; une clé de test (commence par prk_test_) fonctionne dans le bac à sable : les commandes sont créées, mais rien n’est facturé ni produit.

1. 1

   Ouvrez l’onglet

   Dans votre tableau de bord, allez dans Clés API.

2. 2

   Nommez la clé

   Saisissez un nom reconnaissable dans Nom de la clé, par exemple le nom de votre boutique ou de votre serveur. Vous saurez ainsi plus tard quelle clé est utilisée où.

3. 3

   Choisissez test ou live

   Cochez Clé de test pour une clé de bac à sable (prk_test_). Laissez la case vide pour une clé live (prk_live_). Choisissez ensuite sous Droits (scopes) ce que la clé peut faire ; si vous laissez tout coché, elle a tous les droits.

4. 4

   Créez la clé

   Cliquez sur Créer une clé. La clé complète s’affiche une seule fois, avec le message Copiez cette clé maintenant. Elle ne s’affichera qu’une fois.

5. 5

   Copiez-la et conservez-la

   Cliquez sur Copier et placez aussitôt la clé en lieu sûr, par exemple dans une variable d’environnement sur votre serveur ou dans un gestionnaire de mots de passe. Ensuite, la liste n’affiche plus que le début de la clé et sa Dernière utilisation.

L’API gère des droits (scopes) par clé. Une clé sans scopes a tous les droits. Dans le tableau de bord, vous les choisissez sous Droits (scopes) en créant la clé. Si vous laissez tout coché, la clé obtient tous les droits, y compris ceux ajoutés plus tard. La liste indique les droits de chaque clé. Pour modifier les droits d’une clé, créez-en une nouvelle et révoquez l’ancienne.

Base URL, authentification et limites

• Base URL : https://www.printen.eu/api/reseller/v1. Tous les chemins de cet article sont relatifs à cette adresse.
• Authentification : envoyez l’en-tête Authorization: Bearer prk_live_... ou Authorization: Bearer prk_test_... avec chaque requête.
• Format : requêtes et réponses sont en JSON. Une réponse réussie est toujours placée dans un champ data ; les listes contiennent en plus nextCursor pour récupérer la page suivante.
• Montants : toujours en centimes d’euro. 2873 signifie donc 28,73 €.
• Limite : au maximum 120 requêtes par minute et par clé. Les devis (POST /quotes) et les nouvelles commandes ont en plus leur propre limite par compte, plus basse pour les nouveaux comptes. Chaque réponse contient RateLimit-Limit, RateLimit-Remaining et RateLimit-Reset (secondes) pour la limite atteinte en premier. Au-delà, vous recevez le statut 429 avec un en-tête Retry-After.
• Spécification : la spécification OpenAPI complète se trouve sur https://www.printen.eu/reseller-api/openapi.json. Vous pouvez l’importer dans Postman, Insomnia ou un générateur de code.

Testez votre clé avec un appel simple, par exemple la consultation de votre solde. Si vous recevez du JSON avec data, votre clé fonctionne.

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

Comment consulter le catalogue et les options ?

Avec GET /products, vous parcourez le catalogue. Utilisez q comme terme de recherche, category pour une catégorie, lang pour la langue des noms et des options (nl, en, de ou fr), et limit (100 au maximum) et cursor pour passer d’une page à l’autre.

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

Avec l’id de cette liste, vous récupérez un produit avec toutes ses options et ses exigences de fichier.

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
    }
  }
}

Votre premier devis : combien coûte une commande ?

Avec POST /quotes, vous calculez le prix d’une ou plusieurs lignes pour un pays de destination, remise, livraison et TVA comprises. Rien n’est commandé ni facturé. Une ligne contient un resellerSku (votre propre produit) ou un productId avec des options, plus une 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"
  }
}

Passer votre première commande (avec une Idempotency-Key)

1. 1

   Choisissez une clé unique

   Choisissez une Idempotency-Key unique par commande, de préférence votre propre numéro de commande (par exemple shop-order-1001). Cet en-tête est obligatoire.

2. 2

   Composez les lignes

   Utilisez un resellerSku et une quantity par ligne. Si votre produit n’a pas encore de visuel, envoyez aussi une fileUrl (https).

3. 3

   Renseignez le destinataire

   Obligatoires : name, address1, postalCode, city et country (ISO-2, par exemple FR). Facultatifs : company, email, phone, address2 et state.

4. 4

   Ajoutez vos propres références

   Avec externalOrderId et externalOrderNumber, vous reliez la commande à votre système ; ils reviennent dans chaque webhook. reference est votre propre référence.

5. 5

   Envoyez la requête

   Une nouvelle commande renvoie le statut 201. Vérifiez state dans la réponse : SUBMITTED signifie payée et en route vers la production.

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
  }
}

Pourquoi une Idempotency-Key ? Les réseaux ne sont pas fiables : un délai dépassé ne veut pas dire que votre commande n’est pas arrivée. Une Idempotency-Key vous permet de répéter une requête sans risque. Si vous renvoyez la même clé, vous récupérez la commande existante avec "duplicate": true et le statut 200. Une deuxième commande n’est jamais créée.

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

• Utilisez une clé par commande, et toujours la même lorsque vous renvoyez cette commande.
• Une clé existante renvoie toujours la commande d’origine, même si le contenu de votre requête diffère. Si vous voulez vraiment une nouvelle commande, utilisez une nouvelle clé.
• Une clé compte au maximum 200 caractères (caractères ASCII visibles).
• Les clés live et les clés de test ont chacune leur propre espace. Une commande de test avec shop-order-1001 ne bloque donc pas une commande live avec la même clé.

Gérer vos propres produits via l’API

Un produit propre est un produit du catalogue avec des options fixes, votre SKU, votre fichier de visuel, un titre et, en option, votre prix de vente. Créez-en un avec POST /reseller-products ; ensuite, vous le commandez avec 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}'

Avec PATCH /reseller-products/{id}, vous modifiez un produit existant. Vous pouvez utiliser le SKU à la place de l’id. N’envoyez que les champs à modifier, par exemple un nouveau fichier, un autre prix ou des images de mockup dans 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 et title sont obligatoires à la création. Les montants comme retailPriceCents sont en centimes d’euro.
• Un SKU doit être unique dans votre compte. S’il existe déjà, vous recevez 409.
• Si les options ne conviennent pas à ce produit, vous recevez 422.
• Avec "active": false, vous rendez un produit inactif. Les commandes avec ce SKU sont alors refusées.
• Avec DELETE /reseller-products/{id}, vous supprimez un produit. S’il est encore lié à une boutique connectée, vous recevez 409.

Quels sont les statuts de commande, et que faire ?

Chaque commande a un state : le statut de votre côté (paiement et fichier). Dès que la commande est SUBMITTED, un statut de production suit dans status.

Le statut de production dans status va de PAID à SHIPPED puis DELIVERED, en passant par PROCESSING et PRINTING. À SHIPPED, vous trouvez le numéro et le lien de suivi dans tracking. Une commande annulée passe à CANCELLED ou 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_..."

Comment annuler une commande ?

Avec POST /orders/{id}/cancel, vous annulez une commande tant qu’elle n’est pas partie en production. Pour {id}, vous pouvez utiliser l’id de la commande, le resellerOrderId ou le numéro de commande.

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

• Si cela fonctionne, vous récupérez la commande avec state CANCELLED.
• Si la commande est déjà en production, vous recevez 409 : l’annulation n’est plus possible.
• Payée avec le solde : le montant revient sur votre solde et apparaît comme Remboursement dans Mouvements.
• Payée par carte : le montant est remboursé sur cette carte.
• Si rien n’a encore été débité (par exemple en AWAITING_FUNDS), rien n’est remboursé non plus.

Comment tester en toute sécurité dans le bac à sable ?

Avec une clé de test (prk_test_), vous construisez et testez votre intégration sans risque. Vous utilisez la même base URL et les mêmes appels qu’en production.

1. 1

   Testez tout avec prk_test_

   Vérifiez les devis, les commandes, les requêtes répétées avec la même Idempotency-Key, les annulations et le traitement de vos webhooks.

2. 2

   Créez une clé live

   Dans Clés API, créez une clé sans cocher Clé de test.

3. 3

   Remplacez la clé

   Remplacez la clé prk_test_ par la clé prk_live_ dans votre configuration. Rien d’autre ne change.

4. 4

   Vérifiez votre mode de paiement

   Assurez-vous d’avoir assez de solde ou une carte enregistrée dans Solde et paiement, sinon les commandes live restent en AWAITING_FUNDS ou PAYMENT_FAILED.

Que signifie un message d’erreur ?

Chaque erreur a la même forme : un objet error avec un code court et un message lisible. Regardez d’abord le statut HTTP ; le message vous dit généralement exactement ce qui ne va pas.

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