Automatyzacja wystawiania faktur przez API - KonektoSmart Wsparcie Biur Rachunkowych

Ten przewodnik pokazuje cały proces: od wygenerowania tokenu w panelu klienta, przez pierwsze zapytanie, aż po wystawienie faktury, pobranie jej PDF oraz wysłanie dokumentu do biura lub KSeF. Przykłady korzystają z programu curl, ale te same adresy i dane można wykorzystać w dowolnym języku programowania.

Środowisko	Adres
Produkcja	`https://konektosmart.pl/api/external/v1`
Format danych	JSON; pobieranie faktury: PDF
Autoryzacja	`Authorization: Bearer <api_key>`
Swagger / OpenAPI	`https://konektosmart.pl/api/external/swagger_doc`

1. Token API zawsze generuje klient

Token nie jest wydawany przez integratora ani przez pomoc techniczną. Generuje go klient po zalogowaniu do swojego panelu KonektoSmart. Dzięki temu klient sam decyduje, do jakich firm integracja otrzyma dostęp i jak długo token będzie ważny.

Klient loguje się na konto administratora biura lub administratora firmy.
Przechodzi do sekcji Ustawienia → Dostęp przez API.
Wybiera opcję dodania nowego tokenu.
Podaje nazwę, na przykład „Integracja ze sklepem”.
Ustawia datę ważności lub wybiera token bezterminowy.
Potwierdza operację kodem 2FA.
Kopiuje token i przekazuje go integratorowi bezpiecznym kanałem.

Ważne: pełna wartość tokenu jest pokazywana tylko raz. Jeżeli klient zamknie okno bez skopiowania tokenu, musi wygenerować nowy.

Token zaczyna się od ks_live_. Należy traktować go jak hasło. Klient może w każdej chwili unieważnić token w panelu. Od tego momentu każde zapytanie z tym tokenem otrzyma odpowiedź 401.

2. Pierwsze zapytanie do API

Na początku zapisz adres API i token w zmiennych środowiskowych. Nie wpisuj prawdziwego tokenu bezpośrednio w kodzie aplikacji.

export BASE_URL='https://konektosmart.pl/api/external/v1'
export KONEKTO_API_KEY='ks_live_TUTAJ_WSTAW_TOKEN'

Każde zapytanie musi zawierać nagłówek Authorization w formacie Bearer TOKEN. Najlepszym testem połączenia jest endpoint GET /me:

curl --fail-with-body \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  "$BASE_URL/me"

Poprawna odpowiedź ma kod 200 OK. Zawiera dane tokenu, użytkownika, właściciela tokenu oraz podgląd firm dostępnych dla integracji:

{
  "me": {
    "token": {
      "name": "Integracja ze sklepem",
      "token_prefix": "ks_live_aB3dEf",
      "expires_at": "2027-01-31T23:59:59.000Z"
    },
    "owner": { "type": "Company", "id": "3b241101-e2bb-4255-8caf-4136c566a962" },
    "companies": [
      {
        "id": "3b241101-e2bb-4255-8caf-4136c566a962",
        "name": "Przykładowa Firma Sp. z o.o.",
        "nip": "5260250274"
      }
    ],
    "companies_truncated": false
  }
}

Jeżeli companies_truncated ma wartość true, lista w odpowiedzi została skrócona do 100 firm. Pełną listę należy wtedy pobrać przez GET /companies.

3. Zalecana kolejność integracji

GET /me – sprawdź token i jego zakres.
GET /companies – pobierz firmy i zapisz ich identyfikatory id.
GET /company_invoices/options – pobierz dozwolone jednostki, stawki VAT, typy płatności i pozostałe słowniki.
GET /sellers oraz GET /bank_accounts – sprawdź dane sprzedawcy i rachunki danej firmy.
POST /company_invoices – wystaw fakturę.
GET /company_invoices/{id} – odczytaj aktualne dane i status dokumentu.
GET /company_invoices/pdf – pobierz dokument w wybranym wyglądzie.
POST /company_invoices/send – przekaż fakturę do biura lub KSeF, a następnie sprawdzaj jej status.

