API v1

API Master Print

Le catalogue et les prix d'achat de votre compte, dans votre site, votre logiciel de devis ou votre ERP. Sans ressaisie, au même prix que sur master-print.fr.

1. Introduction

L'API Master Print est une API REST qui renvoie le prix de n'importe quel produit du catalogue, pour n'importe quelle configuration, au prix d'achat de votre compte. Elle s'adresse aux revendeurs, agences et imprimeurs partenaires qui veulent intégrer nos prix dans leurs propres outils.

  • Catalogue : catégories, produits, options, valeurs, contraintes, dimensions.
  • Prix : une configuration, un lot de 1 à 50 configurations, la grille par paliers de quantité.
  • Délais et livraison : délais de production, date d'envoi estimée, frais de port.
  • Devis et commandes : devis enregistrés ; commande, fichiers, BAT, suivi et factures — aujourd'hui en bac à sable.
  • Webhooks : notifications signées à chaque changement.

Le prix renvoyé est strictement celui du site pour le même compte et la même configuration : l'API appelle le moteur de prix du site, pas une copie. Aucun prix public de référence n'est exposé.

Toutes les réponses sont en JSON UTF-8. Les noms de champs sont en anglais (snake_case), les libellés en français. Les montants sont en euros, hors taxes et toutes taxes.

2. Obtenir un accès

L'accès à l'API est activé par l'équipe Master Print, à votre demande. Il n'existe ni formulaire ni bouton de demande : parlez-en à votre contact commercial, ou écrivez-nous depuis la page Contact.

  1. Notre équipe active l'API sur votre compte et vous envoie un e-mail « Accès API activé » avec votre identifiant client (MP-000123).
  2. Vous générez votre clé vous-même, dans votre espace client, onglet « API ». Elle s'affiche une seule fois : copiez-la tout de suite.
  3. Vous commencez par le bac à sable ; la production est ouverte ensuite par notre équipe.

L'onglet « API » de votre espace n'apparaît que si l'API est activée sur votre compte. Vous y voyez le statut de votre accès, votre identifiant, vos clés et votre consommation.

3. Démarrage rapide

Deux appels suffisent pour un premier prix : vérifier vos identifiants, puis calculer un prix. Comptez moins d'un quart d'heure.

Étape 1 — vérifier vos identifiants

La réponse donne votre compte, votre niveau tarifaire, vos droits et vos quotas restants.

Étape 2 — calculer un prix

12,5 mètres de film DTF : la réponse détaille le prix ligne par ligne, hors taxes et toutes taxes, avec le délai et la durée de validité du prix.

4. Authentification

Chaque appel porte deux en-têtes :

En-têteValeur
X-Client-IdVotre identifiant client, public et stable : MP-000123.
X-Api-KeyVotre clé secrète : mp_test_… (bac à sable) ou mp_live_… (production).

Bonnes pratiques

  • Gardez la clé côté serveur. L'API s'appelle depuis votre serveur, jamais depuis le navigateur de vos clients : la clé y serait lisible. C'est pourquoi l'API n'envoie aucun en-tête CORS.
  • Jamais dans l'adresse. Une clé passée en paramètre d'URL finit dans les journaux et l'historique : l'appel est refusé (key_in_url).
  • HTTPS obligatoire. Un appel en clair est refusé, pas redirigé.
  • Une clé par intégration (cinq au plus par environnement), chacune avec un nom : « Site WooCommerce », « Logiciel de devis ».
  • Rotation sans coupure. Quand vous régénérez une clé, l'ancienne reste valable 24 heures : le temps de déployer la nouvelle.

Vous pouvez demander une liste blanche d'adresses IP : seuls vos serveurs pourront alors utiliser vos clés.

5. Concepts

Modes de tarification

pricing_modeUnitéProduitsCe que vous envoyez
unitpiecePanneaux, roll-up, X-banner, textilequantity + un format (format ou width_mm × height_mm)
lengthmlFilm DTF, adhésifs, bâches et médias au mètrelength_mm, ou vos visuels dans pieces

Quantité facturable

billable_quantity dit ce qui est réellement facturé : un nombre de pièces, ou une longueur en mètres linéaires. Pour un produit au mètre, donnez vos visuels (pieces) et le serveur les place sur la laize avec le moteur de placement du site : vous ne payez que la longueur utilisée.

Options et contraintes

