EntwicklerAPI-Ressourcen

Belege

Ein Beleg hält Geld für eine oder mehrere Anmeldungen einer Familie fest: eine Zahlung vor Ort, eine Online-Zahlung, eine noch offene Rechnung oder das Storno eines früheren Belegs. In der API ist ein Beleg ein receipt.

Endpunkte

GET/receiptsAlle Belege abrufen
GET/receipts/{uuid}Einen Beleg abrufen
POST/receiptsEinen Beleg anlegen
POST/receipts/{uuid}/transitionEinen Übergang anwenden
POST/receipts/{uuid}/reverseEinen Beleg stornieren
POST/receipts/{uuid}/adjustEinen Beleg korrigieren

Alle Endpunkte für Belege brauchen ROLE_ADMIN und ROLE_PAYMENTS_ADMIN. Beträge sind in Cent; die Positionen eines Stornos sind negativ.

Eine Rechnung ist keine eigene Ressource: Sie ist ein Beleg, der noch nicht bezahlt wurde. Sie legen einen Beleg offen an und wenden pay an, wenn das Geld eingeht. Nehmen Sie das Geld sofort vor Ort entgegen, legen Sie den Beleg gleich bezahlt an.

Das Modell des Belegs

Name
uuid
Typ
string
Beschreibung
Die Kennung des Belegs.
Name
receiptNumber
Typ
string
Beschreibung
Die Belegnummer: das Präfix der Organisation, gefolgt von einer laufenden Nummer. Sie wird vergeben, wenn der Beleg bezahlt wird. Eine offene Rechnung hat deshalb noch keine.
Name
status
Typ
string
Beschreibung
created (offen: eine Rechnung oder eine Online-Zahlung, die noch nicht durchgelaufen ist), paid, failed oder abandoned. Siehe den Workflow des Belegs.
Name
totalAmount
Typ
integer
Beschreibung
Die Summe der Positionen in Cent.
Name
createdAt
Typ
timestamp
Beschreibung
Wann der Beleg angelegt wurde.
Name
billingAddress
Typ
string
Beschreibung
Die Rechnungsanschrift, wie sie auf dem Beleg gedruckt ist, eine Zeile je Zeile. Ein Platzhalter, wenn piiMasked true ist.
Name
billingEmail
Typ
string
Beschreibung
Die E-Mail-Adresse, an die der Beleg geht. Ein Platzhalter, wenn piiMasked true ist.
Name
paymentMethod
Typ
string
Beschreibung
Bei Online-Zahlungen der Name der Zahlungsmethode (Online-Zahlung, wenn er nicht bekannt ist), bei jedem anderen Beleg Bargeld, auch bei offenen Rechnungen und Stornos.
Name
debtor
Typ
object
Beschreibung
Die Debitor:in der Familie: ihre uuid und ihr aktuelles balance.
Name
account
Typ
reference
Beschreibung
Das Konto.
Name
recordedBy
Typ
reference
Beschreibung
Wer den Beleg angelegt hat: die Kolleg:in, die ihn erfasst hat, oder bei Online-Zahlungen das Konto der Familie. Fehlt bei Belegen, die ein Service-Account angelegt hat.
Name
recordedByName
Typ
string
Beschreibung
Wer den Beleg angelegt hat, so wie das Admin-Panel es zeigt: der Name in recordedBy oder {name} (Service-Account) bei einem Service-Account, mit dem Namen, den er damals hatte.
Name
items
Typ
object[]
Beschreibung
Die Positionen des Belegs. Jede hat eine uuid, einen type (attendance für eine Anmeldung, discount für verrechnetes Guthaben), einen amount und die UUID der Anmeldung als attendance, dazu offer und participant als Referenzen. Bei Positionen vom Typ discount sind diese drei null.
Name
isReversal
Typ
boolean
Beschreibung
Ob die Summe des Belegs negativ ist, wie bei einem Storno. Ein Storno über 0 (100 % einbehalten) zeigt false. Sicher erkennen Sie ein Storno an reversalOf.
Name
reversalOf
Typ
reference
Beschreibung
Der Beleg, den dieser storniert. Der name der Referenz ist seine Belegnummer.
Name
reversals
Typ
reference[]
Beschreibung
Belege, die diesen ganz oder teilweise stornieren.
Name
canBeAdjusted
Typ
boolean
Beschreibung
Ob sich dieser Beleg korrigieren lässt: ein bezahlter, nicht stornierter Beleg einer Zahlung vor Ort. Immer false, wenn piiMasked true ist.
Name
onlineTransactionId
Typ
string
Beschreibung
Die Transaktions-ID des Zahlungsdienstleisters, bei Online-Zahlungen.
Name
transitions
Typ
string[]
Beschreibung
Die Übergänge des Workflows, die Sie jetzt anwenden können: pay und abandon bei einem offenen Beleg, sonst keine. Immer leer, wenn piiMasked true ist.
Name
piiMasked
Typ
boolean
Beschreibung
true, wenn die Angaben der Zahlenden vor Ihnen verborgen sind, sodass billingAddress und billingEmail Platzhalter enthalten. Ein solcher Beleg ist schreibgeschützt: Er lässt sich weder bezahlen, verwerfen, stornieren noch korrigieren. Siehe Maskierte personenbezogene Daten.

