Factureringsconcepten in de API

Factureringscycli

Een dienst wordt volgens een van vijf cycli gefactureerd. MONTHLY, QUARTERLY, SEMI_ANNUALLY en ANNUALLY zijn vooraf betaalde looptijden van 1, 3, 6 en 12 maanden: elke nieuwe looptijd wordt vooraf gefactureerd en is verschuldigd op de nextRenewal-datum van het abonnement.

Gebruiksafhankelijke kosten lopen op tijdens de UTC-kalendermaand en verschijnen op een factuur op de 1e van de volgende maand: gebruik in oktober wordt op 1 november gefactureerd. Die factuur bevat HOURLY-dienstkosten en toepasselijk extra dataverkeer en is zeven dagen na uitgifte verschuldigd. De basiskosten van een vooraf betaalde looptijd worden vooraf gefactureerd; toepasselijk extra verkeer achteraf.

Elke configuratie prijst haar cycli onder pricing.rates, een object met de cyclus als sleutel. Elk tarief heeft drie velden:

Geldeenheden

Elk bedrag is een geheel getal in de valuta van het record of het bovenliggende record; de veldnaam geeft de schaal aan. Namen die eindigen op Millicents tellen duizendsten van een cent, dus 150000 is 1,50. Alle andere geldvelden tellen centen: 12999 is 129,99.

Millicenten behouden centfracties in een uurtarief; een looptijdprijs is altijd een geheel aantal centen. Een bestelling bevat alleen de prijs. Belastingen, kortingen en het verschuldigde bedrag staan op de factuur.

De valuta is een ISO 4217-code, verstuurd als currency bij pricing van configuraties, bestellingen, abonnementen en hun items, facturen en transacties, tegoedsaldo en boekingen en het gebruiksoverzicht. Configuraties zijn geprijsd in Amerikaanse dollars en worden omgerekend naar de factureringsvaluta van de organisatie. Deze kan niet meer veranderen zodra er een bestelling, factuur, abonnement of tegoedboeking is.

Diensten bestellen

Hoe u een nieuwe server of IP-blok koopt hangt af van de factureringscyclus:

Bestelling maken vereist cycle en accepteert alle vijf waarden. De twee aanroepen voor één item zijn verkorte uurorders: zij accepteren de itemvelden op het hoogste niveau van de body, zonder type of cycle, plaatsen dezelfde bestelling en voeren dezelfde controles uit. Alle drie accepteren een Idempotency-Key (Idempotentie).

Uurfacturering vereist een gebruiksafhankelijk recht dat een nieuwe organisatie niet heeft. Dit wordt momenteel op verzoek toegekend via support in de cloudconsole. Beschikbare rechten opvragen toont dit als billing.isUsageBased; een uurorder of verkorte aanroep zonder dit recht antwoordt met 422 USAGE_BILLING_DISABLED.

Bestelitems

items bevat één vermelding per server of IP-blok, want een item heeft geen hoeveelheidsveld. Elke vermelding noemt de soort in type, exact BAREMETAL of IP_BLOCK. Andere of ontbrekende type-waarden worden geweigerd met 400 VALIDATION_ERROR. Elk item noemt configuratie en datacenter:

• plan is de id van de configuratie. Een dedicated-serverconfiguratie accepteert ook haar onveranderlijke slug, een IP-blokconfiguratie niet.
• datacenter is de id of code van het datacenter, zoals ams1.

Dedicated-serverconfiguraties opvragen en IP-blokconfiguraties opvragen geven de id van elke configuratie, de slug van dedicated-serverconfiguraties en per datacenter een availability-vermelding met id, code en voorraad quantity terug.

Een BAREMETAL-item accepteert ook adres- en opstartinstellingen:

Met bootMode PXE en een script start de server dat script één keer na inrichting (Aangepaste iPXE-scripts). Het besturingssysteem maakt geen deel uit van de bestelling; u kiest het bij de implementatie.