4. Dostępne endpointy

Metoda i ścieżka	Do czego służy
`GET /me`	Sprawdzenie tokenu, użytkownika i zakresu firm.
`GET /companies`	Lista firm widocznych dla tokenu.
`GET /companies/{id}`	Dane jednej firmy.
`GET /mail_context`	Wyszukanie użytkownika i firm na podstawie adresu e-mail.
`GET /company_invoices`	Lista faktur sprzedaży z filtrami i paginacją.
`GET /company_invoices/{id}`	Pełne dane jednej faktury sprzedaży.
`GET /company_invoices/options`	Słowniki potrzebne do budowania faktury.
`POST /company_invoices`	Wystawienie nowej faktury sprzedaży, faktury do paragonu, rachunku lub paragonu.
`GET /company_invoices/pdf`	Pobranie PDF po id albo numerze i firmie; wybór wyglądu KonektoSmart lub KSeF.
`POST /company_invoices/send`	Wysyłka faktury do biura, KSeF albo obu celów.
`GET /invoice_naming_schemes`	Schematy numeracji firmy.
`GET /invoice_naming_schemes/next_name`	Podgląd proponowanego numeru faktury.
`GET /bank_accounts`	Rachunki bankowe firmy.
`GET /sellers`	Dane sprzedawcy używane na fakturach.

Pobranie listy firm

curl --fail-with-body --get \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  --data-urlencode 'search=Przykładowa' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'limit=50' \
  "$BASE_URL/companies"

Zapisz pole id wybranej firmy. Ten identyfikator będzie potrzebny jako company_id w kolejnych zapytaniach.

5. Pobieranie faktur sprzedaży

Endpoint GET /company_invoices zwraca faktury sprzedaży jednej firmy. Parametr company_id jest wymagany.

Parametr	Format	Opis
`company_id`	UUID	Wymagany identyfikator firmy.
`invoice_type`	string	`vat`, `proforma`, `correction`, `advance`, `final`, `vat_margin`, `receipt`, `bill` albo `non_fiscal_receipt`.
`month_from`	`YYYY-MM`	Pierwszy miesiąc zakresu.
`month_to`	`YYYY-MM`	Ostatni miesiąc zakresu.
`search`	string	Wyszukiwanie po numerze i danych nabywcy.
`sort_by`	string	`issue_date`, `created_at`, `name`, `payment_date`, `total_gross`, `total_net` lub `buyer_name`.
`sort_dir`	string	`asc` albo `desc`.
`offset`	integer	Liczba pominiętych rekordów, domyślnie 0.
`limit`	integer	Od 1 do 100, domyślnie 50.

Uwaga na format dat: filtry month_from i month_to przyjmują miesiąc w formacie YYYY-MM, na przykład 2026-07. Wartość 2026-07-01 jest niezgodna z kontraktem i spowoduje błąd 422 validation_error.

Uwaga na sortowanie: External API używa parametrów sort_by=created_at&sort_dir=desc. Parametr order=created_at:desc należy do innego kontraktu i nie powinien być tutaj używany.

export COMPANY_ID='3b241101-e2bb-4255-8caf-4136c566a962'

curl --fail-with-body --get \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  --data-urlencode "company_id=$COMPANY_ID" \
  --data-urlencode 'invoice_type=vat' \
  --data-urlencode 'month_from=2026-07' \
  --data-urlencode 'month_to=2026-08' \
  --data-urlencode 'sort_by=created_at' \
  --data-urlencode 'sort_dir=desc' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'limit=20' \
  "$BASE_URL/company_invoices"

Odpowiedź zawiera total_count, czyli łączną liczbę pasujących faktur, oraz tablicę company_invoices z aktualną stroną wyników.

Pobranie pełnych danych faktury

export INVOICE_ID='7d9e90c1-3f6c-4c96-a518-5bf54f63dc72'

curl --fail-with-body \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  "$BASE_URL/company_invoices/$INVOICE_ID"