Der Workflow des Belegs

Ein Beleg beginnt offen (created) und endet als paid oder abandoned. Ein offener Beleg ist eine Rechnung: Die Familie schuldet das Geld, nichts ist als bezahlt markiert, und der Beleg hat keine Nummer. Einen Übergang wenden Sie mit POST /receipts/{uuid}/transition an.

Übergang	Von	Nach	Was geschieht
`pay`	`created`	`paid`	Das Geld wurde entgegengenommen. Der Beleg erhält seine Nummer, die Anmeldungen werden als bezahlt markiert, und das Guthaben, das er verrechnet, wird von der Debitor:in der Familie abgezogen.
`abandon`	`created`	`abandoned`	Der Beleg wird verworfen. Die Anmeldungen bleiben unbezahlt.

Um Geld vor Ort in einem Schritt entgegenzunehmen, legen Sie den Beleg mit "paid": true an.

Auch ein Beleg, für den die Familie einen Zahlungslink erhalten hat, ist offen und lässt sich vor Ort bezahlen. Sobald die Familie online zu zahlen beginnt, erhält der Beleg eine onlineTransactionId, und der Zahlungsdienstleister setzt ihn auf paid oder failed: Für Sie hat er dann keine Übergänge mehr.

Ein bezahlter Beleg wechselt seinen Status nicht mehr. Um Geld zurückzugeben, stornieren Sie ihn; um ihn zu berichtigen, korrigieren Sie ihn.

GET/receipts

Alle Belege abrufen

Liefert eine Seite mit Belegen, die neuesten zuerst.

Optionale Filter

Name
q
Typ
string
Beschreibung
Nur Belege, deren Nummer, Rechnungsanschrift oder Rechnungs-E-Mail diesen Text enthält. Außerhalb Ihres eigenen Mandanten wird nur die Belegnummer durchsucht.
Name
status
Typ
string
Beschreibung
Nur Belege in diesem Status: created, paid, failed oder abandoned.
Name
account
Typ
string
Beschreibung
Nur Belege dieses Kontos (UUID, oder E-Mail-Adresse innerhalb Ihres eigenen Mandanten).
Name
debtor
Typ
string
Beschreibung
Nur Belege dieser Debitor:in (UUID).
Name
participant
Typ
string
Beschreibung
Nur Belege, die eine Anmeldung dieser Teilnehmer:in umfassen (UUID).
Name
attendance
Typ
string
Beschreibung
Nur Belege, die diese Anmeldung umfassen (UUID).
Name
edition
Typ
string
Beschreibung
Nur Belege, die Anmeldungen dieser Saison umfassen (UUID oder Alias).
Name
reversals
Typ
boolean
Beschreibung
true nur für Stornos, false, um sie wegzulassen.
Name
createdSince
Typ
timestamp
Beschreibung
Nur Belege, die seit diesem Zeitpunkt angelegt wurden.
Name
page, itemsPerPage
Typ
integer
Beschreibung
Siehe Paginierung.

GET/receipts

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

Antwort

