Abrechnungs-API-Konzepte

Abrechnungszyklen

Ein Dienst wird in einem von fünf Zyklen abgerechnet. MONTHLY, QUARTERLY, SEMI_ANNUALLY und ANNUALLY sind vorausbezahlte Laufzeiten von 1, 3, 6 und 12 Monaten: Jede neue Laufzeit wird vorab berechnet und am nextRenewal-Datum des Abonnements fällig.

Nutzungsabhängige Gebühren sammeln sich im UTC-Kalendermonat an und erscheinen am 1. des Folgemonats auf einer Rechnung: Oktobernutzung wird am 1. November berechnet. Die Rechnung enthält HOURLY-Dienstgebühren und anfallenden Mehrverbrauch beim Datenverkehr und ist sieben Tage nach Erstellung fällig. Die Grundgebühr einer vorausbezahlten Laufzeit wird im Voraus berechnet, anfallender Mehrverbrauch danach.

Jeder Tarif enthält seine Zykluspreise unter pricing.rates, einem nach Zyklus indizierten Objekt. Jeder Preis hat drei Felder:

Geldeinheiten

Jeder Betrag ist eine ganze Zahl in der Währung seines oder des übergeordneten Datensatzes; der Feldname bestimmt die Skalierung. Namen mit Millicents zählen Tausendstel Cent, also entspricht 150000 einem Betrag von 1,50. Alle anderen Geldfelder zählen Cent: 12999 entspricht 129,99.

Millicent erhalten Bruchteile eines Cents in Stundenpreisen; Laufzeitpreise sind stets ganze Centbeträge. Eine Bestellung enthält nur ihren Preis. Steuern, Rabatte und offener Betrag erscheinen auf ihrer Rechnung.

Die Währung ist ein ISO-4217-Code, als currency in Tarif-pricing, Bestellungen, Abonnements und deren Posten, Rechnungen und deren Transaktionen, Guthabensaldo und Einträgen sowie Nutzungsübersicht. Tarife werden in US-Dollar bepreist und in die Abrechnungswährung der Organisation umgerechnet. Diese kann nicht mehr geändert werden, sobald eine Bestellung, Rechnung, ein Abonnement oder Guthabeneintrag besteht.

Dienste bestellen

Wie Sie einen neuen Server oder IP-Block kaufen, hängt vom Abrechnungszyklus ab:

Bestellung erstellen benötigt cycle und akzeptiert alle fünf Werte. Die beiden Einzelpostenaufrufe sind Kurzformen einer stündlichen Bestellung mit einem Posten: Sie akzeptieren dessen Felder auf oberster Body-Ebene ohne type und cycle, erstellen dieselbe Bestellung und führen dieselben Prüfungen aus. Alle drei akzeptieren einen Idempotency-Key (Idempotenz).

Stündliche Abrechnung benötigt eine Nutzungsabrechnungsfreischaltung, die neue Organisationen nicht haben. Derzeit wird sie auf Anfrage über den Support in der Cloud-Konsole erteilt. Berechtigte Funktionen abrufen zeigt sie als billing.isUsageBased; eine stündliche Bestellung oder Kurzform ohne sie antwortet mit 422 USAGE_BILLING_DISABLED.

Bestellposten

items enthält einen Eintrag pro Server oder IP-Block, da Posten kein Mengenfeld haben. Jeder nennt seine Art als type, exakt BAREMETAL oder IP_BLOCK; andere oder fehlende type-Werte werden mit 400 VALIDATION_ERROR abgelehnt. Jeder Posten nennt Tarif und Rechenzentrum:

• plan ist die Tarif-id. Ein Bare-Metal-Tarif akzeptiert auch seinen unveränderlichen slug, ein IP-Block-Tarif nicht.
• datacenter ist die id oder der code des Rechenzentrums, etwa ams1.

Bare-Metal-Tarife auflisten und IP-Block-Tarife auflisten liefern die id jedes Tarifs, den slug eines Bare-Metal-Tarifs sowie pro Rechenzentrum einen availability-Eintrag mit id, code und Bestand quantity.

Ein BAREMETAL-Posten akzeptiert auch Adressen und Starteinstellungen des neuen Servers:

Mit bootMode PXE und einem Skript startet der Server nach der Bereitstellung einmal dieses Skript (Eigene iPXE-Skripte). Das Betriebssystem gehört nicht zur Bestellung; es wird bei der Bereitstellung gewählt.

