Concepts de l’API de facturation

Cycles de facturation

Un service est facturé selon l’un des cinq cycles. MONTHLY, QUARTERLY, SEMI_ANNUALLY et ANNUALLY sont des périodes de 1, 3, 6 et 12 mois, payées à l’avance : chaque nouvelle période est facturée avant son début et son paiement arrive à échéance à la date nextRenewal de l’abonnement.

Les frais d’usage s’accumulent pendant le mois civil UTC et apparaissent sur une facture le 1er du mois suivant : l’usage d’octobre est facturé le 1er novembre. Cette facture comprend les frais de service HOURLY et les dépassements de trafic applicables ; elle est payable sept jours après son émission. Le tarif de base d’une période prépayée est facturé à l’avance ; ses dépassements de trafic applicables sont facturés après coup.

Chaque offre définit ses tarifs dans pricing.rates, un objet indexé par cycle. Chaque tarif contient trois champs :

Unités monétaires

Chaque montant est un entier dans la devise de son enregistrement, ou de celui qui le contient ; le nom du champ indique l’échelle. Un nom se terminant par Millicents compte les millièmes de centime : 150000 vaut 1,50. Les autres champs monétaires comptent les centimes : 12999 vaut 129,99.

Les millicentimes préservent la fraction de centime d’un tarif horaire, tandis qu’un prix par période est toujours un nombre entier de centimes. Une commande ne porte que son prix. Les taxes, remises et montant dû apparaissent sur sa facture.

La devise est un code ISO 4217 envoyé dans currency pour pricing des offres, les commandes, abonnements et articles, les factures et transactions, le solde de crédit et ses entrées, et le récapitulatif d’usage. Les offres sont tarifées en dollars américains puis converties dans la devise de facturation de l’organisation ; celle-ci ne peut plus changer dès que l’organisation possède une commande, une facture, un abonnement ou une entrée de crédit.

Commander des services

La manière d’acheter un serveur ou un bloc d’IP dépend de son cycle de facturation :

Créer une commande exige cycle et accepte les cinq valeurs. Les deux appels à article unique sont des raccourcis pour une commande horaire d’un article : ses champs figurent au premier niveau du corps, sans type ni cycle ; ils passent la même commande et exécutent les mêmes vérifications. Tous trois acceptent une Idempotency-Key (Idempotence).

La facturation horaire exige un droit de facturation à l’usage absent des nouvelles organisations. Il est actuellement accordé sur demande au support dans la console cloud. Obtenir les droits l’indique dans billing.isUsageBased ; une commande horaire ou un raccourci sans ce droit répond 422 USAGE_BILLING_DISABLED.

Articles de commande

items contient une entrée par serveur ou bloc d’IP, car un article n’a pas de champ quantité. Chaque entrée indique sa nature dans type, exactement BAREMETAL ou IP_BLOCK avec cette casse ; toute autre valeur ou l’absence de type est refusée avec 400 VALIDATION_ERROR. Chaque article nomme une offre et un datacenter :

• plan est l’id de l’offre. Une offre bare metal accepte aussi son slug, immuable ; une offre de bloc d’IP ne l’accepte pas.
• datacenter est l’id ou le code du datacenter, comme ams1.

Lister les offres bare metal et Lister les offres de blocs d’IP renvoient l’id de chaque offre, le slug pour le bare metal et une entrée availability par datacenter avec son id, son code et la quantity en stock.

Un article BAREMETAL accepte aussi les adresses et paramètres de démarrage du nouveau serveur :

Avec bootMode à PXE et un script, le serveur démarre une fois sur ce script après provisionnement (Scripts iPXE personnalisés). Le système d’exploitation ne fait pas partie de la commande : il est choisi lors du déploiement.

Le /30 et le /120 sont inclus dans le prix. Un bloc IPv4 plus grand, de longueur 24 à 29, ajoute une ligne IPv4 /<length> aux lines de l’article et à la facture, tarifée comme la différence entre l’offre de bloc d’IP IPv4 de cette longueur et celle en /30.

IPv6 commandé avec IPv4 est omis si le datacenter n’a pas d’espace IPv6 ; le serveur démarre sans. Commandé seul, il fait échouer l’article. Un serveur dont les deux longueurs valent null n’a ni réseau ni adresse et ne peut être déployé avant le rattachement d’un de vos réseaux et l’attribution d’une IPv4 principale (Réseau). Sinon, ses préfixes sont sur un réseau d’accès Internet créé pour lui et facturés sur son abonnement ; un article BAREMETAL n’a donc pas de champ réseau.

Un article IP_BLOCK accepte networkId, le réseau auquel ajouter le bloc. Un réseau inexistant ou appartenant à une autre organisation donne 404 ENTITY_NOT_FOUND. Lister les réseaux virtuels du service donne les réseaux et ID d’un serveur ; un bloc pour le réseau d’un nouveau serveur se commande donc après sa création.

promoCode est facultatif. Sa remise s’applique à la première facture d’une commande par période ; les renouvellements et commandes horaires n’en bénéficient pas. Un code vide équivaut à son absence.

