API do faktur online — połącz Mobilną Fakturę z własnym systemem

REST API (WebApi): wystawiaj faktury ze sklepu, systemu ERP albo aplikacji, pobieraj dokumenty i PDF, prowadź kontrahentów i cennik, zmieniaj stany magazynowe i wysyłaj do KSeF 2.0. Zwykłe zapytania HTTP, dane w formacie JSON.

Od pakietu MiniREST + JSONDokumentacja z przykładami kodu

Dla integratorów, których nie obsłuży gotowa wtyczka

Gdy sklep stoi na WooCommerce albo PrestaShop, wystarczy gotowa integracja konfigurowana w panelu. REST API jest dla pozostałych przypadków: własnego sklepu napisanego od podstaw, systemu ERP, programu magazynowego, aplikacji dla handlowców w terenie albo nietypowego obiegu dokumentów.

API pokrywa cały cykl dokumentu — wystawienie, pobranie, PDF, wysyłkę mailem i skierowanie do KSeF — a do tego kontrahentów, cennik z poziomami cen i stany magazynowe. Numerację, przeliczenia VAT i ewidencję prowadzi panel, więc nie odtwarzasz reguł podatkowych w swoim kodzie.

Dostęp masz od pakietu Mini (59 zł/rok). Poniżej sześć obszarów API oraz to, czego świadomie nie robi — lepiej poznać granice przed wdrożeniem niż w jego połowie.

Otwórz bezpłatne konto Dokumentacja API

API włączasz w panelu: Ustawienia → Integracje → WebAPI — tam przełączasz protokół na REST i generujesz klucz.

Mobilna Faktura — ekran ustawień WebAPI z wyborem protokołu i kluczem

Co daje REST API

Sześć obszarów: dokumenty, kontrahenci i cennik, magazyn, KSeF, konfiguracja dostępu oraz webhooki. Pełny opis każdego adresu, z parametrami i przykładowymi odpowiedziami, znajdziesz w dokumentacji w panelu.

Wystawianie i pobieranie dokumentów

Od pakietu Mini

Twój system wysyła dane dokumentu, panel odsyła identyfikator wystawionej faktury. Pozycje przekazujesz z nazwą, ilością, ceną netto i brutto oraz stawką VAT — numerację, przeliczenia i ewidencję prowadzi Mobilna Faktura, więc nie musisz odtwarzać reguł podatkowych po swojej stronie.

Listę dokumentów pobierasz z filtrami po okresie i kontrahencie, a pojedynczy dokument razem z pozycjami i rozbiciem na stawki VAT. Osobnym żądaniem pobierasz PDF albo zlecasz wysyłkę faktury mailem do kontrahenta.

Przy duplikacie numeru API nie zgłasza błędu — zwraca powodzenie z informacją, że dokument już istnieje, i podaje jego identyfikator. Dzięki temu ponowione żądanie po zerwanym połączeniu nie tworzy drugiej faktury.

  • Wystawianie faktur z pozycjami i stawkami VAT
  • Lista dokumentów z filtrami okresu i kontrahenta
  • Pobranie PDF i wysyłka mailem
  • Ochrona przed podwójnym wystawieniem przy ponowieniu
Przykłady w PHP, Pythonie i JS
Mobilna Faktura — ustawienia WebAPI: wybór protokołu REST i klucz integracji
Ustawienia WebAPI w panelu — protokół i klucz dostępu

Kontrahenci i cennik z poziomami cen

Od pakietu Mini

Bazę kontrahentów czytasz i uzupełniasz przez API — z wyszukiwaniem po nazwie i NIP. Każdy kontrahent ma domyślny poziom cenowy (detaliczna, hurtowa, specjalna, podstawowa), który panel stosuje przy wystawianiu dokumentu.

Kartoteka towarów zwraca obok ceny podstawowej trzy poziomy cenowe wraz z informacją, czy poziom ma własną cenę, czy dziedziczy podstawową. To ten sam mechanizm co w panelu — integracja wystawiająca fakturę klientowi hurtowemu dostaje właściwe ceny bez przeliczania ich po swojej stronie.

Towary są jedynym zasobem, który przez API można edytować: ceny, opisy i poziomy cenowe. Dokumentów i kontrahentów się nie zmienia — tak samo jak w panelu.

  • Kontrahenci: odczyt, wyszukiwanie, dodawanie
  • Cztery poziomy cen z dziedziczeniem ceny podstawowej
  • Edycja cen i opisów towarów
  • Słowniki: stawki VAT, jednostki miary