/30 und /120 sind im Tarifpreis enthalten. Ein größerer IPv4-Block mit Länge 24 bis 29 ergänzt eine Zeile IPv4 /<length> in den lines des Bestellpostens und der Rechnung. Der Preis ist die Differenz zwischen dem IPv4-IP-Block-Tarif dieser Länge und dem /30-Tarif.

Mit IPv4 bestelltes IPv6 entfällt bei fehlendem IPv6-Adressraum im Rechenzentrum; der Server wird ohne IPv6 bereitgestellt. Allein bestelltes IPv6 lässt stattdessen den Posten fehlschlagen. Ein Server mit beiden Längen null erhält weder Netzwerk noch Adresse und kann erst nach Verbindung mit einem eigenen Netzwerk und Zuweisung einer primären IPv4-Adresse bereitgestellt werden (Netzwerke). Andernfalls liegen seine Präfixe auf einem eigens erstellten Internetzugangsnetz und werden über sein eigenes Abonnement abgerechnet; deshalb hat ein BAREMETAL-Posten kein Netzwerkfeld.

Ein IP_BLOCK-Posten akzeptiert networkId, das Zielnetzwerk des Blocks. Ein nicht vorhandenes oder fremdes Netzwerk antwortet mit 404 ENTITY_NOT_FOUND. Virtuelle Dienstnetzwerke auflisten liefert Servernetzwerke mit IDs. Ein Block für das Netzwerk eines neuen Servers wird daher erst nach dessen Erstellung bestellt.

promoCode ist optional. Sein Rabatt gilt für die erste Rechnung einer Laufzeitbestellung; Verlängerungen und stündliche Bestellungen erhalten keinen Rabatt. Ein leerer Code gilt als nicht angegeben.

Die Bestellung wird beim Aufgeben geprüft; Ablehnungen sind 422. OFFERING_NOT_AVAILABLE erscheint als Hauptcode. Alle anderen sind Details unter VALIDATION_FAILED am genannten Feld, das bei Kurzformen kein Präfix items[<i>]. hat:

Laufzeitbestellung bezahlen

Die Antwort einer Laufzeitbestellung enthält data.order mit status UNPAID und data.invoiceId. Die Rechnung ist am Erstellungstag fällig. Sie berechnet jeden Server zum priceMillicents seines Tarifzyklus, kostenpflichtige IPv4-Präfixe als eigene Zeile, Steuern anhand der Rechnungsadresse und den Aktionsrabatt. Eine Organisation ohne Rechnungsadresse erhält nach Speicherung der Bestellung 422 BILLING_ADDRESS_REQUIRED; setzen Sie die Adresse in der Cloud-Konsole und senden Sie dieselbe Anfrage mit demselben Idempotency-Key, um die Rechnung für die gespeicherte Bestellung zu erstellen.

Diese Rechnung wird nicht automatisch bezahlt. Verlängerungs- und Nutzungsrechnungen werden am Fälligkeitstag zuerst aus Kontoguthaben, dann von der Standardkarte beglichen; die erste Bestellrechnung wartet auf eine deckende Zahlung. Ein Skript bezahlt sie über Rechnung bezahlen mit providerType ACCOUNT_CREDIT aus dem Guthaben der Organisation, wie im Schnellstart.

Eine unbezahlte Bestellung wird innerhalb von 24 Stunden storniert. Bis dahin reserviert sie keinen Server: Der Bestand wird bei Bestellung und erneut bei Bereitstellung der bezahlten Bestellung geprüft.

Sobald die Rechnung PAID zeigt, läuft die Bereitstellung im Hintergrund. Jeder Posten erhält ein eigenes Abonnement im Bestellzyklus. Bestellung abrufen zeigt das Ergebnis: Der Posten wechselt von PENDING zu COMPLETED, seine provisionedId enthält die neue Server-ID (bei IP_BLOCK die neue Block-ID), und die Bestellung wechselt von UNPAID zu COMPLETE. Rechnungen auflisten liefert die orderId jeder Bestellrechnung.

Ein nicht bereitstellbarer Posten zeigt FAILED, etwa wenn der Servertarif zwischen Bestellung und Zahlung ausverkauft war. Nach Abschluss mit mindestens einem fehlgeschlagenen Posten zeigt die Bestellung FAILED, auch wenn andere erfolgreich waren. Sie nennt den Fehlergrund nicht, es gibt keine automatische Wiederholung, bezahlte Rechnungen bleiben bezahlt und nichts wird automatisch erstattet. Kontaktieren Sie deshalb den Support mit der Bestell-id.

Stündliche Anfragen

