Gutscheinanwendungen über GraphQL lesen und ändern

Verwenden Sie die API für Gutscheinanwendungen auf /graphql, um die Zielauswahl und das Entfernen eines Gutscheins aus einem Vorgang zu integrieren. Anwendungs-IDs identifizieren einzelne akzeptierte Anwendungen. Gutscheinnummern dienen der Eingabe und Anzeige, nicht als dauerhafte Identität einer Anwendung.

Bevor Sie beginnen

Verwenden Sie den passenden Konto-Header und entweder einen angemeldeten Mitarbeiter mit der Berechtigung zum Ändern von Vorgängen oder das gültige Zugriffstoken des Vorgangs. Eine Vorgangs-ID allein erlaubt keinen anonymen Zugriff. Jede Anwendung muss zum angegebenen Vorgang und Konto gehören.

Das akzeptierte Ziel lesen

query VoucherApplications($id: IdOrNumberOrToken!) {
  request(id: $id) {
    id
    voucherApplications {
      id
      voucherId
      voucherNumberSnapshot
      voucherType
      voucherConfigurationId
      voucherConfigurationRevision
      acceptedAt
      position
      scopeKind
      priceTransferPolicy
      state
      invalidationReason
      productId
      product {
        id
        name
      }
      selectedRequestItemId
      selectedPricingId
      replacesApplicationId
      allocation {
        status
        unallocatableReason
        invalidationReason
        allocatedAmount
        targetPricingId
      }
      actions {
        remove {
          available
          reason
        }
        reselect {
          available
          reason
        }
      }
    }
  }
}

Übergeben Sie {"id":"<order access token>"} als Variablen. Die Liste enthält auch die Historie und ist nach der unveränderlichen position sortiert. voucherNumberSnapshot, Gutscheinart, Konfigurations-ID und -Revision sowie das akzeptierte Ziel beschreiben den Stand bei der Annahme. Spätere Konfigurationsänderungen überschreiben diese Angaben nicht. product liefert aktuelle Anzeigedaten zur akzeptierten Artikel-ID. Optionale Positions- und Preiszeilenreferenzen können entfallen, wenn die referenzierte Warenkorbzeile gelöscht wird.

state ist ACTIVE, INVALIDATED oder REMOVED. Vorgänge dürfen zeitlich unbegrenzt erweitert werden; für Gutscheinanwendungen gibt es keinen Status „geschlossen“. Ein stornierter Vorgang behält seine Historie, kann seine Gutscheinanwendungen aber nicht mehr nutzen.

Die Vorschau interpretieren

allocation ist eine schreibgeschützte Vorschau auf Basis der lokalen Gutscheinbuchungen und des aktuellen Warenkorbs. Sie berücksichtigt Anwendungen unabhängig vom Gutscheintyp in ihrer Anwendungsreihenfolge. Die Vorschau reserviert kein Guthaben, bestätigt keinen externen Guthabenstand und erlaubt keinen Checkout-Abschluss. Verwenden Sie weiterhin den bestehenden Checkout-Ablauf und seine verbindliche Validierung.

allocatedAmount ist der positive Abzug als Money-Wert: {"amount":400,"currency":"EUR"} bedeutet 4,00 €. Bei einer nicht zuordenbaren Anwendung beträgt er 0, bei ungültigen Annahmenachweisen ist er null. targetPricingId bezeichnet die Preiszeile, die in der Vorschau für einen Artikel verwendet wird. Das akzeptierte Ziel bleibt unverändert. Vorschauabzüge können von der bisherigen Checkout-Berechnung abweichen. Ersetzen Sie damit nicht den zahlbaren Betrag und zeigen Sie sie nicht als bestätigte Zahlungen an.

Bei entfernten Anwendungen und stornierten Vorgängen ist die Vorschau null. Ansonsten gilt:

