Klucze 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.

Wejdź w Ustawienia → 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.

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.

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: X-API-Key: bk_live_…. Gdy żądanie ma też nagłówek Authorization: Bearer, liczy się klucz z nagłówka Authorization.

Przykład pełnego wywołania:

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

Brak nagłówka albo nieprawidłowy/zrewokowany klucz zwracają 401 Unauthorized. Poprawny klucz przy endpoincie spoza planu Twojej firmy zwraca 403 Forbidden — patrz Plan firmy a dane z API. Odpowiedzi są w formacie JSON.

Klucz API utworzysz w każdym planie, także w Darmowym. Klucz nie poszerza jednak planu: każdy endpoint jest dostępny w tych samych planach co ekran z tymi danymi w aplikacji.

• Faktury i podsumowanie KPI — w każdym planie.
• Insighty AI — w każdym planie. Rozszerzona analiza z liczbami (pole facts) od planu Pro; w Darmowym to pole jest puste, tak jak na ekranie.
• Prognoza cashflow — od planu Pro, jak strona Kalendarz płatności.

Gdy plan nie obejmuje danych endpointu, odpowiedź to 403 Forbidden z tym samym komunikatem co w aplikacji, np. Ta funkcja jest dostępna w planie Pro. Twój aktualny plan: Darmowy. Odmowa nie zawiera żadnych danych. Po zmianie planu ten sam klucz od razu dostaje dane — nie trzeba go wymieniać.

Faktura w walucie obcej (np. EUR albo USD) ma w bilans.ai dwie kwoty: kwotę z dokumentu w jego walucie i kwotę w złotych. Kwotę w złotych liczymy raz, przy zapisie faktury: kursem podanym na fakturze, a gdy go nie ma — korekta dostaje kurs faktury korygowanej, pozostałe faktury średni kurs NBP z ostatniego dnia roboczego przed datą sprzedaży albo wystawienia (wcześniejszą z nich). To przeliczenie zarządcze — do analiz i porównań, nie do rozliczeń podatkowych.

Pola faktury w GET /api/v1/invoices — dotychczasowe bez zmiany znaczenia, nowe obok nich:

• sum_net, sum_vat, sum_gross i currency — kwoty w walucie faktury, jak dotąd.
• sum_net_pln, sum_vat_pln, sum_gross_pln — kwoty w złotych (przy fakturze w PLN równe kwotom z dokumentu); null, gdy faktura nie ma kursu.
• fx_rate — kurs: ile złotych za 1 jednostkę waluty (przy PLN 1); null bez kursu.
• fx_rate_source — skąd kurs: pln (faktura w złotych), dokument (kurs z faktury), dokument_vat (kurs wyliczony z kwot VAT w złotych na fakturze), korekta (kurs faktury korygowanej), nbp (średni kurs NBP), reczny (kurs wpisany ręcznie w bilans.ai przy fakturze — kwoty w złotych liczone tym kursem, dopóki ktoś nie przywróci kursu automatycznego), brak (bez kursu).
• fx_provisional_reason — wypełnione, gdy kurs jest tymczasowy: czeka_nbp (NBP nie opublikował jeszcze kursu z właściwego dnia), data_przyszla (dzień kursu wypada w przyszłości), brak_nbp (waluty nie ma w tabeli NBP z właściwego dnia — przyjęty ostatni znany kurs NBP), oryginal_tymczasowy (faktura korygowana ma kurs tymczasowy). Faktura z kursem tymczasowym ma kwoty w złotych; kurs może się później zmienić, a z nim te kwoty.
• fx_rate_date i fx_table_no — data notowania i numer tabeli NBP: przy kursie NBP (nbp) — tabela zastosowanego kursu; przy kursie z faktury (dokument, dokument_vat) — tabela, której średni kurs równa się kursowi z faktury (null, gdy żadna); przy pozostałych źródłach — null.

Sumy — GET /api/v1/dashboard/summary sumuje wiele faktur, więc wszystkie jego kwoty (suma, średnia, porównania) są w złotych. Faktura bez kursu liczy się w invoice_count, ale nie w kwotach; średnia dzieli tylko przez faktury z kwotą w złotych. Blok fx podaje liczniki okresu: foreign_count (faktury w walucie obcej), provisional_count (z kursem tymczasowym — wliczone w kwoty) i missing_count (bez kursu — poza kwotami).

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.

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.
• Dane według planu. Endpoint zwraca dane w zakresie planu Twojej firmy — tak samo jak aplikacja (szczegóły w sekcji Plan firmy a dane z API).
• 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.