Angebote, Auftragsbestätigungen, Lieferscheine

Angebote, Auftragsbestätigungen und Lieferscheine anlegen, auflisten, ändern, als PDF abrufen, umwandeln und zu einer Sammelrechnung zusammenfassen (Angebote ab Pro; Auftragsbestätigungen, Lieferscheine und Sammelrechnung 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.

Belege auflisten

get/api/v1/sales-documents

Angebote, Auftragsbestätigungen und Lieferscheine, neueste zuerst. Filter nach Belegart, Status, Nummer und Kette. Angebote sind ab Pro, Auftragsbestätigungen und Lieferscheine ab Business: unter Pro antwortet jeder /sales-documents-Endpunkt mit 403 plan_required; in Pro ebenso, wer eine Auftragsbestätigung oder einen Lieferschein anlegt, deren Status setzt oder dorthin weiterführt (details nennt type bzw. target).

Scope

invoices:read

Parameter

  • type query · "quote" | "order_confirmation" | "delivery_note"
  • status query · "draft" | "sent" | "accepted" | "declined" | "done"
  • number query · stringExakte Belegnummer, z. B. AN-2026-0004.
  • chain_id query · string · uuidAlle Belege einer Kette (Wurzel-id).
  • custom_fields query · objectFilter nach eigenen Feldern: custom_fields[schlüssel]=wert, mehrere sind UND-verknüpft. Ja/Nein: true oder false (nicht gesetzt). Unbekannter Schlüssel → 400.
  • limit query · integer
  • offset query · integer
curl -X GET "https://maxrechnung.de/api/v1/sales-documents" \
  -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 invoices:read fehlt oder Tarif ohne Belege
  • 422 chain_id ist keine UUID
  • 429 Rate Limit überschritten

Schema 200

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

Beispiel 200

{
  "object": "list",
  "data": [
    {
      "object": "sales_document",
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "quote",
      "status": "draft",
      "number": "AN-2026-0004",
      "date": "2026-01-31",
      "valid_until": "2026-01-31",
      "service_date": "2026-01-31",
      "service_date_end": "2026-01-31",
      "payment_terms_text": "…",
      "delivery_time": "…",
      "customer_order_number": "…",
      "customer_order_date": "2026-01-31",
      "source_documents": [
        {
          "type": "quote",
          "number": "…",
          "date": "2026-01-31"
        }
      ],
      "source_id": "00000000-0000-0000-0000-000000000000",
      "invoice_id": "00000000-0000-0000-0000-000000000000",
      "chain_id": "00000000-0000-0000-0000-000000000000",
      "superseded_by": "00000000-0000-0000-0000-000000000000",
      "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_id": "00000000-0000-0000-0000-000000000000",
      "customer_number": "…",
      "supplier_number": "…",
      "small_business": false,
      "vat_scheme": "standard",
      "vat_exempt_clause": "8",
      "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": "…",
      "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"
    }
  ],
  "limit": 0,
  "offset": 0,
  "has_more": false
}

Beleg anlegen

post/api/v1/sales-documents

Legt ein Angebot (ab Pro), eine Auftragsbestätigung oder einen Lieferschein (beide ab Business) als Entwurf an. Felder wie bei der Rechnung; der Beleg kennt kein Zahlungsziel und keine E-Rechnung. Scope invoices:draft. Angebote sind ab Pro, Auftragsbestätigungen und Lieferscheine ab Business: unter Pro antwortet jeder /sales-documents-Endpunkt mit 403 plan_required; in Pro ebenso, wer eine Auftragsbestätigung oder einen Lieferschein anlegt, deren Status setzt oder dorthin weiterführt (details nennt type bzw. target).

Scope

invoices:draft

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

{
  "type": "quote",
  "valid_until": "2026-11-10",
  "payment_terms_text": "50 % bei Auftrag, Rest nach Lieferung",
  "delivery_time": "ca. 3 Wochen nach Auftragseingang",
  "recipient": {
    "name": "Kunde AG",
    "address": "Musterstraße 1\n12345 Berlin"
  },
  "line_items": [
    {
      "description": "Beratung",
      "quantity": 8,
      "unit": "Std.",
      "unit_price": 120,
      "vat_rate": 19
    }
  ]
}

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

Antworten

  • 201 Beleg angelegt
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft fehlt oder Tarif ohne Belege
  • 409 Belegnummer bereits vergeben
  • 422 Ungültige Felder (type fehlt, Rechnungsfeld im Body …)
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "sales_document",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "quote",
  "status": "draft",
  "number": "AN-2026-0004",
  "date": "2026-01-31",
  "valid_until": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "payment_terms_text": "…",
  "delivery_time": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "source_documents": [
    {
      "type": "quote",
      "number": "…",
      "date": "2026-01-31"
    }
  ],
  "source_id": "00000000-0000-0000-0000-000000000000",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "chain_id": "00000000-0000-0000-0000-000000000000",
  "superseded_by": "00000000-0000-0000-0000-000000000000",
  "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_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "small_business": false,
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "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": "…",
  "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"
}

