Klucze API

Publiczne, read-only API do ciągnięcia danych Twojej firmy do własnego BI, ERP albo dashboardu. Tworzysz klucz w panelu konta, dołączasz go w nagłówku zapytania i odpytujesz endpointy /api/v1.

Do czego służy API

Klucze API pozwalają sięgnąć po dane Twojej firmy spoza interfejsu bilans.ai — z arkusza, Power BI, własnego skryptu czy systemu ERP. Zamiast logować się i kopiować liczby ręcznie, Twoja integracja pobiera je automatycznie zapytaniem HTTP.

To jest API tylko do odczytu (read-only). Przez nie możesz czytać faktury, podsumowania i analizy — nie da się nim niczego dodać, zmienić ani usunąć. Import faktur, edycja kategorii czy ustawienia konta zostają wyłącznie w interfejsie webowym i w integracji z KSeF.

Każdy klucz jest przypięty do Twojej firmy (tenanta). Widzi dokładnie te same dane co Ty po zalogowaniu — i tylko je. Klucz innej firmy nigdy nie zobaczy Twoich faktur.

Gdzie znajdziesz panel

Wejdź w Konto → Klucze API. Strona ma trzy części:

  • Referencja endpointów — lista dostępnych adresów API w wersji v1 plus gotowy przykład wywołania przez curl.
  • Formularz tworzenia klucza — pole na nazwę i przycisk „Utwórz klucz".
  • Tabela Twoich kluczy — nazwa, prefiks, data utworzenia, „Ostatnio użyty" i przycisk rewokacji. Klucze zrewokowane zostają na liście (wyszarzone) jako ślad audytowy.

Tworzenie klucza

W formularzu wpisujesz nazwę (2–100 znaków) — to opis dla Ciebie, np. „Integracja z Power BI" albo „Production BI". Nazwa nie wpływa na działanie klucza, służy tylko do rozpoznania go później na liście.

Po kliknięciu „Utwórz klucz" otwiera się okno z pełnym kluczem w formacie bk_live_… i przyciskiem „Kopiuj".

Pełny klucz pokazujemy tylko raz. W bazie trzymamy wyłącznie jego skrót (hash) oraz publiczny prefiks (np. bk_live_abc12345) — nie da się go odtworzyć ani podejrzeć później. Skopiuj go od razu i wklej tam, gdzie ma żyć (zmienna środowiskowa, sekret w integracji). Jeśli zgubisz klucz, jedyne wyjście to go zrewokować i wygenerować nowy.

Jak się autoryzować

Klucz dołączasz do każdego zapytania w nagłówku HTTP. Działają dwa warianty:

  • Authorization: Bearer — standardowy nagłówek, najwygodniejszy w cURL i fetch: Authorization: Bearer bk_live_…
  • X-API-Key — alternatywa, jeśli nagłówka Authorization używasz już do innej autoryzacji: X-API-Key: bk_live_…

Przykład pełnego wywołania:

curl -H "Authorization: Bearer bk_live_…" \
  https://bilans.ai/api/v1/dashboard/summary

Brak nagłówka albo nieprawidłowy/zrewokowany klucz zwracają 401 Unauthorized. Odpowiedzi są w formacie JSON.

Dostępne endpointy

API jest wersjonowane pod prefiksem /api/v1. Wszystkie cztery endpointy to wyłącznie odczyt:

GET /api/v1/invoices

Paginowana lista faktur

Parametry: ?from&to&type=cost|sales&tag&page&limit. Domyślnie ostatnie 30 dni, koszty, 100 pozycji na stronę (maks. 500). Odpowiedź zawiera dane faktur, blok pagination (z hasMore) i wybrany okres.

GET /api/v1/dashboard/summary

Podsumowanie KPI

Parametry: ?from&to. Domyślnie ostatnie 365 dni. Zwraca zagregowane KPI kosztów — sumę netto, liczbę faktur, średnią i porównanie rok do roku. Endpoint nie zwraca prognozy: pola forecast_total_net i forecast_method mają wartość null.

GET /api/v1/insights/combined

AI insighty miesięczne

Parametr: ?month=YYYY-MM. Łączone insighty (koszty + sprzedaż w jednym wywołaniu LLM). Każdy insight ma pole stream (costs / sales / cross), jest cache'owany i zweryfikowany przed zwróceniem.

GET /api/v1/cashflow/forecast

Prognoza cashflow

Parametr: ?horizon=30d|90d. Projekcja salda netto z przedziałem ufności — te same liczby, które widzisz na stronie Kalendarz płatności.

Kontrakt jest stabilny: adresy nie zmieniają się w obrębie v1, a ewentualne zmiany łamiące zgodność trafią dopiero do /api/v2 — wtedy v1 żyje jeszcze minimum 12 miesięcy. Nie ma endpointów zapisujących dane — w tej wersji klient tylko pobiera dane do własnego BI/ERP/dashboardu.

Rewokacja i bezpieczeństwo

Klucz traktuj jak hasło — daje pełny odczyt danych Twojej firmy. Nie commituj go do repozytorium, nie wklejaj w czatach ani zgłoszeniach, trzymaj w sekretach integracji.

Jeśli klucz wyciekł albo przestał być potrzebny, kliknij „Zrewokuj" przy nim na liście i potwierdź. Rewokacja jest nieodwracalna i natychmiastowa — od tej chwili każde zapytanie tym kluczem dostaje 401. Zrewokowany klucz nie znika z listy; zostaje wyszarzony z datą rewokacji, żebyś miał ślad, kiedy go wyłączono.

Kolumna „Ostatnio użyty" aktualizuje się przy każdym poprawnym wywołaniu — to szybki sposób, by sprawdzić, czy klucz jeszcze gdzieś żyje, zanim go skasujesz.

Ograniczenia i zakres

Aktualny zakres API jest celowo wąski:

  • Tylko odczyt. Wszystkie klucze mają jeden zakres — read. Nie ma kluczy zapisujących ani metod modyfikujących dane.
  • Cztery endpointy. Faktury, podsumowanie KPI, miesięczne insighty AI i prognoza cashflow. Inne widoki z aplikacji (marża, koncentracja, anomalie itd.) nie mają jeszcze publicznych endpointów.
  • Rate limiting. Zapytania są objęte limitem przepustowości — przy intensywnym odpytywaniu cache'uj odpowiedzi po swojej stronie zamiast wielokrotnie pytać o to samo.

Jeśli potrzebujesz danych z widoku, którego dziś nie ma w API, albo endpointu zapisującego — napisz do nas. Rozbudowujemy API pod realne integracje, więc Twój przypadek użycia pomaga ustalić, co dodać jako następne.