REST API (WebApi) — przegląd

Pełnowartościowe REST API umożliwia integrację Mobilnej Faktury z dowolnym zewnętrznym systemem: sklepem custom, ERP, CRM, własną aplikacją mobilną, dashboardem menedżerskim.

Dostępność: pakiet MINI i wyższe.

Zastosowania

Auto-fakturowanie ze sklepu napisanego od podstaw (custom — bez WooCommerce/PrestaShop)
Integracja z ERP (SAP, Comarch ERP XL, Symfonia)
Integracja z CRM (Salesforce, HubSpot, Pipedrive)
Agregator zamówień (np. Allegro + Empik + Allegro Lokalnie razem)
Aplikacja mobilna dla handlowców (wystawianie ofert/faktur w terenie)
Dashboard menedżerski (BI - własne wykresy z danych)
Webhook’i od innych systemów (Stripe, PayPal, Slack)

Generowanie API Key

Ustawienia → API / WebApi → + Generuj klucz
Wpisz opis (np. “Sklep XYZ”, “ERP integracja”, “Aplikacja mobilna”)
Wybierz uprawnienia (zakres):
- read:invoices — odczyt faktur
- write:invoices — wystawianie faktur
- read:contractors — odczyt kontrahentów
- write:contractors — dodawanie/edycja kontrahentów
- read:products — odczyt towarów + stanów
- write:products — dodawanie/edycja towarów
- read:payments — odczyt płatności
- write:payments — rejestrowanie płatności
- admin:* — pełne uprawnienia (ostrożnie!)
Generuj → otrzymujesz klucz (np. mfak_live_a1b2c3d4e5f6...)

⚠️ Ważne: klucz pokazany TYLKO raz — skopiuj i zapisz w bezpiecznym miejscu (nigdy nie commituj do git!).

Wiele kluczy

Możesz wygenerować wiele kluczy — np. osobny dla każdej integracji:

mfak_live_xxx — Sklep WordPress
mfak_live_yyy — Aplikacja mobilna handlowca
mfak_live_zzz — ERP

Korzyść: rewokacja jednego klucza nie psuje innych integracji.

Autoryzacja

API używa Bearer token w nagłówku HTTP:

GET https://mobilna-faktura.pl/api/v1/invoices
Authorization: Bearer mfak_live_a1b2c3d4e5f6...
Content-Type: application/json

Każde zapytanie musi mieć ten nagłówek — inaczej zwraca 401 Unauthorized.

Główne endpointy

Faktury (`/api/v1/invoices`)

Method	Endpoint	Co robi
`GET`	`/api/v1/invoices`	Lista faktur (z paginacją + filtrami)
`GET`	`/api/v1/invoices/{id}`	Szczegóły jednej faktury
`POST`	`/api/v1/invoices`	Wystawienie nowej faktury
`PUT`	`/api/v1/invoices/{id}`	Edycja faktury (jeśli niezatwierdzona)
`DELETE`	`/api/v1/invoices/{id}`	Anulowanie faktury
`GET`	`/api/v1/invoices/{id}/pdf`	Pobierz PDF faktury
`POST`	`/api/v1/invoices/{id}/send-email`	Wyślij mailem do kontrahenta
`POST`	`/api/v1/invoices/{id}/send-ksef`	Wyślij do KSeF

Kontrahenci (`/api/v1/contractors`)

Method	Endpoint	Co robi
`GET`	`/api/v1/contractors`	Lista kontrahentów
`GET`	`/api/v1/contractors/{id}`	Szczegóły kontrahenta
`GET`	`/api/v1/contractors?nip=1234567890`	Wyszukiwanie po NIP
`POST`	`/api/v1/contractors`	Dodanie nowego (z auto-pobraniem GUS)
`PUT`	`/api/v1/contractors/{id}`	Edycja
`DELETE`	`/api/v1/contractors/{id}`	Usunięcie (anonimizacja RODO)

Towary i magazyn (`/api/v1/products`)

Method	Endpoint	Co robi
`GET`	`/api/v1/products`	Lista towarów
`GET`	`/api/v1/products/{id}`	Szczegóły towaru + stan magazynowy
`POST`	`/api/v1/products`	Dodanie nowego
`PUT`	`/api/v1/products/{id}/stock`	Aktualizacja stanu (przyjęcie/wydanie)

Płatności (`/api/v1/payments`)

Method	Endpoint	Co robi
`POST`	`/api/v1/payments`	Rejestracja wpłaty (auto-tworzy KP, opłaca fakturę)
`GET`	`/api/v1/payments?invoice={id}`	Lista płatności dla faktury
`GET`	`/api/v1/payments/payu/init`	Generowanie linku PayU dla faktury

Format odpowiedzi (JSON)

Sukces (200, 201)

{
  "status": "success",
  "data": {
    "id": 123,
    "number": "F/123/04/2026",
    "contractor": { "id": 45, "name": "ACME Sp. z o.o." },
    "amount_net": 1000.00,
    "amount_vat": 230.00,
    "amount_gross": 1230.00,
    "issue_date": "2026-04-26",
    "due_date": "2026-05-10",
    "status": "issued"
  }
}

Błąd (400, 401, 404)

{
  "status": "error",
  "code": "VALIDATION_ERROR",
  "message": "Pole 'contractor_nip' jest wymagane",
  "fields": {
    "contractor_nip": ["Pole jest wymagane"]
  }
}

