Vorlagen

Positions-Vorlagen, Sets und Rechnungsvorlagen verwalten, eine Rechnung aus einer Vorlage erstellen und Vorlagen in einen Entwurf einfügen (Positions-Vorlagen ab Pro, Sets und Rechnungsvorlagen ab Business).

Authentifizierung

Jeder Request braucht einen API-Key im Header. Keys entstehen unter Einstellungen → API (nur Business-Tarif). Details zu Scopes, Idempotenz und Rate-Limits auf der Übersichtsseite.

Authorization: Bearer mxr_live_…

Bleibt in diesem Browser-Tab (sessionStorage), nur für „Ausprobieren“ auf dieser Seite, und geht direkt aus deinem Browser an /api/v1 — kein Versand an unseren Server, kein Log.

Positions-Vorlagen auflisten

get/api/v1/item-templates

Gespeicherte Positionen (Beschreibung, Einheit, Menge, Preis, USt.-Satz). Mit customer_id nur die für diesen Kunden sinnvollen: die ihm zugeordneten plus die allgemeinen.

Scope

templates:read

Parameter

  • limit query · integer
  • offset query · integer
  • customer_id query · stringUUID eines Kunden → dessen Vorlagen + allgemeine; none → nur allgemeine; leer → alle.
curl -X GET "https://maxrechnung.de/api/v1/item-templates" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Liste
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:read fehlt
  • 422 customer_id ist keine UUID
  • 429 Rate Limit überschritten

Schema 200

  • object "list"
  • data ItemTemplate[]
  • limit integer
  • offset integer
  • has_more boolean

Beispiel 200

{
  "object": "list",
  "data": [
    {
      "object": "item_template",
      "id": "00000000-0000-0000-0000-000000000000",
      "customer_ids": [
        "00000000-0000-0000-0000-000000000000"
      ],
      "description": "…",
      "unit": "…",
      "quantity": 0,
      "unit_price": 0,
      "price_mode": "net",
      "vat_rate": 19,
      "article_number": "…",
      "archived": false,
      "created_at": "2026-01-31T12:00:00Z",
      "updated_at": "2026-01-31T12:00:00Z"
    }
  ],
  "limit": 0,
  "offset": 0,
  "has_more": false
}

Positions-Vorlage anlegen

post/api/v1/item-templates

Positions-Vorlagen sind ab Pro, Positions-Sets und Rechnungsvorlagen ab Business; darunter antwortet der jeweilige Endpunkt mit 403 plan_required.

Scope

templates:write

Parameter

  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.

Request-Body · application/json · erforderlich