Ten endpoint zwraca między innymi nabywcę, sprzedawcę, pozycje, płatność, oznaczenia podatkowe oraz status KSeF. Dostępne są wyłącznie faktury sprzedaży mieszczące się w zakresie tokenu.

6. Słowniki i dane pomocnicze

Nie wpisuj na stałe w integracji jednostek, stawek VAT, rodzajów płatności czy oznaczeń GTU. Aktualne wartości pobierz z endpointu:

curl --fail-with-body \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  "$BASE_URL/company_invoices/options"

Każda pozycja słownika ma techniczną wartość w polu value i czytelną etykietę w polu name. Wynik można buforować po swojej stronie, ponieważ zmienia się rzadko.

GET /sellers?company_id=... – dane sprzedawcy używane na fakturze.
GET /bank_accounts?company_id=... – rachunki bankowe, z domyślnym rachunkiem na początku.
GET /invoice_naming_schemes?company_id=... – dostępne schematy numeracji.
GET /invoice_naming_schemes/next_name – podgląd kolejnego numeru. Podgląd nie rezerwuje numeru.

7. Wystawienie faktury

Nową fakturę tworzy endpoint POST /company_invoices. Wymagane są: identyfikator firmy, typ faktury, obiekt nabywcy, co najmniej jedna pozycja oraz obiekt płatności.

Uprawnienia: użytkownik, który wygenerował token, musi mieć prawo do wystawiania faktur w danej firmie. Sam dostęp do odczytu firmy nie zawsze oznacza prawo do tworzenia dokumentów.

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  -H 'Content-Type: application/json' \
  "$BASE_URL/company_invoices" \
  -d '{
    "company_id": "3b241101-e2bb-4255-8caf-4136c566a962",
    "invoice_type": "vat",
    "issue_date": "2026-08-07",
    "buyer": {
      "name": "Nabywca Sp. z o.o.",
      "tax_id": "5260250274",
      "tax_id_type": "nip",
      "address": "Prosta 2",
      "zip_code": "00-002",
      "city": "Warszawa"
    },
    "items": [
      {
        "name": "Usługa konsultingowa",
        "quantity": 1,
        "unit": "piece",
        "vat": "23%",
        "price_net": 100.00,
        "total_net": 100.00,
        "total_vat": 23.00,
        "total_gross": 123.00
      }
    ],
    "payment": {
      "type": "transfer",
      "currency": "PLN",
      "date": "2026-08-21"
    }
  }'

Poprawna odpowiedź ma kod 201 Created i zawiera obiekt company_invoice z identyfikatorem id oraz numerem name.

Jeżeli pominiesz pole name, KonektoSmart nada numer zgodnie ze schematem firmy. Jest to zalecane rozwiązanie.
Dozwolone wartości unit, vat, payment.type, gtu i innych pól pobieraj z /company_invoices/options.
Jedna faktura może mieć maksymalnie 1000 pozycji.
Pola sprzedawcy i pochodzenia dokumentu są kontrolowane przez serwer i nie można ich nadpisać w żądaniu.
PDF pobierzesz przez GET /company_invoices/pdf, a wysyłkę do biura lub KSeF uruchomisz przez POST /company_invoices/send.

7.1. Faktura do paragonu, rachunek i paragon

Ten sam endpoint POST /company_invoices pozwala wystawić również fakturę do paragonu, rachunek i paragon. Wybierz odpowiednią wartość pola invoice_type. Pozostałe dane przekaż tak jak przy zwykłej fakturze, zgodnie z zasadami wybranego dokumentu.

Dokument	Wartość `invoice_type`
Faktura do paragonu	`receipt`
Rachunek	`bill`
Paragon	`non_fiscal_receipt`

Nazwy techniczne wpisuj dokładnie tak, jak w słowniku GET /company_invoices/options. Typ receipt oznacza fakturę do paragonu, a non_fiscal_receipt — paragon niefiskalny. Wystawienie dokumentu przez ten endpoint nie wykonuje fiskalizacji na drukarce.

Nowe typy można też wykorzystać w filtrze listy faktur i przy pobieraniu propozycji numeru. Jeżeli pomijasz pole name, firma musi mieć skonfigurowany odpowiedni schemat numeracji.

