billing

OVHcloud amount due, by the OVHcloud API

Returns what an OVHcloud account owes, the amount of its debts in the currency of the account, read through the OVHcloud API with an application's keys that may only read. One watch is offered, set on the probe.

Versions

Generic: the OVHcloud API is the same in its three places, Europe (eu.api.ovh.com), Canada (ca.api.ovh.com) and the United States (api.us.ovhcloud.com), version 1.0. The address is that of protocol:ovh:endpoint, where the keys were created.

How it works

GET <protocol:ovh:endpoint>/me/debtAccount, signed by ovh.sign: the debt balance of the account.

{"active": true, "dueAmount": {"currencyCode": "EUR", "text": "12.00 €", "value": 12, …}, "pendingAmount": {…}, "todoAmount": {…}, "unmaturedAmount": {…}}

• due is dueAmount.value, the amount of the debts the account has; currency its currencyCode. A payment being processed is in pendingAmount and stays due until it clears.
• An address of the API not written https://<host>/<version> stops the collector misconfigured before anything leaves.
• A code 401 (keys wrong, expired or revoked, or the poller's clock off) or 403 (the consumer key not allowed the route) stops the collector misconfigured; a code 400 or 404 too; any other code but 200 stops it unreachable.

The keys come from protocol:ovh: the application secret never leaves the poller, only the signature it makes; the consumer key goes in a header, to the API only, in HTTPS. The answer is not secret.

Prerequisites

• An application created on the API of the account's place, and a consumer key whose access rule allows this route and nothing else:

{
  "accessRules": [
    { "method": "GET", "path": "/me/debtAccount" }
  ]
}

The application key goes in protocol:ovh:application-key, its secret in protocol:ovh:application-secret, the consumer key in protocol:ovh:consumer-key, the address of the API in protocol:ovh:endpoint, https://eu.api.ovh.com/1.0. With an IAM policy of OVHcloud instead, the action is account:apiovh:me/debtAccount/get.

• The poller reaches the API in HTTPS, and its clock is right: OVHcloud refuses a signature too far from its own time. The certificates of OVHcloud are issued by public authorities: the profile "Standard" trusts them.

Variables

The collector declares none of its own: it reads protocol:ovh and protocol:ovh:endpoint.

Outputs

Watches

Limits

• The amount is that of the whole account; the bills it comes from are not listed (/me/debtAccount/debt would give them, one call each).
• Not checked against an OVHcloud account: the route, its fields and their meaning are those of the schema the OVHcloud API publishes for itself (/1.0/me.json: debt.Balance, order.Price), which its console shows.