{
  "description": "Beratung",
  "unit": "Std.",
  "unit_price": 95,
  "price_mode": "net",
  "vat_rate": 19
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 201 Angelegt
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:write fehlt oder Tarif ohne Vorlagen
  • 409 Idempotency-Key schon mit einem anderen Request verwendet, oder der erste Request damit läuft noch
  • 422 Ungültige Felder
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "item_template",
  "id": "00000000-0000-0000-0000-000000000000",
  "customer_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "description": "…",
  "unit": "…",
  "quantity": 0,
  "unit_price": 0,
  "price_mode": "net",
  "vat_rate": 19,
  "article_number": "…",
  "archived": false,
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Positions-Vorlage abrufen

get/api/v1/item-templates/{id}

Scope

templates:read

Parameter

  • id path · string · uuid*
curl -X GET "https://maxrechnung.de/api/v1/item-templates/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 OK
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:read fehlt
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "item_template",
  "id": "00000000-0000-0000-0000-000000000000",
  "customer_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "description": "…",
  "unit": "…",
  "quantity": 0,
  "unit_price": 0,
  "price_mode": "net",
  "vat_rate": 19,
  "article_number": "…",
  "archived": false,
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Positions-Vorlage ändern

patch/api/v1/item-templates/{id}

Nur die übergebenen Felder. Bereits erstellte Rechnungen bleiben unverändert (Werte werden beim Einfügen kopiert). Positions-Vorlagen sind ab Pro, Positions-Sets und Rechnungsvorlagen ab Business; darunter antwortet der jeweilige Endpunkt mit 403 plan_required.

Scope

templates:write

Parameter

  • id path · string · uuid*

Request-Body · application/json · erforderlich

{
  "unit_price": 105
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 OK
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:write fehlt oder Tarif ohne Vorlagen
  • 404 Nicht gefunden
  • 409 customer_ids passt nicht zu einem Set, das diese Position enthält
  • 422 Ungültige Felder
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "item_template",
  "id": "00000000-0000-0000-0000-000000000000",
  "customer_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "description": "…",
  "unit": "…",
  "quantity": 0,
  "unit_price": 0,
  "price_mode": "net",
  "vat_rate": 19,
  "article_number": "…",
  "archived": false,
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Positions-Vorlage löschen

delete/api/v1/item-templates/{id}

Entfernt sie auch aus allen Sets. Rechnungen bleiben unverändert.

Scope

templates:write

Parameter

  • id path · string · uuid*
curl -X DELETE "https://maxrechnung.de/api/v1/item-templates/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Gelöscht
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:write fehlt
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

  • object string
  • id string
  • deleted boolean

Beispiel 200

{
  "object": "…",
  "id": "…",
  "deleted": false
}

Sets auflisten

get/api/v1/item-template-sets

Ein Set bündelt mehrere Positions-Vorlagen mit eigener Menge; eingefügt wird in der gespeicherten Reihenfolge.

Scope

templates:read

Parameter

  • limit query · integer
  • offset query · integer
curl -X GET "https://maxrechnung.de/api/v1/item-template-sets" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Liste
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:read fehlt
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "list",
  "data": [
    {
      "object": "item_template_set",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "…",
      "customer_ids": [
        "00000000-0000-0000-0000-000000000000"
      ],
      "items": [
        {
          "item_template_id": "00000000-0000-0000-0000-000000000000",
          "quantity": 0
        }
      ],
      "created_at": "2026-01-31T12:00:00Z",
      "updated_at": "2026-01-31T12:00:00Z"
    }
  ],
  "limit": 0,
  "offset": 0,
  "has_more": false
}

Set anlegen

post/api/v1/item-template-sets

Positions-Vorlagen sind ab Pro, Positions-Sets und Rechnungsvorlagen ab Business; darunter antwortet der jeweilige Endpunkt mit 403 plan_required.

Scope

templates:write

Parameter

  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.

Request-Body · application/json · erforderlich

{
  "name": "Vor-Ort-Termin",
  "items": [
    {
      "item_template_id": "7d0c6a0e-0b8e-4c1e-9d38-2f5b0a8c1e11",
      "quantity": 1
    },
    {
      "item_template_id": "0f3a1b2c-4d5e-4f60-8a71-b2c3d4e5f607",
      "quantity": 2
    }
  ]
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 201 Angelegt
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:write fehlt oder Tarif ohne Vorlagen
  • 409 Idempotency-Key schon mit einem anderen Request verwendet, oder der erste Request damit läuft noch
  • 422 Ungültige Felder (z. B. unbekannte item_template_id)
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "item_template_set",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "…",
  "customer_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "items": [
    {
      "item_template_id": "00000000-0000-0000-0000-000000000000",
      "quantity": 0
    }
  ],
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Set abrufen

get/api/v1/item-template-sets/{id}

Scope

templates:read

Parameter

  • id path · string · uuid*
curl -X GET "https://maxrechnung.de/api/v1/item-template-sets/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 OK
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:read fehlt
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "item_template_set",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "…",
  "customer_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "items": [
    {
      "item_template_id": "00000000-0000-0000-0000-000000000000",
      "quantity": 0
    }
  ],
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Set ändern

patch/api/v1/item-template-sets/{id}

items ersetzt die Zeilen vollständig. Positions-Vorlagen sind ab Pro, Positions-Sets und Rechnungsvorlagen ab Business; darunter antwortet der jeweilige Endpunkt mit 403 plan_required.

Scope

templates:write

Parameter

  • id path · string · uuid*

Request-Body · application/json · erforderlich

