Kunden

Gespeicherte Empfänger anlegen, auflisten, ändern, löschen und deren USt-IdNr. prüfen.

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.

Kunden auflisten

get/api/v1/customers

Scope

customers:read

Parameter

  • 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/customers" \
  -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 customers:read fehlt
  • 429 Rate Limit überschritten

Schema 200

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

Beispiel 200

{
  "object": "list",
  "data": [
    {
      "object": "customer",
      "id": "00000000-0000-0000-0000-000000000000",
      "name": "…",
      "address": "…",
      "country": "…",
      "customer_number": "…",
      "supplier_number": "…",
      "contact_name": "…",
      "delivery_name": "…",
      "delivery_address": "…",
      "delivery_country": "…",
      "payment_term_days": 0,
      "email": "…",
      "vat_id": "…",
      "buyer_reference": "…",
      "vat_scheme": "standard",
      "vat_exempt_clause": "8",
      "e_invoice_formats": [
        "xrechnung"
      ],
      "xrechnung_version": "3.0.2",
      "zugferd_profile": "basic",
      "price_mode": "net",
      "vat_id_check": {
        "status": "valid",
        "source": "vies",
        "checked_at": "2026-01-31T12:00:00Z",
        "name": "…",
        "stale": false,
        "matches": {
          "name": "…",
          "street": "…",
          "postcode": "…",
          "city": "…"
        }
      },
      "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
}

Kunde anlegen

post/api/v1/customers

Scope

customers: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": "Novak s.r.o.",
  "address": "Vodičkova 12\n110 00 Praha 1",
  "country": "CZ",
  "customer_number": "K-1042"
}

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 customers:write fehlt, oder plan_required: ein Feld ist erst ab Business erlaubt (details)
  • 409 customer_number bereits vergeben
  • 422 Ungültige Felder
  • 429 Rate Limit überschritten

Schema 201

Beispiel 201

{
  "object": "customer",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "…",
  "address": "…",
  "country": "…",
  "customer_number": "…",
  "supplier_number": "…",
  "contact_name": "…",
  "delivery_name": "…",
  "delivery_address": "…",
  "delivery_country": "…",
  "payment_term_days": 0,
  "email": "…",
  "vat_id": "…",
  "buyer_reference": "…",
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "xrechnung_version": "3.0.2",
  "zugferd_profile": "basic",
  "price_mode": "net",
  "vat_id_check": {
    "status": "valid",
    "source": "vies",
    "checked_at": "2026-01-31T12:00:00Z",
    "name": "…",
    "stale": false,
    "matches": {
      "name": "…",
      "street": "…",
      "postcode": "…",
      "city": "…"
    }
  },
  "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"
}

Kunde abrufen

get/api/v1/customers/{id}

Scope

customers:read

Parameter

  • id path · string · uuid*
curl -X GET "https://maxrechnung.de/api/v1/customers/{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 fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "customer",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "…",
  "address": "…",
  "country": "…",
  "customer_number": "…",
  "supplier_number": "…",
  "contact_name": "…",
  "delivery_name": "…",
  "delivery_address": "…",
  "delivery_country": "…",
  "payment_term_days": 0,
  "email": "…",
  "vat_id": "…",
  "buyer_reference": "…",
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "xrechnung_version": "3.0.2",
  "zugferd_profile": "basic",
  "price_mode": "net",
  "vat_id_check": {
    "status": "valid",
    "source": "vies",
    "checked_at": "2026-01-31T12:00:00Z",
    "name": "…",
    "stale": false,
    "matches": {
      "name": "…",
      "street": "…",
      "postcode": "…",
      "city": "…"
    }
  },
  "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"
}

Kunde ändern

patch/api/v1/customers/{id}

Scope

customers:write

Parameter

  • id path · string · uuid*

Request-Body · application/json · erforderlich