Chaque produit liste ses options (options), leurs valeurs et leurs contraintes. Une configuration invalide n'est jamais devinée : une option obligatoire manquante, une valeur inconnue ou une combinaison interdite renvoie une erreur 422 qui nomme le champ (field) et la règle.

Niveau tarifaire

Le prix dépend du niveau de votre compte. Chaque réponse l'indique dans price_tier ; /me le détaille par famille.

Port et totaux

total_excl_tax est le prix des produits. Le port, quand vous donnez une destination (shipping), est renvoyé à part ; total_with_shipping_incl_tax additionne le tout : c'est ce que le site affiche pour la même configuration.

TVA

vat_rate est le taux de votre compte, en fraction : 0.2 pour 20 %, 0 pour un client professionnel de l'Union européenne en autoliquidation.

Délais et validité

production donne le délai en jours ouvrés et la date d'envoi estimée. Un prix est valable 24 heures (price_valid_until).

6. Référence

Générée à partir de la spécification OpenAPI 3.1 que sert l'API elle-même : elle ne peut pas diverger de l'API réelle. Chaque route a ses exemples dans quatre langages et sa console « Essayer », utilisable avec une clé de bac à sable.

Console « Essayer » — bac à sable

Vos identifiants de bac à sable restent dans cette page : ils ne sont ni enregistrés ni envoyés ailleurs qu'à l'API.

Chargement de la référence…

7. Guides par famille de produits

Un exemple réel pour chaque famille. Les identifiants de produit et les codes d'options se lisent dans /products.

Transferts DTF

Le film DTF se facture au mètre, sur une laize de 55 cm. Donnez la longueur, ou vos visuels : le serveur les place sur le film.

Textile

Un produit par modèle. Le coloris, la répartition des tailles (leur somme est la quantité) et, si vous marquez, la liste des marquages : emplacement, technique, taille ou format. Sans marquage, c'est du textile vierge.

Grand format

Panneaux (Akilux, Dibond, PVC expansé) : une quantité et un format, standard ou libre. Un format libre est facturé au plus petit format du catalogue qui le contient.

Adhésifs et médias au mètre

Adhésifs, bâches, papier : au mètre linéaire sur la laize du média. Les options obligatoires (colle, découpe) se lisent dans le détail du produit.

Supports

Roll-up et X-banner : une quantité et un format (structure et visuel, visuel seul, structure seule).

8. Construire un configurateur