La commande est vérifiée à sa création ; un refus donne 422. OFFERING_NOT_AVAILABLE est le code principal. Les autres refus sont des détails sous VALIDATION_FAILED sur le champ nommé, sans préfixe items[<i>]. pour les raccourcis :

Payer une commande par période

La réponse contient data.order, dont le status vaut UNPAID, et data.invoiceId. La facture est payable le jour de son émission. Elle facture chaque serveur au priceMillicents de son offre pour le cycle, tout préfixe IPv4 payant sur une ligne distincte, les taxes selon l’adresse de facturation et la remise promotionnelle. Sans adresse de facturation, l’organisation reçoit 422 BILLING_ADDRESS_REQUIRED après enregistrement de la commande ; définissez l’adresse dans la console, puis renvoyez la même requête avec la même Idempotency-Key pour émettre la facture de cette commande.

Rien ne paie cette facture à votre place. Les factures de renouvellement et d’usage sont prélevées à l’échéance, d’abord sur le crédit puis sur la carte par défaut, mais la première facture d’une commande attend un paiement couvrant son montant. Depuis un script, Payer une facture avec providerType à ACCOUNT_CREDIT utilise le crédit de l’organisation, comme dans le démarrage rapide.

Une commande impayée est annulée dans les 24 heures. Elle ne réserve aucun serveur : le stock est vérifié à la commande puis à nouveau au provisionnement après paiement.

Une fois la facture à PAID, le provisionnement s’exécute en arrière-plan. Chaque article reçoit son propre abonnement au cycle de la commande ; Obtenir une commande indique le résultat : l’article passe de PENDING à COMPLETED, son provisionedId contient l’ID du serveur (du bloc pour IP_BLOCK) et la commande passe de UNPAID à COMPLETE. Lister les factures indique l’orderId de chaque facture de commande.

Un article impossible à provisionner affiche FAILED, par exemple si l’offre du serveur est épuisée entre commande et paiement. La commande affiche FAILED une fois le provisionnement terminé avec au moins un échec, même si les autres articles sont terminés. Elle n’indique pas la cause, aucune nouvelle tentative automatique n’a lieu, une facture payée reste payée et aucun remboursement n’est automatique ; contactez le support avec l’id de commande.

Requêtes horaires

L’id renvoyé par un raccourci est celui du nouveau serveur ou bloc. Créer une commande en HOURLY renvoie invoiceId à null, les subscriptions ouvertes et provisionedItems : une entrée par article avec orderItemId, provisionedId et isProvisioned, plus errorMessage si isProvisioned vaut false.

Si rien n’a pu être provisionné, la requête répond 409 PROVISIONING_FAILED et la commande reste avec status à FAILED. Une commande à plusieurs articles peut réussir partiellement ; la réponse est alors 201 et ses provisionedItems indiquent les réussites. Renvoyer la requête avec la même Idempotency-Key ne crée pas de seconde commande : la réponse est 200, avec isReplayed à true sur Créer une commande ; elle renvoie les ressources initialement provisionnées et réessaie les articles en échec.

Abonnements

Chaque service facturé appartient à un abonnement qui conserve cycle, status, lastRenewal, nextRenewal, terminatedAt une fois terminé et les items facturés, y compris terminés. L’abonnement d’un serveur contient le serveur et un article IP_BLOCK par famille d’adresses commandée. Le provisionedId d’un article est l’ID de la ressource facturée ; subtotalMillicents est son prix par cycle, ou par heure en HOURLY. Ses details contiennent includedEgressGb pour un serveur (null pour illimité), ou ipVersion et prefixLength pour un bloc.

Obtenir l’abonnement du service et Obtenir l’abonnement du bloc d’IP renvoient l’abonnement qui facture le serveur ou bloc. Son status vaut ACTIVE, CANCELLATION_REQUESTED ou CANCELLED.

Résilier un abonnement répond 204. Dès lors, aucune facture de renouvellement n’est émise et un abonnement horaire cesse d’accumuler de l’usage. La suite dépend de ce qu’il facture :

• Un serveur bare metal est supprimé. Il affiche state à DELETING pendant son arrêt et son retrait (Supprimer un service) ; l’abonnement reste à CANCELLATION_REQUESTED jusqu’au retrait du serveur et de ses blocs, puis passe à CANCELLED.
• Un bloc d’IP commandé seul est libéré immédiatement ; son abonnement passe directement à CANCELLED.
• Un serveur cloud ou un abonnement sans article actif est transmis au support sous forme de ticket pour examen manuel. L’abonnement reste à CANCELLATION_REQUESTED jusqu’à sa clôture par le personnel.

Supprimer un service bare metal sur l’unique serveur d’un abonnement lance la même résiliation ; Supprimer un bloc d’IP fait de même pour un bloc commandé seul. Un bloc inclus avec un serveur est refusé avec 422 BUNDLED_ITEM_CANCELLATION_BLOCKED : supprimez le serveur, puis le bloc sera libéré.