7.2. Pobranie faktury w PDF

Endpoint GET /company_invoices/pdf zwraca gotowy plik PDF. Dokument możesz wskazać przez jego id albo przez dokładny numer name i identyfikator firmy company_id. Parametr layout wybiera wygląd pliku: konektosmart lub ksef. Domyślnie używany jest wygląd KonektoSmart.

curl --fail-with-body --get \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  --data-urlencode "id=$INVOICE_ID" \
  --data-urlencode 'layout=konektosmart' \
  "$BASE_URL/company_invoices/pdf" \
  -o faktura.pdf

Jeżeli znasz numer faktury, przekaż go jako parametr zapytania. Dzięki --data-urlencode ukośniki i pozostałe znaki w numerze zostaną poprawnie zakodowane:

curl --fail-with-body --get \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  --data-urlencode "company_id=$COMPANY_ID" \
  --data-urlencode 'name=FV/0001/08/2026' \
  --data-urlencode 'layout=ksef' \
  "$BASE_URL/company_invoices/pdf" \
  -o faktura-ksef.pdf

Poprawna odpowiedź ma kod 200 OK i format application/pdf. To zawartość pliku, a nie JSON ani link do pobrania. Przy błędzie API zwróci JSON z tablicą errors; nie traktuj takiej odpowiedzi jak prawidłowego PDF.

Wygląd KSeF wymaga typu dokumentu obsługiwanego przez KSeF i poprawnych danych XML. Dla rachunku, paragonu niefiskalnego i faktury proforma wybierz layout=konektosmart. Samo pobranie PDF w wyglądzie KSeF nie wysyła faktury do KSeF i nie potwierdza jej przyjęcia.

Jeżeli dokładnie ten sam numer występuje w firmie przy kilku typach dokumentów, API zwróci 409 invoice_number_ambiguous. Pobierz wtedy dokument przez jego id.

7.3. Wysłanie faktury do biura lub KSeF

Po wystawieniu dokumentu możesz przekazać go do biura rachunkowego, wysłać do KSeF albo wykonać obie czynności. Służy do tego endpoint POST /company_invoices/send. Wskaż fakturę przez id albo przez parę company_id i name.

Parametr	Co robi
`to_office: true`	Przekazuje dokument do biura rachunkowego zgodnie z obiegiem dokumentów firmy.
`to_ksef: true`	Zleca wysyłkę faktury do KSeF w tle. Wynik sprawdzisz przez odczyt faktury.
Oba parametry ustawione na `true`	Wykonuje obie czynności, zaczynając od biura. Każdy cel ma osobny wynik.

Przynajmniej jeden z parametrów musi mieć wartość true. Pominięty parametr ma wartość false. Przykład wysyłki do obu celów:

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  -H 'Content-Type: application/json' \
  "$BASE_URL/company_invoices/send" \
  -d "{\"id\":\"$INVOICE_ID\",\"to_office\":true,\"to_ksef\":true}"

Do wysyłki po numerze zamiast pola id przekaż company_id oraz name. Użytkownik tokenu musi mieć uprawnienia do wszystkich wybranych czynności. Wysyłka do KSeF wymaga aktywnej firmy, odpowiednich poświadczeń użytkownika i dokumentu obsługiwanego przez KSeF. Dla faktur wystawionych w KonektoSmart moduł fakturowania musi być aktywny. Wysyłka do biura respektuje zamknięcie miesiąca i stan obiegu dokumentu.

Wyniki znajdziesz osobno w polach delivery.office i delivery.ksef. Cel, którego nie wybrano, ma wartość null. Każdy wybrany cel zawiera status i http_status, a w przypadku błędu także tablicę errors.

Kod odpowiedzi	Co oznacza
`200 OK`	Przekazanie do biura zakończyło się powodzeniem albo dokument był już wysłany.
`202 Accepted`	Zlecenie KSeF zostało zapisane w kolejce albo dokument jest już przetwarzany. To jeszcze nie potwierdzenie przyjęcia faktury przez KSeF.
`207 Multi-Status`	Jeden cel się powiódł lub został przyjęty do kolejki, a drugi zwrócił błąd. Sprawdź oba wyniki.

