FortiKDS Local API

A POS sends orders straight to a FortiKDS over the store's own network. Nothing goes through the internet or fortikds.com, so orders keep flowing when the internet is down, and a problem at one store never affects another store.

This is version 1. To try it from your computer, use the test tool.

1. Turn it on (restaurant)

  1. On the KDS, choose Local API at setup, or later in Settings > POS.
  2. Settings > POS shows the KDS's address, for example 192.168.1.50, port 9200. Give the KDS a fixed IP address in the router, the same as for a network printer.
  3. In the POS, add the KDS by that address.

2. Connection

  • TCP to the KDS's IP address, port 9200.
  • Each message is one JSON object in UTF-8 on one line, ending with a newline (\n). Blank lines are ignored.
  • A message can be at most 256 KB (262,144 bytes), not counting the newline. A longer one is answered with ERROR MESSAGE_TOO_LARGE, and the KDS closes the connection.
  • Keep the connection open. If it drops, connect again and resend every order message that has no answer yet.
  • Keep both directions open until the answer has arrived. If the POS closes its sending side right after a message, the KDS takes the connection as closed and the answer is not sent.
  • Several POS terminals can be connected to the same KDS at the same time, up to 16. When a 17th connects, the KDS closes the connection it heard from least recently to make room (one in the middle of a message is kept). If all 16 are in the middle of a message, the new connection gets ERROR TOO_MANY_CONNECTIONS, and the KDS closes it.
  • A message must end within 60 seconds of its first byte. Otherwise the KDS answers ERROR INVALID_MESSAGE and closes the connection.
  • Read the KDS's replies. A connection that leaves more than 1 MB of replies unread is closed.
  • One connection can have at most 50 order messages waiting for an answer. More get ERROR BUSY.
  • The POS needs no key or sign-in: any device on the store network can connect, the same as with a network printer.

3. Message shape

POS to KDS:

{"type": "ORDER_NEW", "message_id": "T1-000123", "payload": {}}
  • type: required.
  • message_id: required for ORDER_NEW, ORDER_UPDATE, ORDER_VOID and ORDER_RUSH. Unique for each message: a string (or a number) of up to 128 characters. Replies carry it back exactly as you sent it. Missing: ERROR MISSING_MESSAGE_ID. Longer: ERROR INVALID_MESSAGE.
  • payload: depends on the type.

KDS to POS:

{"type": "ORDER_ACK", "version": "1.0", "timestamp": 1763400000000, "source_id": "a1b2c3", "payload": {}}
  • version: always "1.0" for this version.
  • timestamp: milliseconds since 1970-01-01 UTC.
  • source_id: the KDS's ID (the same as device_id in HANDSHAKE_ACK).
  • Status messages (section 7) also have a top-level message_id.

4. Delivery rules

  • The KDS answers every order message with ORDER_ACK (saved) or ERROR (not saved). Both carry your message_id in payload.message_id.
  • A message refused with ERROR changes nothing. After INTERNAL_ERROR (saving failed, which is rare, for example a full disk), send the same message again.
  • If no answer comes within 10 seconds, or the connection drops, send the same message again with the same message_id. The KDS remembers the last 300 saved messages since the app started: a repeat is not applied twice, it is just answered with ORDER_ACK. Refused messages are not remembered, so a fixed message can be sent again.
  • A repeat is the same message_id with the same type and the same order ID. An ID that comes again with another order (for example from a second terminal, or after a POS restart) is a new message and is applied.
  • After the KDS app restarts, a repeated ORDER_NEW still can't make a line twice: for an order the KDS already has (showing, or among its last 100 finished tickets), it never shows more of a line than its quantity (section 5). Send add_on_sequence with items_added so a repeated batch of added items can't be added twice.
  • After the KDS app restarts it no longer knows the message_ids it saved before. A repeated items_removed then removes its quantity a second time. items_modified, the line's new total, is safe to repeat.
  • Order messages are applied one at a time, in the order the KDS receives them.

5. POS to KDS messages

TypePayloadKDS answers with
HANDSHAKEpos_name, pos_version (both optional)HANDSHAKE_ACK
ORDER_NEWorderORDER_ACK or ERROR
ORDER_UPDATEorder_id, changesORDER_ACK or ERROR
ORDER_VOIDorder_idORDER_ACK or ERROR
ORDER_RUSHorder_id, is_rushORDER_ACK or ERROR
ORDER_ACKmessage_id of a status messagenothing
PINGnothingPONG
HEARTBEAT_ACKnothingnothing (optional answer to HEARTBEAT)

