Zeiterfassung – API-Referenz

Zeiteinträge auflisten

GET/api/v1/time-entries

Neueste zuerst. Zeitraum from/to (Kalendertage Europe/Berlin), Filter nach Projekt oder Kunde und Abrechnungsstatus (running, unbilled, invoiced, non_billable).

Berechtigung: time:read

Query-Parameter

fromstring (date)
ab Tag (inkl., Europe/Berlin)
tostring (date)
bis Tag (inkl.)
projectIdstring
max. 128 Zeichen
contactIdstring
nicht zusammen mit projectId
max. 128 Zeichen
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"
limitinteger
Anzahl Einträge (1–100)
1–100 · Standard: 25
cursorstring
`nextCursor` der vorherigen Seite
max. 500 Zeichen

Antwort 200

object"list"Pflicht
dataArray<TimeEntry>Pflicht
- idstringPflicht
- projectIdstring | nullPflicht
- taskIdstring | nullPflicht
- contactIdstring | nullPflicht
- descriptionstringPflicht
- startstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- endstring (date-time) | nullPflicht
  null, solange der Timer läuft
- datestring (date)Pflicht
  Kalendertag des Beginns (Europe/Berlin)
- durationMinutesintegerPflicht
  Dauer in Minuten; bei laufendem Timer die bisher vergangene Zeit
  0–9007199254740991
- runningbooleanPflicht
- billablebooleanPflicht
- billingStatus"running" | "unbilled" | "invoiced" | "non_billable"Pflicht
- hourlyRateCentsinteger | nullPflicht
  abweichender Stundensatz; null = Satz von Aufgabe bzw. Projekt
  0–10000000
- invoicedInvoiceIdstring | nullPflicht
  Rechnung, mit der die Zeit abgerechnet wurde
- invoicedAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- createdAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- updatedAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
hasMorebooleanPflicht
nextCursorstring | nullPflicht

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/time-entries' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "object": "list",
  "data": [
    {
      "id": "string",
      "projectId": "string",
      "taskId": "string",
      "contactId": "string",
      "description": "string",
      "start": "2026-11-01T09:30:00.000Z",
      "end": "2026-11-01T09:30:00.000Z",
      "date": "2026-11-01",
      "durationMinutes": 0,
      "running": false,
      "billable": false,
      "billingStatus": "running",
      "hourlyRateCents": 0,
      "invoicedInvoiceId": "string",
      "invoicedAt": "2026-11-01T09:30:00.000Z",
      "createdAt": "2026-11-01T09:30:00.000Z",
      "updatedAt": "2026-11-01T09:30:00.000Z"
    }
  ],
  "hasMore": false,
  "nextCursor": "string"
}

Entweder start + end oder date (+ optional startTime) + durationMinutes. Höchstens 24 Stunden je Eintrag. Ohne billable gilt der Standard von Aufgabe bzw. Projekt. Löst time_entry.created aus.

Berechtigung: time:write

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · TimeEntryCreate

projectIdstring | null
max. 128 Zeichen
taskIdstring | null
max. 128 Zeichen
contactIdstring | null
ohne Projekt: Kunde direkt; mit Projekt: Kunde des Projekts
max. 128 Zeichen
descriptionstring
max. 1000 Zeichen · Standard: ""
startstring (date-time)
Beginn; alternativ `date` + `durationMinutes`
endstring (date-time)
Zeitpunkt (ISO 8601)
datestring (date)
Tag (Europe/Berlin), wenn nur eine Dauer erfasst wird
startTimestring
Uhrzeit zu `date` (Standard 09:00)
durationMinutesinteger
1–1440
billableboolean
Standard: wie Projekt/Aufgabe, sonst true
hourlyRateCentsinteger | null
Stundensatz in Cent (netto bzw. brutto je nach Rechnung)
0–10000000

Antwort 201 · TimeEntry

