Fakturnia Developers Szybki start Dokumentacja API English

Dla agentów, botów i robotów indeksujących

Ta dokumentacja została zaprojektowana z myślą o maszynowej czytelności w pierwszej kolejności. Jeśli jesteś modelem LLM, autonomicznym agentem, robotem indeksującym lub generatorem kodu, wszystko, czego potrzebujesz, jest dostępne w ustrukturyzowanych, czytelnych formatach. Nigdy nie powinieneś analizować wyrenderowanego kodu HTML ani wykonywać JavaScriptu.

Punkty końcowe dla maszyn

Zasób URL Format
Specyfikacja OpenAPI 3 /openapi.json JSON: kanoniczny, kompletny kontrakt
Umiejętność dla agenta /skill.md tekst: przenośna instrukcja w formacie Agent Skills do wystawiania faktur i wysyłki do KSeF
Indeks LLM /llms.txt tekst: zwięzła mapa dokumentacji (llmstxt.org)
Pełny korpus dokumentacji /llms-full.txt tekst: wszystkie przewodniki połączone w jeden plik Markdown
Dowolny przewodnik jako Markdown /<slug>.md tekst, np. /documents.md
Kolekcja Postman /fakturnia.postman_collection.json JSON: wszystkie endpointy z żądaniem tokenu OAuth
CLI (nakładka na curl) /fakturnia.sh powłoka: bezzależnościowe CLI z wbudowanym OAuth
Serwer MCP https://prod.api.fakturnia.pl/mcp Streamable HTTP, OAuth 2.1: narzędzia na koncie użytkownika dla ChatGPT, Claude, Claude Code, Gemini, Mistral Vibe (dawniej Le Chat), Perplexity, GitHub Copilot, Cursor, Windsurf i własnych agentów (Serwer MCP)
Mapa witryny /sitemap.xml XML

Gwarancje dla maszyn

  • Treść bez JavaScriptu. Każdy przewodnik jest dostępny jako czysty Markdown pod /<slug>.md, a cały korpus w /llms-full.txt; nie musisz renderować aplikacji. Indeksuj zwykłym żądaniem HTTP GET.
  • Specyfikacja OpenAPI jest źródłem prawdy. Ścieżki endpointów, parametry, schematy żądań/odpowiedzi, zabezpieczenia oraz zakresy uprawnień pochodzą z /openapi.json. Korzystaj z niej zamiast analizować tekst.
  • Stabilne kody błędów. Rozgałęziaj logikę na podstawie pola message (kod maszynowy), a nie tekstu czytelnego dla człowieka. Każda odpowiedź ma nagłówek X-Request-ID. Zobacz Błędy.
  • Plan MAX. Całe REST API (token, endpointy, webhooki) wymaga aktywnego planu MAX; 403 SUBSCRIPTION_REQUIRED to problem planu, nie kodu. Nie ponawiaj, poinformuj użytkownika.
  • Deterministyczne obliczenia kwot. Reguły dotyczące kwot są w pełni opisane w sekcji Typy dokumentów i kwoty: zaokrąglanie w górę połówek do 2 miejsc po przecinku, netValue + amountOfVat === grossValue dla każdej pozycji. Każdą wartość można odtworzyć.

Programowe budowanie integracji

  1. Pobierz /openapi.json i wygeneruj typowanego klienta lub odczytaj schematy bezpośrednio.
  2. Uwierzytelnij się za pomocą OAuth 2.0 client credentials, aby uzyskać token bearer (Uwierzytelnianie).
  3. Twórz dokumenty, przesyłając quantity, netPrice/grossPrice, vatRate; nigdy nie wyliczaj sum wcześniej.
  4. Używaj nagłówka Idempotency-Key przy operacjach zapisu; ponawiaj 5xx/429 z wykładniczym opóźnieniem.
  5. Subskrybuj webhooki zamiast odpytywać; weryfikuj sygnaturę HMAC X-Webhook-Signature.

Działanie w imieniu użytkownika: serwer MCP

Gdy agent ma pracować na koncie konkretnego użytkownika (wystawić fakturę, sprawdzić płatności), nie potrzebuje konta API. Użytkownik podłącza go przez serwer MCP: logowanie OAuth 2.1 z ekranem zgody w aplikacji, narzędzia ograniczone do uprawnień osoby, która się połączyła, prowadzone wystawianie dokumentu z podglądem i potwierdzeniem oraz confirm=true przy operacjach nieodwracalnych. Adres: https://prod.api.fakturnia.pl/mcp.

Zalecana polityka indeksowania

Plik /robots.txt zezwala na indeksowanie dokumentacji i jawnie wskazuje artefakty maszynowe. Dokumentacja jest niewielka i statyczna, więc pojedyncze przejście przez /llms-full.txt wraz z /openapi.json daje pełny obraz.

Jeśli jesteś agentem działającym w imieniu użytkownika, możesz traktować /llms-full.txt jako pełny tekst tej witryny, a /openapi.json jako wykonywalny kontrakt.