{
  "name": "…",
  "address": "…",
  "country": "…",
  "customer_number": "…",
  "supplier_number": "…",
  "contact_name": "…",
  "delivery_name": "…",
  "delivery_address": "…",
  "delivery_country": "…",
  "payment_term_days": 0,
  "email": "…",
  "vat_id": "…",
  "buyer_reference": "…",
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "xrechnung_version": "3.0.2",
  "zugferd_profile": "basic",
  "price_mode": "net",
  "custom_fields": {
    "projekt_nr": "P-17"
  }
}

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 fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Nicht gefunden
  • 409 customer_number bereits vergeben
  • 422 Ungültige Felder
  • 429 Rate Limit überschritten

Schema 200

Beispiel 200

{
  "object": "customer",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "…",
  "address": "…",
  "country": "…",
  "customer_number": "…",
  "supplier_number": "…",
  "contact_name": "…",
  "delivery_name": "…",
  "delivery_address": "…",
  "delivery_country": "…",
  "payment_term_days": 0,
  "email": "…",
  "vat_id": "…",
  "buyer_reference": "…",
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "xrechnung_version": "3.0.2",
  "zugferd_profile": "basic",
  "price_mode": "net",
  "vat_id_check": {
    "status": "valid",
    "source": "vies",
    "checked_at": "2026-01-31T12:00:00Z",
    "name": "…",
    "stale": false,
    "matches": {
      "name": "…",
      "street": "…",
      "postcode": "…",
      "city": "…"
    }
  },
  "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"
}

Kunde löschen

delete/api/v1/customers/{id}

Scope

customers:write

Parameter

  • id path · string · uuid*
curl -X DELETE "https://maxrechnung.de/api/v1/customers/{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 fehlt oder der Tarif reicht nicht (plan_required)
  • 404 Nicht gefunden
  • 429 Rate Limit überschritten

Schema 200

  • object string
  • id string
  • deleted boolean

Beispiel 200

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

USt-IdNr. des Kunden prüfen und festhalten

post/api/v1/customers/{id}/vat-check

Prüft vat_id serverseitig (qualifiziert per BZSt, wenn die eigene USt-IdNr. aus dem Firmenprofil deutsch ist, sonst VIES) und schreibt das verifizierte Ergebnis nach vat_id_check. Bodylos. Antwort ist der aktualisierte Kunde.

Scope

customers:write

Parameter

  • id path · string · uuid*
  • 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/customers/{id}/vat-check" \
  -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

  • 200 Geprüft, Ergebnis in vat_id_check
  • 401 Kein oder ungültiger API-Key
  • 403 Scope customers:write fehlt
  • 404 Nicht gefunden
  • 409 Idempotency-Key schon mit einem anderen Request verwendet, oder der erste Request damit läuft noch
  • 422 vat_id fehlt oder ist keine EU-USt-IdNr.
  • 429 Rate Limit überschritten
  • 503 Prüfdienst (VIES/BZSt) aktuell nicht erreichbar

Schema 200

Beispiel 200

{
  "object": "customer",
  "id": "00000000-0000-0000-0000-000000000000",
  "name": "…",
  "address": "…",
  "country": "…",
  "customer_number": "…",
  "supplier_number": "…",
  "contact_name": "…",
  "delivery_name": "…",
  "delivery_address": "…",
  "delivery_country": "…",
  "payment_term_days": 0,
  "email": "…",
  "vat_id": "…",
  "buyer_reference": "…",
  "vat_scheme": "standard",
  "vat_exempt_clause": "8",
  "e_invoice_formats": [
    "xrechnung"
  ],
  "xrechnung_version": "3.0.2",
  "zugferd_profile": "basic",
  "price_mode": "net",
  "vat_id_check": {
    "status": "valid",
    "source": "vies",
    "checked_at": "2026-01-31T12:00:00Z",
    "name": "…",
    "stale": false,
    "matches": {
      "name": "…",
      "street": "…",
      "postcode": "…",
      "city": "…"
    }
  },
  "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.