FD1 SalesBuilder

SalesBuilder functions are used to create and manipulate sales as they are assembled. SalesBuilder implements shopping cart functionality or allows you to create instore checkouts. If your app is creating a sale, then you probably wish to use salesbuilder to create them. You can simply upload a completed sale definition instead, however that means you must implement all logic and business rules and get it correct.

SalesBuilder is a very expansive set of endpoints, as retail isn't quite as simple as just products and payments. There is a core set of key APIs that are used and a range of optional extras. Some APIs allow you to upload a complete sale definition (PUT/PATCH in HTTP terms), but most are function calls to manipulate a sale object.

Using FD1 to manage sale state

With this approach, your App provides most of the user interface, and FD1 APIs provide the support logic. For example, if the customer in the example below has contract pricing, this is applied automatically, and returned in the JSON sale.

The key advantage of this approach is that your App implicitly gets access to all (vast majority) business logic and pricing functionality.

Manage Sale State yourself

This is the classic "build a sale object" and store that into Fieldpine. Typically used by eCommerce webservers. While this looks attractive to most developers it has shortcomings in enforcing business rules and pricing. With this approach, everytime the retailer enables or uses a new pricing method, it may need to be retrofitted to your code, ergo duplicate code paths, more testing, more support issues.

Of course it has advantages too, no reliance on an external API and potentially less to learn. You can use either, and there is a inbetween ground too, where you can validate the sale at various points, and maybe tell the customer "price will be finalised when sale completed"

Contents - Core Endpoints

Contents - All Endpoints

How To Guides

• Add barcode scanner support for browser based applications
• Add scales support for selling weighed items
• Best practices for apps. What to think about and implement

salesbuilder.salesbuilder_create

Creates a single new sale allowing you to add items, payments, customer details and other values.

Available: WebSocket Fieldpine.JS

{
  a: "fd1.salesbuilder.salesbuilder_create",
}

{
  r: "fd1.salesbuilder.salesbuilder_create",
  data: {
       physkey: "jafj459385hggdg39vgcg53038qQQ8",
       startdt: "2024-02-04 14:45:23",
       ...
    }
  }
}

salesbuilder.sale_fetch

Example

{
  a: "fd1.salesbuilder.sale_fetch",
  k: "jafj459385hggdg39vgcg53038qQQ8"
}

salesbuilder.sale_get_price

Example

{
  a: "fd1.salesbuilder.sale_get_price",
  rq: 92838,
  k: "jafj459385hggdg39vgcg53038qQQ8",
  v: {
    pid: [ 1256, 8231 ]
  }
}

{
  r: "fd1.salesbuilder.sale_park",
  rp: 92838,
  k: "jafj459385hggdg39vgcg53038qQQ8",
  data: {
    rows: [
        { pid: 1256, price: 19.95 },
        { pid: 8231, price: 17.20 }
    ]
  }
}

Alternatively a key/value response format can be requested; this may be easier to work with in some circumstances

{
  a: "fd1.salesbuilder.sale_get_price",
  rq: 92838,
  k: "jafj459385hggdg39vgcg53038qQQ8",
  v: {
    _format: "kv",
    pid: [ 1256, 8231 ]
  }
}

{
  r: "fd1.salesbuilder.sale_park",
  rp: 92838,
  k: "jafj459385hggdg39vgcg53038qQQ8",
  data: {
    kv: {
        "1256": 19.95,
        "8231": 17.20
    }
  }
}

salesbuilder.sale_add_product

salesbuilder.sale_edit_product

salesbuilder.sale_set_delivery_address

salesbuilder.sale_set_customer

salesbuilder.sale_add_payment

salesbuilder.sale_edit_payment

salesbuilder.sale_invoke_eftpos

Starts an integrated Eftpos payment sequence. The exact action varies depending on the Eftpos provider in use.

Example

{
  a: "fd1.salesbuilder.sale_invoke_eftpos",
  k: "jafj459385hggdg39vgcg53038qQQ8",
  v: {
    amount: 56.00
  }
}

salesbuilder.sale_park

Example

{
  a: "fd1.salesbuilder.sale_park",
  k: "jafj459385hggdg39vgcg53038qQQ8"
}

{
  r: "fd1.salesbuilder.sale_park",
  k: "jafj459385hggdg39vgcg53038qQQ8"
}

salesbuilder.sale_unpark

Example

{
  a: "fd1.salesbuilder.sale_unpark",
  k: "jafj459385hggdg39vgcg53038qQQ8"
}

{
  r: "fd1.salesbuilder.sale_unpark",
  k: "jafj459385hggdg39vgcg53038qQQ8",
  data: {
    ... sale definition ...
  }
}

salesbuilder.sale_void

Marks a sale as void and stores it for audit purposes.

Example

{
  a: "fd1.salesbuilder.sale_void",
  k: "jafj459385hggdg39vgcg53038qQQ8"
}

{
  r: "fd1.salesbuilder.sale_void",
  k: "jafj459385hggdg39vgcg53038qQQ8"
}