Mobilna Faktura — pulpit panelu z dokumentami i kontrahentami dostępnymi przez API
Panel Mobilnej Faktury — dane, do których sięga integracja

Stany magazynowe przez dokument WZ i PZ

Pakiet Max

Stan towaru zmienia się wyłącznie przez dokument magazynowy: PZ przy zwiększeniu, WZ przy zmniejszeniu — dokładnie tak jak w panelu. Dzięki temu każda zmiana ze sklepu jest widoczna w dokumentach, schodzi z partii i trafia do rozliczeń, zamiast po cichu nadpisywać liczbę w kartotece.

Podajesz albo stan docelowy (inwentaryzacja, pełna synchronizacja ze sklepem), albo zmianę względną (−3 po sprzedaży, +10 po dostawie). Odpowiedź zawiera stan przed i po oraz identyfikator utworzonego dokumentu magazynowego.

Gdy stan już się zgadza, żaden dokument nie powstaje. Ta część API wymaga pakietu Max i włączonej w ustawieniach aktualizacji stanów wraz z drukami.

Mobilna Faktura — moduł magazynu z dokumentami WZ i PZ
Magazyn w panelu — dokumenty tworzone także przez API

Wysyłka do KSeF 2.0 z zewnętrznego systemu

KSeF w każdym pakiecie

Dokument wystawiony przez API kierujesz do Krajowego Systemu e-Faktur osobnym żądaniem i osobnym sprawdzasz status wysyłki. Nie musisz implementować po swojej stronie ani schemy FA, ani uwierzytelniania w KSeF — robi to panel.

Dzięki temu sklep albo ERP może zamknąć całą ścieżkę: zamówienie → faktura → KSeF → PDF do klienta, bez wchodzenia człowieka do panelu.

Mobilna Faktura — moduł KSeF 2.0 ze statusami wysyłki i numerami dokumentów
Moduł KSeF w panelu — statusy i numery dokumentów

Jak zacząć: klucz, protokół, pierwszy dokument

Od pakietu Mini

API jest domyślnie wyłączone. W panelu wchodzisz w Ustawienia → Integracje → WebAPI, przełączasz protokół na REST i generujesz klucz WebApi. Bez przełączenia protokołu każde żądanie kończy się odmową — to najczęstsza przyczyna „API nie działa" na starcie.

Uwierzytelnianie jest bezstanowe: do każdego żądania dołączasz login do panelu, hasło (jawne albo jako skrót MD5) i klucz WebApi. Nie ma osobnego tokenu ani procedury logowania, więc korzystaj wyłącznie z HTTPS, a dane trzymaj w zmiennych środowiskowych — nigdy w repozytorium kodu.

Konto ma jeden klucz. Wygenerowanie nowego natychmiast unieważnia poprzedni, więc wszystkie integracje trzeba zaktualizować od razu. Konto pracuje też w jednym protokole naraz — starsze wdrożenia na SOAP działają dalej, ale nie równolegle z REST.

Instrukcja krok po kroku
Mobilna Faktura — ekran WebAPI z kluczem integracji i wyborem protokołu REST
Generowanie klucza WebApi i wybór protokołu

Webhooki — powiadomienia zamiast odpytywania

Pakiet Max

REST API działa na zasadzie odpytywania — to Twój system pyta, czy coś się zmieniło. Webhooki odwracają kierunek: Mobilna Faktura sama powiadamia wskazany adres, gdy wystawisz fakturę, klient ją opłaci albo dodasz kontrahenta.

Powiadomienia są podpisane, ponawiane przy błędach i zapisywane w dzienniku dostaw, więc widzisz, co i kiedy dotarło. Konfigurujesz je w Ustawieniach, w sekcji zdarzeń biznesowych. Nadają się do spięcia panelu z Zapierem, Make albo n8n bez pisania kodu.

  • Zdarzenia: faktura, płatność, nowy kontrahent
  • Podpisane żądania i ponawianie przy błędach
  • Dziennik dostaw z historią
  • Wymaga pakietu Max
Mobilna Faktura — ustawienia integracji i zdarzeń biznesowych
Panel Mobilnej Faktury — miejsce konfiguracji integracji

Pozostałe sposoby połączenia Mobilnej Faktury