idstringPflicht
projectIdstring | nullPflicht
taskIdstring | nullPflicht
contactIdstring | nullPflicht
descriptionstringPflicht
startstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
endstring (date-time) | nullPflicht
null, solange der Timer läuft
datestring (date)Pflicht
Kalendertag des Beginns (Europe/Berlin)
durationMinutesintegerPflicht
Dauer in Minuten; bei laufendem Timer die bisher vergangene Zeit
0–9007199254740991
runningbooleanPflicht
billablebooleanPflicht
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"Pflicht
hourlyRateCentsinteger | nullPflicht
abweichender Stundensatz; null = Satz von Aufgabe bzw. Projekt
0–10000000
invoicedInvoiceIdstring | nullPflicht
Rechnung, mit der die Zeit abgerechnet wurde
invoicedAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "startTime": "string",
  "durationMinutes": 1,
  "billable": false,
  "hourlyRateCents": 0
}'

Antwort 201

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Zeiteintrag abrufen

GET/api/v1/time-entries/{id}

Berechtigung: time:read

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 200 · TimeEntry

idstringPflicht
projectIdstring | nullPflicht
taskIdstring | nullPflicht
contactIdstring | nullPflicht
descriptionstringPflicht
startstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
endstring (date-time) | nullPflicht
null, solange der Timer läuft
datestring (date)Pflicht
Kalendertag des Beginns (Europe/Berlin)
durationMinutesintegerPflicht
Dauer in Minuten; bei laufendem Timer die bisher vergangene Zeit
0–9007199254740991
runningbooleanPflicht
billablebooleanPflicht
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"Pflicht
hourlyRateCentsinteger | nullPflicht
abweichender Stundensatz; null = Satz von Aufgabe bzw. Projekt
0–10000000
invoicedInvoiceIdstring | nullPflicht
Rechnung, mit der die Zeit abgerechnet wurde
invoicedAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl 'https://www.debt-flow.io/api/v1/time-entries/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Zeiteintrag ändern

PATCH/api/v1/time-entries/{id}

Nur übergebene Felder. durationMinutes setzt das Ende relativ zum Beginn. Abgerechnete Einträge sind gesperrt (409 time_entry_invoiced). Löst time_entry.updated aus.

Berechtigung: time:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Body (JSON) · TimeEntryUpdate

projectIdstring | null
max. 128 Zeichen
taskIdstring | null
max. 128 Zeichen
contactIdstring | null
max. 128 Zeichen
descriptionstring
max. 1000 Zeichen
startstring (date-time)
Zeitpunkt (ISO 8601)
endstring (date-time)
Zeitpunkt (ISO 8601)
durationMinutesinteger
setzt das Ende = Beginn + Dauer
1–1440
billableboolean
hourlyRateCentsinteger | null
Stundensatz in Cent (netto bzw. brutto je nach Rechnung)
0–10000000

Antwort 200 · TimeEntry

idstringPflicht
projectIdstring | nullPflicht
taskIdstring | nullPflicht
contactIdstring | nullPflicht
descriptionstringPflicht
startstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
endstring (date-time) | nullPflicht
null, solange der Timer läuft
datestring (date)Pflicht
Kalendertag des Beginns (Europe/Berlin)
durationMinutesintegerPflicht
Dauer in Minuten; bei laufendem Timer die bisher vergangene Zeit
0–9007199254740991
runningbooleanPflicht
billablebooleanPflicht
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"Pflicht
hourlyRateCentsinteger | nullPflicht
abweichender Stundensatz; null = Satz von Aufgabe bzw. Projekt
0–10000000
invoicedInvoiceIdstring | nullPflicht
Rechnung, mit der die Zeit abgerechnet wurde
invoicedAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 409, 429, 500

curl -X PATCH 'https://www.debt-flow.io/api/v1/time-entries/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "durationMinutes": 1,
  "billable": false,
  "hourlyRateCents": 0
}'

Antwort 200

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Zeiteintrag löschen

DELETE/api/v1/time-entries/{id}

Abgerechnete Einträge sind gesperrt (409 time_entry_invoiced). Löst time_entry.deleted aus.

Berechtigung: time:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Antwort 204

Erfolg, keine Antwort

Mögliche Fehler: 400, 401, 403, 404, 409, 429, 500

curl -X DELETE 'https://www.debt-flow.io/api/v1/time-entries/ID' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Laufenden Zeiteintrag stoppen

POST/api/v1/time-entries/{id}/stop

Setzt das Ende (Standard: jetzt). Mindestens 1 Minute, höchstens 24 Stunden. 409 timer_not_running, wenn der Eintrag nicht läuft.

Berechtigung: time:write

Pfadparameter

idstringPflicht
ID der Ressource
max. 128 Zeichen

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · TimerStop