Przekazanie do biura wykonuje się od razu. Wysyłka do KSeF jest asynchroniczna: API zapisuje zlecenie i zwraca odpowiedź bez czekania na sesję KSeF, wysłanie faktury i UPO. W odpowiedzi znajdziesz delivery.ksef.status: queued, identyfikator zlecenia delivery_id oraz adres status_url do sprawdzania wyniku.

Po odpowiedzi 202 odczytuj fakturę przez GET /company_invoices/{id}, z tym samym tokenem. Pole company_invoice.ksef_delivery pokazuje ostatnie zlecenie: queued oznacza oczekiwanie w kolejce, processing — pracę w tle, accepted — zakończenie próby wysyłki, a failed — błąd. Samo accepted nie potwierdza rejestracji faktury: sprawdzaj też ksef_status i ksef_invoice_number.

Jeżeli zadanie zakończy się błędem, szczegóły będą w company_invoice.ksef_delivery.errors, a jego kod w company_invoice.ksef_delivery.http_status. Odrzucenie przez KSeF zawiera również invoice_status.code i invoice_status.description. Odczyt istniejącej faktury nadal zwraca HTTP 200 — wynik wysyłki sprawdzaj w tych polach.

Ponowne żądanie dla aktywnego zlecenia zwraca ten sam delivery_id, bez tworzenia kolejnej wysyłki. Status already_sent oznacza dokument już wysłany, a in_progress — przetwarzanie rozpoczęte wcześniej. Dla biura pozostają statusy sent i already_sent.

Po przerwanym połączeniu najpierw sprawdź fakturę. Jeżeli wynik wysyłki nie daje się potwierdzić, zobaczysz uncertain i ksef_delivery_outcome_unknown. System nie ponowi takiej wysyłki automatycznie. Poczekaj na ustalenie statusu albo skontaktuj się z obsługą — ponowienie bez wyjaśnienia wyniku mogłoby utworzyć duplikat.

Po odpowiedzi 207 sprawdź oba cele. Błąd biura nie anuluje przyjętego zlecenia KSeF, a poprawne zakolejkowanie nie gwarantuje końcowego przyjęcia przez KSeF. Nie uruchamiaj równolegle wysyłki tej samej faktury z API, panelu i automatu.

curl --fail-with-body \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  "$BASE_URL/company_invoices/$INVOICE_ID"

8. Rozpoznawanie adresu e-mail

Endpoint GET /mail_context pomaga ustalić, do którego użytkownika i firmy należy adres e-mail. Przydaje się na przykład w integracji z programem pocztowym.

curl --fail-with-body --get \
  -H "Authorization: Bearer $KONEKTO_API_KEY" \
  --data-urlencode 'email=jan@example.com' \
  --data-urlencode 'offset=0' \
  --data-urlencode 'limit=25' \
  "$BASE_URL/mail_context"

Adres jest porównywany bez rozróżniania wielkości liter z głównym adresem użytkownika oraz adresem korespondencyjnym. Brak wyniku zwraca 200 OK z pustą tablicą users.

9. Obsługa błędów

Błędy mają wspólny format. Pole error jest stabilnym kodem przeznaczonym dla programu. Pole message jest tekstem dla człowieka i może się zmienić.

{
  "errors": [
    {
      "field": "month_from",
      "error": "validation_error",
      "message": "month_from jest nieprawidłowy"
    }
  ],
  "details": {}
}