{
  "name": "Vor-Ort-Termin (groß)"
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 OK
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:write fehlt oder Tarif ohne Vorlagen
  • 404 Nicht gefunden
  • 422 Ungültige Felder
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "item_template_set",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "…",
  "customer_ids": [
    "00000000-0000-0000-0000-000000000000"
  ],
  "items": [
    {
      "item_template_id": "00000000-0000-0000-0000-000000000000",
      "quantity": 0
    }
  ],
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Set löschen

delete/api/v1/item-template-sets/{id}

Die enthaltenen Positions-Vorlagen bleiben erhalten.

Scope

templates:write

Parameter

  • id path · string · uuid*
curl -X DELETE "https://maxrechnung.de/api/v1/item-template-sets/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Gelöscht
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:write fehlt
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

  • object string
  • id string
  • deleted boolean

Beispiel 200

{
  "object": "…",
  "id": "…",
  "deleted": false
}

Rechnungsvorlagen auflisten

get/api/v1/invoice-templates

Gespeicherte Rechnungen ohne Nummer und Daten: Empfänger, Positionen, Steuerregelung, Zahlungsziel, Hinweis. Neue Rechnung daraus: POST /invoice-templates/{id}/invoices.

Scope

templates:read

Parameter

  • limit query · integer
  • offset query · integer
curl -X GET "https://maxrechnung.de/api/v1/invoice-templates" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Liste
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:read fehlt
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "list",
  "data": [
    {
      "object": "invoice_template",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "…",
      "customer_id": "00000000-0000-0000-0000-000000000000",
      "recipient": {
        "name": "…",
        "address": "…",
        "email": "…",
        "vat_id": "…",
        "contact_name": "…"
      },
      "delivery": {
        "name": "…",
        "address": "…",
        "country": "…"
      },
      "buyer_reference": "…",
      "customer_number": "…",
      "supplier_number": "…",
      "vat_scheme": "standard",
      "vat_exempt_clause": "…",
      "price_mode": "net",
      "payment_term_days": 0,
      "line_items": [
        {
          "description": "…",
          "quantity": 0,
          "unit": "…",
          "unit_price": 0,
          "vat_rate": 0
        }
      ],
      "notes": "…",
      "updated_at": "2026-01-31T12:00:00Z"
    }
  ],
  "limit": 0,
  "offset": 0,
  "has_more": false
}

Rechnungsvorlage aus einer Rechnung anlegen

post/api/v1/invoice-templates

Übernimmt Empfänger, Positionen, Steuerregelung, Preismodus, Zahlungsziel und Hinweis der Rechnung invoice_id (auch festgeschriebene). Positions-Vorlagen sind ab Pro, Positions-Sets und Rechnungsvorlagen ab Business; darunter antwortet der jeweilige Endpunkt mit 403 plan_required.

Scope

templates:write

Parameter

  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.

Request-Body · application/json · erforderlich

{
  "name": "Monatliche Wartung",
  "invoice_id": "3f1c2b4a-5d6e-4f70-8a91-b2c3d4e5f601"
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 201 Angelegt
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:write fehlt oder Tarif ohne Vorlagen
  • 409 Idempotency-Key schon mit einem anderen Request verwendet, oder der erste Request damit läuft noch
  • 422 Ungültige Felder (z. B. invoice_id unbekannt)
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "invoice_template",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "…",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "…"
  },
  "buyer_reference": "…",
  "customer_number": "…",
  "supplier_number": "…",
  "vat_scheme": "standard",
  "vat_exempt_clause": "…",
  "price_mode": "net",
  "payment_term_days": 0,
  "line_items": [
    {
      "description": "…",
      "quantity": 0,
      "unit": "…",
      "unit_price": 0,
      "vat_rate": 0
    }
  ],
  "notes": "…",
  "updated_at": "2026-01-31T12:00:00Z"
}

Rechnungsvorlage abrufen

get/api/v1/invoice-templates/{id}

Scope

templates:read

Parameter

  • id path · string · uuid*
curl -X GET "https://maxrechnung.de/api/v1/invoice-templates/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 OK
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:read fehlt
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "invoice_template",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "…",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "…"
  },
  "buyer_reference": "…",
  "customer_number": "…",
  "supplier_number": "…",
  "vat_scheme": "standard",
  "vat_exempt_clause": "…",
  "price_mode": "net",
  "payment_term_days": 0,
  "line_items": [
    {
      "description": "…",
      "quantity": 0,
      "unit": "…",
      "unit_price": 0,
      "vat_rate": 0
    }
  ],
  "notes": "…",
  "updated_at": "2026-01-31T12:00:00Z"
}

Rechnungsvorlage ändern

patch/api/v1/invoice-templates/{id}

Umbenennen, Kunde zuordnen (customer_id, null = keiner) oder mit invoice_id den Inhalt aus einer anderen Rechnung neu übernehmen. Positions-Vorlagen sind ab Pro, Positions-Sets und Rechnungsvorlagen ab Business; darunter antwortet der jeweilige Endpunkt mit 403 plan_required.

Scope

templates:write

Parameter

  • id path · string · uuid*

Request-Body · application/json · erforderlich

{
  "name": "Wartung (monatlich)",
  "customer_id": null
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 OK
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:write fehlt oder Tarif ohne Vorlagen
  • 404 Nicht gefunden
  • 422 Ungültige Felder
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "invoice_template",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "…",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "…"
  },
  "buyer_reference": "…",
  "customer_number": "…",
  "supplier_number": "…",
  "vat_scheme": "standard",
  "vat_exempt_clause": "…",
  "price_mode": "net",
  "payment_term_days": 0,
  "line_items": [
    {
      "description": "…",
      "quantity": 0,
      "unit": "…",
      "unit_price": 0,
      "vat_rate": 0
    }
  ],
  "notes": "…",
  "updated_at": "2026-01-31T12:00:00Z"
}

