Endpunkte

Basis-URL für alle Endpunkte:

https://docforge.de/api/v1

Brands auflisten

Gibt alle Brands (Firmen/Marken) deines Accounts zurück.

GET /api/v1/brands

Antwort

{
  "data": [
    {
      "id": "uuid",
      "company_name": "Meine Firma GmbH",
      "owner_name": "Max Mustermann",
      "city": "Ingolstadt",
      "is_active": true,
      "created_at": "2026-01-15T10:30:00Z"
    }
  ]
}

Beispiel

curl https://docforge.de/api/v1/brands \
  -H "Authorization: Bearer df_live_dein_api_key"

Dokumente auflisten

Gibt Dokumente zurück, optional gefiltert nach Brand, Typ oder Status.

GET /api/v1/documents

Query-Parameter

Parameter	Typ	Beschreibung
`brand_id`	string	Nur Dokumente dieser Brand (UUID)
`doc_type`	string	Dokumenttyp filtern (siehe unten)
`status`	string	Status filtern (siehe unten)
`limit`	number	Anzahl Ergebnisse (1–100, Standard: 50)

Dokumenttypen: angebot, rechnung, lieferschein, auftragsbestaetigung, gutschrift, storno

Status: entwurf, final, versendet, angenommen, abgelehnt, bezahlt, storniert, ueberfaellig, geloescht

Dokumente mit Status geloescht werden automatisch aus allen API-Ergebnissen herausgefiltert und können nicht über die API abgerufen werden.

Antwort

{
  "data": [
    {
      "id": "uuid",
      "brand_id": "uuid",
      "doc_type": "rechnung",
      "doc_number": "RE-2026-0001",
      "status": "entwurf",
      "customer_name": "Max Mustermann",
      "customer_company": "Mustermann GmbH",
      "subject": "Rechnung für Dienstleistungen",
      "subtotal": 1000.00,
      "tax_amount": 190.00,
      "total": 1190.00,
      "issue_date": "2026-03-07",
      "pdf_url": "https://...",
      "created_at": "2026-03-07T14:00:00Z"
    }
  ]
}

Beispiel

# Alle Rechnungen einer Brand
curl "https://docforge.de/api/v1/documents?brand_id=uuid&doc_type=rechnung" \
  -H "Authorization: Bearer df_live_dein_api_key"

Dokument erstellen

Erstellt ein neues Dokument mit automatischer Nummernvergabe und Berechnung der Summen.

POST /api/v1/documents

Request Body

{
  "brand_id": "uuid-deiner-brand",
  "doc_type": "rechnung",
  "customer_name": "Max Mustermann",
  "customer_company": "Mustermann GmbH",
  "customer_street": "Musterstraße 1",
  "customer_zip": "85049",
  "customer_city": "Ingolstadt",
  "customer_email": "max@mustermann.de",
  "subject": "Rechnung für Webdesign",
  "intro_text": "Vielen Dank für Ihren Auftrag.",
  "closing_text": "Wir freuen uns auf die Zusammenarbeit.",
  "items": [
    {
      "name": "Webdesign Startseite",
      "description": "Responsive Landingpage",
      "unit": "Pauschal",
      "quantity": 1,
      "unit_price": 1200.00,
      "tax_rate": 19
    },
    {
      "name": "SEO-Optimierung",
      "unit": "Stunden",
      "quantity": 5,
      "unit_price": 80.00
    }
  ]
}

Pflichtfelder

Feld	Typ	Beschreibung
`brand_id`	string	UUID der Brand
`doc_type`	string	Dokumenttyp (siehe oben)
`customer_name`	string	Kundenname
`subject`	string	Betreff des Dokuments
`items`	array	Mindestens eine Position

Optionale Felder

Feld	Typ	Standard
`customer_company`	string	—
`customer_street`	string	—
`customer_zip`	string	—
`customer_city`	string	—
`customer_email`	string	—
`intro_text`	string	—
`closing_text`	string	—

Position (items)

Feld	Typ	Pflicht	Standard
`name`	string	ja	—
`description`	string	nein	—
`unit`	string	nein	`Stück`
`quantity`	number	ja	—
`unit_price`	number	ja	—
`tax_rate`	number	nein	`19` (bzw. `0` bei Kleinunternehmer)

Automatische Berechnung

subtotal = Summe aller quantity * unit_price
tax_amount = Summe aller quantity * unit_price * (tax_rate / 100)
total = subtotal + tax_amount
doc_number = Automatisch generiert (z.B. RE-2026-0001)
issue_date = Aktuelles Datum
status = entwurf

Bei Kleinunternehmern (is_kleinunternehmer = true in der Brand) wird tax_rate automatisch auf 0 gesetzt.

Neue Dokumente werden immer mit Status entwurf erstellt.

Antwort (201 Created)

{
  "data": {
    "id": "uuid-des-dokuments",
    "doc_number": "RE-2026-0001"
  }
}

Beispiel

curl -X POST https://docforge.de/api/v1/documents \
  -H "Authorization: Bearer df_live_dein_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "brand_id": "deine-brand-uuid",
    "doc_type": "rechnung",
    "customer_name": "Max Mustermann",
    "subject": "Rechnung März 2026",
    "items": [
      {
        "name": "Beratung",
        "quantity": 2,
        "unit_price": 150.00
      }
    ]
  }'

Fehlermeldungen

Alle Fehler folgen dem gleichen Format:

{
  "error": "Fehlerbeschreibung"
}

Status	Bedeutung
`400`	Pflichtfelder fehlen
`401`	Ungültige oder fehlende Authentifizierung
`403`	Kein Business-Plan
`404`	Brand nicht gefunden (oder gehört nicht zu deinem Account)
`500`	Interner Serverfehler

Endpunkte

On this page