Automatyzacja wystawiania faktur przez API

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

W tym artykule

• Jak wygenerować token API
• Jak wykonać pierwsze zapytanie
• Zalecana kolejność integracji
• Dostępne endpointy
• Jak pobierać faktury
• Jak wystawić fakturę
• Obsługa błędów
• Limity zapytań
• Bezpieczeństwo

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.

1. Klient loguje się na konto administratora biura lub administratora firmy.
2. Przechodzi do sekcji Ustawienia → Dostęp przez API.
3. Wybiera opcję dodania nowego tokenu.
4. Podaje nazwę, na przykład „Integracja ze sklepem”.
5. Ustawia datę ważności lub wybiera token bezterminowy.
6. Potwierdza operację kodem 2FA.
7. 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

1. GET /me – sprawdź token i jego zakres.
2. GET /companies – pobierz firmy i zapisz ich identyfikatory id.
3. GET /company_invoices/options – pobierz dozwolone jednostki, stawki VAT, typy płatności i pozostałe słowniki.
4. GET /sellers oraz GET /bank_accounts – sprawdź dane sprzedawcy i rachunki danej firmy.
5. POST /company_invoices – wystaw fakturę.
6. 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.