API Reference

Complete API documentation for the Taskfree Invoice platform. Every endpoint, nothing left out.

Authentication

Base URL: https://f8j4vnqvduyaq65x88go5gxe.taskfree.de

All API endpoints (except health checks) require authentication. Two methods are supported:

  • Session Auth — Log in via Django admin or standard login views. The session cookie is sent automatically.
  • Token Auth — Include Authorization: Token <your-token> header. Tokens are managed via Django admin (rest_framework.authtoken).

Default permission: IsAuthenticated. Rate limiting applies (Anonymous & User throttling).

Health & Monitoring
GET
/api/health/
Health check (DB, Redis, LLM, Brevo). Returns 200 or 503.
GET
/api/metrics/
Current metrics & active alerts (JSON).
GET
/api/status/
Traffic-light status: {"overall":"green","services":{"llm":"green"...}}
GET
/monitoring/dod/
Monitoring Definition of Done page (web UI)
Invoices
POST
/api/v1/invoices/generate/
Generate invoice from notes. Body: notes, worker_id, customer_id, tax_rate
POST
/api/v1/invoices/<uuid:pk>/send/
Send invoice via email. Body: confirmed: true
POST
/api/v1/invoices/<uuid:pk>/pay/
Create Stripe payment link for invoice
POST
/api/v1/invoices/<uuid:pk>/void/
Void an invoice. Body: reason
POST
/api/v1/invoices/<uuid:pk>/reissue/
Reissue as credit note
GET
/api/v1/invoices/<uuid:pk>/datev/
Export single invoice as DATEV CSV. Query: skr=skr04|skr03
GET
/api/v1/invoices/datev/batch/
Batch DATEV export. Query: start, end, skr
Quotes
GET
/api/v1/invoices/quotes/
List all quotes (paginated)
POST
/api/v1/invoices/quotes/
Create a new quote. Body: title, customer_id, line items, etc.
GET
/api/v1/invoices/quotes/<uuid:pk>/
Quote detail
POST
/api/v1/invoices/quotes/<uuid:pk>/send/
Send quote to customer
POST
/api/v1/invoices/quotes/<uuid:pk>/accept/
Accept quote → creates linked invoice
POST
/api/v1/invoices/quotes/<uuid:pk>/reject/
Reject quote
Orders
GET
/api/v1/invoices/orders/
List all orders
POST
/api/v1/invoices/orders/
Create order manually
GET
/api/v1/invoices/orders/<uuid:pk>/
Order detail
PATCH
/api/v1/invoices/orders/<uuid:pk>/status/
Update order status. Body: status (confirmed → in_progress → completed)
POST
/api/v1/invoices/quotes/<uuid:quote_id>/create-order/
Create order from accepted quote (copies line items)
Reminders
GET
/api/v1/invoices/<uuid:pk>/reminders/
List reminders for an invoice
GET
/api/v1/invoices/<uuid:pk>/reminders/status/
Reminder status overview
POST
/api/v1/invoices/<uuid:pk>/reminders/trigger/
Trigger first automated reminder
POST
/api/v1/invoices/<uuid:pk>/reminders/send/
Send reminder now (manual)
Voice
GET
/api/v1/voice/transcribe/
Voice transcription page (web UI)
POST
/api/v1/voice/transcribe/
Upload audio for AI transcription. Form: audio file. Returns {"transcript":"..."} or 503 with text fallback.
Files & Audit
POST
/api/v1/files/upload/
Upload file to Supabase storage. Form: file, file_type (photo|voice|document)
GET
/api/v1/files/download/<path>/
Download file from Supabase storage
GET
/api/v1/files/audit-logs/
List audit logs (paginated)
GET
/api/v1/files/audit-logs/<uuid:pk>/
Single audit log entry
Accounts & Companies
GET
/api/v1/companies/companies/<uuid:pk>/escalation-schedule/
Get company escalation schedule
GET
/api/v1/companies/companies/<uuid:pk>/escalation-settings/
Get company escalation settings
PUT
/api/v1/companies/companies/<uuid:pk>/escalation-settings/
Update escalation settings
POST
/api/v1/companies/customers/match/
Fuzzy-match a customer. Body: name, phone, address
POST
/api/v1/companies/customers/check-duplicate/
Check if customer already exists
POST
/api/v1/companies/customers/find-similar/
Find similar existing customers
Web UI Pages
GET
/
Dashboard
GET
/invoices/
Invoice list page
GET
/invoices/<uuid:pk>/
Invoice detail page
GET
/invoices/<uuid:pk>/send/
Review & send invoice page
GET
/invoices/manual/
Manual invoice input fallback (when AI is down)
GET
/files/upload/
File upload page
GET
/invoices/datev/export/
DATEV export page
GET
/status/
System status indicator page (traffic lights)
GET
/api-docs/
This page
Administration
GET
/admin/
Django Admin panel
POST
/api/v1/invoices/webhooks/brevo/
Brevo email delivery webhook (bounce, delivered, opened)
Examples
Generate Invoice
POST /api/v1/invoices/generate/
Content-Type: application/json

{
  "notes": "Fixed sink, 2 hours at 75 EUR/hr",
  "worker_id": "uuid-of-worker",
  "customer_id": "uuid-of-customer",
  "tax_rate": 19
}
Send Invoice
POST /api/v1/invoices/<uuid>/send/
Content-Type: application/json

{
  "confirmed": true
}
Upload File
POST /api/v1/files/upload/
Content-Type: multipart/form-data

file: <binary>
file_type: voice
503 Degradation Response (AI down)
HTTP/1.1 503 Service Unavailable
Content-Type: application/json

{
  "error": "Die KI ist momentan nicht erreichbar. Bitte geben Sie die Daten manuell ein.",
  "error_type": "llm_unavailable",
  "fallback_action": "manual_input",
  "user_friendly": true
}