НачалоФункцииЦениЗа насКонтактиRoadmap

Решения

Дигитално менюAR меню с 3DОнлайн поръчкиСобствена доставкаКухненски дисплей (KDS)HACCP дневнициСайт за ресторантФискални устройства (POS)
За разработчици · API 1.0.0

FudiAR API

REST API и подписани webhooks за данните на един ресторант: меню, поръчки, сметки, фискални бонове, фактури, склад и дневни отчети. JSON, суми в евро, време в UTC.

За кого е

Счетоводни програми

Четат боновете, сторната, фактурите и дневния отчет по ДДС групи - числата, които са на касовата бележка, не на поръчката.

Агрегатори за доставка

Пишат поръчки направо в кухнята на ресторанта с POST /orders - със същите цени, наличности и 86 като менюто, идемпотентно по вашия номер.

ERP и BI

Заприхождават доставки от доставчик в склада и четат наличности и движения - средната цена и партидите се смятат както в админа.

Достъп

Ключовете се създават от собственика в Админ → API и webhooks. API-то е част от плана Business. Ключът се показва веднъж, принадлежи на един ресторант, носи права (scopes) и може да се ограничи до IP адреси и да се отмени по всяко време. Всяка заявка го подава в заглавката:

curl https://fudiar.com/api/v1/menu \
  -H "Authorization: Bearer fudiar_live_<prefix>_<secret>"

Права (scopes)

x:write включва x:read.

ScopeКакво позволява
menu:readRead the menu - categories, dishes, modifiers, prices, availability.
orders:readRead orders and their items.
orders:writeCreate orders (implies orders:read).
bills:readRead bills, payments and the fiscal references of a bill.
fiscal:readRead fiscal documents - receipts, stornos, X/Z reports, cash in/out.
invoices:readRead invoices and credit notes.
stock:readRead stock levels and the stock movement ledger.
stock:writePost supplier deliveries (implies stock:read).
reports:readRead the daily sales summary.

Endpoints

Базов адрес https://fudiar.com. Пълните схеми на заявките и отговорите са в openapi.yaml (OpenAPI 3.1) - отваря се в Swagger UI, Postman, Insomnia.

Meta

GET/api/v1API index
GET/api/v1/openapi.yamlThis OpenAPI document

Menu

GET/api/v1/menumenu:readMenu - categories and dishes

Orders

GET/api/v1/ordersorders:readList orders
POST/api/v1/ordersorders:writeCreate an order
GET/api/v1/orders/{id}orders:readGet an order

Bills

GET/api/v1/billsbills:readList bills
GET/api/v1/bills/{id}bills:readGet a bill

Fiscal

GET/api/v1/fiscal-documentsfiscal:readList fiscal documents
GET/api/v1/fiscal-documents/{id}fiscal:readGet a fiscal document

Invoices

GET/api/v1/invoicesinvoices:readList invoices and credit notes
GET/api/v1/invoices/{id}invoices:readGet an invoice

Stock

GET/api/v1/stock/levelsstock:readStock levels
GET/api/v1/stock/movementsstock:readStock movements
POST/api/v1/stock/documentsstock:writePost a supplier delivery

Reports

GET/api/v1/reports/dailyreports:readDaily sales summary

Конвенции

  • Успех: { "data": … }; списъците добавят next_cursor. Грешка: { "error": { "code", "message" } }. Всеки отговор носи x-request-id.
  • Суми - числа в евро, закръглени до стотинка, с currency: "EUR". Време - ISO-8601 в UTC.
  • Списъците са от най-новото, по created_at и id. Подайте limit и next_cursor от предишната страница като cursor; from / to филтрират по време на създаване.
  • Фискалните номера (device_receipt_number, unique_sale_number) идват само от фискалното устройство. Телефон, имейл и адрес на гост не се връщат никога.
  • POST /orders и POST /stock/documents са идемпотентни по вашия external_id: повторът връща вече създадения обект с 200, друго съдържание със същия номер е 409.

Грешки

HTTPcodeКога
400invalid_requestНевалидна заявка - съобщението казва какво да поправите.
401unauthorized / key_revokedЛипсващ, грешен, изтекъл или отменен ключ.
403forbidden_scope / ip_not_allowed / plan_requiredКлючът няма правото, IP адресът не е разрешен или планът не включва API-то.
404not_foundНяма такъв обект в този ресторант.
409conflictСъщият external_id с друго съдържание, вече въведена фактура на доставчик или ресторантът не приема поръчката в момента.
429rate_limitedТвърде много заявки - изчакайте Retry-After секунди.

Лимити

Лимитът е на ключ (по подразбиране 120 заявки в минута; ресторантът може да зададе друг за всеки ключ). Над него отговорът е 429 rate_limited със заглавка Retry-After в секунди.

Webhooks

Адресите (само https) и събитията им се добавят в същия екран. FudiAR изпраща POST с JSON { id, type, created_at, data } и заглавки FudiAR-Signature, FudiAR-Event, FudiAR-Delivery. Всеки отговор 2xx е доставка; иначе има повторни опити с нарастващ интервал до 24 часа, а 410 Gone изключва адреса. Ползвайте id на събитието за дедупликация.

СъбитиеКога
order.createdA new order. Any new order - from the menu, a waiter, the till, the kiosk or this API. Fetch the full order with `GET /api/v1/orders/{id}`.
bill.paidA bill was paid
fiscal.printedA receipt or storno was printed by the fiscal device. Installation test receipts do not fire this event.
invoice.issuedAn invoice or credit note was issued
stock.lowA stock item fell below its minimum. At most once per item per day and endpoint.

Проверка на подписа

FudiAR-Signature: t=<unix>,v1=<hex>, където v1 = HMAC-SHA256(тайна, "t.тяло") върху суровото тяло на заявката. Отхвърляйте подписи, по-стари от 5 минути. Пример за Node.js:

import { createHmac, timingSafeEqual } from "node:crypto";

// rawBody: the request body EXACTLY as received (a string/Buffer, not re-serialized JSON).
export function verifyFudiarSignature(header, rawBody, secret, toleranceSec = 300) {
  const parts = Object.fromEntries(header.split(",").map((kv) => kv.trim().split("=", 2)));
  const t = Number(parts.t);
  if (!Number.isInteger(t) || !parts.v1) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // replay protection
  const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest();
  const given = Buffer.from(parts.v1, "hex");
  return given.length === expected.length && timingSafeEqual(given, expected);
}

Промени

v1Първа публична версия: меню, поръчки (четене и създаване), сметки, фискални документи, фактури, склад (наличности, движения, доставки), дневен отчет и webhooks. Промени в v1 са само добавящи - нови полета и endpoints, без премахване.