endstring (date-time)
Endzeit (Standard: jetzt)

Antwort 200 · TimeEntry

idstringPflicht
projectIdstring | nullPflicht
taskIdstring | nullPflicht
contactIdstring | nullPflicht
descriptionstringPflicht
startstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
endstring (date-time) | nullPflicht
null, solange der Timer läuft
datestring (date)Pflicht
Kalendertag des Beginns (Europe/Berlin)
durationMinutesintegerPflicht
Dauer in Minuten; bei laufendem Timer die bisher vergangene Zeit
0–9007199254740991
runningbooleanPflicht
billablebooleanPflicht
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"Pflicht
hourlyRateCentsinteger | nullPflicht
abweichender Stundensatz; null = Satz von Aufgabe bzw. Projekt
0–10000000
invoicedInvoiceIdstring | nullPflicht
Rechnung, mit der die Zeit abgerechnet wurde
invoicedAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/ID/stop' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "end": "2026-11-01T09:30:00.000Z"
}'

Antwort 200

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Rechnungsentwurf aus Zeiten erzeugen

POST/api/v1/time-entries/invoice

Rechnet offene, abrechenbare Zeiten eines Projekts (optional Zeitraum) oder ausgewählte Einträge ab. Legt einen Rechnungsentwurf an (ohne Nummer, nicht festgeschrieben) und markiert die Einträge als abgerechnet – in einer Transaktion. Positionen je Projekt, Aufgabe oder Eintrag; Menge = Stunden (2 Nachkommastellen) nach Abrechnungstakt. Fehler: 400 ohne Kunde/Stundensatz, 409 time_entries_not_billable, 422 nothing_to_invoice. Löst invoice.created und time_entry.updated aus. Weiter mit POST /invoices/{id}/finalize.

Berechtigung: time:write, invoices:write

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · TimeInvoiceRequest

projectIdstring
alle offenen, abrechenbaren Zeiten des Projekts (optional mit from/to)
max. 128 Zeichen
entryIdsArray<string>
oder genau diese Zeiteinträge
max. 128 Zeichen
fromstring (date)
Datum (YYYY-MM-DD)
tostring (date)
Datum (YYYY-MM-DD)
contactIdstring
Rechnungsempfänger; Standard: Kunde des Projekts
max. 128 Zeichen
groupBy"project" | "task" | "entry"
Standard: "task"
roundingMinutesinteger
Abrechnungstakt je Zeiteintrag in Minuten
-9007199254740991–9007199254740991 · Standard: 1
roundingMode"up" | "nearest"
Standard: "up"
taxRatenumber
Steuersatz der Positionen (bei Regelbesteuerung)
0–100 · Standard: 19
hourlyRateCentsinteger
Satz für Einträge ohne Stundensatz
0–10000000
issueDatestring (date)
Rechnungsdatum (Standard: heute)
subjectstring
max. 200 Zeichen
introTextstring
max. 5000 Zeichen
closingTextstring
max. 5000 Zeichen

Antwort 201 · TimeInvoiceResult

invoiceIdstringPflicht
ID des Rechnungsentwurfs (GET /invoices/{id})
status"draft"Pflicht
contactIdstringPflicht
entryCountintegerPflicht
-9007199254740991–9007199254740991
totalMinutesintegerPflicht
-9007199254740991–9007199254740991
totalsDocumentTotalsPflicht
- netCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- taxCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- grossCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- groupsArray<object>Pflicht
  - taxRatenumberPflicht
  - categorystringPflicht
  - netCentsintegerPflicht
    Betrag in Cent
    -100000000000–100000000000
  - taxCentsintegerPflicht
    Betrag in Cent
    -100000000000–100000000000
  - grossCentsintegerPflicht
    Betrag in Cent
    -100000000000–100000000000

Mögliche Fehler: 400, 401, 403, 404, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/invoice' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "string",
  "entryIds": [
    "string"
  ],
  "from": "2026-11-01",
  "to": "2026-11-01",
  "contactId": "string",
  "groupBy": "task",
  "roundingMinutes": 1,
  "roundingMode": "up",
  "taxRate": 19,
  "hourlyRateCents": 0,
  "issueDate": "2026-11-01",
  "subject": "string",
  "introText": "string",
  "closingText": "string"
}'

Antwort 201

