ID Faktura/Integracje/API
API ID Faktury.
Podłącz swój program.
Wystawiaj faktury, pobieraj PDF, synchronizuj kontrahentów i towary, odbieraj powiadomienia o wpłatach. Zwykłe REST i JSON, klucz w nagłówku, odpowiedzi po polsku.
Pełne API jest w planie Pro + POS. Klucz sklepu (faktury z zamówień sklepu) działa w każdym planie, także darmowym.
- Utwórz kluczID Faktura → Ustawienia → Połączone aplikacje → „+ Nowy klucz API”. Klucz zobaczysz raz — zapisz go.
- Dodaj nagłówek
Authorization: Bearer TWÓJ_KLUCZ_API - Wyślij pierwsze zapytanieOdpowiedź zawiera nazwę Twojej firmy.
PIERWSZE ZAPYTANIE
Sprawdź połączenie.
curl https://idfaktura.pl/api/integrations/shop/ping \
-H "Authorization: Bearer TWÓJ_KLUCZ_API"FAKTURA
Wystaw fakturę jednym zapytaniem.
Podaj nabywcę (albo contractor_id z kartoteki) i pozycje. Ceny netto (unit_price_net) albo brutto ("price_mode": "gross" i unit_price_gross). Pozycja z sku lub ean łączy się z towarem w magazynie. Nagłówek Idempotency-Key chroni przed podwójną fakturą, gdy Twój program wyśle to samo zapytanie drugi raz.
curl -X POST https://idfaktura.pl/api/documents/ \
-H "Authorization: Bearer TWÓJ_KLUCZ_API" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: zamowienie-1024" \
-d '{
"type": "sale_invoice",
"buyer_name": "Hotel Mazurski sp. z o.o.",
"buyer_nip": "5260250995",
"buyer_street": "al. Warszawska 118",
"buyer_zip": "10-701",
"buyer_city": "Olsztyn",
"buyer_email": "recepcja@example.com",
"payment_method": "przelew",
"price_mode": "net",
"items": [
{ "name": "Abonament serwisowy — listopad 2026", "quantity": 1,
"unit": "usł.", "unit_price_net": 450.00, "vat_rate": "23" },
{ "name": "Róża czerwona 60 cm", "sku": "KW-ROZ-60C", "quantity": 12,
"unit_price_net": 8.24, "vat_rate": "8" }
]
}'Odpowiedź:
{ "id": "6f1c…", "number": "FV/2026/11/024", "type": "sale_invoice", "status": "issued",
"gross_total": 660.28, "public_token": "LS0T6U…", … }
Faktura trafia do KSeF tak jak każda inna w ID Fakturze — według ustawień Twojej firmy. Szkic zapiszesz z "status": "draft".
PDF I LISTA
Pobierz PDF. Przeglądaj dokumenty.
curl https://idfaktura.pl/api/documents/6f1c…/pdf \
-H "Authorization: Bearer TWÓJ_KLUCZ_API" -o FV-2026-11-024.pdfcurl "https://idfaktura.pl/api/documents/?type=sale_invoice&date_from=2026-11-01&date_to=2026-11-30&page=1&per_page=50" \
-H "Authorization: Bearer TWÓJ_KLUCZ_API"KONTRAHENCI I SKLEPY
Kontrahent po NIP-ie. Faktura z zamówienia.
curl -X POST https://idfaktura.pl/api/contractors/upsert-by-nip \
-H "Authorization: Bearer TWÓJ_KLUCZ_API" -H "Content-Type: application/json" \
-d '{ "nip": "5260250995", "name": "Hotel Mazurski sp. z o.o.", "city": "Olsztyn" }'
Sklep internetowy? Użyj prostszej ścieżki: wysyłasz zamówienie, a ID Faktura sama dopasuje kontrahenta i towary. Jedno zamówienie (source + external_id) to zawsze jeden dokument. Gotowe wtyczki: WooCommerce i PrestaShop.
curl -X POST https://idfaktura.pl/api/integrations/shop/documents \
-H "Authorization: Bearer KLUCZ_SKLEPU" -H "Content-Type: application/json" \
-d '{
"source": "moj-sklep", "external_id": "1024", "kind": "invoice", "paid": true,
"customer_name": "Jan Nowak", "customer_company": "Hotel Mazurski sp. z o.o.",
"customer_nip": "5260250995", "customer_email": "jan@example.com",
"items": [ { "name": "Wazon szklany 30 cm", "ean": "5901234000004",
"quantity": 2, "unit_price_gross": 39.00, "vat_rate": "23" } ]
}'WEBHOOKI
Dowiedz się od razu o fakturze i wpłacie.
W ID Fakturze → Ustawienia → Integracje dodaj adres swojego serwera i wybierz zdarzenia: document.created, document.sent (wysłana do KSeF), document.paid, payment.received, contractor.created. Wysyłamy POST z JSON i nagłówkami X-Webhook-Event oraz X-Webhook-Signature (HMAC-SHA256 treści, kluczem z ustawień). Nieudane dostarczenia ponawiamy.
{ "event": "document.created", "tenant_id": "…", "document_id": "6f1c…",
"number": "FV/2026/11/024", "type": "sale_invoice", "gross_total": 660.28 }import hmac, hashlib
def podpis_ok(sekret, body, naglowek):
moj = hmac.new(sekret.encode(), body,
hashlib.sha256).hexdigest()
return hmac.compare_digest(moj, naglowek)
# naglowek = X-Webhook-Signature$body = file_get_contents('php://input');
$moj = hash_hmac('sha256', $body, $sekret);
$jego = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'] ?? '';
$ok = hash_equals($moj, $jego);ADRESY
Co jest w API.
| Metoda | Adres | Do czego |
|---|---|---|
| POST | /api/documents/ | Wystaw dokument (faktura, proforma, korekta, paragon…) |
| GET | /api/documents/ | Lista dokumentów: type, status, date_from, date_to, contractor_id, search, page, per_page |
| GET | /api/documents/{id} | Szczegóły dokumentu z pozycjami |
| GET | /api/documents/{id}/pdf | PDF dokumentu |
| GET | /api/contractors/ | Lista kontrahentów: search (nazwa, NIP, miasto, e-mail), page, per_page |
| GET | /api/contractors/{id} | Kontrahent |
| POST | /api/contractors/upsert-by-nip | Znajdź po NIP-ie albo dodaj kontrahenta |
| GET | /api/products/ | Lista towarów i usług: search, type, category, page, per_page |
| GET | /api/products/{id} | Towar |
| POST | /api/products/ | Dodaj towar |
| PATCH | /api/products/{id} | Zmień towar |
| PATCH | /api/products/{id}/price | Zmień cenę |
| POST | /api/products/bulk-upsert-external | Hurtowo: dodaj albo zaktualizuj towary z Twojego systemu |
| POST | /api/integrations/shop/documents | Faktura z zamówienia sklepu (jedno zamówienie = jeden dokument) |
| POST | /api/integrations/orders | Zamówienie od klienta (ZK) z Twojego systemu |
Pełny opis pól i odpowiedzi: openapi.json — wczytasz go do Postmana, Insomnii albo generatora klienta.
UPRAWNIENIA KLUCZA
Klucz robi tylko to, na co pozwolisz.
documents:write | Wystawianie dokumentów i ich odczyt (lista, szczegóły, PDF). |
documents:read | Tylko odczyt dokumentów i PDF. |
contractors:read / contractors:write | Odczyt kontrahentów / dodawanie i uzupełnianie po NIP-ie. |
products:read / products:write | Odczyt towarów / dodawanie, zmiana cen, hurtowy import. |
shop:write | Klucz sklepu: tylko faktura z zamówienia sklepu i jej PDF. Działa w każdym planie. |
Nowy klucz z Ustawień ma: documents:write, contractors:read, products:read. Klucz wyłączysz jednym kliknięciem.
BŁĘDY
Kody odpowiedzi.
401 | Brak klucza albo klucz nieprawidłowy lub wyłączony. |
402 | Plan nie obejmuje tej funkcji albo limit faktur planu FREE jest wyczerpany. |
403 | Klucz nie ma potrzebnego uprawnienia (zobacz tabelę uprawnień). |
404 | Nie ma takiego dokumentu, kontrahenta albo towaru w Twojej firmie. |
422 | Błędne dane — odpowiedź mówi, które pole poprawić. |
Każda firma widzi tylko swoje dane. Połączenie wyłącznie przez HTTPS. Dane trzymamy w Polsce — szczegóły na stronie Bezpieczeństwo.
POTRZEBUJESZ POMOCY Z INTEGRACJĄ?
Napisz, co chcesz połączyć.
Pomożemy dobrać adresy i uprawnienia. Integrację możemy też zrobić za Ciebie.
ZACZNIJ OD KLUCZA
Załóż konto.
Pierwszą fakturę wystawisz z API w kilka minut.
Bez karty. Pełne API w planie Pro + POS.