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.

  1. Utwórz kluczID Faktura → Ustawienia → Połączone aplikacje → „+ Nowy klucz API”. Klucz zobaczysz raz — zapisz go.
  2. Dodaj nagłówekAuthorization: Bearer TWÓJ_KLUCZ_API
  3. 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.pdf
curl "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.

MetodaAdresDo 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}/pdfPDF 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-nipZnajdź 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}/priceZmień cenę
POST/api/products/bulk-upsert-externalHurtowo: dodaj albo zaktualizuj towary z Twojego systemu
POST/api/integrations/shop/documentsFaktura z zamówienia sklepu (jedno zamówienie = jeden dokument)
POST/api/integrations/ordersZamó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:writeWystawianie dokumentów i ich odczyt (lista, szczegóły, PDF).
documents:readTylko odczyt dokumentów i PDF.
contractors:read / contractors:writeOdczyt kontrahentów / dodawanie i uzupełnianie po NIP-ie.
products:read / products:writeOdczyt towarów / dodawanie, zmiana cen, hurtowy import.
shop:writeKlucz 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.

401Brak klucza albo klucz nieprawidłowy lub wyłączony.
402Plan nie obejmuje tej funkcji albo limit faktur planu FREE jest wyczerpany.
403Klucz nie ma potrzebnego uprawnienia (zobacz tabelę uprawnień).
404Nie ma takiego dokumentu, kontrahenta albo towaru w Twojej firmie.
422Błę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.

Powiększony zrzut ID Faktura

Rzeczywisty ekran aplikacji · dane demonstracyjne