/30 en /120 zijn in de configuratieprijs inbegrepen. Een groter IPv4-blok, lengte 24 tot 29, voegt een regel IPv4 /<length> toe aan lines van het bestelitem en de factuur. De prijs is het verschil tussen de IPv4-IP-blokconfiguratie van die lengte en de /30-configuratie.

Samen met IPv4 besteld IPv6 wordt weggelaten als het datacenter geen IPv6-ruimte heeft; de server komt dan zonder IPv6 beschikbaar. Alleen besteld IPv6 laat in dat geval het item mislukken. Een server met beide lengtes null krijgt geen netwerk of adres en kan pas worden geïmplementeerd nadat u een eigen netwerk aansluit en een primair IPv4-adres toewijst (Netwerken). Anders staan zijn prefixen op een eigen internettoegangsnetwerk en worden ze op het serverabonnement gefactureerd. Daarom heeft een BAREMETAL-item geen netwerkveld.

Een IP_BLOCK-item accepteert networkId, het netwerk waaraan het blok wordt toegevoegd. Een niet-bestaand netwerk of een netwerk van een andere organisatie antwoordt met 404 ENTITY_NOT_FOUND. Virtuele dienstnetwerken opvragen geeft de servernetwerken met hun ID's. Een blok voor het netwerk van een nieuwe server bestelt u dus zodra die server bestaat.

promoCode is optioneel. De korting geldt voor de eerste factuur van een looptijdbestelling; verlengingen en uurorders krijgen geen korting. Een lege code geldt als niet opgegeven.

De bestelling wordt bij plaatsing gecontroleerd; een weigering is 422. OFFERING_NOT_AVAILABLE verschijnt als hoofdcode. Alle andere weigeringen zijn een detail onder VALIDATION_FAILED op het genoemde veld, dat bij verkorte aanroepen geen voorvoegsel items[<i>]. heeft:

Een looptijdbestelling betalen

Het antwoord bevat data.order met status UNPAID en data.invoiceId. De factuur is op de uitgiftedag verschuldigd. Ze factureert elke server tegen priceMillicents van de configuratiecyclus, betaald IPv4-prefix als aparte regel, belasting voor het factuuradres en de promotiekorting. Zonder factuuradres krijgt een organisatie na opslag van de bestelling 422 BILLING_ADDRESS_REQUIRED. Stel het adres in de cloudconsole in en verstuur dezelfde aanvraag met dezelfde Idempotency-Key om de factuur voor die opgeslagen bestelling te maken.

Deze factuur wordt niet voor u betaald. Verlengings- en gebruiksfacturen worden op de vervaldag eerst uit accounttegoed en daarna via de standaardkaart betaald; de eerste bestelfactuur wacht tot een betaling haar dekt. Vanuit een script betaalt Factuur betalen met providerType ACCOUNT_CREDIT uit het tegoed van de organisatie, zoals in de Snelstart.

Een onbetaalde bestelling wordt binnen 24 uur geannuleerd. Tot die tijd reserveert zij geen server: voorraad wordt bij plaatsing en opnieuw bij inrichting na betaling gecontroleerd.

Zodra de factuur PAID toont, loopt inrichting op de achtergrond. Elk item krijgt een eigen abonnement op de bestelcyclus. Bestelling opvragen toont het resultaat: het item gaat van PENDING naar COMPLETED, de provisionedId bevat de nieuwe server-ID (de blok-ID voor een IP_BLOCK-item) en de bestelling gaat van UNPAID naar COMPLETE. Facturen opvragen geeft de orderId van elke bestelfactuur.

Een item dat niet kan worden ingericht toont FAILED, bijvoorbeeld als de serverconfiguratie tussen bestelling en betaling is uitverkocht. De bestelling toont FAILED zodra inrichting eindigt met minstens één mislukt item, ook als andere zijn voltooid. De bestelling noemt de oorzaak niet, niets probeert automatisch opnieuw, een betaalde factuur blijft betaald en niets wordt automatisch terugbetaald. Neem daarom contact op met support met de bestel-id.

Uuraanvragen