HANDSHAKE is optional. Orders work without it, but it is a quick way to check that the KDS is ready (status in HANDSHAKE_ACK).

ORDER_NEW

Shows a new ticket. The KDS times every ticket from when it receives it, like a printed ticket.

{"type": "ORDER_NEW", "message_id": "T1-000123", "payload": {"order": {
  "id": "ord-5521",
  "order_number": "1042",
  "type": "dine_in",
  "table_number": "12",
  "server_name": "Anna",
  "guest_count": 2,
  "notes": "Birthday, bring the cake last",
  "items": [
    {"id": "ln-1", "name": "Beef Noodle Soup", "name_secondary": "牛肉面", "quantity": 2,
     "modifiers": [{"text": "No cilantro", "type": "removal"}, {"text": "Extra spicy", "type": "addition"}],
     "notes": ["Peanut allergy"]},
    {"id": "ln-2", "name": "Spring Rolls", "quantity": 1}
  ]
}}}

Order fields:

FieldTypeRequiredMeaning
idstring, up to 128 characters and 128 bytes in UTF-8, without + or ~yesYour order's ID. Used by ORDER_UPDATE, ORDER_VOID and ORDER_RUSH. Give every order its own ID and never use it again: an ID that comes again is taken for the same order, so don't use an order number that starts again each day. A letter or digit is 1 byte; a Chinese character is 3. (The KDS uses + and ~ in its own ticket IDs.)
itemsarray of items, at least oneyesWhat the kitchen makes.
order_numberstring or whole numbernoThe number shown on the ticket. A number of fewer than 4 digits shows with zeros in front: 918 shows as #0918.
typedine_in, pickup, delivery, curbside or drive_thrunoOrder type. Default dine_in.
table_numberstring or whole numbernoTable.
customer_namestringnoCustomer name. It shows in the ticket's heading when the order has no table (on a delivery order: when it has no order_source).
server_namestringnoServer name. Kept with the order; this version of FortiKDS doesn't show it.
guest_countwhole number, 0 to 999noGuests. Kept with the order; this version of FortiKDS doesn't show it.
notesstringnoNote for the whole order.
order_sourcestringnoWhere the order came from, e.g. Online or Uber Eats. A delivery ticket shows it in its heading.
is_rushtrue or falsenoShows the ticket as rush.

Item fields:

FieldTypeRequiredMeaning
idstring, up to 128 charactersyesYour line ID, unique within the order, including items added later with items_added. Used by ORDER_UPDATE.
namestringyesItem name.
name_secondarystringnoSecond-language name. Kept with the order; this version of FortiKDS shows only name.
quantitywhole number, 1 to 999noDefault 1.
modifiersarray of modifiersnoOptions for this item.
notesarray of strings, or of objects with textnoSpecial instructions for this item.

Modifier fields:

  • text: string, required.
  • text_secondary: string; kept with the order, this version of FortiKDS shows only text.
  • quantity: whole number, 1 to 999; default 1.
  • type: normal, addition, removal, warning or alert; default normal.

What a modifier's type looks like on the ticket: removal has - in front, alert is red with ! in front, and normal, addition and warning look the same. The KDS never guesses the type from the text. A modifier or note that contains one of the KDS's allergy words (Settings > Orders > Allergy words) shows like alert.

