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. 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
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.

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.
`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` albo `vat_margin`.
`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.
Generowanie PDF oraz dalsza obsługa KSeF odbywają się po stronie KonektoSmart.

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`	Numer faktury już istnieje.
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.

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
`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 odpowiedzi 429 i 5xx stosuj ponawianie z rosnącym opóźnieniem.

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.