Beleg lesen

get/api/v1/sales-documents/{id}

Scope

invoices:read

Parameter

  • id path · string · uuid*Interne id des Belegs (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. AN-2026-0004) liefert GET /sales-documents?number=… (MCP: list_sales_documents mit number) die id.
curl -X GET "https://maxrechnung.de/api/v1/sales-documents/{id}" \
  -H "Authorization: Bearer $MXR_API_KEY"

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

Antworten

  • 200 Beleg
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:read fehlt oder Tarif ohne Belege
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "sales_document",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "quote",
  "status": "draft",
  "number": "AN-2026-0004",
  "date": "2026-01-31",
  "valid_until": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "payment_terms_text": "…",
  "delivery_time": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "source_documents": [
    {
      "type": "quote",
      "number": "…",
      "date": "2026-01-31"
    }
  ],
  "source_id": "00000000-0000-0000-0000-000000000000",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "chain_id": "00000000-0000-0000-0000-000000000000",
  "superseded_by": "00000000-0000-0000-0000-000000000000",
  "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_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "small_business": false,
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "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": "…",
  "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"
}

Beleg ändern

patch/api/v1/sales-documents/{id}

Ändert Felder; die Belegart steht fest (Umwandeln über POST /sales-documents/{id}/convert). Statuswechsel: PATCH /sales-documents/{id}/status. Auftragsbestätigungen und Lieferscheine bleiben in jedem Status änderbar — auch vorhandene in Pro. Angebote sind nur als Entwurf (`draft`) änderbar: ab sent antwortet der Aufruf mit 409 conflict; Änderungen an einem versendeten oder abgelehnten Angebot laufen über POST /sales-documents/{id}/revise (neue Fassung), ein angenommenes Angebot bleibt, wie es ist. Ein Body nur mit custom_fields ändert die eigenen Felder in jedem Status. Scope invoices:draft.

Scope

invoices:draft

Parameter

  • id path · string · uuid*Interne id des Belegs (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. AN-2026-0004) liefert GET /sales-documents?number=… (MCP: list_sales_documents mit number) die id.

Request-Body · application/json · erforderlich

{
  "valid_until": "2026-12-01",
  "notes": "Angebot gilt bis Jahresende."
}

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

Antworten

  • 200 Aktualisierter Beleg
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft fehlt oder Tarif ohne Belege
  • 404 Nicht gefunden
  • 409 Belegnummer bereits vergeben, oder Angebot ist nicht mehr im Entwurf (gesperrt)
  • 422 Ungültige Felder (type im Body, Rechnungsfeld …)
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "sales_document",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "quote",
  "status": "draft",
  "number": "AN-2026-0004",
  "date": "2026-01-31",
  "valid_until": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "payment_terms_text": "…",
  "delivery_time": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "source_documents": [
    {
      "type": "quote",
      "number": "…",
      "date": "2026-01-31"
    }
  ],
  "source_id": "00000000-0000-0000-0000-000000000000",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "chain_id": "00000000-0000-0000-0000-000000000000",
  "superseded_by": "00000000-0000-0000-0000-000000000000",
  "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_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "small_business": false,
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "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": "…",
  "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"
}

Beleg löschen

delete/api/v1/sales-documents/{id}

Löscht den Beleg endgültig; eine daraus entstandene Rechnung bleibt bestehen (Bezug darauf entfällt). Scope invoices:draft.

Scope

invoices:draft

Parameter

  • id path · string · uuid*Interne id des Belegs (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. AN-2026-0004) liefert GET /sales-documents?number=… (MCP: list_sales_documents mit number) die id.
curl -X DELETE "https://maxrechnung.de/api/v1/sales-documents/{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 invoices:draft fehlt oder Tarif ohne Belege
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

  • object string
  • id string
  • deleted boolean

Beispiel 200

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

Belegstatus setzen

patch/api/v1/sales-documents/{id}/status

Angebot: draft, sent, accepted, declined; AB und Lieferschein: draft, sent, done. Abgelaufene Angebote (valid_until überschritten, Status sent) zeigt die Liste als „abgelaufen“ an, gespeichert bleibt sent. Ein Angebot kehrt nicht zu draft zurück, und ein ersetztes Angebot (superseded_by) ändert seinen Status nicht mehr (409 conflict). Angebote ab Pro; der Status einer Auftragsbestätigung oder eines Lieferscheins ab Business (403 plan_required). Scope invoices:draft.

