Statut. Ce document est une version devant être complétée en fonction de l'avancement du projet.

Introduction

L'API Imprim permet de consulter les pages produits, de calculer un prix, de simuler un panier et de créer ou consulter une commande. Elle n'expose pas les endpoints de catalogue détaillés des sites sur mesure : les options et variantes disponibles sont directement incluses dans chaque produit.

Les endpoints sont disponibles sous https://api.123imprim.com/0.2/imprim/. Toutes les requêtes utilisent du JSON et nécessitent le token partenaire dans l'en-tête HTTP :

Authorization: Token <token_partenaire>

Produits

Une ressource produit représente une page produit Imprim.

GET /0.2/imprim/produit/ : liste des pages produits accessibles.
GET /0.2/imprim/produit/<id>/ : détail d'une page produit.

L'identifiant retourné est celui de la page produit. C'est cet identifiant qui doit être envoyé dans le champ produit des endpoints prix et panier.

{
  "id": 123,
  "nom": "Flyers A5",
  "nombre_visuels_min": 1,
  "nombre_visuels_max": 2,
  "delais": [3, 6],
  "quantites": {
    "range": false,
    "available": [100, 250, 500]
  },
  "options": [
    {
      "id": 1,
      "nom": "Support",
      "type": "variante",
      "variantes": [
        {
          "id": 456,
          "nom": "Couché brillant 135 g"
        }
      ]
    },
    {
      "id": 98,
      "nom": "Largeur",
      "type": "decimal",
      "variantes": []
    }
  ]
}

nombre_visuels_min et nombre_visuels_max valent 1 lorsque le produit ne fournit pas d'information spécifique. Le champ delais contient les identifiants des délais disponibles pour ce produit ; ils peuvent être utilisés dans le champ delai d'une ligne.

Le champ quantites décrit les quantités commandables et prend l'une des deux formes suivantes :

quantités figées : {"range": false, "available": [100, 250, 500]} — seules les quantités listées dans available sont acceptées ;
quantité libre : {"range": true, "min": 1, "max": 5000} — toute quantité comprise entre min (1 par défaut) et max est acceptée.

