Nutzung prüfen und ein Top-up hinzufügen
Verwenden Sie diese Anleitung, um einer bestehenden eSIM Datenvolumen hinzuzufügen. Sie benötigen die Berechtigung, die eSIM zu lesen und ein Paket zu kaufen, sowie ausreichend Wallet-Guthaben. Die Verfügbarkeit von Top-ups hängt vom Profil, den bestehenden Paketen und dem gewählten Angebot ab.
1. Aktive Pakete prüfen
Öffnen Sie das Profil über eSIMs und prüfen Sie die Datenpakete. Mit der API können Sie die Pakete der eSIM auflisten und deren Status, Ablaufzeitpunkt und Guthaben prüfen.
balance.total_bytes ist das gekaufte Datenvolumen. Ein Nullwert (fehlender Messwert) bei used_bytes, remaining_bytes oder used_percent bedeutet, dass keine Messung vorliegt. Behandeln Sie diese Werte in Ihrer Anwendung als unbekannt.
Lesen Sie das Feld balance_reporting der eSIM, um zu entscheiden, was angezeigt wird. Wenn es unavailable ist, zeigen Sie das gekaufte Datenvolumen an, ohne es als gemessenes Restdatenvolumen darzustellen. Wenn es available ist, kann der Verbrauch trotzdem unbekannt bleiben, bis ein Bericht eintrifft. Die tägliche Nutzungshistorie ist separat und derzeit nicht verfügbar.
Verwenden Sie balance.as_of für den Zeitpunkt der letzten Saldoaktualisierung; bevor Verbrauch gemeldet wird, kann dies der Zeitpunkt der Paketbereitstellung sein. balance.observed_at ist, sofern vorhanden, der Netz-Messzeitpunkt. Zeigen Sie den Zeitstempel zusammen mit dem gemessenen Verbrauch an, damit der Kunde einen verzögerten Bericht erkennen kann.
2. Kompatible Angebote auflisten
Wählen Sie Top up auf der eSIM oder rufen Sie Kompatible Angebote auflisten für dieses Profil auf. Verwenden Sie ein zurückgegebenes Angebot, anstatt aus dem allgemeinen Katalog zu wählen. Abdeckung im selben Land bedeutet nicht automatisch Kompatibilität.
Wenn ein Top-up nicht verfügbar ist, lesen Sie available_actions auf der eSIM, um den Grund zu erfahren. Eine nicht abgeschlossene Bestellung oder das Paketlimit kann einen weiteren Kauf verhindern. Schließen Sie die bestehende Bestellung ab, bevor Sie es erneut versuchen. Aktualisieren Sie die kompatiblen Angebote vor dem Absenden: Ein Angebot kann zwischen Auswahl und Kauf nicht mehr verfügbar werden.
Eine eSIM im Status expired ist inaktiv und kann nach Abschluss eines kompatiblen Top-ups zu active zurückkehren. Prüfen Sie die verfügbare Aktion und die kompatiblen Angebote, bevor Sie entscheiden, dass das installierte Profil ersetzt werden muss.
3. Geltende Konditionen prüfen
Zeigen Sie Datenvolumen, Abdeckung, veröffentlichten Preis mit Währung und Gültigkeit des ausgewählten Angebots an. Vergleichen Sie die Gültigkeit des neuen Pakets mit der active_until-Servicegrenze der eSIM, sofern vorhanden. Wenn diese Grenze die gekaufte Gültigkeit verkürzen würde, gibt die Bestellung 409 mit der tatsächlichen Gültigkeit zurück. Zeigen Sie den kürzeren Zeitraum an und holen Sie die Zustimmung ein, bevor Sie acknowledge_shortened_validity: true setzen.
Ein Top-up erstellt ein weiteres Paket. Es ändert weder das Guthaben eines bestehenden Pakets noch verlängert es dessen Ablaufzeitpunkt. Prüfen Sie Aktivierung und Ablauf des neuen Pakets nach der Bereitstellung.
4. Bestellung genehmigen und verfolgen
Bestätigen Sie den Kauf im Dashboard. Erstellen Sie mit der API eine Bestellung unter Verwendung der vorhandenen esim_id, der ausgewählten offer_id, des revision des Angebots als offer_revision und des pricing.price als expected_price. Lassen Sie subscriber_id weg; ein Top-up behält die bestehende Zuordnung bei. Speichern Sie die Bestell-ID und einen Idempotency-Key für erneute Versuche.
Wenn sich der akzeptierte Preis oder die Revision geändert hat, rufen Sie das aktuelle Angebot ab und bestätigen Sie die neuen Konditionen, bevor Sie einen weiteren Kauf absenden. Übernehmen Sie den zurückgegebenen Preisbetrag und die Währung ohne Umrechnung oder Rundung.
Verfolgen Sie die Bestellung unter Orders oder rufen Sie die Bestellung ab über die API. Prüfen Sie status nach den Antworten von 201 und 202. Falls die Antwort verloren geht, wiederholen Sie dieselbe Anfrage mit demselben Schlüssel; erstellen Sie keinen Ersatzkauf, solange das Ergebnis unklar ist.
5. Das resultierende Paket prüfen
Wenn die Bestellung completed ist, verwenden Sie deren package_id, um das neue Paket abzurufen. Prüfen Sie, ob Ziel-eSIM, Abdeckung und Datenvolumen mit dem Kauf übereinstimmen. Das Top-up nutzt das installierte Profil; Sie müssen keine neue eSIM installieren. Ein Paket, das auf die erste Nutzung wartet, kann noch keinen Aktivierungs- oder Ablaufzeitstempel haben.
Fehlerbehebung
Falls die Bestellung abgeschlossen ist, das Guthaben aber unbekannt bleibt, vergleichen Sie Paketstatus und Berichtszeitstempel. Die Meldung kann hinter der Gerätenutzung zurückliegen; eine erneute Bestellung löst diese Verzögerung nicht. Falls ein Kauf fehlschlägt, prüfen Sie die Fehlerdetails und eine etwaige Gutschriftreferenz, bevor Sie es erneut versuchen.
Nächste Schritte
Verwandte Ressourcen
Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.