De id in het antwoord van een verkorte aanroep is de nieuwe server- of blok-ID. Bestelling maken op HOURLY antwoordt met invoiceId null, de geopende subscriptions en provisionedItems: één vermelding per item met orderItemId, provisionedId en isProvisioned, plus errorMessage wanneer isProvisioned false is.

Kan niets worden ingericht, dan antwoordt de aanvraag met 409 PROVISIONING_FAILED; de geplaatste bestelling blijft met status FAILED bewaard. Met meerdere items kan een bestelling gedeeltelijk slagen. Het antwoord is dan 201 en provisionedItems toont welke items beschikbaar zijn. Dezelfde aanvraag met dezelfde Idempotency-Key plaatst geen tweede bestelling. Ze antwoordt met 200, met isReplayed true bij Bestelling maken, geeft terug wat de eerste aanvraag heeft ingericht en probeert mislukte items opnieuw.

Abonnementen

Elke gefactureerde dienst hoort bij een abonnement met cycle, status, lastRenewal, nextRenewal, na beëindiging terminatedAt en de gefactureerde items, inclusief beëindigde. Een serverabonnement bevat de server en één IP_BLOCK-item per bestelde adresfamilie. De provisionedId van een item is de ID van de gefactureerde server of het blok; subtotalMillicents is de prijs per cyclus of bij HOURLY per uur. De details bevatten bij servers includedEgressGb (null voor onbeperkt) en bij blokken ipVersion en prefixLength.

Dienstabonnement opvragen en IP-blokabonnement opvragen geven het abonnement dat één server of blok factureert. De status is ACTIVE, CANCELLATION_REQUESTED of CANCELLED.

Abonnement opzeggen antwoordt met 204. Vanaf dat moment ontstaan geen verlengingsfacturen meer en stopt een uurabonnement met gebruik opbouwen. Het vervolg hangt af van de gefactureerde dienst:

• Een dedicated server wordt verwijderd. Hij toont state DELETING tijdens uitschakeling en afbraak (Een dienst verwijderen); het abonnement toont CANCELLATION_REQUESTED tot server en adresblokken weg zijn en daarna CANCELLED.
• Een apart besteld IP-blok wordt direct vrijgegeven; het abonnement gaat rechtstreeks naar CANCELLED.
• Een cloudserver of een abonnement zonder actief item gaat als ticket naar support voor handmatige beoordeling. Het abonnement toont CANCELLATION_REQUESTED totdat zij klaar zijn.

Dedicated server verwijderen start voor de enige server van een abonnement dezelfde opzegging; IP-blok verwijderen doet dit voor een apart besteld blok. Een met een server geleverd blok wordt geweigerd met 422 BUNDLED_ITEM_CANCELLATION_BLOCKED: verwijder de server, waarna het blok wordt vrijgegeven.

Een herhaalde aanvraag tijdens de opzegging antwoordt opnieuw met 204. Een weigering is 422; alleen SUBSCRIPTION_CANCELLATION_INCOMPLETE volgt op een gedeeltelijke wijziging:

Facturen

Facturen opvragen accepteert unpaidOnly=true voor openstaande facturen: UNPAID, PARTIAL en OVERDUE. Een factuur-status is een van die drie, PAID, COLLECTIONS, CANCELLED of REFUNDED; type is STANDARD of bij tegoedaankoop CREDIT_PURCHASE. Factuur-pdf downloaden geeft de pdf zelf terug in plaats van JSON.

Factuur betalen accepteert een JSON-body met providerType ACCOUNT_CREDIT of STRIPE; het ook in de enum genoemde MANUAL wordt geweigerd met 400. Het antwoord is 200 met betalings-status (PENDING, SUCCEEDED, FAILED of CANCELLED), de op de factuur geregistreerde transactionId, een clientSecret en declineCode.

• ACCOUNT_CREDIT betaalt uit organisatietegoed en is de methode voor scripts met een sleutel. Het gebruikt het saldo tot het verschuldigde bedrag; bij een te laag saldo blijft de factuur PARTIAL terwijl de betaling SUCCEEDED is.
• STRIPE met de methodId van een opgeslagen kaart belast die kaart.
• STRIPE zonder methodId start een kaartbetaling die via een kaartformulier moet worden afgerond.