Die id einer Kurzformantwort ist die neue Server- oder Block-ID. Bestellung erstellen mit HOURLY antwortet mit invoiceId null, den eröffneten subscriptions und provisionedItems: ein Eintrag je Posten mit orderItemId, provisionedId und isProvisioned sowie errorMessage, wenn isProvisioned false ist.

Kann nichts bereitgestellt werden, antwortet die Anfrage mit 409 PROVISIONING_FAILED; ihre Bestellung bleibt mit status FAILED erhalten. Bei mehreren Posten ist Teilerfolg möglich; die Antwort ist dann 201, und provisionedItems zeigt die erfolgreichen Posten. Dieselbe Anfrage mit demselben Idempotency-Key legt keine zweite Bestellung an. Sie antwortet mit 200, bei Bestellung erstellen mit isReplayed true, liefert das ursprünglich Bereitgestellte und versucht fehlgeschlagene Posten erneut.

Abonnements

Jeder abgerechnete Dienst gehört zu einem Abonnement mit cycle, status, lastRenewal und nextRenewal, nach Ende terminatedAt sowie den abgerechneten items, einschließlich beendeter. Ein Serverabonnement enthält den Server und einen IP_BLOCK-Posten je bestellter Adressfamilie. Die provisionedId eines Postens ist die ID des abgerechneten Servers oder Blocks; subtotalMillicents ist sein Preis pro Zyklus oder bei HOURLY pro Stunde. Seine details enthalten beim Server includedEgressGb (null für unbegrenzt), beim Block ipVersion und prefixLength.

Dienstabonnement abrufen und IP-Block-Abonnement abrufen liefern das einen Server oder Block abrechnende Abonnement. Dessen status ist ACTIVE, CANCELLATION_REQUESTED oder CANCELLED.

Abonnement kündigen antwortet mit 204. Ab diesem Moment erstellt es keine Verlängerungsrechnung mehr; bei stündlicher Abrechnung endet das Ansammeln von Nutzung. Der weitere Ablauf hängt vom abgerechneten Dienst ab:

• Ein Bare-Metal-Server wird gelöscht. Während Ausschalten und Abbau zeigt er state DELETING (Dienst entfernen); das Abonnement zeigt bis zur Entfernung von Server und Adressblöcken CANCELLATION_REQUESTED, danach CANCELLED.
• Ein eigenständig bestellter IP-Block wird sofort freigegeben; sein Abonnement wechselt direkt zu CANCELLED.
• Ein Cloud-Server oder ein Abonnement ohne verbleibenden aktiven Posten geht als Ticket zur manuellen Prüfung an unseren Support. Bis zu dessen Abschluss zeigt es CANCELLATION_REQUESTED.

Bare-Metal-Dienst löschen startet beim einzigen Server eines Abonnements dieselbe Kündigung; IP-Block löschen tut dies für eigenständig bestellte Blöcke. Ein mit einem Server gelieferter Block wird mit 422 BUNDLED_ITEM_CANCELLATION_BLOCKED abgelehnt: Löschen Sie den Server, der Block wird danach freigegeben.

Eine erneute Anfrage während ausstehender Kündigung antwortet wieder mit 204. Ablehnungen sind 422; nur SUBSCRIPTION_CANCELLATION_INCOMPLETE folgt auf eine teilweise Änderung:

Rechnungen

Rechnungen auflisten akzeptiert unpaidOnly=true für offene Rechnungen: UNPAID, PARTIAL und OVERDUE. Der status einer Rechnung ist einer dieser drei oder PAID, COLLECTIONS, CANCELLED oder REFUNDED; ihr type ist STANDARD oder bei Guthabenaufladungen CREDIT_PURCHASE. Rechnungs-PDF herunterladen liefert direkt das PDF statt JSON.

Rechnung bezahlen akzeptiert einen JSON-Body mit providerType ACCOUNT_CREDIT oder STRIPE; das ebenfalls im Enum geführte MANUAL wird mit 400 abgelehnt. Die Antwort ist 200 mit Zahlungs-status (PENDING, SUCCEEDED, FAILED oder CANCELLED), der auf der Rechnung erfassten transactionId, clientSecret und declineCode.

• ACCOUNT_CREDIT bezahlt aus Organisationsguthaben und ist die Zahlungsart für Skripte mit Schlüssel. Es verwendet den Saldo bis zum offenen Betrag. Reicht er nicht, bleibt die Rechnung PARTIAL, während die Zahlung SUCCEEDED ist.
• STRIPE mit der methodId einer gespeicherten Karte belastet diese Karte.
• STRIPE ohne methodId startet eine durch ein Kartenformular abzuschließende Zahlung.