Chaque option expose un champ type indiquant la nature de la valeur attendue : variante (choix parmi les variantes listées), integer ou decimal (valeur libre saisie, transmise via le champ valeurs d'une ligne). Les options à valeur libre ont une liste variantes vide.

Structure d'une ligne Imprim

Les endpoints prix et panier utilisent la structure suivante :

{
  "label": "Référence facultative de la ligne",
  "produit": 123,
  "variantes": [456, 789],
  "valeurs": {"98": "120.5", "99": "100"},
  "quantites_multiples": [100, 250],
  "delai": 6
}

produit est l'identifiant de la page produit.
variantes contient les identifiants des variantes choisies, au maximum une par option.
valeurs contient les valeurs libres des options de type integer ou decimal (ex. dimensions ouvertes, numérotation). C'est un objet indexé par id d'option (le même id que celui exposé dans options du produit), dont la valeur est le nombre saisi sous forme de chaîne. Ce champ est facultatif et ne contient que les options à valeur libre ; les options de type variante passent par variantes. Une même option ne peut pas être fournie à la fois dans variantes et valeurs.
quantites_multiples contient une ou plusieurs quantités strictement positives. Par exemple, [100, 250] représente deux fichiers ou visuels, imprimés respectivement à 100 et 250 exemplaires.
delai est défini par ligne. Il est facultatif et utilise le délai principal du produit par défaut.
Le BAT n'est pas un champ séparé : lorsqu'il est disponible, il doit être sélectionné comme une variante.

Prix

Le calcul des prix se fait avec une requête POST /0.2/imprim/prix/ contenant une ligne Imprim (mêmes champs que ci-dessus, y compris variantes et valeurs). La réponse contient les prix disponibles par délai. Tous les prix sont exprimés en centimes d'euro hors taxes.

{
  "J+6": {
    "Message": "",
    "PrixHT": "12500"
  }
}

Lorsque le prix d'un délai ne peut pas être calculé, Message contient la cause et PrixHT est vide.

Panier

Une requête POST /0.2/imprim/panier/ calcule un panier éphémère. Le panier est supprimé dès que la réponse a été produite.

{
  "devis": "DEV-CLIENT-42",
  "adresse_livraison": {
    "prenom": "Jean",
    "nom": "Dupont",
    "societe": "Société Exemple",
    "adresse1": "1 rue de l'Imprimerie",
    "adresse2": "",
    "code_postal": "69007",
    "ville": "LYON 07",
    "pays": "France",
    "email": "jean.dupont@example.com",
    "telephone": "0102030405",
    "instructions": "Sonner à l'accueil"
  },
  "lignes": [
    {
      "label": "Flyers salon",
      "produit": 123,
      "variantes": [456, 789],
      "valeurs": {"98": "120.5", "99": "100"},
      "quantites_multiples": [100, 250],
      "delai": 6
    }
  ]
}

Le retour conserve la signature tarifaire suivante :

{
  "devis": "DEV-CLIENT-42",
  "prix_ht": 12500,
  "remise_grand_compte_ht": 500,
  "prix_total_ht": 12000,
  "prix_tva": 2400,
  "prix_final_ttc": 14400,
  "lignes": [
    {
      "label": "Flyers salon",
      "produit": 123,
      "variantes": [456, 789],
      "valeurs": {"98": "120.5", "99": "100"},
      "quantites_multiples": [100, 250],
      "delai": 6,
      "prix_ht": 12500
    }
  ],
  "adresse_livraison": {
    "prenom": "Jean",
    "nom": "Dupont",
    "societe": "Société Exemple",
    "adresse1": "1 rue de l'Imprimerie",
    "adresse2": "",
    "code_postal": "69007",
    "ville": "LYON 07",
    "pays": "France",
    "email": "jean.dupont@example.com",
    "telephone": "0102030405",
    "instructions": "Sonner à l'accueil"
  }
}

Contrairement aux autres sites, le panier Imprim ne retourne pas de champs frais_port_ht ou emballage_renforce_ht séparés.

Création d'une commande

Pour transformer le panier en commande, envoyer le même payload à POST /0.2/imprim/panier/validate/. Cette opération nécessite un client authentifié autorisé à commander. En cas de succès, l'API retourne la commande créée avec un statut HTTP 201.

Consultation des commandes

GET /0.2/imprim/commande/ : commandes du client authentifié.
GET /0.2/imprim/commande/<id>/ : détail d'une commande du client.

{
  "id": 987,
  "status": "En attente de fichiers",
  "number": "IMP987",
  "reference_client": "DEV-CLIENT-42",
  "adresse_livraison": {
    "prenom": "Jean",
    "nom": "Dupont",
    "societe": "Société Exemple",
    "adresse1": "1 rue de l'Imprimerie",
    "adresse2": "",
    "code_postal": "69007",
    "ville": "LYON 07",
    "pays": "France",
    "email": "jean.dupont@example.com",
    "telephone": "0102030405",
    "instructions": "Sonner à l'accueil"
  },
  "prix_fact_ht": 12500,
  "remise_grand_compte_ht": 500,
  "prix_fact_total_ht": 12000,
  "prix_fact_total_tva": 2400,
  "prix_fact_total_ttc": 14400,
  "amount_due": 14400,
  "lignes": [
    {
      "id": 654,
      "label": "Flyers salon",
      "produit": 123,
      "variantes": [456, 789],
      "valeurs": {"98": "120.5", "99": "100"},
      "quantites_multiples": [100, 250]
    }
  ]
}

Le statut est celui de la commande de production associée. Les montants et le numéro proviennent directement de la commande Imprim.

Erreurs de validation

L'API retourne un statut HTTP 400 notamment lorsque :

la page produit n'existe pas ou n'est pas accessible au client ;
une variante n'est pas disponible pour le produit ;
plusieurs variantes de la même option sont envoyées ;
une quantité est vide, nulle ou négative ;
le délai demandé n'est pas disponible pour le produit.