{
  "invoiceId": "string",
  "status": "draft",
  "contactId": "string",
  "entryCount": 0,
  "totalMinutes": 0,
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  }
}

Vorschau: Rechnung aus Zeiten

POST/api/v1/time-entries/invoice-preview

Wie POST /time-entries/invoice, legt aber nichts an. Liefert Positionen, Summen und Hinweise (warnings).

Berechtigung: time:read

Body (JSON) · TimeInvoiceRequest

projectIdstring
alle offenen, abrechenbaren Zeiten des Projekts (optional mit from/to)
max. 128 Zeichen
entryIdsArray<string>
oder genau diese Zeiteinträge
max. 128 Zeichen
fromstring (date)
Datum (YYYY-MM-DD)
tostring (date)
Datum (YYYY-MM-DD)
contactIdstring
Rechnungsempfänger; Standard: Kunde des Projekts
max. 128 Zeichen
groupBy"project" | "task" | "entry"
Standard: "task"
roundingMinutesinteger
Abrechnungstakt je Zeiteintrag in Minuten
-9007199254740991–9007199254740991 · Standard: 1
roundingMode"up" | "nearest"
Standard: "up"
taxRatenumber
Steuersatz der Positionen (bei Regelbesteuerung)
0–100 · Standard: 19
hourlyRateCentsinteger
Satz für Einträge ohne Stundensatz
0–10000000
issueDatestring (date)
Rechnungsdatum (Standard: heute)
subjectstring
max. 200 Zeichen
introTextstring
max. 5000 Zeichen
closingTextstring
max. 5000 Zeichen

Antwort 200 · TimeInvoicePreview

contactIdstring | nullPflicht
contactNamestring | nullPflicht
projectIdstring | nullPflicht
entryCountintegerPflicht
-9007199254740991–9007199254740991
entryIdsArray<string>Pflicht
totalMinutesintegerPflicht
Minuten nach Rundung
-9007199254740991–9007199254740991
servicePeriodobject | nullPflicht
- fromstring (date)Pflicht
  Datum (YYYY-MM-DD)
- tostring (date)Pflicht
  Datum (YYYY-MM-DD)
priceMode"net" | "gross"Pflicht
taxTreatmentstringPflicht
linesArray<DocumentLine>Pflicht
- idstring
  stabile Positions-ID (vom Server vergeben, wenn leer)
  max. 40 Zeichen
- type"item" | "text" | "subtotal"
  Position, reine Textzeile oder Zwischensumme
  Standard: "item"
- articleIdstring
  Bezug zum Artikelstamm
  max. 128 Zeichen
- titlestringPflicht
  max. 300 Zeichen
- descriptionstring
  max. 5000 Zeichen
- quantitynumber
  -1000000–1000000 · Standard: 1
- unitstring
  Einheit, z. B. Stk, Std, pauschal (UN/ECE Rec 20 für E-Rechnung: Modul)
  max. 20 Zeichen
- unitPriceCentsinteger
  Betrag in Cent
  -100000000000–100000000000 · Standard: 0
- discountPercentnumber
  0–100
- taxRatenumber
  Steuersatz in Prozent (19, 7, 0 …)
  0–100 · Standard: 19
- totalCentsinteger
  Betrag in Cent
  -100000000000–100000000000
- servicePeriodobject
  - fromstring (date)Pflicht
    Datum (YYYY-MM-DD)
  - tostring (date)Pflicht
    Datum (YYYY-MM-DD)
- projectIdstring
  max. 128 Zeichen
- timeEntryIdsArray<string>
  max. 128 Zeichen
totalsDocumentTotalsPflicht
- netCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- taxCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- grossCentsintegerPflicht
  Betrag in Cent
  -100000000000–100000000000
- groupsArray<object>Pflicht
  - taxRatenumberPflicht
  - categorystringPflicht
  - netCentsintegerPflicht
    Betrag in Cent
    -100000000000–100000000000
  - taxCentsintegerPflicht
    Betrag in Cent
    -100000000000–100000000000
  - grossCentsintegerPflicht
    Betrag in Cent
    -100000000000–100000000000
missingRateEntryIdsArray<string>Pflicht
Einträge ohne Stundensatz – ohne `hourlyRateCents` wird keine Rechnung erstellt
warningsArray<string>Pflicht

