EntwicklerAPI-Ressourcen

Debitor:innen

Eine Debitor:in ist das Zahlungskonto einer Familie: was sie bezahlt hat, welche Beiträge noch offen sind und wie hoch ihr Saldo ist. Eine Familie wird mit ihrer ersten Anmeldung zur Debitor:in. In der API ist eine Debitor:in ein debtor.

Endpunkte

GET/debtorsAlle Debitor:innen abrufen
GET/debtors/{uuid}Eine Debitor:in abrufen
POST/debtors/{uuid}/book-entriesEine Buchung hinzufügen

Alle Endpunkte für Debitor:innen brauchen ROLE_ADMIN und ROLE_PAYMENTS_ADMIN. Beträge stehen in Cent. Bei Buchungen schreiben positive Werte der Familie etwas gut. Negative Werte sind Forderungen an die Familie.

Das Modell der Debitor:in

Name
uuid
Typ
string
Beschreibung
Die Kennung der Debitor:in.
Name
account
Typ
reference
Beschreibung
Das Konto.
Name
balance
Typ
integer
Beschreibung
Die Summe aller Buchungen, die keine Zahlungen sind, in Cent: von Hand angelegte Buchungen, auf Belegen verrechnetes Guthaben, Forderungen für teilweise bezahlte Beiträge und Stornos, die dem Saldo gutgeschrieben wurden. Ein positiver Saldo wird mit der nächsten Zahlung aufgebraucht. Ein negativer Saldo ist eine Forderung.
Name
paid
Typ
integer
Beschreibung
Die Summe der Buchungen vom type payment, in Cent: eingegangenes Geld abzüglich ausgezahlter Stornos.
Name
due
Typ
integer
Beschreibung
Die Summe der Beiträge der offenen Anmeldungen, in Cent.
Name
openAttendances
Typ
string[]
Beschreibung
Die UUIDs der Anmeldungen, deren Beitrag fällig und unbezahlt ist.
Name
receipts
Typ
reference[]
Beschreibung
Die Belege der Familie. Der name der Referenz ist die Belegnummer.
Name
bookEntries
Typ
object[]
Beschreibung
Die Buchungen der Debitor:in. Jede hat eine uuid, ein bookingDate, einen value in Cent, einen type (payment für eingegangenes oder ausgezahltes Geld, manual für alles andere), den Text postingRecord und die UUID des Belegs receipt, aus dem sie entstanden ist. Bei einer von Hand angelegten Buchung ist receipt gleich null.

GET/debtors

Alle Debitor:innen abrufen

Liefert eine Seite mit Debitor:innen, sortiert nach dem Nachnamen der Familie. Außerhalb Ihres eigenen Mandanten sind sie nach Anlage sortiert.

Optionale Filter

Name
q
Typ
string
Beschreibung
Nur Debitor:innen von Familien, deren Name oder E-Mail-Adresse diesen Text enthält. Findet außerhalb Ihres eigenen Mandanten nichts.
Name
account
Typ
string
Beschreibung
Nur die Debitor:in dieses Kontos (UUID, oder E-Mail-Adresse innerhalb Ihres eigenen Mandanten).
Name
withBalance
Typ
boolean
Beschreibung
true für nur die Debitor:innen mit einem positiven balance.
Name
page, itemsPerPage
Typ
integer
Beschreibung
Siehe Paginierung.

GET/debtors

curl -G https://example.fepli.eu/api/debtors \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  --data-urlencode "account=familie.mueller@example.org"

Antwort

[
  {
    "uuid": "0191c7b4-5a6b-7c8d-9e0f-1a2b3c4d5e09",
    "account": {
      "uuid": "0191c7b2-4d5e-7f60-8a1b-2c3d4e5f6a05",
      "name": "Anna Müller"
    },
    "balance": 0,
    "paid": 1250,
    "due": 400,
    "bookEntries": [
      {
        "uuid": "0192e1a1-0a1b-7c2d-8e3f-4a5b6c7d8e29",
        "bookingDate": "2026-09-10T10:22:31+02:00",
        "value": 1250,
        "type": "payment",
        "postingRecord": "RE-142",
        "receipt": "0192e1a0-7b8c-7d9e-a0f1-2b3c4d5e6f08"
      }
    ],
    "receipts": [
      { "uuid": "0192e1a0-7b8c-7d9e-a0f1-2b3c4d5e6f08", "name": "RE-142" }
    ],
    "openAttendances": ["0192d0f9-5c6d-7e7f-9a8b-0c1d2e3f4a30"]
  }
]

GET/debtors/{uuid}

Eine Debitor:in abrufen

Liefert eine Debitor:in. Die UUID der Debitor:in eines Kontos steht in dessen Feld debtor.

GET/debtors/{uuid}

curl https://example.fepli.eu/api/debtors/0191c7b4-5a6b-7c8d-9e0f-1a2b3c4d5e09 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

POST/debtors/{uuid}/book-entries

Eine Buchung hinzufügen

Fügt der Debitor:in eine freie Buchung hinzu: eine Gutschrift für die Familie, zum Beispiel nach einer Überzahlung, oder eine Forderung an die Familie. Liefert die aktualisierte Debitor:in.

Pflichtattribute

Name
value
Typ
integer
Beschreibung
Der Betrag in Cent. Positiv schreibt der Familie etwas gut, negativ belastet sie. Darf nicht 0 sein.
Name
postingRecord
Typ
string
Beschreibung
Der Buchungstext, bis zu 255 Zeichen.

POST/debtors/{uuid}/book-entries

curl -X POST https://example.fepli.eu/api/debtors/0191c7b4-5a6b-7c8d-9e0f-1a2b3c4d5e09/book-entries \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"value": 500, "postingRecord": "Gutschrift: doppelt überwiesen"}'