Mögliche Gründe sind BALANCE_UNAVAILABLE, ZERO_BALANCE, NO_ELIGIBLE_PRODUCT, NO_ELIGIBLE_VALUE und CART_VALUE_EXHAUSTED. Fehlender anrechenbarer Wert oder fehlendes Guthaben macht die Anwendung nicht ungültig. Bei nicht verfügbarem Guthaben erklären Sie, dass der Stand derzeit nicht bestätigt werden kann und vor dem Checkout geprüft werden muss. Fehlt der ausgewählte Artikel, bieten Sie vor Beginn der finanziellen Nutzung einen Artikelwechsel oder das Entfernen des Gutscheins an.

Invalidierungsgründe sind TARGET_RESELECTED, LEGACY_VOUCHER_MISSING, LEGACY_SCOPE_AMBIGUOUS, SNAPSHOT_UNSUPPORTED und SNAPSHOT_CORRUPT. Zeigen Sie bei TARGET_RESELECTED die verknüpfte Ersatzanwendung an. Ungültige Altdaten oder Snapshot-Nachweise erfordern eine Klärung durch Mitarbeiter.

Verfügbare Aktionen prüfen

Verwenden Sie actions.remove und actions.reselect, um zu entscheiden, ob Sie eine Aktion anbieten. Beide liefern available und einen optionalen typisierten Grund reason. Für Gäste mit dem Zugriffstoken des Vorgangs und berechtigte Mitarbeiter gelten dieselben Zuteilungs- und Lebenszyklusregeln. Die Neuauswahl gilt nur für GOODS-Gutscheine; eine VALUE-Anwendung hat kein veränderbares Artikelziel.

Die Verfügbarkeit ist ein Hinweis, keine Berechtigung oder Reservierung. Die Mutation prüft Berechtigungen und Lebenszyklus erneut unter Sperre sowie das übergebene Ziel, die bisherige Warenkorbdarstellung und die Preiszuordnung. Eine verfügbare Neuauswahl garantiert nicht, dass jeder Artikel als Ziel unterstützt wird. Entfernte oder invalidierte Historieneinträge bieten keine neue Aktion; ein identischer Wiederholungsversuch zum Entfernen kann weiterhin idempotent erfolgreich sein.

Diese Aktionen beenden nicht die zukünftige Nutzung des Restguthabens und erstatten keine frühere Einlösung. Stellen Sie Entfernen oder Zieländerungen nicht als Ersatz dafür dar. Das Lesen der Vorschau oder Aktionsverfügbarkeit löst keine Abbuchung aus und bestätigt keine ausstehende Zahlung.

Eine Anwendung entfernen

mutation RemoveVoucherApplication($input: RequestRemoveVoucherApplicationInput!) {
  requestRemoveVoucherApplication(input: $input) {
    application {
      id
      state
    }
    request {
      id
      voucherApplications {
        id
        state
      }
    }
    errorCodes
    errors {
      key
      message
    }
  }
}

Variablen: {"input":{"id":"<order access token>","applicationId":"<application UUID>"}}.

Bei Erfolg wird der erhaltene Datensatz mit state: REMOVED zurückgegeben. Der bisherige Gutscheineintrag im Warenkorb wird entfernt und die zugehörige Preiszuordnung wird in derselben Transaktion freigegeben. Erneutes Entfernen desselben bereits entfernten Datensatzes ist ohne weitere Änderung erfolgreich. Ein invalidierter Historieneintrag kann nicht entfernt werden.

Ein neues GOODS-Ziel auswählen

Für ein eindeutiges vorhandenes Warenkorbziel übergeben Sie dessen zulässige Artikel-ID. Soll eine neue, mit dem Gutschein verknüpfte Zielposition entstehen, übergeben Sie zusätzlich requestItem im bestehenden Format RequestItemInput. Senden Sie anschließend:

mutation ReselectVoucherApplication($input: RequestReselectVoucherApplicationInput!) {
  requestReselectVoucherApplication(input: $input) {
    application {
      id
      productId
      position
      state
      replacesApplicationId
    }
    request {
      id
      voucherApplications {
        id
        state
        position
        allocation {
          status
          allocatedAmount
          targetPricingId
        }
      }
    }
    errorCodes
    errors {
      key
      message
    }
  }
}