Mögliche Fehler: 400, 401, 403, 404, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/invoice-preview' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "string",
  "entryIds": [
    "string"
  ],
  "from": "2026-11-01",
  "to": "2026-11-01",
  "contactId": "string",
  "groupBy": "task",
  "roundingMinutes": 1,
  "roundingMode": "up",
  "taxRate": 19,
  "hourlyRateCents": 0,
  "issueDate": "2026-11-01",
  "subject": "string",
  "introText": "string",
  "closingText": "string"
}'

Antwort 200

{
  "contactId": "string",
  "contactName": "string",
  "projectId": "string",
  "entryCount": 0,
  "entryIds": [
    "string"
  ],
  "totalMinutes": 0,
  "servicePeriod": {
    "from": "2026-11-01",
    "to": "2026-11-01"
  },
  "priceMode": "net",
  "taxTreatment": "string",
  "lines": [
    {
      "id": "string",
      "type": "item",
      "articleId": "string",
      "title": "string",
      "description": "string",
      "quantity": 1,
      "unit": "string",
      "unitPriceCents": 0,
      "discountPercent": 0,
      "taxRate": 19,
      "totalCents": 0,
      "servicePeriod": {
        "from": "2026-11-01",
        "to": "2026-11-01"
      },
      "projectId": "string",
      "timeEntryIds": [
        "string"
      ]
    }
  ],
  "totals": {
    "netCents": 0,
    "taxCents": 0,
    "grossCents": 0,
    "groups": [
      {
        "taxRate": 0,
        "category": "string",
        "netCents": 0,
        "taxCents": 0,
        "grossCents": 0
      }
    ]
  },
  "missingRateEntryIds": [
    "string"
  ],
  "warnings": [
    "string"
  ]
}

Abgerechnete Zeiten wieder freigeben

POST/api/v1/time-entries/release

Gibt die Zeiten einer Rechnung zur erneuten Abrechnung frei – nur wenn der Rechnungsentwurf gelöscht oder die Rechnung storniert ist (sonst 409 invoice_active). Löst time_entry.updated je Eintrag aus.

Berechtigung: time:write

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · TimeEntriesRelease

invoiceIdstringPflicht
gelöschter Entwurf oder stornierte Rechnung
max. 128 Zeichen

Antwort 200 · TimeEntriesReleaseResult

releasedintegerPflicht
-9007199254740991–9007199254740991

Mögliche Fehler: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/release' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "invoiceId": "string"
}'

Antwort 200

{
  "released": 0
}

Auswertung der Zeiten

GET/api/v1/time-entries/summary

Summen je Projekt, Aufgabe, Kunde, Tag, Woche oder Monat für einen Zeitraum (Standard: laufender Monat). Beträge = exakte Minuten × Stundensatz (Eintrag → Aufgabe → Projekt); Minuten ohne Satz stehen in missingRateMinutes.

Berechtigung: time:read

Query-Parameter

fromstring (date)
Standard: erster Tag des laufenden Monats
tostring (date)
Standard: heute
projectIdstring
max. 128 Zeichen
contactIdstring
max. 128 Zeichen
groupBy"project" | "task" | "contact" | "day" | "week" | "month"
Standard: "project"

Antwort 200 · TimeSummary

fromstring (date)Pflicht
Datum (YYYY-MM-DD)
tostring (date)Pflicht
Datum (YYYY-MM-DD)
groupBy"project" | "task" | "contact" | "day" | "week" | "month"Pflicht
totalsobjectPflicht
- entriesintegerPflicht
  -9007199254740991–9007199254740991
- minutesintegerPflicht
  -9007199254740991–9007199254740991
- billableMinutesintegerPflicht
  -9007199254740991–9007199254740991
- nonBillableMinutesintegerPflicht
  -9007199254740991–9007199254740991
- unbilledMinutesintegerPflicht
  -9007199254740991–9007199254740991
- invoicedMinutesintegerPflicht
  -9007199254740991–9007199254740991
- billableAmountCentsintegerPflicht
  abrechenbare Zeit × Stundensatz
  -9007199254740991–9007199254740991
- unbilledAmountCentsintegerPflicht
  noch nicht abgerechnet
  -9007199254740991–9007199254740991
- invoicedAmountCentsintegerPflicht
  -9007199254740991–9007199254740991