[
  {
    "uuid": "0192e1a0-7b8c-7d9e-a0f1-2b3c4d5e6f08",
    "receiptNumber": "RE-142",
    "status": "paid",
    "totalAmount": 1250,
    "createdAt": "2026-09-10T10:22:31+02:00",
    "billingAddress": "Anna Müller\nLindenallee 12\n12345 Elmsbrück",
    "billingEmail": "familie.mueller@example.org",
    "paymentMethod": "Bargeld",
    "debtor": {
      "uuid": "0191c7b4-5a6b-7c8d-9e0f-1a2b3c4d5e09",
      "balance": 0
    },
    "account": {
      "uuid": "0191c7b2-4d5e-7f60-8a1b-2c3d4e5f6a05",
      "name": "Anna Müller"
    },
    "recordedBy": {
      "uuid": "0190a1b2-c3d4-7e5f-8a6b-7c8d9e0f1a22",
      "name": "Sabine Krüger"
    },
    "recordedByName": "Sabine Krüger",
    "items": [
      {
        "uuid": "0192e1a0-8c9d-7e0f-a1b2-c3d4e5f6a724",
        "type": "attendance",
        "amount": 750,
        "attendance": "0192d0e8-3a4b-7c5d-9e6f-7a8b9c0d1e07",
        "offer": {
          "uuid": "0192a4f1-6e3b-7c85-b1d2-8f4e6a9c3b03",
          "name": "Fahrradtour durch den Stadtpark",
          "alias": "fahrradtour-durch-den-stadtpark"
        },
        "participant": {
          "uuid": "0191c7b3-1f2a-7c4d-8e5f-6a7b8c9d0e06",
          "name": "Lena Müller"
        }
      },
      {
        "uuid": "0192e1a0-9dae-7f10-b2c3-d4e5f6a7b825",
        "type": "attendance",
        "amount": 500,
        "attendance": "0192d0f1-4b5c-7d6e-8f7a-9b0c1d2e3f23",
        "offer": {
          "uuid": "0193c8a2-5d6e-7f70-9a8b-1c2d3e4f5a14",
          "name": "Töpfern für Anfänger",
          "alias": "toepfern-fuer-anfaenger"
        },
        "participant": {
          "uuid": "0191c7b3-2e3f-7a4b-9c5d-6e7f8a9b0c16",
          "name": "Paul Müller"
        }
      }
    ],
    "isReversal": false,
    "reversals": [],
    "canBeAdjusted": true,
    "transitions": [],
    "piiMasked": false
  }
]

GET/receipts/{uuid}

Einen Beleg abrufen

Liefert einen Beleg.

GET/receipts/{uuid}

curl https://example.fepli.eu/api/receipts/0192e1a0-7b8c-7d9e-a0f1-2b3c4d5e6f08 \
  -H "Authorization: Bearer $FEPLI_TOKEN"

POST/receipts

Einen Beleg anlegen

Legt einen Beleg für eine oder mehrere offene Anmeldungen einer Familie an. Standardmäßig ist der Beleg offen: eine Rechnung, die Rechnung des Admin-Panels. Nichts gilt als bezahlt, bis Sie pay anwenden.

Mit "paid": true hält der Beleg Geld fest, das vor Ort entgegengenommen wurde, wie Zahlung erfassen im Admin-Panel: Die Anmeldungen werden als bezahlt markiert, und der Beleg erhält sofort seine Nummer.

Alle Anmeldungen müssen zur selben Familie gehören, unbezahlt sein und zu einer Saison gehören, die Beiträge über fepli einzieht.
Sehen Sie die Angaben der Familie maskiert, mit oder ohne Konto, lautet die Antwort 403.
Hat die Debitor:in der Familie ein positives balance, wird es zuerst verrechnet (als Position vom Typ discount), es sei denn, Sie senden "useBalance": false. Verrechnet wird nur der Teil, den kein anderer offener Beleg schon gegen seine Gebühren setzt. Der Betrag kann daher niedriger sein als balance.
Ist der Betrag einer Position kleiner als der Beitrag, wird der Rest beim Bezahlen des Belegs als Forderung an die Debitor:in der Familie gebucht (bei Teilnehmer:innen mit Konto).

Pflichtattribute

Name
items
Typ
object[]
Beschreibung
Die Anmeldungen auf dem Beleg: Objekte mit attendance (UUID) und optional amount in Cent, von 0 bis zum Beitrag. Ohne amount wird der volle Beitrag berechnet.

Optionale Attribute

