API Reference, FuturWeb web services

Introduction

The Futurlog Web Services (FuturWeb) enable information exchange between your systems and Futurlog. The principle: your applications call our services to push (downstream) your catalogues and orders, and to pull (upstream) stock levels, statuses and tracking. The API is REST and exchanges JSON.

Authentication

Each call authenticates directly in the URL, via your merchant code, your login and your key. The general structure of a request is:

https://jws.futurlog.com/{Application}/{Action}/{MerchantCode}/{Login}/{Key}/{Parameter}

Parameter	Description
MerchantCode	Your merchant code, 3 alphanumeric characters.
Login	Your identifier. In the test environment, it is suffixed with `-test`.
Key	Your 64-character secret key `[a-Z0-9]`. Distinct between test and production.

Test vs production. The test environment uses a login suffixed with -test and a different key. Validate your integrations in test before switching to production credentials.

Format & error handling

All requests send the Accept: application/json header. A successful response returns an HTTP 200 code (a boolean for creations, a list for reads). On failure, the body contains an Error object:

{
  "Error": {
    "Message": "...",
    "Code": "E_UNKNOWN_MERCHANT",
    "Data": [ { "Key": "...", "Value": "..." } ]
  }
}

Orders

POST

Create a new order

Submits an order to be picked and dispatched. The order number is mandatory and must be unique.

/Order/CreateNewOrder/{merchantCode}/{login}/{key}

Body: Order object (see models)
Response: Boolean · HTTP 200

E_UNKNOWN_USER_OR_KEYE_UNKNOWN_MERCHANTE_NO_ORDERE_NO_ORDER_LINEE_NO_ORDER_NUMBERE_ALREADY_EXISTING_ORDERE_UNKNOWN_ERROR

GET

Get order progress

Retrieves shipments (statuses, parcels, tracking) from a given date. Recommended to call at the end of the day.

/Order/GetShipments/{merchantCode}/{login}/{key}/{dateFromUtc}

Parameter: dateFromUtc — yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss
Response: List of ShipmentReturn · HTTP 200

E_UNKNOWN_USER_OR_KEYE_UNKNOWN_MERCHANTE_UNKNOWN_ERROR

GET

Get the list of statuses

Reference list of order statuses (40 statuses, codes 1 to 490).

/Order/GetStates/{merchantCode}/{login}/{key}

Response: List of StateReturn · HTTP 200

GET

Get my carrier list

/Order/GetCarriers/{merchantCode}/{login}/{key}

Response: List of CarrierReturn · HTTP 200

GET

Get the list of orders in error

/Order/GetOrderErrors/{merchantCode}/{login}/{key}

Response: List of OrderErrorReturn · HTTP 200

POST

Create a new expected return

Notifies an expected customer return to the warehouse (for quality control and restocking).

/Order/CreateNewExpectedReturn/{merchantCode}/{login}/{key}

Body: ExpectedParcelReturn object
Response: Boolean · HTTP 200

E_UNKNOWN_USER_OR_KEYE_UNKNOWN_MERCHANTE_NO_ORDERE_UNKNOWN_PRODUCT_CODEE_NO_RETURN_LINE_QUANTITYE_UNKNOWN_BRANDE_UNKNOWN_ERROR

GET

Get the list of returned orders

/Order/GetReturns/{merchantCode}/{login}/{key}/{dateFromUtc}

Parameter: dateFromUtc — yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss
Response: List of OrderReturn · HTTP 200

Products & stock

POST

Declare / update a product

CreateNewProduct creates the product (or updates it if it already exists). UpdateProduct updates it (or creates it if it does not exist).

/Product/CreateNewProduct/{merchantCode}/{login}/{key}

/Product/UpdateProduct/{merchantCode}/{login}/{key}

Body: Product object
Response: Boolean · HTTP 200

E_UNKNOWN_USER_OR_KEYE_UNKNOWN_MERCHANTE_NO_PRODUCT_CODEE_UNKNOWN_ERROR

POST

Declare / update products in bulk

/Product/CreateNewProducts/{merchantCode}/{login}/{key}

/Product/UpdateProducts/{merchantCode}/{login}/{key}

Body: List of Product
Response: Boolean · HTTP 200

If an error occurs on one product, no product is saved / modified (atomic transaction).

POST

Delete a product

/Product/DeleteProduct/{merchantCode}/{login}/{key}/{productCode}

Parameter: productCode — code of the product to delete
Response: Boolean · HTTP 200

E_NO_PRODUCT_CODEE_UNKNOWN_PRODUCT_CODEE_UNKNOWN_MERCHANTE_UNKNOWN_ERROR

GET