Rechnungsvorlage löschen

delete/api/v1/invoice-templates/{id}

Bereits erstellte Rechnungen bleiben unverändert.

Scope

templates:write

Parameter

  • id path · string · uuid*
curl -X DELETE "https://maxrechnung.de/api/v1/invoice-templates/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Gelöscht
  • 401 Kein oder ungültiger API-Key
  • 403 Scope templates:write fehlt
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

  • object string
  • id string
  • deleted boolean

Beispiel 200

{
  "object": "…",
  "id": "…",
  "deleted": false
}

Rechnung aus Vorlage erstellen

post/api/v1/invoice-templates/{id}/invoices

Legt einen Entwurf an: nächste freie Nummer, Rechnungs- und Leistungsdatum heute (oder invoice_date), Absender aus dem Firmenprofil. Ist die Vorlage an einen Kunden gebunden, kommen die Empfängerdaten aktuell aus dem Kunden. Braucht invoices:draft und templates:read; zählt wie jede neue Rechnung ins Monatskontingent. Antwort ist die neue Rechnung.

Scope

invoices:draft und templates:read

Parameter

  • id path · string · uuid*Interne id der Rechnungsvorlage (UUID), aus GET /invoice-templates.
  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.

Request-Body · application/json

  • invoice_date string · dateRechnungs- und Leistungsdatum; Standard heute.
{
  "invoice_date": "2026-10-01"
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 201 Entwurf angelegt
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft oder templates:read fehlt oder Tarif ohne Vorlagen
  • 404 Vorlage nicht gefunden
  • 409 Idempotency-Key schon mit einem anderen Request verwendet, oder der erste Request damit läuft noch
  • 422 Ungültiges invoice_date
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "invoice",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "invoice",
  "status": "draft",
  "number": "RE-2026-004",
  "invoice_date": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "collected_on": "2026-01-31",
  "due_date": "2026-01-31",
  "payment_term_days": 14,
  "amount_paid": 0,
  "amount_open": 428.4,
  "corrected_invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "number": "…",
    "date": "2026-01-31"
  },
  "sender": {
    "name": "…",
    "address": "…",
    "tax_id": "…",
    "tax_id_kind": "vat_id",
    "email": "…",
    "bank_name": "…",
    "iban": "…"
  },
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "vat_id_check": {
      "status": "valid",
      "source": "vies",
      "checked_at": "2026-01-31T12:00:00Z",
      "name": "…",
      "stale": false,
      "matches": {
        "name": "…",
        "street": "…",
        "postcode": "…",
        "city": "…"
      }
    },
    "country": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "DE"
  },
  "buyer_reference": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "small_business": false,
  "price_mode": "net",
  "language": "de",
  "currency": "EUR",
  "exchange_rate": 0,
  "discount": {
    "type": "percent",
    "value": 0,
    "reason": "…"
  },
  "skonto": {
    "percent": 0,
    "days": 0
  },
  "line_items": [
    {
      "description": "…",
      "quantity": 3,
      "unit": "Std.",
      "unit_price": 120,
      "vat_rate": 19,
      "article_number": "BER-01",
      "vat_exempt_clause": "8"
    }
  ],
  "notes": "…",
  "advances": [
    {
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "number": "…",
      "date": "2026-01-31",
      "net": 0,
      "vat": 0,
      "gross": 0,
      "vat_groups": [
        {
          "rate": 0,
          "net": 0,
          "vat": 0
        }
      ],
      "paid": false
    }
  ],
  "totals": {
    "lines": 0,
    "discount": 0,
    "net": 0,
    "vat": 0,
    "gross": 0,
    "service": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "prepaid": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "vat_groups": [
      {
        "rate": 0,
        "net": 0,
        "vat": 0
      }
    ]
  },
  "custom_fields": {
    "projekt_nr": "P-17",
    "stripe_customer_id": "cus_Q1w2e3"
  },
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Vorlage in Rechnungsentwurf einfügen

post/api/v1/invoices/{id}/items

