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.
- Notre équipe active l'API sur votre compte et vous envoie un e-mail « Accès API activé » avec votre identifiant client (
MP-000123). - 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.
- 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ête | Valeur |
|---|---|
X-Client-Id | Votre identifiant client, public et stable : MP-000123. |
X-Api-Key | Votre 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_mode | Unité | Produits | Ce que vous envoyez |
|---|---|---|---|
unit | piece | Panneaux, roll-up, X-banner, textile | quantity + un format (format ou width_mm × height_mm) |
length | ml | Film DTF, adhésifs, bâches et médias au mètre | length_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.
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 :
- Dimensions —
dimensions.standard_formatspour une liste de formats ;width_mmetheight_mm(min, max, pas) sifree_formatest vrai ;roll_width_mmpour un produit au mètre. - Quantité —
quantity(min, max, pas) et ses paliers ; les prix par palier se lisent dans/products/{id}/price-grid. - Options — pour chaque entrée de
options:selectdonne une liste à choix unique,multi_selectdes cases à cocher,quantity_mapune quantité par valeur (les tailles),marking_listune liste de marquages.requiredrend le champ obligatoire. - Contraintes — appliquez
constraintscô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épond422avec le champ en cause. - Prix — à chaque changement, envoyez la configuration à
/prices(ou/prices/batchpour 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
/productspage par page aveclimit(100 au plus) etcursor; arrêtez-vous quandnext_cursorest 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 unETag. Renvoyez-le dansIf-None-Match: si rien n'a changé, la réponse est304, 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
- Devis —
POST /quotesavec une ou plusieurs lignes. Le devis porte un numéro (Q-2026-000123) et une date de validité (15 jours). - Commande —
POST /ordersavecquote_id(ou directement deslines), l'adresse de livraison, votre référence. L'en-têteIdempotency-Keyest obligatoire. - Paiement — selon votre compte. À la commande : statut
awaiting_paymentet 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_exceededau-delà). - Fichiers —
POST /orders/{id}/lines/{line_id}/files, un fichier par ligne, enmultipart/form-data(champfile). - BAT — seulement si vous l'avez demandé (
proof_required: true) : statutawaiting_proof_approval, puis…/proofs/{proof_id}/approveou/rejectavec un commentaire. Sans BAT, la production démarre dès que les fichiers sont conformes. - 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
| Statut | Ce qu'il veut dire |
|---|---|
awaiting_payment | Paiement à la commande attendu (comptes en paiement par carte uniquement) |
awaiting_files | Un fichier d'impression manque sur au moins une ligne |
awaiting_proof_approval | Un BAT attend votre réponse |
in_production | En production : la commande ne s'annule plus |
shipped | Expédiée : tracking donne le transporteur et le numéro de suivi |
delivered | Livrée |
cancelled | Annulé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énement | Quand |
|---|---|
order.status_changed | Une commande change de statut |
proof.available | Un BAT attend votre validation |
order.shipped | Une commande est expédiée (avec le numéro de suivi) |
price.changed | Des 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 HTTP | Quand |
|---|---|
| 400 | JSON mal formé, paramètre de type incorrect, Idempotency-Key absent |
| 401 | Identifiant ou clé manquant ou invalide |
| 403 | Compte non activé, suspendu, adresse hors liste blanche, droit absent |
| 404 | Produit ou ressource inexistant |
| 409 | Conflit : pas de tarif pour ce compte, prix modifié (price_changed), plafond d'encours dépassé, annulation impossible |
| 422 | Configuration invalide : option manquante, valeur inconnue, combinaison interdite, dimension hors limites |
| 429 | Limite de débit atteinte |
| 500 / 503 | Erreur 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-LimitetX-RateLimit-Remaining. Au-delà :429avecRetry-After(en secondes). /prices/batchcompte 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 :
limitde 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 :
| Adresse | Clés | |
|---|---|---|
| Bac à sable | https://master-print.fr/api/sandbox/v1 | mp_test_… |
| Production | https://master-print.fr/api/v1 | mp_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).
| Date | Modification |
|---|---|
| 16/11/2026 | Premiè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/2026 | Devis (/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.