Get stock levels

Stock levels available for sale. Without productCode, returns all products. Daily recalculation at the end of the day.

/Product/GetStocks/{merchantCode}/{login}/{key}/{productCode}

Parameter: productCode — optional
Response: List of StockReturn · HTTP 200

GET

Get the list of products in error

/Product/GetProductErrors/{merchantCode}/{login}/{key}

Response: List of ProductErrorReturn · HTTP 200

Receipts

POST

Create a new expected receipt

Notifies an upcoming goods receipt at the warehouse.

/Product/CreateNewExpectedReceipt/{merchantCode}/{login}/{key}

Body: Receipt object
Response: Boolean · HTTP 200

E_NO_RECEIPTE_ALREADY_EXISTING_RECEIPTE_NO_RECEIPT_LINEE_NO_SCHEDULED_DATEE_NO_SUPPLIER_NAMEE_UNKNOWN_PRODUCT_CODEE_NO_RECEIPT_LINE_QUANTITY

GET

Get the list of receipts

/Product/GetReceipts/{merchantCode}/{login}/{key}/{dateFromUtc}

Parameter: dateFromUtc — yyyy-MM-dd or yyyy-MM-ddTHH:mm:ss
Response: List of ReceiptReturn · HTTP 200

Data models

Objects sent / received, exhaustive field list. (M) = mandatory, (M/O) = mandatory or optional depending on your FuturLog settings, string[n] = max length n, ? = nullable. Unannotated fields are optional.

Order request

{
  "OrderNumber": "string[9]",                // (M) unique
  "BrandCode": "string[3]",                  // (M/O) brand code
  "CurrencyCode": "string[3]",               // currency (EUR, USD, ...)
  "CustomerNumber": "string[50]",            // customer order no. (B2B)
  "Language": "string[2]",                   // brand language
  "Incoterm": "string[3]",
  "DateUtc": "datetime?",                    // order date
  "ScheduledTransmissionDate": "datetime?",  // scheduled transmission to logistics
  "MerchantCarrierCode": "string[7]",        // merchant carrier: code
  "MerchantCarrierLabel": "string[50]",      // merchant carrier: name
  "ShippingServiceCode": "string[3]",        // A2P, CIT, BPR, CDI, ACP, DOM, RDV, MRL...
  "StockType": "string[3]",              // stock type (STD, DEF, BLQ), STD by default
  "PickerComments": "string[500]",           // picker comment
  "EshopId": "string", "EshopCustom1": "string",     // e-shop ref. / info
  "CustomInvoiceBase64": "string",          // custom invoice (Base64)
  "CustomDocumentBase64": "string",         // custom document (Base64)
  "Address": {                                    // (M) delivery address
    "CorporateName": "string[100]",
    "LastName": "string[50]", "FirstName": "string[50]",
    "Address1": "string[35]",              // (M)
    "Address2": "string[35]", "Address3": "string[35]",
    "ZipCode": "string[10]",               // (M)
    "City": "string[50]",                  // (M)
    "ProvinceCode": "string[2]",            // US / Canada
    "CountryCode": "string[2]",             // (M)
    "MobilePhone": "string[30]",            // (M)
    "Phone": "string[30]",
    "Email": "string[100]",
    "PickupPointNumber": "string[10]",       // pickup point
    "Comments": "string[500]"
  },
  "Billing": {                                    // billing
    "CorporateName": "string[50]",
    "LastName": "string[50]", "FirstName": "string[50]",
    "Address1": "string[35]",              // (M)
    "Address2": "string[35]", "Address3": "string[35]",
    "ZipCode": "string[10]",               // (M)
    "City": "string[50]",                  // (M)
    "ProvinceCode": "string[2]",            // US / Canada
    "CountryCode": "string[2]",             // (M)
    "BillNumber": "string[50]",            // invoice no.
    "TotalAmount": "decimal?",            // (M) order total incl. VAT
    "ShipmentPrice": "decimal?",          // shipping cost incl. VAT
    "ShipmentVAT": "decimal?",            // (M/O) shipping VAT rate
    "Discount": "decimal?", "DiscountHT": "decimal?", "DiscountTTC": "decimal?"  // discount (excl./incl. VAT per settings)
  },
  "Gift": {                                       // gift
    "Message": "string",                   // gift card message
    "PackageType": "int?"                  // gift wrap type
  },
  "OrderLines": [ {                               // (M) order lines
    "ProductCode": "string[30]",            // (M) product ref.
    "InternalProductCode": "string[30]",    // (M) internal ref.
    "ProductLabel": "string[120]",         // (M)
    "ProductBatchNumber": "string[30]",      // batch no.
    "Quantity": 0,                         // (M)
    "UnitPrice": "decimal?", "UnitPriceHT": "decimal?", "UnitPriceTTC": "decimal?",  // (M/O) unit price (excl./incl. VAT per settings)
    "VATRate": "decimal?"                  // (M/O) VAT rate
  } ]
}

