Zum Inhalt springen
Dokumentation
Handbuch API Demo
Deutsch
App öffnen

Paginierung

Die drei Listenformen der NovaFisko-API, die Parameter page und per_page und der richtige Weg, alle Seiten zu durchlaufen.

Aktualisiert am 05.10.2026 Diese Seite bearbeiten

Nicht alle Listen sind paginiert. Die API liefert je nach Art der Ressource drei Formen. Die Referenz gibt die Form jeder Route an.

Form Wann Beispiele
Einfaches Array Stammdaten begrenzter Größe companies, accounts, journals, third-parties, vat-codes, fiscal-years
Seitenweise Paginierung Listen, die ständig wachsen entries, documents, document-imports, bank-transactions, coda-files, history, sync/conflicts
Cursor-Stream Verfolgen von Änderungen sync/pull

Einfache Arrays

Stammdaten werden vollständig zurückgegeben, als JSON-Array auf der obersten Ebene. Filtern Sie sie mit den Suchparametern der Route.

curl "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/third-parties?type=supplier&q=brasserie" \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

[
  {
    "id": 41,
    "type": "supplier",
    "code": "BRASSCOL",
    "name": "Brasserie des Collines SA",
    "vat_number": "BE0999900134",
    "version": 3
  }
]

Seitenweise Paginierung

Parameter

Parameter Standard Maximum Beschreibung
page 1 Seitennummer, beginnend bei 1
per_page 50 200 Anzahl der Elemente pro Seite

Die Bankbewegungen (bank-transactions) bilden eine Ausnahme: standardmäßig 100 Elemente, höchstens 500.

Form der Antwort

curl "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/entries?from=2026-07-01&to=2026-09-30&per_page=2&page=1" \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

{
  "current_page": 1,
  "data": [
    {
      "id": 1842,
      "journal_id": 3,
      "number": 212,
      "entry_date": "2026-09-30T00:00:00.000000Z",
      "label": "Brasserie des Collines SA",
      "reference": "F-2026-0918",
      "status": "posted",
      "journal": {"id": 3, "code": "ACH", "type": "purchase"},
      "third_party": {"id": 41, "name": "Brasserie des Collines SA"},
      "lines": [
        {"id": 5521, "account_id": 118, "debit": "1250.00", "credit": "0.00", "account": {"id": 118, "number": "604000", "label": "Achats de marchandises"}},
        {"id": 5522, "account_id": 77, "debit": "262.50", "credit": "0.00", "account": {"id": 77, "number": "411000", "label": "TVA à récupérer"}},
        {"id": 5523, "account_id": 90, "debit": "0.00", "credit": "1512.50", "account": {"id": 90, "number": "440000", "label": "Fournisseurs"}}
      ]
    }
  ],
  "first_page_url": "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/entries?page=1",
  "from": 1,
  "last_page": 87,
  "last_page_url": "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/entries?page=87",
  "links": [
    {"url": null, "label": "« Précédent", "active": false},
    {"url": "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/entries?page=1", "label": "1", "active": true}
  ],
  "next_page_url": "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/entries?page=2",
  "path": "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/entries",
  "per_page": 2,
  "prev_page_url": null,
  "to": 2,
  "total": 173
}
Feld Beschreibung
data Die Elemente der Seite
current_page, last_page Aktuelle Seite und letzte Seite
per_page Angewendete Seitengröße, nach Begrenzung auf das Maximum
total Gesamtzahl der Elemente, die den Filtern entsprechen
from, to Position des ersten und des letzten Elements der Seite
next_page_url, prev_page_url URL der nächsten oder vorherigen Seite, null, wenn es keine gibt
Achtung

Die URLs in next_page_url und links übernehmen Ihre Filter (from, to, per_page...) nicht. Bauen Sie die URL der nächsten Seite selbst auf, indem Sie page erhöhen und Ihre Parameter beibehalten.

Varianten

Einige Routen ergänzen die Standardpaginierung um Felder oder vereinfachen ihre Form.

Route Besonderheit
sync/conflicts Standardpaginierung, zusätzlich open: die Anzahl der noch offenen Konflikte
trash data, current_page, per_page, last_page, total, zusätzlich counts, types, retention_days, can_purge
activity, firms/{firm}/activity data, current_page, per_page und has_more anstelle von total
firms/{firm}/webhooks/{webhook}/deliveries data und meta: {current_page, last_page, per_page, total}

Beim Aktivitätsprotokoll blättern Sie weiter, solange has_more den Wert true hat.

Alle Seiten durchlaufen

use GuzzleHttp\Client;

$client = new Client([
    'base_uri' => 'https://api.novafisko.com/v1/',
    'headers' => ['Authorization' => 'Bearer '.getenv('NOVAFISKO_TOKEN'), 'Accept' => 'application/json'],
]);

$page = 1;
do {
    $response = json_decode((string) $client->get("companies/{$company}/entries", [
        'query' => ['fiscal_year_id' => 7, 'per_page' => 200, 'page' => $page],
    ])->getBody(), true);

    foreach ($response['data'] as $entry) {
        // Handle one entry
    }
    $page++;
} while ($page <= $response['last_page']);

import os
import requests

session = requests.Session()
session.headers.update({"Authorization": f"Bearer {os.environ['NOVAFISKO_TOKEN']}", "Accept": "application/json"})

def all_entries(company, **filters):
    page = 1
    while True:
        payload = session.get(
            f"https://api.novafisko.com/v1/companies/{company}/entries",
            params={**filters, "per_page": 200, "page": page},
            timeout=60,
        ).json()
        yield from payload["data"]
        if page >= payload["last_page"]:
            break
        page += 1

Reihenfolge und Stabilität

Paginierte Listen sind vom neuesten zum ältesten Element sortiert (entries nach Buchungsdatum, dann nach id, history nach id). Werden während Ihres Durchlaufs Elemente angelegt, kann ein Element von einer Seite auf die nächste rutschen und zweimal erscheinen. Zwei Gegenmaßnahmen:

  • begrenzen Sie den Zeitraum mit from und to auf ein geschlossenes Intervall;
  • entfernen Sie Duplikate auf Ihrer Seite anhand der id.
Tipp

Für eine vollständige, aktuell gehaltene Kopie fragen Sie die Listen nicht in einer Schleife ab. Laden Sie sie einmal und verfolgen Sie die Änderungen danach mit sync/pull.

Cursor-Stream

GET sync/pull kennt keine Seiten. Sie übergeben den zuletzt erhaltenen Cursor, und die Route liefert die seither eingetretenen Änderungen.

curl "https://api.novafisko.com/v1/companies/k3Jd9fPq2LmX/sync/pull?since=48211&limit=500" \
  -H "Authorization: Bearer $NOVAFISKO_TOKEN"

{
  "cursor": 48236,
  "has_more": false,
  "full_resync": false,
  "changes": [
    {"resource": "third_parties", "op": "upsert", "id": 41, "version": 4, "data": {"id": 41, "name": "Brasserie des Collines SA"}, "changed_at": "2026-10-05T08:41:02+00:00", "seq": 48236}
  ],
  "server_time": "2026-10-05T08:41:09+00:00"
}

Solange has_more den Wert true hat, rufen Sie die Route sofort mit dem neuen cursor erneut auf. Den vollständigen Ablauf finden Sie unter Fortlaufend synchronisieren.

Siehe auch