Hängt eine Positions-Vorlage (item_template_id, optional mit abweichender quantity) oder ein Set (item_template_set_id) an den Entwurf an. Der Preis wird wie im Editor in den Preismodus der Rechnung umgerechnet (netto ⇄ brutto mit dem USt.-Satz der Position; ohne USt.-Ausweis gilt netto). Eine einzelne leere Startposition wird ersetzt. Wie im Editor: eine archivierte Positions-Vorlage lässt sich nicht einzeln einfügen (in Sets bleibt sie); eine Vorlage oder ein Set mit Kundenbindung (customer_ids) nur, wenn der Empfänger des Entwurfs genau einem dieser Kunden entspricht. Braucht invoices:draft und templates:read. Ohne Idempotency-Key hängt jeder Aufruf erneut an.

Scope

invoices:draft und templates:read

Parameter

  • id path · string · uuid*Interne id der Rechnung (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. RE-2026-0004) liefert GET /invoices?number=… (MCP: list_invoices mit number) die id.
  • Idempotency-Key header · stringFrei gewählter Schlüssel, höchstens 255 Zeichen. Eine Wiederholung mit demselben Schlüssel und demselben Body liefert 24 Stunden lang die erste Antwort zurück.

Request-Body · application/json · erforderlich

  • item_template_id string · uuid
  • item_template_set_id string · uuid
  • quantity numberNur mit item_template_id; Standard = Menge der Vorlage.
{
  "item_template_id": "7d0c6a0e-0b8e-4c1e-9d38-2f5b0a8c1e11",
  "quantity": 3
}

MXR_API_KEY als Umgebungsvariable setzen. GUI-Clients (Postman, Insomnia, Bruno …): /api/openapi.json importieren.

Antworten

  • 200 Aktualisierter Entwurf
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft oder templates:read fehlt oder Tarif ohne Vorlagen
  • 404 Rechnung, Vorlage oder Set nicht gefunden
  • 409 Beleg ist festgeschrieben, Positions-Vorlage archiviert oder Vorlage/Set nur für andere Kunden
  • 422 Nicht genau eines von item_template_id / item_template_set_id
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "invoice",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "invoice",
  "status": "draft",
  "number": "RE-2026-004",
  "invoice_date": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "collected_on": "2026-01-31",
  "due_date": "2026-01-31",
  "payment_term_days": 14,
  "amount_paid": 0,
  "amount_open": 428.4,
  "corrected_invoice": {
    "id": "00000000-0000-0000-0000-000000000000",
    "number": "…",
    "date": "2026-01-31"
  },
  "sender": {
    "name": "…",
    "address": "…",
    "tax_id": "…",
    "tax_id_kind": "vat_id",
    "email": "…",
    "bank_name": "…",
    "iban": "…"
  },
  "recipient": {
    "name": "…",
    "address": "…",
    "email": "…",
    "vat_id": "…",
    "vat_id_check": {
      "status": "valid",
      "source": "vies",
      "checked_at": "2026-01-31T12:00:00Z",
      "name": "…",
      "stale": false,
      "matches": {
        "name": "…",
        "street": "…",
        "postcode": "…",
        "city": "…"
      }
    },
    "country": "…",
    "contact_name": "…"
  },
  "delivery": {
    "name": "…",
    "address": "…",
    "country": "DE"
  },
  "buyer_reference": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "customer_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "small_business": false,
  "price_mode": "net",
  "language": "de",
  "currency": "EUR",
  "exchange_rate": 0,
  "discount": {
    "type": "percent",
    "value": 0,
    "reason": "…"
  },
  "skonto": {
    "percent": 0,
    "days": 0
  },
  "line_items": [
    {
      "description": "…",
      "quantity": 3,
      "unit": "Std.",
      "unit_price": 120,
      "vat_rate": 19,
      "article_number": "BER-01",
      "vat_exempt_clause": "8"
    }
  ],
  "notes": "…",
  "advances": [
    {
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "number": "…",
      "date": "2026-01-31",
      "net": 0,
      "vat": 0,
      "gross": 0,
      "vat_groups": [
        {
          "rate": 0,
          "net": 0,
          "vat": 0
        }
      ],
      "paid": false
    }
  ],
  "totals": {
    "lines": 0,
    "discount": 0,
    "net": 0,
    "vat": 0,
    "gross": 0,
    "service": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "prepaid": {
      "net": 0,
      "vat": 0,
      "gross": 0
    },
    "vat_groups": [
      {
        "rate": 0,
        "net": 0,
        "vat": 0
      }
    ]
  },
  "custom_fields": {
    "projekt_nr": "P-17",
    "stripe_customer_id": "cus_Q1w2e3"
  },
  "created_at": "2026-01-31T12:00:00Z",
  "updated_at": "2026-01-31T12:00:00Z"
}

Schemas

Von den Endpunkten oben referenzierte Objekte. Vollständig auch in der OpenAPI-Spezifikation.