- missingRateMinutesintegerPflicht
  abrechenbare Minuten ohne Stundensatz (nicht im Betrag enthalten)
  -9007199254740991–9007199254740991
rowsArray<TimeSummaryRow>Pflicht
- keystringPflicht
- labelstringPflicht
- entriesintegerPflicht
  -9007199254740991–9007199254740991
- minutesintegerPflicht
  -9007199254740991–9007199254740991
- billableMinutesintegerPflicht
  -9007199254740991–9007199254740991
- nonBillableMinutesintegerPflicht
  -9007199254740991–9007199254740991
- unbilledMinutesintegerPflicht
  -9007199254740991–9007199254740991
- invoicedMinutesintegerPflicht
  -9007199254740991–9007199254740991
- billableAmountCentsintegerPflicht
  abrechenbare Zeit × Stundensatz
  -9007199254740991–9007199254740991
- unbilledAmountCentsintegerPflicht
  noch nicht abgerechnet
  -9007199254740991–9007199254740991
- invoicedAmountCentsintegerPflicht
  -9007199254740991–9007199254740991
- missingRateMinutesintegerPflicht
  abrechenbare Minuten ohne Stundensatz (nicht im Betrag enthalten)
  -9007199254740991–9007199254740991

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/time-entries/summary' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "from": "2026-11-01",
  "to": "2026-11-01",
  "groupBy": "project",
  "totals": {
    "entries": 0,
    "minutes": 0,
    "billableMinutes": 0,
    "nonBillableMinutes": 0,
    "unbilledMinutes": 0,
    "invoicedMinutes": 0,
    "billableAmountCents": 0,
    "unbilledAmountCents": 0,
    "invoicedAmountCents": 0,
    "missingRateMinutes": 0
  },
  "rows": [
    {
      "key": "string",
      "label": "string",
      "entries": 0,
      "minutes": 0,
      "billableMinutes": 0,
      "nonBillableMinutes": 0,
      "unbilledMinutes": 0,
      "invoicedMinutes": 0,
      "billableAmountCents": 0,
      "unbilledAmountCents": 0,
      "invoicedAmountCents": 0,
      "missingRateMinutes": 0
    }
  ]
}

Laufenden Timer abrufen

GET/api/v1/time-entries/timer

Höchstens ein Timer läuft je Konto. entry.durationMinutes = bisher vergangene Zeit.

Berechtigung: time:read

Antwort 200 · Timer

runningbooleanPflicht
entryTimeEntry | nullPflicht
- idstringPflicht
- projectIdstring | nullPflicht
- taskIdstring | nullPflicht
- contactIdstring | nullPflicht
- descriptionstringPflicht
- startstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- endstring (date-time) | nullPflicht
  null, solange der Timer läuft
- datestring (date)Pflicht
  Kalendertag des Beginns (Europe/Berlin)
- durationMinutesintegerPflicht
  Dauer in Minuten; bei laufendem Timer die bisher vergangene Zeit
  0–9007199254740991
- runningbooleanPflicht
- billablebooleanPflicht
- billingStatus"running" | "unbilled" | "invoiced" | "non_billable"Pflicht
- hourlyRateCentsinteger | nullPflicht
  abweichender Stundensatz; null = Satz von Aufgabe bzw. Projekt
  0–10000000
- invoicedInvoiceIdstring | nullPflicht
  Rechnung, mit der die Zeit abgerechnet wurde
- invoicedAtstring (date-time) | nullPflicht
  Zeitpunkt (ISO 8601)
- createdAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)
- updatedAtstring (date-time)Pflicht
  Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 429, 500

curl 'https://www.debt-flow.io/api/v1/time-entries/timer' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY"

Antwort 200

{
  "running": false,
  "entry": {
    "id": "string",
    "projectId": "string",
    "taskId": "string",
    "contactId": "string",
    "description": "string",
    "start": "2026-11-01T09:30:00.000Z",
    "end": "2026-11-01T09:30:00.000Z",
    "date": "2026-11-01",
    "durationMinutes": 0,
    "running": false,
    "billable": false,
    "billingStatus": "running",
    "hourlyRateCents": 0,
    "invoicedInvoiceId": "string",
    "invoicedAt": "2026-11-01T09:30:00.000Z",
    "createdAt": "2026-11-01T09:30:00.000Z",
    "updatedAt": "2026-11-01T09:30:00.000Z"
  }
}

