This is version 1. To try it from your computer, use the test tool.
1. Turn it on (restaurant)
- On the KDS, choose Local API at setup, or later in Settings > POS.
- Settings > POS shows the KDS's address, for example
192.168.1.50, port9200. Give the KDS a fixed IP address in the router, the same as for a network printer. - 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
ERRORMESSAGE_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
ERRORTOO_MANY_CONNECTIONS, and the KDS closes it. - A message must end within 60 seconds of its first byte. Otherwise the KDS answers
ERRORINVALID_MESSAGEand 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
ERRORBUSY. - 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 forORDER_NEW,ORDER_UPDATE,ORDER_VOIDandORDER_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:ERRORMISSING_MESSAGE_ID. Longer:ERRORINVALID_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 asdevice_idinHANDSHAKE_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) orERROR(not saved). Both carry yourmessage_idinpayload.message_id. - A message refused with
ERRORchanges nothing. AfterINTERNAL_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 withORDER_ACK. Refused messages are not remembered, so a fixed message can be sent again. - A repeat is the same
message_idwith 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_NEWstill 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). Sendadd_on_sequencewithitems_addedso 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 repeateditems_removedthen 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
| Type | Payload | KDS answers with |
|---|---|---|
HANDSHAKE | pos_name, pos_version (both optional) | HANDSHAKE_ACK |
ORDER_NEW | order | ORDER_ACK or ERROR |
ORDER_UPDATE | order_id, changes | ORDER_ACK or ERROR |
ORDER_VOID | order_id | ORDER_ACK or ERROR |
ORDER_RUSH | order_id, is_rush | ORDER_ACK or ERROR |
ORDER_ACK | message_id of a status message | nothing |
PING | nothing | PONG |
HEARTBEAT_ACK | nothing | nothing (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:
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string, up to 128 characters and 128 bytes in UTF-8, without + or ~ | yes | Your 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.) |
items | array of items, at least one | yes | What the kitchen makes. |
order_number | string or whole number | no | The number shown on the ticket. A number of fewer than 4 digits shows with zeros in front: 918 shows as #0918. |
type | dine_in, pickup, delivery, curbside or drive_thru | no | Order type. Default dine_in. |
table_number | string or whole number | no | Table. |
customer_name | string | no | Customer 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_name | string | no | Server name. Kept with the order; this version of FortiKDS doesn't show it. |
guest_count | whole number, 0 to 999 | no | Guests. Kept with the order; this version of FortiKDS doesn't show it. |
notes | string | no | Note for the whole order. |
order_source | string | no | Where the order came from, e.g. Online or Uber Eats. A delivery ticket shows it in its heading. |
is_rush | true or false | no | Shows the ticket as rush. |
Item fields:
| Field | Type | Required | Meaning |
|---|---|---|---|
id | string, up to 128 characters | yes | Your line ID, unique within the order, including items added later with items_added. Used by ORDER_UPDATE. |
name | string | yes | Item name. |
name_secondary | string | no | Second-language name. Kept with the order; this version of FortiKDS shows only name. |
quantity | whole number, 1 to 999 | no | Default 1. |
modifiers | array of modifiers | no | Options for this item. |
notes | array of strings, or of objects with text | no | Special instructions for this item. |
Modifier fields:
text: string, required.text_secondary: string; kept with the order, this version of FortiKDS shows onlytext.quantity: whole number, 1 to 999; default 1.type:normal,addition,removal,warningoralert; defaultnormal.
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_NEWis 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_rushcan 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:
| Field | Type | What the kitchen sees |
|---|---|---|
items_added | array of items (same fields as above), at least one | A new ticket for the same order with just these items, marked as added. |
add_on_sequence | whole number, 1 to 99999 | Numbers 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_removed | array of {"id", "quantity"} | A void slip for the removed quantity (default: 1), also when the line's ticket was already finished. |
items_modified | array 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_metadata | object with table_number, order_number, notes | The 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_modifiedfor 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 withERRORUPDATE_FAILED, and nothing changes. Asking for no more than the order's finished tickets already have (0 included) is fine.items_removedfor a line on a finished ticket shows a void slip. For a line or order the KDS never had,items_removedandorder_metadatachange nothing and are answered withORDER_ACK.items_addedfor 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
| Type | When | Payload |
|---|---|---|
HANDSHAKE_ACK | Answer to HANDSHAKE | device_id, station_name (the KDS's name), status (ready or not_accepting), reason (only when not accepting), active_orders |
ORDER_ACK | An order message was saved | message_id, order_id (the order ID from your message), original_type |
ERROR | A message was refused | error_code, error_message, message_id (when the refused message had one) |
PONG | Answer to PING | nothing |
HEARTBEAT | Every 30 seconds while connected | active_orders, avg_ticket_time_seconds, late_orders |
ORDER_BUMPED | The kitchen finished a ticket | see section 7 |
ITEM_BUMPED | The kitchen finished, partly finished or undid one item | see section 7 |
ITEM_FORWARDED | The kitchen sent an item to another KDS | see section 7 |
ORDER_RECALLED | The kitchen brought a finished ticket back | see 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: checkis_completedandremaining_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_code | Meaning | What to do |
|---|---|---|
INVALID_MESSAGE | The 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_LARGE | Over 256 KB. The KDS closes the connection. | Send smaller messages. |
UNKNOWN_TYPE | type is missing or not supported. | Check the type. |
TOO_MANY_CONNECTIONS | All 16 POS connections are in the middle of a message. The KDS closes this one. | Connect again in a moment. |
BUSY | This connection already has 50 order messages waiting for an answer. | Wait for their answers, then send again. |
MISSING_MESSAGE_ID | An order message without message_id. | Add a unique message_id. |
INVALID_ORDER | A 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_ACCEPTING | The 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_FAILED | A line in items_modified isn't on a ticket showing on the KDS. Nothing changed. | Check the IDs. |
INTERNAL_ERROR | The 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.
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]
| Command | What it does |
|---|---|
hello | Sends 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 TABLE | Sends 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 QTY | Sends ORDER_UPDATE with items_modified: the line's new total quantity. |
rush ORDER_ID on|off | Sends ORDER_RUSH. |
void ORDER_ID | Sends ORDER_VOID. |
send FILE | Sends any JSON message from a file, as one line. Adds a message_id if the file has none. |
listen | Stays 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_FORWARDEDandORDER_RECALLEDwithORDER_ACK, as your POS must. - Exit code:
0when the KDS answered withORDER_ACK(HANDSHAKE_ACKforhello),1onERROR,2when 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.