Scope

invoices:draft

Parameter

  • id path · string · uuid*Interne id des Belegs (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. AN-2026-0004) liefert GET /sales-documents?number=… (MCP: list_sales_documents mit number) die id.

Request-Body · application/json · erforderlich

  • status "draft" | "sent" | "accepted" | "declined" | "done"*
{
  "status": "sent"
}

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

Antworten

  • 200 Beleg
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft fehlt oder Tarif ohne Belege
  • 404 Nicht gefunden
  • 409 Angebot zurück auf draft, oder Angebot ist ersetzt
  • 422 Status passt nicht zur Belegart
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "sales_document",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "quote",
  "status": "draft",
  "number": "AN-2026-0004",
  "date": "2026-01-31",
  "valid_until": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "payment_terms_text": "…",
  "delivery_time": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "source_documents": [
    {
      "type": "quote",
      "number": "…",
      "date": "2026-01-31"
    }
  ],
  "source_id": "00000000-0000-0000-0000-000000000000",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "chain_id": "00000000-0000-0000-0000-000000000000",
  "superseded_by": "00000000-0000-0000-0000-000000000000",
  "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_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "small_business": false,
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "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": "…",
  "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"
}

Beleg umwandeln

post/api/v1/sales-documents/{id}/convert

Erzeugt den Folgebeleg: order_confirmation oder delivery_note (neuer Beleg in derselben Kette, Antwort SalesDocument) oder invoice (Rechnungsentwurf mit nächster RE-Nummer, Zahlungsziel aus dem Profil, Antwort Invoice, feuert invoice.created). Angebot → AB/Lieferschein/Rechnung, AB → Lieferschein/Rechnung, Lieferschein → Rechnung. Ab Pro: Angebot → Rechnung; jedes Weiterführen in eine oder aus einer Auftragsbestätigung bzw. einem Lieferschein ab Business (403 plan_required). Der Ausgangsbeleg rückt im Status weiter; der Rechnungsentwurf zählt ins Monatskontingent. Steht der Beleg unter § 19 UStG (Kleinunternehmer), die Rechnungsvorgaben des Kontos inzwischen auf Umsatzsteuer, weist die Rechnung Umsatzsteuer aus; price_basis legt fest, ob der Preis als Brutto gilt (gross, Vorgabe — der Gesamtbetrag bleibt) oder als netto zuzüglich USt (net). Scope invoices:draft. Ohne Idempotency-Key erzeugt jeder Aufruf einen weiteren Beleg.

Scope

invoices:draft