Kody HTTP

200 OK — sukces (GET / PUT)
201 Created — utworzono zasób (POST)
204 No Content — sukces bez treści (DELETE)
400 Bad Request — błąd walidacji (sprawdź fields)
401 Unauthorized — brak / błędny API Key
403 Forbidden — API Key nie ma uprawnień do tego zasobu
404 Not Found — zasób nie istnieje
429 Too Many Requests — przekroczony limit (1000/godz dla MINI, 5000/godz dla MAX)
500 Internal Server Error — błąd serwera (zgłoś do support)

Przykłady kodu

PHP (z biblioteką Guzzle)

$client = new GuzzleHttp\Client([
    'base_uri' => 'https://mobilna-faktura.pl/api/v1/',
    'headers' => [
        'Authorization' => 'Bearer mfak_live_xxx',
        'Content-Type' => 'application/json',
    ]
]);

// Wystawienie faktury
$response = $client->post('invoices', [
    'json' => [
        'contractor_nip' => '1234567890',
        'positions' => [
            ['name' => 'Usługa konsultingowa', 'quantity' => 1, 'price_net' => 1000, 'vat' => 23]
        ],
        'issue_date' => '2026-04-26',
    ]
]);

$invoice = json_decode($response->getBody(), true);
echo "Wystawiono fakturę: " . $invoice['data']['number'];

Python (z requests)

import requests

API_KEY = 'mfak_live_xxx'
BASE_URL = 'https://mobilna-faktura.pl/api/v1'

response = requests.post(
    f'{BASE_URL}/invoices',
    headers={'Authorization': f'Bearer {API_KEY}'},
    json={
        'contractor_nip': '1234567890',
        'positions': [
            {'name': 'Usługa', 'quantity': 1, 'price_net': 1000, 'vat': 23}
        ],
        'issue_date': '2026-04-26',
    }
)

invoice = response.json()
print(f"Wystawiono fakturę: {invoice['data']['number']}")

JavaScript (fetch)

const API_KEY = 'mfak_live_xxx';

const response = await fetch('https://mobilna-faktura.pl/api/v1/invoices', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    contractor_nip: '1234567890',
    positions: [
      { name: 'Usługa', quantity: 1, price_net: 1000, vat: 23 }
    ],
    issue_date: '2026-04-26',
  })
});

const invoice = await response.json();
console.log('Wystawiono:', invoice.data.number);

cURL

curl -X POST https://mobilna-faktura.pl/api/v1/invoices \
  -H "Authorization: Bearer mfak_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "contractor_nip": "1234567890",
    "positions": [{"name":"Usługa","quantity":1,"price_net":1000,"vat":23}],
    "issue_date": "2026-04-26"
  }'

Sandbox (środowisko testowe)

Sandbox dla developerów — testowanie integracji bez wpływu na produkcję:

URL: https://sandbox.mobilna-faktura.pl/api/v1/
API Key: osobny dla sandbox (generowany w Ustawienia → API → Sandbox)
Dane: izolowana baza testowa (nie wpływa na prawdziwe faktury/klientów)
Resetowanie: każdej nocy baza sandbox jest resetowana (czysta)

Po przetestowaniu w sandbox → przepnij URL na produkcję + użyj produkcyjnego klucza.

Dokumentacja online

Pełna dokumentacja API z interaktywną przeglądarką (Swagger/OpenAPI):

URL: https://mobilna-faktura.pl/api/docs
Wszystkie endpointy z przykładami request/response
Try it out — wyślij testowy request bezpośrednio z przeglądarki
Schemas — pełne schematy JSON dla każdego pola

Webhook’i (notyfikacje)

System może wysyłać powiadomienia do Twojego URL przy zdarzeniach:

Ustawienia → API → Webhooks → + Dodaj webhook
URL Twojego endpointu (np. https://mojsklep.pl/webhook/mfaktura)
Zdarzenia (zaznacz):
- invoice.created — wystawiono fakturę
- invoice.paid — opłacono fakturę
- payment.received — otrzymano wpłatę
- contractor.created — dodano kontrahenta
Sekret (do weryfikacji autentyczności) — generowany automatycznie

System wysyła POST z JSON-em zdarzenia → Twój endpoint reaguje (np. aktualizuje status w sklepie).

Rate limiting

Pakiet	Limit
MINI	1 000 requestów / godzinę
STANDARD	3 000 / godzinę
MAX	10 000 / godzinę

Po przekroczeniu — 429 Too Many Requests + nagłówek Retry-After: 60 (czekaj 60 sekund).

Versioning (semver)

API używa semantic versioning:

v1 — aktualna stabilna wersja (backward compatible w obrębie v1.x)
v2 — następna wersja (planowana, breaking changes)

Stara wersja wspierana minimum 12 miesięcy po wydaniu nowej.

Changelog: https://mobilna-faktura.pl/api/changelog.

Korzyści

Pełna kontrola integracji custom (zamiast ograniczeń wtyczek)
Standard REST + JSON — łatwe dla każdego dewelopera
Sandbox — bezpieczne testy
Webhook’i — push’owe powiadomienia (zamiast polling)
Dokumentacja online z try-it-out
Skalowalność — wysokie limity dla pakietu MAX

REST API (WebApi) - integracje custom z panelem