Endpointy API

Bazowy URL, format odpowiedzi i paginacja

Wszystkie endpointy są dostępne pod adresem https://app.bakepilot.pl/api/v1/. Odpowiedzi są w formacie JSON (UTF-8), daty w formacie ISO 8601, kwoty w walucie dokumentu. Pojedynczy zasób jest w polu data. Listy są stronicowane parametrami limit i offset, a odpowiedź ma pole meta z total (liczba wszystkich pozycji), limit i offset. Pełną, zawsze aktualną specyfikację z możliwością przetestowania na żywo znajdziesz pod /api/v1/docs (Swagger), a maszynowy opis OpenAPI pod /api/v1/openapi.

• Bazowy URL: https://app.bakepilot.pl/api/v1/
• Lista: { data: [...], meta: { total, limit, offset } }; pojedynczy zasób: { data: {...} }
• Paginacja: limit (domyślnie 50, maksymalnie 200; produkty i składniki do 500) i offset (od 0)
• Dokumentacja interaktywna (Swagger): https://app.bakepilot.pl/api/v1/docs
• Specyfikacja OpenAPI: https://app.bakepilot.pl/api/v1/openapi

Otwórz interaktywną dokumentację API (Swagger) (otwiera się w nowej karcie)

Przykład wywołania (curl)

Klucz przekazujesz w nagłówku Authorization: Bearer albo X-API-Key. Poniższe wywołanie pobiera recepturę przeliczoną na 100 sztuk - te same liczby, które zobaczysz na wydruku w aplikacji.

• curl -H "Authorization: Bearer bp_live_TWOJ_KLUCZ" "https://app.bakepilot.pl/api/v1/recipes?limit=20"
• curl -H "Authorization: Bearer bp_live_TWOJ_KLUCZ" "https://app.bakepilot.pl/api/v1/recipes/ID_RECEPTURY?qty=100"
• curl -H "X-API-Key: bp_live_TWOJ_KLUCZ" "https://app.bakepilot.pl/api/v1/wz?status=issued&limit=50"
• curl -X POST -H "Authorization: Bearer bp_live_TWOJ_KLUCZ" -H "Content-Type: application/json" -d '{"customer_name":"Anna Kowalska","customer_phone":"600100200","pickup_date":"2026-10-01T10:00:00","items":[{"product_name":"Jagodzianka","quantity":6,"unit_price":12,"total_price":72}]}' https://app.bakepilot.pl/api/v1/orders

Zamówienia

GET /orders zwraca zamówienia organizacji od najnowszego (parametry limit, offset oraz status). GET /orders/{id} zwraca zamówienie razem z pozycjami (order_items). POST /orders tworzy zamówienie - domyślnie w statusie Szkic (draft), a polem status możesz od razu ustawić confirmed, in_production lub ready. Klient jest dopasowywany po customer_id, numerze telefonu lub NIP-ie albo tworzony automatycznie. Pozycje przekazujesz w polu items.

• GET /orders - lista (limit, offset, status)
• GET /orders/{id} - zamówienie z pozycjami
• POST /orders - utworzenie zamówienia, status domyślny draft (Szkic)
• Wymagane: customer_name, pickup_date, items (minimum jedna pozycja)
• Pozycja: product_name, quantity, unit_price, total_price; product_id, variant_id i configuration opcjonalne
• Dodatkowe pola: payment_method_note (gotowka, przelew, karta, termin), crates_small, crates_medium, crates_large
• Statusy delivered i cancelled nie są dozwolone przy tworzeniu

Klienci

GET /customers zwraca klientów organizacji od najnowszego (limit, offset). POST /customers dodaje klienta. Tworzenie jest idempotentne: jeśli istnieje już klient o tym samym telefonie, e-mailu lub NIP-ie, API zwraca jego id z polem deduplicated: true zamiast tworzyć duplikat - chyba że dodasz parametr ?force=true.