GET /products/{id} contient tout ce qu'il faut pour générer un formulaire :

  1. Dimensions — dimensions.standard_formats pour une liste de formats ; width_mm et height_mm (min, max, pas) si free_format est vrai ; roll_width_mm pour un produit au mètre.
  2. Quantité — quantity (min, max, pas) et ses paliers ; les prix par palier se lisent dans /products/{id}/price-grid.
  3. Options — pour chaque entrée de options : select donne une liste à choix unique, multi_select des cases à cocher, quantity_map une quantité par valeur (les tailles), marking_list une liste de marquages. required rend le champ obligatoire.
  4. Contraintes — appliquez constraints côté formulaire (une seule valeur par groupe, somme des tailles égale à la quantité, marquage dans les limites de son emplacement). L'API les revérifie : en cas d'écart elle répond 422 avec le champ en cause.
  5. Prix — à chaque changement, envoyez la configuration à /prices (ou /prices/batch pour comparer plusieurs quantités d'un coup).

Textile : tous les couples coloris × taille n'existent pas. variants liste ceux qui sont réellement vendus, avec leur disponibilité.

9. Synchroniser le catalogue

  • Première synchronisation : parcourez /products page par page avec limit (100 au plus) et cursor ; arrêtez-vous quand next_cursor est nul.
  • Ensuite : /products?updated_since=… ne renvoie que ce qui a changé — produits, options ou prix — produits retirés compris (status: discontinued).
  • ETag : les réponses du catalogue portent un ETag. Renvoyez-le dans If-None-Match : si rien n'a changé, la réponse est 304, sans corps.
  • Fréquence : une synchronisation par jour suffit pour le catalogue. Les prix, eux, se demandent au moment du devis : ils dépendent de la quantité et de vos conditions.

10. Du prix à la commande

État d'ouverture. Les devis sont ouverts. Les commandes se créent et se suivent de bout en bout en bac à sable, sans aucun effet réel ; en production elles ne sont pas encore ouvertes (orders_not_open) — l'ouverture sera annoncée dans le journal des modifications. Ces routes demandent un compte « prix, devis et commandes ».

Le parcours

  1. Devis — POST /quotes avec une ou plusieurs lignes. Le devis porte un numéro (Q-2026-000123) et une date de validité (15 jours).
  2. Commande — POST /orders avec quote_id (ou directement des lines), l'adresse de livraison, votre référence. L'en-tête Idempotency-Key est obligatoire.
  3. Paiement — selon votre compte. À la commande : statut awaiting_payment et lien de paiement (payment.payment_url). Sur facture : la commande rejoint votre facture regroupée, dans la limite de votre plafond d'encours (credit_limit_exceeded au-delà).
  4. Fichiers — POST /orders/{id}/lines/{line_id}/files, un fichier par ligne, en multipart/form-data (champ file).
  5. BAT — seulement si vous l'avez demandé (proof_required: true) : statut awaiting_proof_approval, puis …/proofs/{proof_id}/approve ou /reject avec un commentaire. Sans BAT, la production démarre dès que les fichiers sont conformes.
  6. Suivi — GET /orders/{id} : statut de chaque ligne, historique horodaté, numéro de suivi du colis, numéro de facture.

Idempotence

Envoyez un identifiant unique par commande dans Idempotency-Key (un UUID). Si votre appel est rejoué — coupure réseau, nouvelle tentative —, l'API rend la commande d'origine (code 200, en-tête Idempotent-Replayed: true) : jamais deux commandes. La même clé avec une demande différente est un conflit (idempotency_conflict).

Prix garanti

Une commande créée depuis un devis valide reprend son prix. Si le devis a expiré, le prix est recalculé ; s'il a changé, l'API répond 409 price_changed avec l'ancien et le nouveau total : confirmez avec accept_price_change: true.

Statuts

StatutCe qu'il veut dire
awaiting_paymentPaiement à la commande attendu (comptes en paiement par carte uniquement)
awaiting_filesUn fichier d'impression manque sur au moins une ligne
awaiting_proof_approvalUn BAT attend votre réponse
in_productionEn production : la commande ne s'annule plus
shippedExpédiée : tracking donne le transporteur et le numéro de suivi
deliveredLivrée
cancelledAnnulée (POST /orders/{id}/cancel, tant que la production n'a pas démarré)

Envoi neutre

blind_shipping: true : le colis part sans mention Master Print, pour une livraison directe chez votre client.

Simuler en bac à sable

POST /orders/{id}/simulate joue le reste du monde : payment_received, production_started, shipped, delivered. Chaque changement déclenche vos webhooks. Les factures du bac à sable sont des PDF de démonstration.

11. Webhooks

Abonnez une adresse HTTPS de votre serveur avec POST /webhooks : l'API l'appelle en POST, corps JSON, à chaque événement. Cinq abonnements au plus par environnement.

ÉvénementQuand
order.status_changedUne commande change de statut
proof.availableUn BAT attend votre validation
order.shippedUne commande est expédiée (avec le numéro de suivi)
price.changedDes produits ou leurs prix ont changé : resynchronisez avec updated_since
{
  "id": "evt_3f9a1c0b7d2e4a5f6b8c9d0e",
  "type": "order.status_changed",
  "created_at": "2026-11-16T10:02:11+01:00",
  "environment": "sandbox",
  "data": { "order_id": "MP-ORD-2026-000123", "status": "shipped", "previous_status": "in_production" }
}

Vérifier la signature

Chaque envoi porte X-MP-Signature: t=<horodatage>,v1=<signature>. La signature est le HMAC-SHA256, avec votre secret, de <horodatage>.<corps brut>. Le secret (whsec_…) vous est rendu une seule fois, à la création de l'abonnement. Refusez un envoi dont la signature ne correspond pas, ou dont l'horodatage a plus de cinq minutes.

// Node.js
const crypto = require("crypto");
function signatureValide(secret, entete, corpsBrut) {
  const { t, v1 } = Object.fromEntries(entete.split(",").map(p => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const attendue = crypto.createHmac("sha256", secret).update(t + "." + corpsBrut).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(attendue), Buffer.from(v1));
}

Nouvelles tentatives

Répondez par un code 2xx en moins de dix secondes. Sinon l'envoi est repris cinq fois, de plus en plus espacées (1 minute, 5 minutes, 30 minutes, 2 heures, 12 heures), puis abandonné. X-MP-Delivery identifie l'événement : un même événement peut vous arriver deux fois, traitez-le une seule fois. L'historique de vos envois se lit dans GET /webhooks/{id}/deliveries.

12. Erreurs

Toutes les erreurs ont le même format : un code machine stable, un message lisible en français, le champ en cause quand il y en a un, et un identifiant de requête à transmettre au support.

{
  "error": {
    "code": "invalid_option_combination",
    "message": "Une seule valeur pour l'option « Œillets ».",
    "field": "options.eyelets",
    "request_id": "req_01JB8X4K2Q",
    "doc_url": "https://master-print.fr/developpeurs#erreur-invalid_option_combination"
  }
}
Code HTTPQuand
400JSON mal formé, paramètre de type incorrect, Idempotency-Key absent
401Identifiant ou clé manquant ou invalide
403Compte non activé, suspendu, adresse hors liste blanche, droit absent
404Produit ou ressource inexistant
409Conflit : pas de tarif pour ce compte, prix modifié (price_changed), plafond d'encours dépassé, annulation impossible
422Configuration invalide : option manquante, valeur inconnue, combinaison interdite, dimension hors limites
429Limite de débit atteinte
500 / 503Erreur du serveur ou maintenance (avec Retry-After)

Tous les codes

Chargement…

13. Limites et quotas

  • 60 appels par minute et 10 000 par jour, par clé. Ces valeurs se règlent par compte : demandez-nous si votre usage le justifie.
  • Chaque réponse porte X-RateLimit-Limit et X-RateLimit-Remaining. Au-delà : 429 avec Retry-After (en secondes).
  • /prices/batch compte pour un appel et accepte jusqu'à 50 configurations : préférez-le aux appels en rafale.
  • Après 20 échecs d'authentification en 5 minutes, l'adresse appelante est bloquée 15 minutes.
  • Pagination : limit de 1 à 100.

14. Bac à sable

Le bac à sable a les mêmes routes que la production, à une autre adresse et avec ses propres clés :

AdresseClés
Bac à sablehttps://master-print.fr/api/sandbox/v1mp_test_…
Productionhttps://master-print.fr/api/v1mp_live_…

Une clé de bac à sable ne fonctionne pas sur l'adresse de production, et inversement (wrong_environment). Le catalogue et les prix du bac à sable sont ceux de votre compte : vous testez sur des données réalistes. Les commandes du bac à sable sont simulées de bout en bout — rien n'est produit, rien n'est facturé — et vous les faites avancer vous-même avec POST /orders/{id}/simulate. Le bac à sable a ses propres quotas, identiques à ceux de la production.

15. Journal des modifications et versions

La version est dans l'adresse (/v1). Aucun changement cassant n'est fait dans une version publiée ; l'ajout de champs ou de produits n'est pas cassant et peut arriver à tout moment — ignorez les champs que vous ne connaissez pas. Une nouvelle version majeure est annoncée six mois avant l'arrêt de la précédente (e-mail aux comptes actifs et en-tête Deprecation).

DateModification
16/11/2026Première publication : identité et quotas (/me), catalogue (/categories, /products), prix (/prices, /prices/batch, grille par paliers), délais et frais de port, bac à sable.
16/11/2026Devis (/quotes), commandes en bac à sable (/orders, fichiers, BAT, annulation, simulation, factures de démonstration) et webhooks signés. Les commandes en production ne sont pas encore ouvertes.

16. Support

Pour une question technique, écrivez-nous depuis la page Contact en indiquant votre identifiant client et, pour une erreur, le request_id de la réponse. Nous répondons sous deux jours ouvrés.

État du service : GET /api/v1/status (sans authentification) — vérification…

17. Conditions d'utilisation

L'usage de l'API est soumis aux conditions générales de vente de Master Print. Les points propres à l'API :

  • Usage autorisé : intégrer nos prix et notre catalogue dans vos propres outils, pour votre activité.
  • Confidentialité des prix d'achat : les prix renvoyés sont les vôtres ; ne les publiez pas et ne les transmettez pas à des tiers.
  • Sécurité : vous êtes responsable de la confidentialité de vos clés ; révoquez sans attendre une clé qui aurait fuité.
  • Suspension : l'accès peut être suspendu ou révoqué à tout moment, notamment en cas d'usage anormal ; vous en êtes prévenu par e-mail.

Les conditions détaillées de l'API (commandes, paiement, responsabilité) seront publiées ici avec l'ouverture des commandes.