Asystenci AI (MCP) Claude i ChatGPT nad Twoim kontem — osobne połączenie z OAuth 2.1, bezpłatne w każdym pakiecie. Integracje e-commerce Allegro, BaseLinker, WooCommerce i PrestaShop — gotowe połączenia, bez pisania kodu. KSeF 2.0 online Wysyłka faktur do Krajowego Systemu e-Faktur z UPO i odbiór faktur zakupowych. Synchronizacja z Windows Dwukierunkowa wymiana danych między programem Faktura VAT a kontem online. Księgowość online KPiR, ryczałt, ewidencja VAT i pliki JPK — zapisy powstają z wystawionych faktur. Fakturowanie online Faktury VAT, pro-forma, korekty i rachunki w przeglądarce oraz na telefonie.

Wszystkie funkcje Mobilnej Faktury

Dla kogo

REST API jest dla Ciebie, jeśli…

  • masz własny sklep albo aplikację i chcesz, żeby faktura powstawała automatycznie po zamówieniu;
  • pracujesz na systemie ERP lub magazynowym, z którego dane mają trafiać do dokumentów sprzedaży;
  • budujesz aplikację dla handlowców wystawiających dokumenty w terenie;
  • potrzebujesz własnych raportów na danych z panelu, po swoich filtrach i okresach;
  • chcesz wysyłać dokumenty do KSeF 2.0 z zewnętrznego systemu, bez implementowania schemy FA.

Wybierz coś innego, jeśli…

Najczęstsze pytania

Od jakiego pakietu działa REST API?

Od pakietu Mini wzwyż (59 zł/rok). Jeden wyjątek dotyczy zapisu stanów magazynowych — zmiana stanu towaru wymaga pakietu Max, ponieważ powstaje przy niej dokument WZ albo PZ. Odczyt towarów działa od pakietu Mini.

Jak wygląda uwierzytelnianie? Czy jest token?

Tokenu nie ma. API jest bezstanowe: do każdego żądania dołączasz login do panelu, hasło (jawne albo jako skrót MD5) oraz klucz WebApi wygenerowany w ustawieniach. Dlatego korzystaj wyłącznie z HTTPS i trzymaj dane w zmiennych środowiskowych, nigdy w repozytorium kodu. Jeśli szukasz połączenia z uwierzytelnianiem OAuth, to opis znajdziesz na stronie o asystentach AI — MCP działa inaczej niż REST API.

Dlaczego dostaję odmowę mimo poprawnych danych logowania?

Konto pracuje w jednym protokole naraz — SOAP albo REST — a domyślnie ustawiony jest SOAP. Dopóki nie przełączysz protokołu na REST w Ustawieniach → Integracje → WebAPI, każde żądanie kończy się odmową. Wyjątkiem jest sprawdzenie konfiguracji, które odpowiada w obu trybach i jest dobrym pierwszym krokiem przy diagnozie.

Ile kluczy mogę mieć i co się dzieje przy regeneracji?

Jeden klucz na konto. Wygenerowanie nowego natychmiast unieważnia poprzedni, więc wszystkie integracje korzystające ze starego przestaną działać — zaktualizuj je od razu po regeneracji.

Czy przez API mogę poprawić wystawioną fakturę?

Nie. Dokument można wystawić, pobrać, wysłać i usunąć, ale nie zmienić — tak samo jak w panelu, gdzie wystawionej faktury się nie edytuje, tylko koryguje. Edycja przez API działa dla kartoteki towarów: cen, opisów i poziomów cenowych. Usuwanie działa na liście identyfikatorów, a nie na adresie pojedynczego dokumentu.

Czy jest sandbox albo środowisko testowe?

Nie ma osobnego sandboxa dla REST API. Do testów najwygodniej założyć bezpłatne konto i pracować na nim, zanim podłączysz integrację do konta produkcyjnego. Środowisko testowe istnieje natomiast dla KSeF — to osobny mechanizm po stronie Ministerstwa Finansów.

Czym API różni się od gotowych integracji ze sklepami?

Gotowe integracje (Allegro, BaseLinker, WooCommerce, PrestaShop) konfigurujesz w panelu i nie wymagają pisania kodu — sprawdzą się, gdy Twój sklep stoi na jednej z tych platform. REST API jest dla przypadków, których wtyczka nie obejmuje: własnego sklepu, systemu ERP, aplikacji handlowca albo nietypowego obiegu dokumentów.

Czy stare integracje na SOAP przestaną działać?

Nie. SOAP (MWebApi) działa dalej i pozostaje dostępny — REST jest nowszym, wygodniejszym wariantem. Konto pracuje jednak w jednym protokole naraz, więc przełączenie na REST wyłącza SOAP dla tego konta. Adresy REST zawierają numer wersji, a zmiany łamiące zgodność trafią do kolejnej wersji — istniejące wdrożenia nie przestaną działać z dnia na dzień.