API Bephoto

Consultez la documentation ci-dessous pour automatiser vos commandes d'impression.

Documentation API Bephoto

Introduction

L'envoi des commandes d'impression se fait via une API REST. Avant de pouvoir effectuer des requêtes vers l'API, vous devez d'abord vous authentifier en utilisant les informations reçues pour obtenir un jeton d'authentification. Ce jeton doit être inclus dans l'en-tête "Authorization" de chaque requête API suivante :

Authorization: Bearer <your-authentication-token>

Le jeton est valable un an. Un nouveau jeton est émis à chaque authentification.

URL API en direct https://api.bephoto.be

Authentification

Authentifiez-vous en appelant le point de terminaison /user/login avec vos informations d'identification :

POST /user/login { "email": "<string>", "password": "<string>" }

Réponse:

{ "status": 1, "token": "<string>" }

Réponse d'erreur:

{ "error": "Unauthorized" }

Paramètres envoyés à l'API

  • email: L'adresse email de l'utilisateur.
  • password: Le mot de passe de l'utilisateur.

Authentification par clé d'API

Pour ne pas utiliser de mot de passe dans votre intégration, authentifiez-vous avec une clé d'API en appelant /user/loginToken. La clé est fournie par Bephoto sur demande, par compte :

POST /user/loginToken { "token": "<string>" }

Réponse:

{ "status": 1, "token": "<string>" }

Réponse d'erreur:

{ "error": "Unauthorised" }

Paramètres envoyés à l'API

  • token: La clé d'API fournie par Bephoto.

Création de commande

Créez une nouvelle commande en appelant /orders avec des métadonnées optionnelles. Après avoir créé une commande, vous recevrez un idorder unique, qui doit être utilisé dans les appels suivants :

POST /orders { "metadata": "<string>" }

Réponse:

{ "status": 1, "order": { "idorder": "<integer>", "datestart": "<timestamp>", "totalorder": "<float>", "totalcost": "<float>", "dateconfirmation": "<timestamp>", "dateprocessed": "<timestamp>", "shippingmethod": "<string>", "metadata": "<string>" } }

Paramètres envoyés à l'API

  • metadata: Métadonnées personnalisées associées à la commande. Max. longueur : 255 caractères.

Récupérer une commande

Récupérez les informations d'une commande en appelant /orders/{IDORDER} :

GET /orders/{IDORDER}

Réponse:

{ "status": 1, "order": { "idorder": "<integer>", "datestart": "<timestamp>", "totalorder": "<float>", "totalcost": "<float>", "dateconfirmation": "<timestamp>", "dateprocessed": "<timestamp>", "shippingmethod": "<string>", "metadata": "<string>", "products": [{ "idproduct": "<integer>", "idpaper": "<integer>", "quantity": "<integer>", "size": "<string>" }] } }

Le champ shippingmethod vaut PICKUP (enlèvement) ou BPOST (livraison à une adresse). Le champ totalcost contient les frais de la commande, totalorder le total à payer. Une commande principale renvoie aussi ses sous-commandes (suborders) ; une sous-commande renvoie l'ID de sa commande principale (parent_idorder).

Paramètres envoyés à l'API

  • idorder: L'ID unique de la commande.

Méthode d'expédition

Choisissez la méthode d'expédition en appelant /orders/{IDORDER}/shipping/{SHIPPING_METHOD}. Sans appel, la commande est en livraison (BPOST). Toute autre valeur renvoie une erreur.

POST /orders/{IDORDER}/shipping/{SHIPPING_METHOD}

Réponse:

{ "status": 1 }

Paramètres envoyés à l'API

  • idorder: L'ID unique de la commande.
  • shipping_method: PICKUP pour un enlèvement, BPOST pour une livraison à une adresse. Pour une livraison, indiquez l'adresse via /orders/{IDORDER}/shipping-address.

Adresse de livraison

Indiquez l'adresse de livraison d'une commande en appelant /orders/{IDORDER}/shipping-address. La commande passe alors en livraison. Une commande n'a qu'une seule adresse : créez une commande par destinataire.

POST /orders/{IDORDER}/shipping-address { "nom": "<string>", "prenom": "<string>", "societe": "<string>", "adresse": "<string>", "complement_adresse": "<string>", "cp": "<string>", "localite": "<string>", "pays": "<string>", "email": "<string>" }