HTTP	Kod `error`	Co oznacza
400	`bad_request`	Niepoprawny JSON lub żądanie odrzucone przez reguły faktury.
401	`invalid_token`, `expired_token`, `revoked_token`	Brak tokenu, niepoprawny token, token wygasły albo unieważniony.
403	`access_denied`, `invoice_creation_not_allowed`, `month_closed`	Brak uprawnień albo zamknięty miesiąc.
404	`not_found`	Zasób nie istnieje lub jest poza zakresem tokenu.
409	`numbering_conflict`, `invoice_number_ambiguous`, `delivery_in_progress`, `ksef_delivery_outcome_unknown`	Numer już istnieje, pasuje do kilku dokumentów albo trwa wysyłka tej faktury. Przy niejednoznacznym numerze użyj id; przed ponowieniem wysyłki sprawdź status dokumentu.
422	`validation_error`	Brakujący parametr, zły typ albo niepoprawny format.
429	`rate_limit_exceeded`	Przekroczony limit zapytań.
500	`internal_error`	Nieoczekiwany błąd po stronie serwera.
503	`service_unavailable`	Niedostępny generator PDF lub usługa KSeF. Przed ponowieniem wysyłki sprawdź status faktury.

Logikę integracji opieraj na kodzie HTTP i polu error. Nie porównuj tekstu z pola message.

10. Limity zapytań

Limity są liczone dla użytkownika, który wygenerował token. Kilka tokenów tej samej osoby nie zwiększa dostępnej puli. Dodatkowo obowiązuje wspólny limit 300 zapytań na minutę z jednego adresu IP.

Endpoint	Limit na minutę	Limit na dobę
`GET /me`	30	900
`GET /companies` i `GET /companies/{id}`	30	1800
`GET /mail_context`	25	1000
`POST /company_invoices`	10	300
`POST /company_invoices/send`	10	300
`GET /company_invoices/pdf`	30	1800
`GET /company_invoices` i `GET /company_invoices/{id}`	30	1800
`GET /company_invoices/options`	30	900
`GET /invoice_naming_schemes` i `/next_name`	30	1800
`GET /bank_accounts` i `GET /sellers`	30	900

Po przekroczeniu limitu API zwraca 429 i nagłówek Retry-After. Klient HTTP powinien odczekać wskazany czas. Dla odczytu i pobierania PDF stosuj ponawianie z rosnącym opóźnieniem po 429 i 5xx. Przed ponowieniem tworzenia lub wysyłki faktury po przerwanym połączeniu lub błędzie 5xx najpierw sprawdź, czy poprzednia operacja została wykonana.

11. Bezpieczeństwo i dobre praktyki

Przechowuj token wyłącznie po stronie serwera, najlepiej w magazynie sekretów lub zmiennej środowiskowej.
Nie umieszczaj tokenu w kodzie aplikacji frontendowej, mobilnej, repozytorium ani logach.
Używaj osobnego tokenu dla każdej integracji i każdego środowiska.
Nie przesyłaj tokenu e-mailem ani w otwartym komunikatorze.
Po odpowiedzi 401 expired_token zatrzymaj integrację i poproś klienta o wygenerowanie nowego tokenu.
Przy podejrzeniu wycieku klient powinien natychmiast unieważnić token w panelu.
Buforuj słowniki, rachunki bankowe i dane sprzedawcy. Nie ma potrzeby pobierania ich przed każdym dokumentem.
Nie ponawiaj automatycznie żądania tworzącego fakturę po większości błędów 4xx. Najpierw popraw dane wejściowe.

12. Pełna dokumentacja techniczna

Pełny kontrakt API jest dostępny jako dokument Swagger 2.0. Zawiera wszystkie parametry, typy, wartości enum, modele odpowiedzi i obsługiwane błędy:

curl --fail-with-body \
  https://konektosmart.pl/api/external/swagger_doc \
  -o konektosmart-external-api.json

Dokument Swaggera jest publiczny i nie wymaga tokenu. Można go zaimportować do Postmana, Insomnii lub generatora klienta OpenAPI.

13. Jak zgłosić problem

W zgłoszeniu podaj metodę i ścieżkę żądania, datę i godzinę ze strefą czasową, kod HTTP, wartość pola error oraz pierwsze 16 znaków prefiksu tokenu. Nigdy nie wysyłaj pełnego tokenu.

Dzięki tym informacjom pomoc techniczna może szybko odnaleźć żądanie w logach i ustalić przyczynę problemu.