• GET /customers - lista klientów (limit, offset)
• POST /customers - dodanie klienta, odpowiedź { id, deduplicated }
• Wymagane: first_name, last_name
• Opcjonalne: phone, email, nip, address, customer_type (b2c lub b2b), b2b_discount, zgody marketingowe
• Dedup po telefonie, e-mailu lub NIP-ie; ?force=true zawsze tworzy nowego

Produkty

GET /products zwraca katalog produktów organizacji ułożony alfabetycznie - domyślnie tylko aktywne, parametr active=false pokazuje wszystkie, search filtruje po nazwie. GET /products/{id} zwraca produkt z wariantami (product_variants), składem na etykietę, alergenami, wagą netto i terminem przydatności. Produktów nie tworzysz przez API - obsługujesz je w panelu.

• GET /products - katalog (limit do 500, offset, active, search)
• GET /products/{id} - produkt z wariantami, składem i alergenami
• Tworzenie i edycja produktów: w panelu aplikacji

Receptury i składniki (tylko odczyt)

GET /recipes zwraca listę receptur z wydajnością („Z wypieku wychodzi”: yield_unit i portions_count), wagą wypieku i kosztami. GET /recipes/{id} zwraca recepturę ze składnikami: dla każdej pozycji nazwę, ilość w gramach (amount_grams), a przy półproduktach sub_recipe_id. Parametr qty przelicza recepturę na wielkość produkcji w jednostce receptury - w polu scaled_amount_grams dostajesz ilości pomnożone, a w scaling mnożnik i wagę po przeliczeniu. GET /ingredients i GET /ingredients/{id} zwracają bazę składników z cenami za kg, wartościami odżywczymi i nazwą na etykietę.

• GET /recipes - lista (limit, offset, active, search)
• GET /recipes/{id}?qty=100 - receptura przeliczona na 100 sztuk / kg / blach
• Receptura bez ustawionej wydajności: scaling.factor = null i unavailable_reason
• GET /ingredients, GET /ingredients/{id} - baza składników (limit do 500, offset, active, search)
• Uprawnienia klucza: recipes:read, ingredients:read (klucze utworzone wcześniej dostały je automatycznie)

Dokumenty WZ, oferty i umowy (tylko odczyt)

GET /wz zwraca dokumenty WZ od najnowszego (parametr status: issued, invoiced, cancelled), a GET /wz/{id} dokument z pozycjami (wz_items: nazwa produktu, ilość, cena netto i brutto, stawka VAT). GET /offers i GET /offers/{id} zwracają oferty z pozycjami (offer_items), GET /contracts i GET /contracts/{id} umowy z warunkami płatności i datami wysłania oraz podpisania. Dokumentów nie tworzysz przez API - powstają w panelu.

• GET /wz, GET /wz/{id} - dokumenty WZ z pozycjami (uprawnienie wz:read)
• GET /offers, GET /offers/{id} - oferty z pozycjami (offers:read)
• GET /contracts, GET /contracts/{id} - umowy (contracts:read)
• Każda lista przyjmuje limit, offset i status

Obsługa błędów

API zwraca standardowe kody HTTP: 200 (sukces), 201 (utworzono), 400 (błędny JSON), 401 (brak lub błędny klucz), 403 (plan bez API albo klucz bez wymaganego uprawnienia), 404 (zasób nie istnieje w Twojej organizacji), 422 (błędne dane wejściowe albo parametry, np. limit poza zakresem), 429 (limit zapytań, nagłówek Retry-After), 500 (błąd po naszej stronie). Każdy błąd ma format JSON { error: { code, message } }, a komunikat (message) jest po polsku.

• 200 / 201 - sukces / utworzono
• 400 - nieprawidłowy JSON
• 401 - brak lub błędny klucz API
• 403 - plan bez API (kod plan_required) albo klucz bez uprawnienia
• 404 - zasób nie istnieje (także cudzy identyfikator)
• 422 - błędne dane wejściowe lub parametry
• 429 - przekroczono limit 120 zapytań na minutę, nagłówek Retry-After
• 500 - błąd serwera, szczegóły zapisujemy po naszej stronie