Name
paid
Typ
boolean
Beschreibung
Das Geld wurde vor Ort entgegengenommen: Der Beleg ist sofort bezahlt. Der Standard ist false, ein offener Beleg.
Name
useBalance
Typ
boolean
Beschreibung
Das Guthaben der Familie verrechnen, abzüglich dessen, was andere offene Belege schon halten. Der Standard ist true.
Name
billingAddress
Typ
string
Beschreibung
Die Rechnungsanschrift, wie sie auf dem Beleg gedruckt wird. Der Standard ist die Anschrift des Kontos, sonst die der Teilnehmer:in.
Name
billingEmail
Typ
string
Beschreibung
Wohin der Beleg geschickt wird. Der Standard ist die E-Mail-Adresse des Kontos.
Name
notify
Typ
boolean
Beschreibung
Den Beleg per E-Mail an die Familie schicken. Der Standard ist false. Braucht paid.

POST/receipts

curl -X POST https://example.fepli.eu/api/receipts \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "attendance": "0192d0e8-3a4b-7c5d-9e6f-7a8b9c0d1e07" },
      { "attendance": "0192d0f1-4b5c-7d6e-8f7a-9b0c1d2e3f23" }
    ]
  }'

Antwort (201 Created, Auszug)

{
  "uuid": "0193d2b4-6c7d-7e8f-9a0b-1c2d3e4f5a26",
  "receiptNumber": null,
  "status": "created",
  "totalAmount": 1250,
  "…": "…",
  "transitions": ["pay", "abandon"]
}

POST/receipts/{uuid}/transition

Einen Übergang anwenden

Führt einen offenen Beleg durch seinen Workflow: pay, wenn das Geld entgegengenommen wurde, abandon, wenn der Beleg nicht mehr gebraucht wird. Die transitions des Belegs nennen die Übergänge, die jetzt möglich sind. Alles andere ergibt ein 409, das die möglichen Übergänge nennt. Dasselbe gilt für jeden Übergang bei einer Online-Zahlung. Bei einem Beleg mit piiMasked true lautet die Antwort 403.

Vor pay wird der Beleg gegen das geprüft, was seit seiner Erstellung geschehen ist. Wurde inzwischen eine seiner Anmeldungen bezahlt oder deckt der Teil des Guthabens der Familie, den kein anderer offener Beleg hält, nicht mehr, was der Beleg davon verrechnet, lautet die Antwort 409: Verwerfen Sie den Beleg und legen Sie einen neuen an.

Pflichtattribute

Name
transition
Typ
string
Beschreibung
pay oder abandon.

Optionale Attribute

Name
notify
Typ
boolean
Beschreibung
Bei pay: den Beleg per E-Mail an die Familie schicken. Der Standard ist false.

POST/receipts/{uuid}/transition

curl -X POST https://example.fepli.eu/api/receipts/0193d2b4-6c7d-7e8f-9a0b-1c2d3e4f5a26/transition \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"transition": "pay", "notify": true}'

Antwort (Auszug)

{
  "uuid": "0193d2b4-6c7d-7e8f-9a0b-1c2d3e4f5a26",
  "receiptNumber": "RE-158",
  "status": "paid",
  "totalAmount": 1250,
  "…": "…",
  "canBeAdjusted": true,
  "transitions": []
}

POST/receipts/{uuid}/reverse

Einen Beleg stornieren

Storniert einen bezahlten Beleg ganz oder teilweise und liefert den neuen Stornobeleg. Standardmäßig werden die Anmeldungen wieder als unbezahlt markiert und das Geld wird ausgezahlt. Der Stornobeleg geht wie im Admin-Panel per E-Mail an die Rechnungsanschrift.

Nur bezahlte Belege lassen sich stornieren, und ein Storno lässt sich selbst nicht stornieren (409). Ein offener Beleg hat nichts zu stornieren: Verwerfen Sie ihn stattdessen. Anmeldungen, die schon storniert und als unbezahlt markiert wurden, werden übersprungen. Bleibt nichts zu stornieren, lautet die Antwort 409. Bei einem Beleg mit piiMasked true lautet die Antwort 403: Der Storno würde die Platzhalter in einen neuen Beleg kopieren.

Optionale Attribute