Eine den Karteninhaber erfordernde Zahlung, ob neue Karte oder gespeicherte mit 3-D Secure, antwortet mit PENDING und clientSecret. Stripe.js schließt sie im Browser mit unserem veröffentlichbaren Schlüssel ab, den die API nicht ausgibt. Rechnungszahlung bestätigen erfasst danach das Ergebnis anhand von providerType STRIPE und der von Stripe vergebenen providerTransactionId. Kartenzahlungen erfolgen daher in der Cloud-Konsole.

Eine abgelehnte Zahlung ist 422; data enthält dieselbe Zahlungsansicht:

declineCode wird nur bei Kartenablehnung gesetzt, etwa INSUFFICIENT_FUNDS oder EXPIRED_CARD. Eine allgemeine Ablehnung zeigt GENERIC_DECLINE, ebenso eine vom Kartennetz als betrügerisch, verloren oder gestohlen markierte Karte. Eine der Plattform unbekannte Ablehnung zeigt UNKNOWN.

Nutzung im aktuellen Zeitraum

Aktuelle Nutzung abrufen umfasst stündliche Dienste im laufenden Abrechnungszeitraum mit Beträgen in Cent:

• periodStart und periodEnd begrenzen den Zeitraum.
• accruedAmount ist die bisher aufgelaufene Summe: abrechenbare Stunden jedes Dienstes zum Stundenpreis abzüglich Postenrabatt zuzüglich Verkehr über dem Tarifkontingent.
• estimatedAmount rechnet Stunden bis periodEnd hoch, als liefen aktive Dienste bis dahin; beendete zählen mit ihren aufgelaufenen Beträgen. Datenverkehr zählt nach bisheriger Messung.
• activeServiceCount und terminatedServiceCount zählen die zugrunde liegenden Dienste.
• isPartial ist true, wenn ein Nutzungsteil nicht gelesen werden konnte; die Beträge lassen diesen Teil dann aus.

Kontoguthaben

Guthabensaldo abrufen liefert creditBalance sowie kleinsten und größten Kaufbetrag minPurchaseAmount und maxPurchaseAmount, alles in Cent. Guthaben kaufen akzeptiert amount in Cent und antwortet mit 201 und einer CREDIT_PURCHASE-Rechnung. Beträge außerhalb der Grenzen sind 422 VALIDATION_FAILED mit Detail CREDIT_AMOUNT_INVALID für amount. Diese Rechnung enthält keine Steuer, wird nie automatisch belastet und in der Cloud-Konsole per Karte bezahlt. Nach Zahlung wird das Guthaben hinzugefügt.

Der Saldo ist die Summe eines Buchungsjournals. Guthabeneinträge auflisten paginiert mit neuesten zuerst; Guthabeneintrag abrufen liest einen Eintrag mit amount in Cent, type, description, createdAt und bei Rechnungsbezug invoiceId. Ein bezahlter Guthabenkauf ergänzt eine ADDITION; für Rechnungen ausgegebenes Guthaben ist ein negativer INVOICE_PAYMENT. Weitere Typen sind PROMOTION, MANUAL_ADJUSTMENT für durch Mitarbeiter hinzugefügtes oder entferntes Guthaben und REFUND für bei Rückgängigmachung einer Guthabenzahlung zurückgegebenes Guthaben.

Zahlungsmethoden

Karten werden über Stripe in der Cloud-Konsole hinzugefügt; die Kartennummer durchläuft diese API nie. Karte hinzufügen benötigt keinen Body und antwortet mit 201, provider STRIPE und dem clientSecret der Stripe-Einrichtung hinter dem Kartenformular. Stripe.js schließt diese wie eine Kartenzahlung im Browser ab. Ohne Rechnungsadresse der Organisation antwortet die erste Karteneinrichtung mit 422 BILLING_ADDRESS_REQUIRED.

Standardzahlungsmethode festlegen antwortet mit 204 und bestimmt die gespeicherte Karte für Verlängerungs- und Nutzungsrechnungen. Zahlungsmethode löschen antwortet mit 204 und entfernt die Karte aus Organisation und Stripe. Kein Aufruf listet gespeicherte Karten auf: Ihre IDs liegen im Organisationsdatensatz, den nur eine Konsolensitzung liest. Ein Schlüssel kann daher die von diesen beiden Aufrufen und methodId bei Rechnung bezahlen benötigte ID nicht ermitteln.