Parameter

  • id path · string · uuid*Interne id des Belegs (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. AN-2026-0004) liefert GET /sales-documents?number=… (MCP: list_sales_documents 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

  • target "order_confirmation" | "delivery_note" | "invoice"*
  • price_basis "gross" | "net"Nur für target: invoice aus einem § 19-Beleg, wenn die Rechnungsvorgaben inzwischen auf Umsatzsteuer stehen: gross = Preis gilt als Brutto (1.000 € = 840,34 € + 159,66 € USt), net = Preis netto, USt kommt hinzu. Sonst ohne Wirkung.
{
  "target": "invoice"
}

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

Antworten

  • 201 Neuer Beleg oder Rechnungsentwurf (je nach target)
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft fehlt oder Tarif ohne Belege
  • 404 Nicht gefunden
  • 409 Idempotency-Key schon mit einem anderen Request verwendet, oder der erste Request damit läuft noch
  • 422 target passt nicht zur Belegart
  • 429 Rate Limit überschritten

Schema 201

Eine der folgenden Formen:

Beispiel 201

{
  "object": "sales_document",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "quote",
  "status": "draft",
  "number": "AN-2026-0004",
  "date": "2026-01-31",
  "valid_until": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "payment_terms_text": "…",
  "delivery_time": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "source_documents": [
    {
      "type": "quote",
      "number": "…",
      "date": "2026-01-31"
    }
  ],
  "source_id": "00000000-0000-0000-0000-000000000000",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "chain_id": "00000000-0000-0000-0000-000000000000",
  "superseded_by": "00000000-0000-0000-0000-000000000000",
  "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_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "small_business": false,
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "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": "…",
  "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"
}

Neue Fassung eines Angebots

post/api/v1/sales-documents/{id}/revise

Für ein versendetes (sent) oder abgelehntes (declined) Angebot: legt eine Kopie als Entwurf an (neue Angebotsnummer, heutiges Datum) und setzt am alten Angebot superseded_by. Das alte Angebot gilt damit als ersetzt; sein Annahme-Link bleibt erreichbar, nimmt aber keine Antwort mehr an. Den Annahme-Link erzeugt nur der Mailversand aus der App; die API legt keinen an und gibt keinen aus. Entwürfe (direkt änderbar), angenommene, erledigte und bereits ersetzte Angebote: 409 conflict. Ab Pro. Scope invoices:draft. Ohne Idempotency-Key legt jeder Aufruf eine weitere Fassung an.

Scope

invoices:draft

Parameter

  • id path · string · uuid*Interne id des Belegs (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. AN-2026-0004) liefert GET /sales-documents?number=… (MCP: list_sales_documents 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.
curl -X POST "https://maxrechnung.de/api/v1/sales-documents/{id}/revise" \
  -H "Authorization: Bearer $MXR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"

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

Antworten

  • 201 Neue Fassung (Entwurf)
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft fehlt oder Tarif ohne Belege
  • 404 Nicht gefunden
  • 409 Für diesen Status gibt es keine neue Fassung
  • 422 Kein Angebot
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "sales_document",
  "id": "00000000-0000-0000-0000-000000000000",
  "type": "quote",
  "status": "draft",
  "number": "AN-2026-0004",
  "date": "2026-01-31",
  "valid_until": "2026-01-31",
  "service_date": "2026-01-31",
  "service_date_end": "2026-01-31",
  "payment_terms_text": "…",
  "delivery_time": "…",
  "customer_order_number": "…",
  "customer_order_date": "2026-01-31",
  "source_documents": [
    {
      "type": "quote",
      "number": "…",
      "date": "2026-01-31"
    }
  ],
  "source_id": "00000000-0000-0000-0000-000000000000",
  "invoice_id": "00000000-0000-0000-0000-000000000000",
  "chain_id": "00000000-0000-0000-0000-000000000000",
  "superseded_by": "00000000-0000-0000-0000-000000000000",
  "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_id": "00000000-0000-0000-0000-000000000000",
  "customer_number": "…",
  "supplier_number": "…",
  "small_business": false,
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "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": "…",
  "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"
}

PDF des Belegs

get/api/v1/sales-documents/{id}/pdf

Serverseitig gerendertes PDF (DIN 5008) — Lieferscheine ohne Preise, mit Unterschriftszeile. Kein ENTWURF-Wasserzeichen.

Scope

invoices:read

Parameter

  • id path · string · uuid*Interne id des Belegs (UUID), nicht die Belegnummer. Zu einer Nummer (z. B. AN-2026-0004) liefert GET /sales-documents?number=… (MCP: list_sales_documents mit number) die id.
curl -X GET "https://maxrechnung.de/api/v1/sales-documents/{id}/pdf" \
  -H "Authorization: Bearer $MXR_API_KEY"

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

Antworten

  • 200 PDF
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:read fehlt oder Tarif ohne Belege
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Sammelrechnung aus Belegen

post/api/v1/sales-documents/merge

Eine Rechnung aus mehreren Belegen desselben Empfängers und derselben Währung (z. B. alle Lieferscheine eines Monats): je Beleg eine Überschriftszeile, dann dessen Positionen; alle Bezüge in der Bezugszeile. Reihenfolge der Positionen = Reihenfolge der ids. Kopf, Steuer und Rabatt kommen aus dem ersten Beleg — deshalb müssen Preismodus (netto/brutto), Steuerregelung und Rabatt bei allen gleich sein (ein Rabatt nur als gleicher Prozentsatz). Kein Beleg darf schon abgerechnet sein, keiner Vorbeleg eines anderen (etwa AB und ihr Lieferschein). Die Belege gelten danach als erledigt und verweisen auf die Rechnung; Vorbelege der Kette rücken mit. Antwort Invoice (Entwurf). Ab Business. Scope invoices:draft.

Scope

invoices:draft

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

  • ids string · uuid[]*
{
  "ids": [
    "7d0c6a0e-0b8e-4c1e-9d38-2f5b0a8c1e11",
    "0b1f3c2d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"
  ]
}

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

Antworten

  • 201 Rechnungsentwurf
  • 400 Ungültiges JSON im Body
  • 401 Kein oder ungültiger API-Key
  • 403 Scope invoices:draft fehlt oder Tarif ohne Belege
  • 404 Mindestens ein Beleg nicht gefunden
  • 409 Ein Beleg ist schon abgerechnet oder durch eine neue Fassung ersetzt
  • 422 Leere Liste; Empfänger, Währung, Preismodus, Steuerregelung oder Rabatt verschieden; Belege derselben Kette
  • 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"
}

Schemas

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