Name
items
Typ
string[]
Beschreibung
Die UUIDs der Positionen, die storniert werden. Lassen Sie sie weg, um jede Anmeldung auf dem Beleg zu stornieren.
Name
partial
Typ
object
Beschreibung
Weniger als den vollen Betrag stornieren. {"type": "percent", "value": 20} behält 20 % ein und storniert die übrigen 80 %, zum Beispiel, um eine Stornogebühr zu behalten. {"type": "amount", "value": 1250} storniert genau 1250 Cent. Lassen Sie es weg, um den vollen Betrag zu stornieren.
Name
payout
Typ
string
Beschreibung
Wohin das Geld geht: payout (zurückgegeben, der Standard) oder balance (dem Guthaben der Familie gutgeschrieben, zur späteren Verrechnung).
Name
unpay
Typ
boolean
Beschreibung
Die Anmeldungen wieder als unbezahlt markieren. Der Standard ist true. Senden Sie false, wenn das Geld aus einem anderen Grund zurückgegeben wurde und die Anmeldungen bezahlt bleiben.
Name
withdraw
Typ
boolean
Beschreibung
Die Anmeldungen auch abmelden. Der Standard ist false.

POST/receipts/{uuid}/reverse

curl -X POST https://example.fepli.eu/api/receipts/0192e1a0-7b8c-7d9e-a0f1-2b3c4d5e6f08/reverse \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": ["0192e1a0-8c9d-7e0f-a1b2-c3d4e5f6a724"],
    "payout": "balance",
    "withdraw": true
  }'

Antwort (Auszug)

{
  "uuid": "0193d3c5-7d8e-7f90-8a1b-2c3d4e5f6a27",
  "receiptNumber": "RE-157",
  "status": "paid",
  "totalAmount": -750,
  "isReversal": true,
  "reversalOf": {
    "uuid": "0192e1a0-7b8c-7d9e-a0f1-2b3c4d5e6f08",
    "name": "RE-142"
  },
  "items": [
    {
      "uuid": "0193d3c5-8e9f-7a01-9b2c-3d4e5f6a7b28",
      "type": "attendance",
      "amount": -750,
      "attendance": "0192d0e8-3a4b-7c5d-9e6f-7a8b9c0d1e07",
      "…": "…"
    }
  ],
  "…": "…"
}

POST/receipts/{uuid}/adjust

Einen Beleg korrigieren

Korrigiert den Beleg einer Zahlung vor Ort, zum Beispiel, wenn ein falscher Betrag eingegeben wurde. Der ursprüngliche Beleg wird vollständig storniert, und ein neuer wird mit den Positionen, der Anschrift und der E-Mail-Adresse ausgestellt, die Sie senden. Liefert den neuen Beleg.

Nur bezahlte, nicht stornierte Belege einer Zahlung vor Ort lassen sich korrigieren: Prüfen Sie canBeAdjusted. Sonst lautet die Antwort 409. Bei einem Beleg mit piiMasked true lautet die Antwort 403, auch wenn die Anfrage eine neue Anschrift sendet.

Pflichtattribute

Name
items
Typ
object[]
Beschreibung
Die Positionen des neuen Belegs: Objekte mit attendance (UUID, eine der Anmeldungen des ursprünglichen Belegs) und amount in Cent.

Optionale Attribute

Name
billingAddress
Typ
string
Beschreibung
Die Rechnungsanschrift. Der Standard ist die des ursprünglichen Belegs.
Name
billingEmail
Typ
string
Beschreibung
Die E-Mail-Adresse. Der Standard ist die des ursprünglichen Belegs.
Name
paid
Typ
boolean
Beschreibung
Den neuen Beleg als bezahlt markieren. Der Standard ist true. Mit false bleibt der neue Beleg offen, bis Sie pay anwenden.
Name
notify
Typ
boolean
Beschreibung
Den neuen Beleg per E-Mail schicken. Der Standard ist false. Braucht paid und eine billingEmail in der Anfrage.

POST/receipts/{uuid}/adjust

curl -X POST https://example.fepli.eu/api/receipts/0192e1a0-7b8c-7d9e-a0f1-2b3c4d5e6f08/adjust \
  -H "Authorization: Bearer $FEPLI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "attendance": "0192d0e8-3a4b-7c5d-9e6f-7a8b9c0d1e07", "amount": 750 },
      { "attendance": "0192d0f1-4b5c-7d6e-8f7a-9b0c1d2e3f23", "amount": 250 }
    ]
  }'