Variablen: {"input":{"id":"<order access token>","applicationId":"<old application UUID>","productId":"<eligible product UUID>","idempotencyKey":"<unique command key>"}}.

Für eine neue Zielposition ergänzen Sie in input: "requestItem":{"offerableId":"<eligible product UUID>","offerableType":"PRODUCT","pricings":[{"priceOriginId":"<eligible product UUID>","priceOriginType":"PRODUCT","quantity":1}]}. Der Artikel muss mit productId übereinstimmen. Dadurch entsteht eine neue Warenkorbposition; eine vorhandene Position wird weder umgewidmet noch verbraucht. Fügen Sie damit nicht unbemerkt doppelte Mengen hinzu. Ein mehrdeutiges vorhandenes Ziel, das die bisherige Berechnung nicht abbilden kann, führt zu INVALID_TARGET, ohne den Vorgang zu ändern.

Die Neuauswahl ist eine neue Annahme derselben Gutscheinidentität anhand ihrer aktuellen Konfiguration. Der alte Datensatz erhält INVALIDATED mit TARGET_RESELECTED. Die Ersatzanwendung wird hinten in der Prioritätsreihenfolge angefügt und verweist über replacesApplicationId auf den Vorgänger. Warenkorbänderungen, Annahme und Preiszuordnung werden gemeinsam gespeichert oder vollständig zurückgerollt.

Wird bei der Neuauswahl die Preisübernahme auf eine andere vorhandene Position übertragen, erhält die bisherige Position wieder ihren regulär konfigurierten Preis. Die Preisübernahme gilt nur für das neue Ziel. Finanziell gesperrte Positionen dürfen nicht neu bepreist werden. Lässt sich der reguläre Preis nicht sicher bestimmen, wird der Befehl ohne Warenkorbänderung abgelehnt.

Fordern Sie in der Mutationsantwort das aktualisierte request.voucherApplications.allocation für alle Gutscheine an, nicht nur für die Ersatzanwendung. Ihre Verschiebung ans Ende kann den Abzug eines anderen Gutscheins erhöhen und den eigenen verringern. Stellen Sie eine Zieländerung niemals als Beibehaltung der Priorität dar.

Verwenden Sie bei der Wiederholung desselben Befehls denselben Schlüssel, dieselbe Vorgänger-ID, dieselbe Artikel-ID und die vollständigen identischen Positionseingaben. Der Server gibt die gespeicherte Ersatzanwendung zurück, ohne sie erneut anzuwenden, auch wenn sich ihr Lebenszyklus inzwischen geändert hat. Derselbe Schlüssel für einen anderen Befehl führt zu IDEMPOTENCY_CONFLICT. Schlüssel sind innerhalb des Kontos eindeutig. Eine tatsächlich neue Auswahl benötigt einen neuen Schlüssel.

Behandlung abgelehnter Befehle

Verwenden Sie errorCodes für die Programmlogik und errors für Felddetails. Bei FINANCIAL_USE_STARTED ist eine Stornierung, Erstattung oder Klärung erforderlich – kein Entfernen und keine Neuauswahl. Auch ausstehende Finanzoperationen und Operationen mit unklarem Ergebnis blockieren diese Befehle. REQUEST_NOT_EDITABLE verlangt einen bearbeitbaren Vorgang. INVALID_STATE_TRANSITION bezeichnet einen unzulässigen Zustandswechsel.

FEATURE_DISABLED bedeutet, dass diese Schreibvorgänge für das Konto nicht verfügbar sind. APPLICATION_NOT_FOUND gibt keine Datensätze anderer Vorgänge oder Konten preis. Bei INVALID_TARGET ist ein zulässiger, bereits im Warenkorb vorhandener Artikel erforderlich. PROJECTION_MISMATCH und INVALID_APPLICATION erfordern eine Klärung durch Mitarbeiter; reparieren Sie die Historie nicht automatisch. ACTIVE_APPLICATION_EXISTS bezeichnet eine bereits aktive Anwendung.