Product request

{
  "Code": "string[30]",               // (M) product code
  "Label": "string[120]",            // (M) product label
  "BarCode": "string[60]",           // barcode
  "BrandCode": "string[3]",          // brand code
  "ExternalCode": "string[60]",      // supplier code
  "HsCode": "string[10]",            // customs (HS) code
  "OriginCountryCode": "string[2]",  // country of origin
  "Family": "string[100]",           // product category
  "Model": "string[100]", "Color": "string[50]", "Size": "string[100]",
  "Type": "string[100]",            // 'p' = physical, 'v' = virtual
  "Weight": "decimal?",             // weight in kg
  "Height": "decimal?", "Width": "decimal?", "Length": "decimal?",   // dimensions in cm
  "UnitPriceHT": "decimal?",        // last price excl. VAT
  "TvaRate": "decimal?",            // VAT rate
  "WeePrice": "decimal?",           // eco-participation fee
  "AlertThreshold": 0,               // low-stock alert threshold
  "IsActive": true, "IsLotManaged": false,
  "PictureUrl": "string[300]",       // image URL
  "EshopId": "string", "EshopCustom1": "string",     // e-shop ref. / info
  "Parameter1": "string", "Parameter2": "string",  // custom parameters
  "ProductsInBundle": [ { "Code": "string[30]", "Quantity": 1 } ]  // components (if this is a bundle)
}

Receipt request expected receipt

{
  "ScheduledDate": "datetime",      // (M) expected receipt date
  "StockType": "string[3]",    // target stock type: STD (default), DEF (defective), BLQ (blocked)
  "SupplierName": "string[100]",    // (M) supplier
  "ReceiptNumber": "string[12]",    // receipt no.
  "CarrierName": "string[100]",     // carrier
  "DeliveryComments": "string[500]", // delivery comment
  "ReceiptLines": [ {                       // (M) receipt lines
    "ProductCode": "string[30]",          // (M) product ref.
    "Quantity": 0                        // (M) announced quantity
  } ]
}

StockReturn response

{
  "Data": [ {
    "Code": "string[30]",
    "AvailableQuantity": 0,
    "ReservedQuantity": 0,
    "BatchesStock": [ { "Number": "string[50]", "OnHandQuantity": 0 } ]
  } ]
}

Other available response structures: ShipmentReturn (orders, parcels, tracking), ReceiptReturn, OrderReturn, CarrierReturn, StateReturn, OrderErrorReturn, ProductErrorReturn.

Error codes

Returned in the Error.Code object. Main codes by domain:

Domain	Codes
Authentication	E_UNKNOWN_USER_OR_KEY · E_UNKNOWN_MERCHANT
Order	E_NO_ORDER · E_NO_ORDER_LINE · E_NO_ORDER_NUMBER · E_ALREADY_EXISTING_ORDER · E_ORDER_NUMBER_TOO_LONG · E_NO_COUNTRY_CODE · E_UNKNOWN_CARRIER · E_UNKNOWN_BRAND · E_NO_ADDRESS · E_NO_ZIPCODE · E_NO_EMAIL · E_INVALID_EMAIL · E_INVALID_TOTAL_AMOUNT
Product	E_NO_PRODUCT_CODE · E_UNKNOWN_PRODUCT_CODE · E_PRODUCT_CODE_TOO_LONG · E_NO_PRODUCT_LABEL · E_UNKNOWN_HS_CODE · E_ALREADY_EXISTING_BAR_CODE · E_CIRCULAR_SUBSTITUTION
Receipt	E_NO_RECEIPT · E_ALREADY_EXISTING_RECEIPT · E_NO_RECEIPT_LINE · E_NO_SCHEDULED_DATE · E_NO_SUPPLIER_NAME
General	E_UNKNOWN_ERROR

Need integration support? Speak to a Futurlog expert or consult the web services overview.

Futurlog API Reference

Introduction

Authentication

Format & error handling

Orders

Create a new order

Get order progress

Get the list of statuses

Get my carrier list

Get the list of orders in error

Create a new expected return

Get the list of returned orders

Products & stock

Declare / update a product

Declare / update products in bulk

Delete a product

Get stock levels

Get the list of products in error

Receipts

Create a new expected receipt

Get the list of receipts

Data models

Order request

Product request

Receipt request expected receipt

StockReturn response

Error codes