Une nouvelle demande pendant la résiliation répond encore 204. Un refus donne 422 ; seul SUBSCRIPTION_CANCELLATION_INCOMPLETE survient après une modification partielle :

Factures

Lister les factures accepte unpaidOnly=true pour les factures ouvertes : UNPAID, PARTIAL, OVERDUE. Le status d’une facture est l’une de ces trois valeurs, PAID, COLLECTIONS, CANCELLED ou REFUNDED ; son type est STANDARD ou, pour un achat de crédit, CREDIT_PURCHASE. Télécharger le PDF d’une facture renvoie le PDF lui-même, pas du JSON.

Payer une facture accepte un corps JSON dont providerType vaut ACCOUNT_CREDIT ou STRIPE ; MANUAL, aussi présent dans l’énumération, est refusé avec 400. La réponse 200 contient le status du paiement (PENDING, SUCCEEDED, FAILED, CANCELLED), le transactionId enregistré sur la facture, un clientSecret et un declineCode.

• ACCOUNT_CREDIT paie avec le crédit de l’organisation, méthode utilisée par un script muni d’une clé. Il prend le solde disponible jusqu’au montant dû ; un solde inférieur laisse la facture à PARTIAL et le paiement à SUCCEEDED.
• STRIPE avec le methodId d’une carte enregistrée débite cette carte.
• STRIPE sans methodId lance un paiement par carte à terminer dans un formulaire.

Un paiement nécessitant le titulaire, avec une nouvelle carte ou une carte enregistrée demandant 3-D Secure, répond PENDING avec un clientSecret. Stripe.js le termine dans un navigateur avec notre clé publiable, non fournie par l’API ; Confirmer le paiement d’une facture enregistre ensuite le résultat avec providerType à STRIPE et le providerTransactionId fourni par Stripe. Les paiements par carte se font donc dans la console cloud.

Un paiement refusé donne 422 avec la même vue du paiement dans data :

declineCode n’est renseigné que pour un refus de carte, par exemple INSUFFICIENT_FUNDS ou EXPIRED_CARD. Un refus générique vaut GENERIC_DECLINE, tout comme une carte signalée frauduleuse, perdue ou volée par le réseau ; un refus non reconnu vaut UNKNOWN.

Usage de la période actuelle

Obtenir l’usage actuel couvre les services horaires pendant la période de facturation en cours, avec les montants en centimes :

• periodStart et periodEnd délimitent la période.
• accruedAmount est le montant accumulé : heures facturables de chaque service au tarif horaire, moins les remises d’article, plus les dépassements du quota de trafic.
• estimatedAmount projette les heures jusqu’à periodEnd, comme si les services actifs continuaient jusque-là ; les services terminés gardent leur montant accumulé. Le trafic est celui mesuré à ce jour.
• activeServiceCount et terminatedServiceCount comptent les services correspondant à ces montants.
• isPartial vaut true si une partie de l’usage n’a pas pu être lue ; les montants l’excluent alors.

Crédit du compte

Obtenir le solde de crédit renvoie creditBalance et les montants minimal et maximal d’un achat, minPurchaseAmount et maxPurchaseAmount, tous en centimes. Acheter du crédit accepte amount en centimes et répond 201 avec une facture CREDIT_PURCHASE ; un montant hors limites donne 422 VALIDATION_FAILED et un détail CREDIT_AMOUNT_INVALID sur amount. Cette facture n’a pas de taxe, n’est jamais prélevée automatiquement et se paie par carte dans la console. Le crédit est ajouté après paiement.

Le solde est la somme d’un registre. Lister les entrées de crédit le pagine du plus récent au plus ancien ; Obtenir une entrée de crédit lit une entrée : amount en centimes, type, description, createdAt et, si une facture est concernée, invoiceId. Un achat de crédit payé ajoute une ADDITION ; le crédit dépensé sur une facture est un INVOICE_PAYMENT négatif. Les autres types sont PROMOTION, MANUAL_ADJUSTMENT pour le crédit ajouté ou retiré par notre personnel et REFUND pour le crédit restitué lors de l’annulation d’un paiement par crédit.

Moyens de paiement

Les cartes sont ajoutées dans la console cloud via Stripe ; leur numéro ne transite jamais par cette API. Ajouter une carte n’accepte aucun corps et répond 201 avec provider à STRIPE et le clientSecret de la configuration Stripe derrière le formulaire de carte, que Stripe.js termine dans un navigateur comme un paiement. Sans adresse de facturation, la première configuration répond 422 BILLING_ADDRESS_REQUIRED.

Définir le moyen de paiement par défaut répond 204 et désigne une carte enregistrée pour les prélèvements de renouvellement et d’usage. Supprimer un moyen de paiement répond 204 et retire une carte de l’organisation et de Stripe. Aucun appel ne liste les cartes enregistrées : leurs ID figurent sur l’enregistrement d’organisation, lisible uniquement par une session console. Une clé ne peut donc pas trouver l’ID utilisé par ces deux appels et par le methodId de Payer une facture.