Timer starten

POST/api/v1/time-entries/timer

Legt einen laufenden Zeiteintrag an. Ein bereits laufender Timer wird zum Startzeitpunkt beendet. Löst time_entry.created (und ggf. time_entry.updated für den beendeten) aus.

Berechtigung: time:write

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · TimerStart

projectIdstring | null
max. 128 Zeichen
taskIdstring | null
max. 128 Zeichen
contactIdstring | null
max. 128 Zeichen
descriptionstring
max. 1000 Zeichen · Standard: ""
billableboolean
startstring (date-time)
Startzeit (Standard: jetzt); höchstens 24 Std. zurück

Antwort 201 · TimeEntry

idstringPflicht
projectIdstring | nullPflicht
taskIdstring | nullPflicht
contactIdstring | nullPflicht
descriptionstringPflicht
startstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
endstring (date-time) | nullPflicht
null, solange der Timer läuft
datestring (date)Pflicht
Kalendertag des Beginns (Europe/Berlin)
durationMinutesintegerPflicht
Dauer in Minuten; bei laufendem Timer die bisher vergangene Zeit
0–9007199254740991
runningbooleanPflicht
billablebooleanPflicht
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"Pflicht
hourlyRateCentsinteger | nullPflicht
abweichender Stundensatz; null = Satz von Aufgabe bzw. Projekt
0–10000000
invoicedInvoiceIdstring | nullPflicht
Rechnung, mit der die Zeit abgerechnet wurde
invoicedAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/timer' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "",
  "billable": false,
  "start": "2026-11-01T09:30:00.000Z"
}'

Antwort 201

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}

Laufenden Timer stoppen

POST/api/v1/time-entries/timer/stop

Stoppt den laufenden Timer, ohne seine ID zu kennen (z. B. für Zapier/Make). 409 timer_not_running, wenn keiner läuft.

Berechtigung: time:write

Header

Idempotency-Keystring
Eindeutiger Schlüssel (8–255 Zeichen). Wiederholte Anfragen mit gleichem Schlüssel liefern 24 h lang dieselbe Antwort.
max. 255 Zeichen

Body (JSON) · TimerStop

endstring (date-time)
Endzeit (Standard: jetzt)

Antwort 200 · TimeEntry

idstringPflicht
projectIdstring | nullPflicht
taskIdstring | nullPflicht
contactIdstring | nullPflicht
descriptionstringPflicht
startstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
endstring (date-time) | nullPflicht
null, solange der Timer läuft
datestring (date)Pflicht
Kalendertag des Beginns (Europe/Berlin)
durationMinutesintegerPflicht
Dauer in Minuten; bei laufendem Timer die bisher vergangene Zeit
0–9007199254740991
runningbooleanPflicht
billablebooleanPflicht
billingStatus"running" | "unbilled" | "invoiced" | "non_billable"Pflicht
hourlyRateCentsinteger | nullPflicht
abweichender Stundensatz; null = Satz von Aufgabe bzw. Projekt
0–10000000
invoicedInvoiceIdstring | nullPflicht
Rechnung, mit der die Zeit abgerechnet wurde
invoicedAtstring (date-time) | nullPflicht
Zeitpunkt (ISO 8601)
createdAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)
updatedAtstring (date-time)Pflicht
Zeitpunkt (ISO 8601)

Mögliche Fehler: 400, 401, 403, 409, 422, 429, 500

curl -X POST 'https://www.debt-flow.io/api/v1/time-entries/timer/stop' \
  -H "Authorization: Bearer $DEBTFLOW_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "end": "2026-11-01T09:30:00.000Z"
}'

Antwort 200

{
  "id": "string",
  "projectId": "string",
  "taskId": "string",
  "contactId": "string",
  "description": "string",
  "start": "2026-11-01T09:30:00.000Z",
  "end": "2026-11-01T09:30:00.000Z",
  "date": "2026-11-01",
  "durationMinutes": 0,
  "running": false,
  "billable": false,
  "billingStatus": "running",
  "hourlyRateCents": 0,
  "invoicedInvoiceId": "string",
  "invoicedAt": "2026-11-01T09:30:00.000Z",
  "createdAt": "2026-11-01T09:30:00.000Z",
  "updatedAt": "2026-11-01T09:30:00.000Z"
}