Dokumenty cykliczne

Reguła cykliczna to szablon dokumentu połączony z harmonogramem. Raz skonfigurowana, sama wystawia faktury (tryb AUTO), przygotowuje szkice do akceptacji (DRAFT) albo tylko przypomina o wystawieniu (REMINDER). Przez API odczytasz stan reguł i historię generacji oraz wstrzymasz lub wznowisz regułę, np. gdy klient zrezygnuje z abonamentu w Twoim systemie.

Moduł wymaga planu MAX na koncie Fakturnia. Bez niego każdy endpoint zwraca 403 z kodem SUBSCRIPTION_REQUIRED.

Zakresy uprawnień: recurring:browse, recurring:read, recurring:toggle.

Reguły tworzy się i edytuje w aplikacji Fakturnia. API celowo ich nie zakłada: szablon reguły to kompletny dokument z pozycjami i automatyzacjami, a jego konfiguracja jest po prostu wygodniejsza w edytorze niż w JSON-ie.

Lista reguł#

curl -s https://prod.api.fakturnia.pl/external/v1/recurring-rules \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "rules": [
      {
        "id": "665f0c1234567890abcdef12",
        "name": "Abonament, Firma Sp. z o.o.",
        "status": "ACTIVE",
        "mode": "AUTO",
        "documentSummary": {
          "documentType": "FakturaVAT",
          "buyerName": "Firma Sp. z o.o.",
          "grossSum": 1230,
          "currency": "PLN"
        },
        "schedule": { "frequency": "MONTHLY", "dayOfMonth": 1, "startDate": "2026-01-01", "endType": "NEVER" },
        "nextRunAt": "2026-08-01",
        "occurrencesCount": 7,
        "documentsIssuedCount": 7
      }
    ],
    "summary": {
      "total": 3,
      "active": 2,
      "paused": 1,
      "finished": 0,
      "nextRunAt": "2026-08-01",
      "monthlyRecurringGross": 2460
    }
  }
}

Parametr ?status=ACTIVE|PAUSED|FINISHED zawęża listę. Blok summary zawsze opisuje wszystkie reguły konta, niezależnie od filtra.

monthlyRecurringGross to miesięczny przychód brutto z aktywnych reguł, po przeliczeniu częstotliwości na miesiąc (np. reguła kwartalna liczy się jako 1/3 kwoty). Sumowane są tylko reguły w PLN, bo API nie zgaduje kursów walut.

Zamiast pełnego szablonu dokumentu reguła zwraca documentSummary: typ dokumentu, nazwę nabywcy, kwotę brutto i walutę. To wystarcza do listowania i raportowania, a wygenerowane dokumenty pobierzesz normalnie przez endpointy dokumentów.

Szczegóły reguły#

curl -s https://prod.api.fakturnia.pl/external/v1/recurring-rules/{id} \
  -H "Authorization: Bearer $TOKEN"

Poza polami z listy szczegóły zawierają pełny harmonogram i automatyzacje:

Historia generacji#

Dziennik wystąpień reguły, od najnowszych:

curl -s "https://prod.api.fakturnia.pl/external/v1/recurring-rules/{id}/history?itemsPerPage=50" \
  -H "Authorization: Bearer $TOKEN"

{
  "success": true,
  "data": {
    "runs": [
      {
        "id": "666a0d1234567890abcdef56",
        "plannedDate": "2026-07-01",
        "issueDate": "2026-07-01",
        "documentId": "666a0e1234567890abcdef78",
        "documentNumber": "FV/7/2026",
        "status": "GENERATED",
        "emailSent": true,
        "ksefQueued": false
      }
    ]
  }
}

documentId i documentNumber wskazują wygenerowany dokument. Historia jest stronicowana jak listy: currentPage, itemsPerPage (domyślnie 50, do 200), w odpowiedzi totalCount i totalPages; starszy parametr limit nadal działa jako alias itemsPerPage. Lista reguł GET /recurring-rules także jest stronicowana (itemsPerPage do 100), a jej summary zawsze obejmuje wszystkie reguły.

Pauza i wznowienie#

# Wstrzymanie
curl -s -X PATCH https://prod.api.fakturnia.pl/external/v1/recurring-rules/{id}/toggle \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "active": false }'

# Wznowienie
curl -s -X PATCH https://prod.api.fakturnia.pl/external/v1/recurring-rules/{id}/toggle \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "active": true }'

Wstrzymana reguła nie generuje dokumentów. Wznowienie przelicza nextRunAt od dnia dzisiejszego: wystąpienia zaległe z okresu pauzy nie są nadrabiane. To bezpieczne zachowanie dla typowego scenariusza, w którym klient zawiesza abonament i wraca po kilku miesiącach.

Reguły zakończonej (FINISHED, czyli po dacie końcowej lub limicie wystąpień) nie można wznowić, próba zwraca 409 CONFLICT.

Dobre praktyki#

• Nasłuchuj webhooka document.created zamiast odpytywać listę. Dokumenty wystawiane przez reguły emitują document.created (jak każdy nowy dokument, z API albo z aplikacji), więc Twoja integracja dostaje je natychmiast. Historia reguły (/history) pozwala potem powiązać wystąpienie z documentId.
• Monitoruj wystąpienia FAILED. Okresowo (np. raz dziennie) przejrzyj historię aktywnych reguł; pole error mówi, dlaczego generacja się nie powiodła. Nieudane wystąpienie nie zatrzymuje cyklu, kolejne terminy idą dalej.
• Pauzuj zamiast usuwać. Gdy klient zawiesza abonament, wywołaj toggle z active: false. Historia i konfiguracja reguły zostają, a wznowienie samo przeliczy nextRunAt bez ryzyka wystawienia zaległych faktur.
• Trzymaj id reguły, nie jej nazwę. Nazwa jest edytowalna w aplikacji i może się zmienić bez ostrzeżenia.
• Rozróżniaj liczniki. occurrencesCount liczy wystąpienia harmonogramu (także przypomnienia i pominięcia), documentsIssuedCount tylko faktycznie wystawione dokumenty. Do raportowania sprzedaży używaj tego drugiego.
• Traktuj monthlyRecurringGross jako przybliżenie. Suma obejmuje wyłącznie aktywne reguły w PLN; reguły walutowe dolicz po własnym kursie na podstawie documentSummary.