NAV Navbar
  • Introduction
  • Overview
  • KDS Cloud Overview
  • KDS Cloud Information
  • KDS Cloud Orders
  • KDS Cloud Notifications
  • Introduction

    The Fresh Technology Integrations API allows for outside parties to send and pull data from the Fresh Technology systems.

    Setup

    Before someone can begin to integrate with the Fresh Technologies Integrations API, please contact Austin Fabel at Fresh Technology to discuss your integration and next steps.

    Getting Started

    Production

    If you are creating an integration for your own use, the above steps will need to be repeated on the Fresh Tools Production environment Fresh Tools. If your integration is intended to be used by your customers, the customer will need to follow the steps above on their Tools account and supply you with the integration token. Tokens are assigned at the account level and will be unique per customer.

    The Integration token will be required for all calls to the Integrations API, if the token is not valid, or has been revoked, the request will fail with a 401 (Unauthorized).

    Overview

    Be sure to check the HTTP syntax to see what headers are required to be sent. Some routes require different headers, however all requests will require the integration token to be sent.

    Environment URL
    demo https://demo-integrations-api.ftservices.cloud
    production https://integrations-api.ftservices.cloud

    Authorization

    Every request on the Integrations API requires 1 header sent.

    KDS Cloud Overview

    KDS Cloud allows for outside integrations to send orders to be displayed on FreshKDS screens. Through the use of KDS Cloud, orders can be sent from any third party system whether on premise or cloud based with the granular control over which screen(s) will receive the orders.

    KDS Cloud Information

    Get KDS Information

    GET /integrators/kds-information HTTP/1.1
    https://demo-integrations-api.ftservices.cloud
    x-integration-token: pUiVhtLDbqmYG312IEJ0UDcjhWXhivXKiZxwoNWBJPeFTDCaZHs7UQgoVKtFLeCt6sJ572WD0Xnh10l2baOiph
    
    HTTP/1.1 200 OK
    content-type: application/json
    
    [
        {
            "id": "81db5db1-b5af-4e45-8767-71fb78e29bdb",
            "name": "Test Location Fresh",
            "address": {
                "zip": "12345",
                "city": "Any Town",
                "line1": "123 Test Lane",
                "line2": null,
                "state": "NV"
            },
            "timezone": "US/Pacific",
            "devices": [
                {
                    "id": "ef837416-c674-40ab-9aa3-eb0f202e8646",
                    "name": "Device 1"
                }
            ]
        }
    ]
    

    GET /integrators/kds-information

    Get KDS Locations

    GET /integrators/kds-information/locations HTTP/1.1
    https://demo-integrations-api.ftservices.cloud
    x-integration-token: pUiVhtLDbqmYG312IEJ0UDcjhWXhivXKiZxwoNWBJPeFTDCaZHs7UQgoVKtFLeCt6sJ572WD0Xnh10l2baOiph
    
    HTTP/1.1 200 OK
    content-type: application/json
    
    [
        {
            "id": "81db5db1-b5af-4e45-8767-71fb78e29bdb",
            "name": "Test Location Fresh",
            "address": {
                "zip": "12345",
                "city": "Any Town",
                "line1": "123 Test Lane",
                "line2": null,
                "state": "NV"
            },
            "timezone": "US/Pacific"
        }
    ]
    

    GET /integrators/kds-information/locations

    KDS Cloud Orders

    Get KDS Active Orders

    GET /integrators/kds-orders/active HTTP/1.1
    host: https://dev-integrations-api.ftservices.cloud
    x-integration-token: 1234567890
    x-location-id: 5fcbcc8c-d637-4d91-a576-9de31ffe7a3d
    x-device-ids: 319fb5bc-6189-4dc6-a1e0-42dbf36177e9 (Comma delimited for multiple devices, value of 'all' for all active devices at location)
    
    HTTP/1.1 200 OK
    content-type: application/json
    
    [
        {
            "deviceId": "49d0d0a9-e7a8-438c-9e14-e26198e637df",
            "deviceName": "Device 2",
            "orderCount": 2,
            "orders": [
                {
                    "orderId": "223456789",
                    "orderName": "2 Test Order"
                },
                {
                    "orderId": "323456789",
                    "orderName": "2 Test Order 2"
                }
            ]
        },
        {
            "deviceId": "74b6041f-c095-47b9-ba4f-340b89142935",
            "deviceName": "Device 3",
            "orderCount": 1,
            "orders": [
                {
                    "orderId": "423456789",
                    "orderName": "3 Test Order"
                }
            ]
        }
    ]
    

    Returns array of requested (all) devices with the orders active and on screen for those devices

    GET /integrators/kds-orders/active

    Send KDS Order

    POST /integrators/kds-orders HTTP/1.1
    host: https://demo-integrations-api.ftservices.cloud
    x-integration-token: 1234567890
    x-location-id: 5fcbcc8c-d637-4d91-a576-9de31ffe7a3d
    x-device-ids: 319fb5bc-6189-4dc6-a1e0-42dbf36177e9 (Comma delimited for multiple devices, value of 'all' for all active devices at location)
    
    HTTP/1.1 200 OK
    content-type: application/json
    
    {
        "orderId" : "d2874775-34e2-4829-8b59-1260e40eca4e",
        "deliveryStatuses": [
            {
                "device": "e1675528-aba9-4b97-8482-a72380870fd5",
                "status": "success"
            }
        ]
    }
    

    POST /integrators/kds-orders

    Additional Headers

    Body Parameters

    KDS Order

    Property Required Type Description
    id yes string Integration order id
    name yes string Order Name/Number
    time yes date Order Date/Time, ISO 8601 Format
    pickupTime no date Pickup Date/Time, ISO 8601 Format
    phoneNumber no string Phone number to contact regarding order
    deliveryAddress no string If order is for delivery, can supply and address for display
    mode yes string Order Mode (For Here, ToGo, Pickup, DriveThru, Delivery, CurbSide) note: if invalid order mode, mode will be added to order name
    server no string Server Name
    source no string Identifier of Integrator. This is for partner integrations with KDS and value to send must be supplied by Fresh Technology. Current accepted values are null or togotechnology.
    items yes KdsItem[] Items
    terminal yes string Pos Terminal
    specialInstructions no string Text based special instructions that will be displayed on the order
    customerArrivedUrl no url If SMS Bolt-On enabled and this value is supplied. This link will be included with the SMS for Order Received and Order Ready for Pickup. This URL should route to integrators system to send the Customer Arrived Notification to KDS
    vehicleModel no string Car Model
    vehicleColor no string Car Color
    retry no object If specified devices are not connected when the order is sent. Values in this object are used for notification and expiration
    costs no Costs Object that contains costs associated with the order
    deliveryService no DeliveryService Object contains information regarding the order if a delivery server is being used

    KDS Item

    Property Required Type Description
    name yes string Order Name/Number
    qty yes int Quantity
    price no string Cost of item, value should be a string and can include the currenty symbol or not
    mods yes string[] Item Modifiers, empty array if none
    specialInstructions no string Text based special instructions that will be displayed on the item

    Retry

    Property Required Type Description
    notificationUrl no string URL to POST final success or failure either upon success or expiration
    expiration no date ISO 8601 Format date when retrys should no longer be attempted. If not supplied, value of 2 minutes from submission time will be used

    NOTE: Order responds will include an array of device id's and status of delivery to the device. If a retry object is specified, KDS Cloud will attempt to deliver until the expiration time. If no expiration time is specified, retry will attempt for 2 minutes.

    Notification POST Data

    If a notificationUrl is provided, when either all deliveries are successful, or the order delivery has expired, a POST will be made to the supplied url

    HTTP/1.1 200 OK
    content-type: application/json
    
    {
      "orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
      "finalStatus": "all-delivered",
      "deliveryStatuses": [
        {
          "device": "e1675528-aba9-4b97-8482-a72380870fd5",
          "status": "success"
        }
      ]
    }
    
    HTTP/1.1 200 OK
    content-type: application/json
    {
      "orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
      "finalStatus": "order-retry-expired",
      "deliveryStatuses": [
        {
          "device": "e1675528-aba9-4b97-8482-a72380870fd5",
          "status": "kds-not-connected"
        }
      ]
    }
    

    Costs

    Property Required Type Description
    subtotal no string Sub total of the order
    tax no string Tax on the order
    deliveryFee no string Delivery Fee for the order
    surcharge no string Surcharge for the order
    convenienceFee no string Convenience Fee for the order
    tip no string Tip on the order
    total no string Total for the order
    promoCodes no promoCodes[] Promo codes for the order

    Promo Codes

    Property Required Type Description
    name no string Name of the promo code
    amount yes string Amount of Promo Code, value should be a string and can include the currenty symbol or not

    Delivery Service

    Property Required Type Description
    name yes string Name of the delivery service
    orderId yes string Delivery Service order Id
    driverPhone no string Phone number of the delivery driver

    KDS Cloud Notifications

    Send KDS Customer Arrived Notification

    KDS has a robust Takeout Management section as well as the standard Kitchen Display. If a customer has enabled that view, any order type they have configured to display there will for fulfillment. Through KDS Cloud, a signal can be sent to the KDS to notify the Takeout Management screen that a customer has arrived.

    POST /integrators/kds-notifications/customer-arrived HTTP/1.1
    host: https://demo-integrations-api.ftservices.cloud
    x-integration-token: 1234567890
    x-location-id: 5fcbcc8c-d637-4d91-a576-9de31ffe7a3d
    x-device-ids: 319fb5bc-6189-4dc6-a1e0-42dbf36177e9 (Comma delimited for multiple devices, value of 'all' for all active devices at location)
    
    HTTP/1.1 200 OK
    content-type: application/json
    
    {
        "orderId" : "d2874775-34e2-4829-8b59-1260e40eca4e",
        "deliveryStatuses": [
            {
                "device": "e1675528-aba9-4b97-8482-a72380870fd5",
                "status": "success"
            }
        ]
    }
    

    POST /integrators/kds-notifications/customer-arrived

    Additional Headers

    Body Parameters

    Property Required Type Description
    id yes string Integration order id. This is the orderId that was returned when submitting the order through KDS Cloud
    source no string Identifier of Integrator. This is for partner integrations with KDS and value to send must be supplied by Fresh Technology. Should not be supplied in most cases.
    retry no object If specified devices are not connected when the order is sent. Values in this object are used for notification and expiration

    Retry

    Property Required Type Description
    notificationUrl no string URL to POST final success or failure either upon success or expiration
    expiration no date ISO 8601 Format date when retrys should no longer be attempted. If not supplied, value of 2 minutes from submission time will be used

    NOTE: Order responds will include an array of device id's and status of delivery to the device. If a retry object is specified, KDS Cloud will attempt to deliver until the expiration time. If no expiration time is specified, retry will attempt for 2 minutes.

    Notification POST Data

    If a notificationUrl is provided, when either all deliveries are successful, or the order delivery has expired, a POST will be made to the supplied url

    HTTP/1.1 200 OK
    content-type: application/json
    
    {
      "orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
      "finalStatus": "all-delivered",
      "deliveryStatuses": [
        {
          "device": "e1675528-aba9-4b97-8482-a72380870fd5",
          "status": "success"
        }
      ]
    }
    
    HTTP/1.1 200 OK
    content-type: application/json
    {
      "orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
      "finalStatus": "order-retry-expired",
      "deliveryStatuses": [
        {
          "device": "e1675528-aba9-4b97-8482-a72380870fd5",
          "status": "kds-not-connected"
        }
      ]
    }
    

    Send KDS Estimated Arrival Update

    KDS has a robust Takeout Management section as well as the standard Kitchen Display. If a customer has enabled that view, any order type they have configured to display there will for fulfillment. Through KDS Cloud, you are able to send an update of estimated arrival time for an order displayed on the Takeout Management section. An example being tracking a delivery driver or customer coming into the restaurant to get the order and allowing the kitchen staff visibility into when the order needs to be ready.

    POST /integrators/kds-notifications/estimated-arrival-update' HTTP/1.1
    host: https://demo-integrations-api.ftservices.cloud
    x-integration-token: 1234567890
    x-location-id: 5fcbcc8c-d637-4d91-a576-9de31ffe7a3d
    x-device-ids: 319fb5bc-6189-4dc6-a1e0-42dbf36177e9 (Comma delimited for multiple devices, value of 'all' for all active devices at location)
    
    HTTP/1.1 200 OK
    content-type: application/json
    
    {
        "orderId" : "d2874775-34e2-4829-8b59-1260e40eca4e",
        "deliveryStatuses": [
            {
                "device": "e1675528-aba9-4b97-8482-a72380870fd5",
                "status": "success"
            }
        ]
    }
    

    POST /integrators/kds-notifications/estimated-arrival-update

    Additional Headers

    Body Parameters

    Property Required Type Description
    id yes string Integration order id. This is the orderId that was returned when submitting the order through KDS Cloud
    minutes yes int Minutes estimated till arrival
    source no string Identifier of Integrator. This is for partner integrations with KDS and value to send must be supplied by Fresh Technology. Should not be supplied in most cases.
    retry no object If specified devices are not connected when the order is sent. Values in this object are used for notification and expiration

    Retry

    Property Required Type Description
    notificationUrl no string URL to POST final success or failure either upon success or expiration
    expiration no date ISO 8601 Format date when retrys should no longer be attempted. If not supplied, value of 2 minutes from submission time will be used

    NOTE: Order responds will include an array of device id's and status of delivery to the device. If a retry object is specified, KDS Cloud will attempt to deliver until the expiration time. If no expiration time is specified, retry will attempt for 2 minutes.

    Notification POST Data

    If a notificationUrl is provided, when either all deliveries are successful, or the order delivery has expired, a POST will be made to the supplied url

    HTTP/1.1 200 OK
    content-type: application/json
    
    {
      "orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
      "finalStatus": "all-delivered",
      "deliveryStatuses": [
        {
          "device": "e1675528-aba9-4b97-8482-a72380870fd5",
          "status": "success"
        }
      ]
    }
    
    HTTP/1.1 200 OK
    content-type: application/json
    {
      "orderId": "3cd27748-741e-4784-9cb8-abcd01285670",
      "finalStatus": "order-retry-expired",
      "deliveryStatuses": [
        {
          "device": "e1675528-aba9-4b97-8482-a72380870fd5",
          "status": "kds-not-connected"
        }
      ]
    }