Réponse:

{ "status": 1, "idadrliv": "<integer>" }

Paramètres envoyés à l'API

  • idorder: L'ID unique de la commande.
  • nom: Nom du destinataire (obligatoire).
  • prenom: Prénom du destinataire (obligatoire).
  • societe: Société, école ou studio (optionnel).
  • adresse: Rue et numéro (obligatoire).
  • complement_adresse: Complément d'adresse (optionnel).
  • cp: Code postal (obligatoire).
  • localite: Localité (obligatoire).
  • pays: Code pays, BE par défaut (optionnel).
  • email: Email du destinataire pour le suivi de l'envoi (optionnel).

Récupérer les produits

Obtenez une liste des produits d'impression disponibles en appelant /products :

GET /products

Réponse:

{ "status": 1, "products": { "<idformat>": { "idformat": "<integer>", "format": "<string>", "largeur": "<integer>", "hauteur": "<integer>", "prix": { "<idpaper>": "<float>" } } } }

Le prix renvoyé est le prix de base à l'unité. Les prix sont dégressifs : le prix unitaire baisse selon la quantité totale commandée pour un même produit et un même papier. Utilisez /calculate ou /orders/{IDORDER}/price pour obtenir le prix réellement appliqué.

Ajoutez ?include=montage pour obtenir aussi les montages disponibles sur votre compte (pochettes, planches d'identité, montages scolaires), reconnaissables à idtypeformat = 100. Chaque mise en page est un produit distinct : choisissez la mise en page en choisissant le produit. Envoyez une seule photo par montage ; le laboratoire compose la planche.

Champs renvoyés

  • idformat: L'ID unique du produit, à envoyer comme idproduct.
  • format: Le nom du produit.
  • largeur, hauteur: Les dimensions du produit (en millimètres).
  • prix: Le prix de base par type de papier : la clé est l'idpaper, la valeur le prix unitaire.
  • idtypeformat: 100 pour un montage composé par le laboratoire.

Simuler un prix

Calculez le prix d'une liste de produits, sans créer de commande, en appelant /calculate. Le palier de prix est appliqué selon la quantité de chaque ligne :

POST /calculate { "products": "[{ \"idproduct\": <integer>, \"idpaper\": <integer>, \"quantity\": <integer> }]", "shippingmethod": "<string>" }

Réponse:

{ "products": [{ "idproduct": "<integer>", "idpaper": "<integer>", "quantity": "<integer>", "price": "<float>", "total": "<float>" }], "total_products": "<float>", "total_shipping": "<float>", "total_order": "<float>" }

Paramètres envoyés à l'API

  • products: La liste des produits, encodée en JSON dans une chaîne. Chaque produit contient idproduct, idpaper et quantity.
  • shippingmethod: Optionnel : PICKUP ou BPOST. Si présent, total_shipping contient les frais applicables à votre compte ; sinon il vaut 0.

Ajouter des produits

Ajoutez des produits à votre commande en envoyant une requête POST à /orders/{IDORDER}/products :

POST /orders/{IDORDER}/products { "idproduct": "<integer>", "idpaper": "<integer>", "quantity": "<integer>", "fileurl": "<string>", "filename": "<string>", "filesize": "<integer>", "backprint": "<string>" }

Plusieurs produits peuvent être ajoutés en un seul appel :

POST /orders/{IDORDER}/products { "products": [{ "idproduct": "<integer>", "idpaper": "<integer>", "quantity": "<integer>", "fileurl": "<string>", "filename": "<string>", "filesize": "<integer>", "backprint": "<string>" }] }

Réponse:

{ "status": 1, "products": [{ "idproduct": "<integer>", "idpaper": "<integer>", "quantity": "<integer>", "fileurl": "<string>", "filename": "<string>", "filesize": "<integer>" }] }

Paramètres envoyés à l'API

  • idproduct: L'ID unique du produit à ajouter.
  • idpaper: ID du type de papier (1 pour brillant, 2 pour lustre).
  • quantity: Quantité de produit à ajouter.
  • fileurl: URL publique du fichier image à imprimer (obligatoire). Le fichier doit être au format JPEG et rester disponible pendant le traitement de la commande.
  • filename: Nom du fichier image à imprimer.
  • filesize: Taille du fichier en octets.
  • backprint: Texte imprimé au dos de la photo, suivi du nom du fichier (optionnel, 30 caractères maximum). Sur une sous-commande, le libellé de l'enveloppe est utilisé par défaut. Un texte plus long est coupé, pas refusé.

Sous-commandes : une enveloppe par enfant

Pour qu'un lot soit emballé enveloppe par enveloppe (photo scolaire), créez une sous-commande par enveloppe sous la commande principale en appelant /orders/{IDORDER}/suborders :

POST /orders/{IDORDER}/suborders { "label": "<string>" }

Réponse:

{ "status": 1, "order": { "idorder": "<integer>", "label": "<string>", "parent_idorder": "<integer>" } }

Ajoutez ensuite les photos de l'enveloppe avec /orders/{SUBORDER_ID}/products. Le prix, la livraison et la confirmation se gèrent uniquement sur la commande principale : ces appels sur une sous-commande renvoient une erreur. Confirmer la commande principale confirme toutes ses sous-commandes.

Les enveloppes sont emballées dans l'ordre de création des sous-commandes : créez-les triées par classe, puis par enfant. Le libellé est imprimé sur l'étiquette de l'enveloppe et, par défaut, au dos de chaque photo de l'enveloppe.

Une enveloppe qui n'atteint pas le minimum de votre compte (nombre de tirages et montant) entraîne des frais de traitement, ajoutés aux frais de la commande principale. /orders/{IDORDER}/price détaille ces frais par enveloppe. Le champ totalorder d'une sous-commande reste à 0 jusqu'à la confirmation de la commande principale, qui y inscrit le montant de l'enveloppe.

Paramètres envoyés à l'API

  • idorder: L'ID unique de la commande.
  • label: Libellé de l'enveloppe, par exemple « 3A - Dupont Léa » (obligatoire, 100 caractères maximum). Les guillemets sont retirés et « / » est remplacé par « - ». Les caractères hors alphabet latin sont translittérés (Ł devient L).

Prix d'une commande

Avant de confirmer, obtenez le prix unitaire appliqué à chaque produit de la commande en appelant /orders/{IDORDER}/price. Les quantités d'un même produit et d'un même papier sont additionnées pour déterminer le palier :

POST /orders/{IDORDER}/price {}

Réponse:

{ "status": 1, "products": [{ "idformat": "<integer>", "idpapier": "<integer>", "prix": "<float>", "quantite": "<integer>" }], "suborders": [{ "idorder": "<integer>", "label": "<string>", "prints": "<integer>", "total": "<float>", "fee": "<float>" }] }

Le champ suborders détaille chaque enveloppe : nombre de tirages, montant et frais de traitement éventuels.

Paramètres envoyés à l'API

  • idorder: L'ID unique de la commande.

Confirmer la commande

Une fois tous les produits ajoutés, fermez la commande en appelant /orders/{IDORDER}/close :

Une commande confirmée ne peut plus être modifiée.

POST /orders/{IDORDER}/close {}

Réponse:

{ "status": 1, "total_order": "<float>", "products": [{ "idformat": "<integer>", "idpapier": "<integer>", "prix": "<float>", "quantite": "<integer>" }] }

Paramètres envoyés à l'API

  • idorder: L'ID unique de la commande.

Exemple : photos scolaires

Une école, une enveloppe par enfant, livrée à l'école :

  1. POST /orders Créez la commande principale de l'école.
  2. POST /orders/{IDORDER}/shipping-address Indiquez l'adresse de l'école.
  3. POST /orders/{IDORDER}/suborders Créez une sous-commande par enfant, triées par classe puis par enfant.
  4. POST /orders/{SUBORDER_ID}/products Ajoutez les photos de chaque enfant : tirages, pochettes, planches d'identité.
  5. POST /orders/{IDORDER}/price Vérifiez le prix et les frais par enveloppe.
  6. POST /orders/{IDORDER}/close Confirmez : toutes les enveloppes partent en production.

Pour un envoi au domicile d'un parent, créez une commande séparée avec sa propre adresse de livraison.