Fakturnia Developers Szybki start Dokumentacja API English

Konta pocztowe

Konto Fakturnia może wysyłać dokumenty e-mailem z własnej skrzynki właściciela zamiast z adresu systemowego. Skrzynki podłącza się w aplikacji (Inne → Konta pocztowe): SMTP z hasłem albo Gmail i Outlook przez OAuth. Przez API sprawdzisz, które skrzynki są podłączone i w jakim są stanie. To wszystko: podłączanie, weryfikacja i edycja odbywają się wyłącznie w aplikacji, bo wymagają hasła albo zgody OAuth, których integracja nie powinna przechowywać.

Po co integracji ten odczyt: żeby wiedzieć, z jakiego adresu wychodzą faktury (np. do wpisania w stopce sklepu), żeby ostrzec użytkownika, gdy domyślna skrzynka ma błąd weryfikacji, albo żeby pokazać stan konfiguracji w panelu integracji.

Endpointy

Metoda Ścieżka Scope Opis
GET /email-accounts email-accounts:browse lista skrzynek, domyślna pierwsza
GET /email-accounts/{id} email-accounts:read jedna skrzynka 
curl -s https://sandbox.api.fakturnia.pl/external/v1/email-accounts \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "emailAccounts": [
      {
        "id": "681a3b2c4d5e6f7a8b9c0d1e",
        "provider": "gmail",
        "isOAuth": true,
        "email": "biuro@firma.pl",
        "host": null,
        "port": null,
        "secure": true,
        "verificationStatus": "verified",
        "isVerified": 1,
        "isDefault": true,
        "lastError": null,
        "lastVerifiedAt": "2026-09-20T10:00:00.000Z",
        "createdAt": "2026-09-01T10:00:00.000Z",
        "updatedAt": "2026-09-20T10:00:00.000Z"
      },
      {
        "id": "681a3b2c4d5e6f7a8b9c0d1f",
        "provider": "smtp",
        "isOAuth": false,
        "email": "faktury@firma.pl",
        "host": "smtp.firma.pl",
        "port": 465,
        "secure": true,
        "verificationStatus": "error",
        "isVerified": 2,
        "isDefault": false,
        "lastError": "535 Authentication failed",
        "lastVerifiedAt": "2026-08-30T08:12:00.000Z",
        "createdAt": "2026-08-30T08:00:00.000Z",
        "updatedAt": "2026-09-25T06:40:00.000Z"
      }
    ]
  },
  "executionTime": 6
}

Pola

Pole Znaczenie
provider smtp, gmail albo outlook
isOAuth true dla Gmail i Outlook, false dla SMTP
email adres nadawcy
host, port, secure konfiguracja SMTP (null dla OAuth); secure: true to SSL na porcie 465, false to STARTTLS
verificationStatus unverified (jeszcze niesprawdzona albo weryfikacja w aplikacji nie powiodła się; wtedy powód jest w lastError), verified (wysyłka testowa przeszła), error (ostatnia wysyłka nie powiodła się, patrz lastError)
isVerified ten sam stan jako liczba, jak w aplikacji: 0, 1, 2
isDefault skrzynka używana do wysyłki dokumentów, gdy użytkownik nie wybierze innej
lastError komunikat serwera pocztowego z ostatniej nieudanej próby albo null
lastVerifiedAt kiedy skrzynka ostatnio przeszła weryfikację

Sekrety (hasło SMTP, tokeny OAuth) nigdy nie są zwracane, także w szczegółach pojedynczej skrzynki.

Co się dzieje, gdy skrzynka ma błąd

Gdy wysyłka z własnej skrzynki nie powiedzie się, Fakturnia oznacza ją stanem error, a dokument wychodzi z adresu systemowego, więc odbiorca i tak dostaje fakturę. Użytkownik musi jednak poprawić konfigurację w aplikacji. Jeśli Twoja integracja pokazuje stan skrzynek, zwróć uwagę na verificationStatus === 'error' przy skrzynce z isDefault: true.

Błędy

Status Kod Kiedy
403 NO_PERMISSIONS token bez email-accounts:browse albo email-accounts:read
403 SUBSCRIPTION_REQUIRED konto bez planu MAX (patrz Uwierzytelnianie)
404 NOT_FOUND skrzynka nie istnieje albo należy do innego konta