Bephoto API

Refer to the documentation below to automate your print orders.

Bephoto API Documentation

Introduction

Sending print orders is done through a REST API. Before being able to make requests to the API, you should first authenticate using the credentials received to obtain an authentication token. The token should be included in the "Authorization" header of every subsequent API request:

Authorization: Bearer <your-authentication-token>

The token is valid for one year. A new token is issued on every authentication.

Live API URL https://api.bephoto.be

Authentication

Authenticate by calling the /user/login endpoint with your credentials:

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

Response:

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

Error Response:

{ "error": "Unauthorized" }

Parameters sent to the API

  • email: The user's email address.
  • password: The user's password.

API Key Authentication

To avoid using a password in your integration, authenticate with an API key by calling /user/loginToken. The key is provided by Bephoto on request, per account:

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

Response:

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

Error Response:

{ "error": "Unauthorised" }

Parameters sent to the API

  • token: The API key provided by Bephoto.

Order Creation

Create a new order by calling /orders with optional metadata. After creating an order, you will receive a unique idorder, which should be used in subsequent calls:

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

Response:

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

Parameters sent to the API

  • metadata: Custom metadata associated with the order. Max length: 255 characters.

Fetching Order

Fetch information for an order by calling /orders/{IDORDER}:

GET /orders/{IDORDER}

Response:

{ "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>" }] } }

The shippingmethod field is PICKUP (collection) or BPOST (delivery to an address). The totalcost field holds the order fees, totalorder the total to pay. A main order also returns its sub-orders (suborders); a sub-order returns the ID of its main order (parent_idorder).

Parameters sent to the API

  • idorder: The unique ID of the order.

Shipping Method

Choose the shipping method by calling /orders/{IDORDER}/shipping/{SHIPPING_METHOD}. Without this call, the order is set to delivery (BPOST). Any other value returns an error.

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

Response:

{ "status": 1 }

Parameters sent to the API

  • idorder: The unique ID of the order.
  • shipping_method: PICKUP for collection, BPOST for delivery to an address. For a delivery, provide the address through /orders/{IDORDER}/shipping-address.

Delivery Address

Set the delivery address of an order by calling /orders/{IDORDER}/shipping-address. The order is then set to delivery. An order has a single address: create one order per recipient.

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

Response:

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

Parameters sent to the API

  • idorder: The unique ID of the order.
  • nom: Recipient's last name (required).
  • prenom: Recipient's first name (required).
  • societe: Company, school or studio (optional).
  • adresse: Street and number (required).
  • complement_adresse: Additional address line (optional).
  • cp: Postal code (required).
  • localite: City (required).
  • pays: Country code, BE by default (optional).
  • email: Recipient's email for shipment tracking (optional).

Fetching Products

Get a list of available print products by calling /products:

GET /products

Response:

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

The price returned is the base unit price. Prices are tiered: the unit price decreases with the total quantity ordered for the same product and paper. Use /calculate or /orders/{IDORDER}/price to get the price actually applied.

Add ?include=montage to also get the montages available on your account (pochettes, ID sheets, school layouts), recognisable by idtypeformat = 100. Each layout is a separate product: choose the layout by choosing the product. Send one photo per montage; the lab composes the sheet.

Returned fields

  • idformat: The unique ID of the product, to send as idproduct.
  • format: The product name.
  • largeur, hauteur: The product dimensions (in millimetres).
  • prix: The base price per paper type: the key is the idpaper, the value the unit price.
  • idtypeformat: 100 for a montage composed by the lab.

Simulating a Price

Calculate the price of a list of products, without creating an order, by calling /calculate. The price tier is applied on the quantity of each line:

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

Response:

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

Parameters sent to the API

  • products: The list of products, JSON-encoded in a string. Each product contains idproduct, idpaper and quantity.
  • shippingmethod: Optional: PICKUP or BPOST. When present, total_shipping holds the fees applicable to your account; otherwise it is 0.

Adding Products

Add products to your order by sending a POST request to /orders/{IDORDER}/products:

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

Several products can be added in a single call:

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

Response:

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

Parameters sent to the API

  • idproduct: The unique ID of the product to add.
  • idpaper: Paper type ID (1 for glossy, 2 for lustre).
  • quantity: Quantity of product to add.
  • fileurl: Public URL of the image file to print (required). The file must be in JPEG format and remain available during order processing.
  • filename: Name of the image file to print.
  • filesize: File size in bytes.
  • backprint: Text printed on the back of the photo, followed by the file name (optional, 30 characters max). On a sub-order, the envelope label is used by default. Longer text is cut, not rejected.

Sub-orders: one envelope per child

To have a batch packed envelope by envelope (school photography), create one sub-order per envelope under the main order by calling /orders/{IDORDER}/suborders:

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

Response:

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

Then add the envelope's photos with /orders/{SUBORDER_ID}/products. Price, shipping and confirmation are handled on the main order only: these calls on a sub-order return an error. Confirming the main order confirms all its sub-orders.

Envelopes are packed in the order the sub-orders were created: create them sorted by class, then by child. The label is printed on the envelope label and, by default, on the back of each photo in the envelope.

An envelope below your account minimum (number of prints and amount) incurs a handling fee, added to the main order's fees. /orders/{IDORDER}/price details these fees per envelope. A sub-order's totalorder stays at 0 until the main order is confirmed, which then records the envelope's amount.

Parameters sent to the API

  • idorder: The unique ID of the order.
  • label: Envelope label, for example "3A - Dupont Léa" (required, 100 characters max). Quotes are removed and "/" is replaced with "-". Characters outside the Latin alphabet are transliterated (Ł becomes L).

Order Price

Before confirming, get the unit price applied to each product of the order by calling /orders/{IDORDER}/price. Quantities of the same product and paper are added up to determine the tier:

POST /orders/{IDORDER}/price {}

Response:

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

The suborders field details each envelope: number of prints, amount and handling fee, if any.

Parameters sent to the API

  • idorder: The unique ID of the order.

Confirming Order

Once all products are added, close the order by calling /orders/{IDORDER}/close:

A confirmed order can no longer be modified.

POST /orders/{IDORDER}/close {}

Response:

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

Parameters sent to the API

  • idorder: The unique ID of the order.

Example: school photography

One school, one envelope per child, delivered to the school:

  1. POST /orders Create the school's main order.
  2. POST /orders/{IDORDER}/shipping-address Set the school's address.
  3. POST /orders/{IDORDER}/suborders Create one sub-order per child, sorted by class, then by child.
  4. POST /orders/{SUBORDER_ID}/products Add each child's photos: prints, pochettes, ID sheets.
  5. POST /orders/{IDORDER}/price Check the price and the fees per envelope.
  6. POST /orders/{IDORDER}/close Confirm: every envelope goes into production.

For delivery to a parent's home, create a separate order with its own delivery address.