If the KDS already has the order (a ticket of it is showing, or among the last 100 finished tickets), ORDER_NEW never shows more of a line than its quantity in the order: each line is compared with what the order's tickets on the KDS already have, and only the rest shows.

  • If the order's main ticket is still showing, ORDER_NEW is merged into it. The rest is added to it, and a line already on it gets the new name, modifiers and notes; its quantity can go up, never down. The order number and type are replaced. The table, customer name, server name and guest count are replaced when given. is_rush can turn rush on, not off. The order note stays as it was.
  • If the main ticket was already finished (or only the order's added items are showing), the rest shows as a new ticket for the same order, marked as added.
  • A line on a finished ticket, or on a ticket of added items, isn't changed: only more of it can show.

For example, an order had 1 Burger, and its ticket was finished. An ORDER_NEW for the same order with 3 Burgers and 1 Coke shows a new ticket with 2 Burgers and 1 Coke, marked as added.

To change an order, ORDER_UPDATE is clearer.

ORDER_UPDATE

Changes an order that is already on the KDS. changes holds one or more of:

FieldTypeWhat the kitchen sees
items_addedarray of items (same fields as above), at least oneA new ticket for the same order with just these items, marked as added.
add_on_sequencewhole number, 1 to 99999Numbers each batch of items_added (1, 2, 3...). A batch sent again with the same number is not added twice, while the order's tickets are on the KDS or among its last 100 finished tickets.
items_removedarray of {"id", "quantity"}A void slip for the removed quantity (default: 1), also when the line's ticket was already finished.
items_modifiedarray of {"id", "quantity"}The line's new total quantity in the order. What the order's finished tickets already have is taken off, and the tickets still showing get the rest: more shows on the line's newest ticket, less comes off the newest tickets first with a void slip. A finished ticket doesn't change. 0 removes the line from the tickets still showing.
order_metadataobject with table_number, order_number, notesThe table, number or note of the order's tickets changes. notes set to null or "" removes the note.
{"type": "ORDER_UPDATE", "message_id": "T1-000124", "payload": {"order_id": "ord-5521", "changes": {
  "items_added": [{"id": "ln-3", "name": "Iced Tea", "quantity": 2}],
  "add_on_sequence": 1,
  "order_metadata": {"table_number": "14"}
}}}

Each line can appear once per ORDER_UPDATE: in items_removed or items_modified, not both, and a line in items_added can't also be removed or changed in the same message. Otherwise the message is refused with ERROR INVALID_ORDER.

The changes in one ORDER_UPDATE are applied together:

  • items_modified for a line that isn't on a ticket still showing on the KDS (never received, or its ticket was finished or cleared) refuses the whole message with ERROR UPDATE_FAILED, and nothing changes. Asking for no more than the order's finished tickets already have (0 included) is fine.
  • items_removed for a line on a finished ticket shows a void slip. For a line or order the KDS never had, items_removed and order_metadata change nothing and are answered with ORDER_ACK.
  • items_added for an order the KDS doesn't show still shows the added items as a ticket.

ORDER_VOID

Voids the whole order. The kitchen sees a void slip for each of the order's tickets, showing or already finished. An order the KDS doesn't have changes nothing and is answered with ORDER_ACK.

{"type": "ORDER_VOID", "message_id": "T1-000125", "payload": {"order_id": "ord-5521"}}

ORDER_RUSH

{"type": "ORDER_RUSH", "message_id": "T1-000126", "payload": {"order_id": "ord-5521", "is_rush": true}}

is_rush is required: true shows RUSH on the order's tickets and plays the rush sound, false clears it. An order the KDS doesn't show changes nothing and is answered with ORDER_ACK.

6. KDS to POS messages

TypeWhenPayload
HANDSHAKE_ACKAnswer to HANDSHAKEdevice_id, station_name (the KDS's name), status (ready or not_accepting), reason (only when not accepting), active_orders
ORDER_ACKAn order message was savedmessage_id, order_id (the order ID from your message), original_type
ERRORA message was refusederror_code, error_message, message_id (when the refused message had one)
PONGAnswer to PINGnothing
HEARTBEATEvery 30 seconds while connectedactive_orders, avg_ticket_time_seconds, late_orders
ORDER_BUMPEDThe kitchen finished a ticketsee section 7
ITEM_BUMPEDThe kitchen finished, partly finished or undid one itemsee section 7
ITEM_FORWARDEDThe kitchen sent an item to another KDSsee section 7
ORDER_RECALLEDThe kitchen brought a finished ticket backsee section 7

active_orders is the number of tickets showing (void slips are not counted), late_orders the number of those that are late, and avg_ticket_time_seconds the middle (median) time the kitchen took to finish an item over the last hour, in whole seconds. The numbers follow the tickets as they turn late.

7. Status messages

ORDER_BUMPED, ITEM_BUMPED, ITEM_FORWARDED and ORDER_RECALLED go to every POS connected to that KDS, only while it is set to Local API. Each has a top-level message_id. Answer with:

{"type": "ORDER_ACK", "payload": {"message_id": "ORDER_BUMPED-a1b2c3-ord-5521-1763400000000-7"}}

Without that answer, the KDS sends the same message again every second, at most 8 times in all. An answer from any connected POS stops the repeats. A status message and its repeats go only to the POS connected when it was first sent; a POS that connects later doesn't get it.

In every status message, pos_order_id is your order ID, and order_id is the KDS ticket's ID. They are the same for the ticket made by ORDER_NEW; a ticket of added items has its own order_id.

  • ORDER_BUMPED: order_id, pos_order_id, order_number, bumped_at (milliseconds), duration_seconds, station, items (each: item_id, item_name, quantity, remaining_quantity, is_completed).
  • ITEM_BUMPED: order_id, pos_order_id, item_id, item_name, quantity, remaining_quantity, is_completed, station. It is also sent when the kitchen finishes part of a line or undoes it: check is_completed and remaining_quantity.
  • ITEM_FORWARDED: order_id, pos_order_id, item_id, item_name, quantity, delta_quantity, from_station_id, from_station, to_station_id, to_station.
  • ORDER_RECALLED: order_id, pos_order_id.

8. Errors

error_codeMeaningWhat to do
INVALID_MESSAGEThe line isn't a JSON object, its message_id is longer than 128 characters, or the message didn't end within 60 seconds (the KDS then closes the connection).Fix the message.
MESSAGE_TOO_LARGEOver 256 KB. The KDS closes the connection.Send smaller messages.
UNKNOWN_TYPEtype is missing or not supported.Check the type.
TOO_MANY_CONNECTIONSAll 16 POS connections are in the middle of a message. The KDS closes this one.Connect again in a moment.
BUSYThis connection already has 50 order messages waiting for an answer.Wait for their answers, then send again.
MISSING_MESSAGE_IDAn order message without message_id.Add a unique message_id.
INVALID_ORDERA field is missing, has the wrong type or is out of range, or a line is changed twice. error_message names the field.Fix the field.
NOT_ACCEPTINGThe KDS isn't set to Local API, isn't signed in to its FortiKDS account, or its location's plan isn't active. error_message says which.Show the reason to staff, and send again later.
UPDATE_FAILEDA line in items_modified isn't on a ticket showing on the KDS. Nothing changed.Check the IDs.
INTERNAL_ERRORThe KDS couldn't save the message.Send the same message again.

9. Version

This is version 1 ("version": "1.0"). New optional fields may be added later; ignore fields you don't know. A change that breaks version 1 will get a new version number.

10. Test tool

A small test POS for your computer. It sends test orders to a FortiKDS and shows every line the KDS sends back. It is one Python file and needs only Python 3.8 or newer.

Download fortikds-test-pos.py

Run it on a computer on the store network. Put the KDS's address from Settings > POS in place of 192.168.1.50. On some computers the command is python3.

python fortikds-test-pos.py 192.168.1.50 hello
python fortikds-test-pos.py 192.168.1.50 new ord-1
python fortikds-test-pos.py 192.168.1.50 add ord-1 --seq 1
python fortikds-test-pos.py 192.168.1.50 void ord-1

Usage:

python fortikds-test-pos.py HOST [--port 9200] [--wait SECONDS] COMMAND [args]
CommandWhat it does
helloSends HANDSHAKE and shows the HANDSHAKE_ACK.
new [ORDER_ID]Sends a sample ORDER_NEW: 2 items (lines ln-1 and ln-2), table 12. Without ORDER_ID, the order ID is test- and the time in milliseconds.
add ORDER_ID [--seq N]Sends ORDER_UPDATE with one item in items_added and add_on_sequence N (1 to 99999; default 1). The item is line ln-3 for N=1, ln-4 for N=2, and so on.
table ORDER_ID TABLESends ORDER_UPDATE with a new table_number in order_metadata.
remove ORDER_ID ITEM_ID [QTY]Sends ORDER_UPDATE with items_removed.
qty ORDER_ID ITEM_ID QTYSends ORDER_UPDATE with items_modified: the line's new total quantity.
rush ORDER_ID on|offSends ORDER_RUSH.
void ORDER_IDSends ORDER_VOID.
send FILESends any JSON message from a file, as one line. Adds a message_id if the file has none.
listenStays connected and shows what the KDS sends, until Ctrl+C.
  • Each line the tool sends is shown after >>, and each line it receives after <<.
  • After the answer, it keeps listening for 3 seconds, or for the seconds given with --wait.
  • It answers ORDER_BUMPED, ITEM_BUMPED, ITEM_FORWARDED and ORDER_RECALLED with ORDER_ACK, as your POS must.
  • Exit code: 0 when the KDS answered with ORDER_ACK (HANDSHAKE_ACK for hello), 1 on ERROR, 2 when no answer came within 10 seconds, there was no connection, or the command line was wrong.

To test a repeat, put an order message with a fixed message_id in a file and send it twice. If the first one is saved, the KDS answers both with ORDER_ACK but applies the message once.