Een kaartbetaling die de kaarthouder nodig heeft, met een nieuwe kaart of een opgeslagen kaart die 3-D Secure vraagt, antwoordt met PENDING en clientSecret. Stripe.js rondt deze in een browser af met onze publiceerbare sleutel, die de API niet verstrekt. Factuurbetaling bevestigen registreert daarna het resultaat met providerType STRIPE en de providerTransactionId die Stripe aan de betaling gaf. Kaartbetalingen vinden daarom plaats in de cloudconsole.

Een geweigerde betaling is 422; data bevat dezelfde betalingsweergave:

declineCode is alleen ingesteld bij kaartweigering, bijvoorbeeld INSUFFICIENT_FUNDS of EXPIRED_CARD. Een algemene weigering toont GENERIC_DECLINE, net als een kaart die het netwerk als frauduleus, verloren of gestolen markeert. Een onbekende weigering toont UNKNOWN.

Gebruik in de huidige periode

Huidig gebruik opvragen omvat uurdiensten in de lopende factureringsperiode, met bedragen in centen:

• periodStart en periodEnd begrenzen de periode.
• accruedAmount is wat deze diensten tot nu toe hebben opgebouwd: factureerbare uren tegen uurtarief, min itemkorting, plus verkeer boven de configuratiebundel.
• estimatedAmount schat uren tot periodEnd, alsof actieve diensten tot dan draaien; beëindigde tellen voor hun opgebouwde bedrag. Verkeer telt zoals tot nu toe gemeten.
• activeServiceCount en terminatedServiceCount tellen de diensten achter die bedragen.
• isPartial is true als een deel van het gebruik niet kon worden gelezen; de bedragen laten dat deel dan weg.

Accounttegoed

Tegoedsaldo opvragen geeft creditBalance en het kleinste en grootste aankoopbedrag minPurchaseAmount en maxPurchaseAmount, alle in centen. Tegoed kopen accepteert amount in centen en antwoordt met 201 en een CREDIT_PURCHASE-factuur. Een bedrag buiten de grenzen is 422 VALIDATION_FAILED met detail CREDIT_AMOUNT_INVALID op amount. Deze factuur bevat geen belasting, wordt nooit automatisch afgeschreven en wordt in de cloudconsole per kaart betaald. Het tegoed wordt na betaling toegevoegd.

Het saldo is de som van een grootboek. Tegoedboekingen opvragen pagineert met nieuwste eerst; Tegoedboeking opvragen leest één boeking: amount in centen, type, description, createdAt en bij een betrokken factuur invoiceId. Een betaalde tegoedaankoop voegt een ADDITION toe; aan een factuur besteed tegoed is een negatieve INVOICE_PAYMENT. Overige typen zijn PROMOTION, MANUAL_ADJUSTMENT voor door medewerkers toegevoegd of verwijderd tegoed en REFUND voor teruggegeven tegoed bij terugdraaien van een tegoedbetaling.

Betaalmethoden

Kaarten worden via Stripe in de cloudconsole toegevoegd, zodat het kaartnummer nooit door deze API gaat. Een kaart toevoegen vereist geen body en antwoordt met 201, provider STRIPE en het clientSecret van de Stripe-instelling achter het kaartformulier. Stripe.js rondt dit net als een kaartbetaling in de browser af. Zonder factuuradres van de organisatie antwoordt de eerste kaartinstelling met 422 BILLING_ADDRESS_REQUIRED.

Standaardbetaalmethode instellen antwoordt met 204 en maakt een opgeslagen kaart de betaalkaart voor verlengings- en gebruiksfacturen. Betaalmethode verwijderen antwoordt met 204 en verwijdert een kaart uit de organisatie en Stripe. Geen aanroep geeft opgeslagen kaarten weer: hun ID's staan in het organisatierecord, dat alleen een consolesessie leest. Een sleutel kan dus de ID voor deze twee aanroepen en methodId van Factuur betalen niet vinden.