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:read | Read the menu - categories, dishes, modifiers, prices, availability. |
orders:read | Read orders and their items. |
orders:write | Create orders (implies orders:read). |
bills:read | Read bills, payments and the fiscal references of a bill. |
fiscal:read | Read fiscal documents - receipts, stornos, X/Z reports, cash in/out. |
invoices:read | Read invoices and credit notes. |
stock:read | Read stock levels and the stock movement ledger. |
stock:write | Post supplier deliveries (implies stock:read). |
reports:read | Read the daily sales summary. |
Endpoints
Базов адрес https://fudiar.com. Пълните схеми на заявките и отговорите са в openapi.yaml (OpenAPI 3.1) - отваря се в Swagger UI, Postman, Insomnia.
Meta
Menu
Orders
Bills
Fiscal
Invoices
Stock
Reports
Конвенции
- Успех:
{ "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.
Грешки
| HTTP | code | Кога |
|---|---|---|
| 400 | invalid_request | Невалидна заявка - съобщението казва какво да поправите. |
| 401 | unauthorized / key_revoked | Липсващ, грешен, изтекъл или отменен ключ. |
| 403 | forbidden_scope / ip_not_allowed / plan_required | Ключът няма правото, IP адресът не е разрешен или планът не включва API-то. |
| 404 | not_found | Няма такъв обект в този ресторант. |
| 409 | conflict | Същият external_id с друго съдържание, вече въведена фактура на доставчик или ресторантът не приема поръчката в момента. |
| 429 | rate_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.created | A 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.paid | A bill was paid |
fiscal.printed | A receipt or storno was printed by the fiscal device. Installation test receipts do not fire this event. |
invoice.issued | An invoice or credit note was issued |
stock.low | A 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);
}