API Zdalnej Księgowości

Zaloguj się jako admin, otwórz Ustawienia → 🔑 API Zdalnej Księgowości i kliknij „Wygeneruj token".

Token w postaci jawnej jest wyświetlany tylko raz — natychmiast go skopiuj. Serwer przechowuje wyłącznie skrót SHA-256, więc utracony token można jedynie zastąpić rotacją (która unieważnia stary).

Format tokenu: bb_<userId>_<secret>. Wysyłaj go w każdym żądaniu jako Authorization: Bearer <token>.

Body żądania to obiekt JSON z następującymi polami:

• title (string, wymagane) — nazwa transakcji
• amount (number, wymagane) — musi być dodatnie
• type (string, opcjonalne, domyślnie expense) — jedno z expense / income / prepaid_expense / pending_income
• category (string, opcjonalne) — nazwa kategorii
• note (string, opcjonalne) — dowolna notatka
• created_at (string, opcjonalne) — ISO 8601; domyślnie teraz

curl -X POST https://billbook.me/api/ingest \
  -H "Authorization: Bearer bb_<userId>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{"title":"Coffee","amount":120,"type":"expense","category":"Food"}'

# response: 201
{ "id": "...", "created_at": "..." }

Zwraca nazwy kategorii admina w kolejności rozwijanego menu w panelu. Odpowiedź zawiera tylko nazwy — bez id, user id ani danych transakcji.

curl https://billbook.me/api/ingest/categories \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "categories": ["Food", "Rent", "..."] }

Zwraca ostatnio aktualizowane prefiksy tagów (znaczniki #XXX osadzane w tytułach). Domyślnie 20; użyj ?limit=, aby nadpisać (maks. 100).

Zwraca pustą tablicę zamiast błędu, jeśli tabela tag_prefixes jeszcze nie istnieje.

curl "https://billbook.me/api/ingest/tags?limit=20" \
  -H "Authorization: Bearer bb_<userId>_<secret>"

# response: 200
{ "tags": ["#management-fee", "#travel", "..."] }

Wszystkie błędy są w formacie JSON: { "error": "wiadomość" }.

• 401 — brak autoryzacji, błędny format tokenu, odwołany lub niezgodny
• 402 — subskrypcja wygasła; do zapisu wymagane odnowienie
• 405 — metoda nieobsługiwana (np. GET na /api/ingest)
• 501 — brak SUPABASE_SERVICE_ROLE_KEY na serwerze
• 500 — inny błąd wewnętrzny

Z założenia token może pisać tylko do własnej organizacji — nie może podszywać się pod inne org ani czytać istniejących danych:

• user_id zawsze należy do właściciela tokenu; nie da się go sfałszować
• org_id zawsze jest org właściciela; zapisy międzyorganizacyjne są niemożliwe
• Tokeny wydawane są tylko roli admin (manager / staff dostają 403)
• Odpowiedzi nie ujawniają innych wierszy — zwracane jest tylko { id, created_at }
• Unieważnienie działa natychmiast; rotuj w dowolnym momencie z Ustawień

Dodaj akcję „Pobierz zawartość URL", URL https://billbook.me/api/ingest, metoda POST, nagłówki Authorization: Bearer bb_... i Content-Type: application/json, treść jako JSON: {"title":"Kawa","amount":120,"type":"expense"}. Podłącz title i amount do wejścia Skrótu lub zmiennych „Pytaj za każdym razem".