Commander par l'API

Trois appels : lire le catalogue, poser la commande, suivre le provisionnement. Le paiement tient dans la commande ou dans un appel séparé.

GET /catalog/products

Permissions : catalog:read

Les produits privés et les catégories retirées ne sont jamais listés, et ne peuvent pas être commandés.

GET /catalog/products/{shortname}

Permissions : catalog:read

{ "data": {
  "shortname": "vps-1",
  "category": "vps",
  "title": { "fr-fr": "VPS Xeon 1", "en-us": "VPS 1" },
  "providerType": null,
  "recurrences": ["monthly", "yearly"],
  "prices": [
    { "recurrence": "monthly", "priceCents": 500 },
    { "recurrence": "yearly", "priceCents": 5500 }
  ],
  "addons": [
    { "shortname": "extra-ram-1gb",
      "title": { "fr-fr": "+1 Go RAM", "en-us": "+1 Gb RAM" },
      "kind": "RESOURCE_DELTA", "maxQuantity": 10,
      "prices": [ { "recurrence": "monthly", "priceCents": 200 } ] }
  ],
  "characteristics": [
    { "key": "os", "label": { "fr-fr": "Système", "en-us": "OS" },
      "kind": "os-picker", "required": true, "sensitive": false,
      "defaultValue": null,
      "options": ["debian-13"],
      "choices": [ { "value": "debian", "label": { "fr-fr": "Debian" }, "versions": ["13"] } ],
      "companionKeys": ["osVersion"] }
  ]
} }

Une option (addons[])

Une caractéristique (characteristics[])

Deux cas de companionKeys :

• authValue (kind: "auth-credential") demande authType à côté, valant PASSWORD ou SSH_KEY.
• os (kind: "os-picker") demande osVersion si vous envoyez la famille et la version séparément. Le plus simple est d'envoyer la valeur composite d'options (debian-13) et rien d'autre. C'est aussi ce que prend POST /services/{code}/reinstall.

POST /orders

Permissions : orders:write, plus celles du financement choisi. En-tête obligatoire : Idempotency-Key.

Les valeurs de characteristics sont toujours des chaînes, même pour un nombre.

Le bloc payment

Un financement refusé avant toute écriture ne laisse pas de commande derrière lui : moyen introuvable, moyen inactif, solde court, plafond dépassé.

Un total nul, après une remise de 100 %, se règle sans paiement et la commande passe directement à PAID.

Exemple

curl -X POST -H "Authorization: Bearer $FRESHPERF_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: 6f1c0b62-4f4b-4f8e-9b06-0c1d7a5c9e21" \
     -d '{
       "lines": [{
         "product": "vps-1",
         "recurrence": "monthly",
         "quantity": 1,
         "characteristics": {
           "os": "debian-13",
           "location": "paris",
           "authType": "SSH_KEY",
           "authValue": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAI... admin@laptop"
         },
         "addons": [{ "shortname": "extra-ram-1gb", "quantity": 2 }]
       }],
       "customerNote": "Migration du serveur web",
       "payment": { "method": "balance" }
     }' \
     https://api.freshperf.fr/v1/orders

{ "data": {
  "order": {
    "orderNumber": "ORD-20260828-0001",
    "status": "PAID",
    "currency": "EUR",
    "subtotalCents": 900, "taxCents": 180, "discountCents": 0, "totalCents": 1080,
    "amountPaidCents": 1080, "remainingDueCents": 0,
    "promoCode": null, "customerNote": "Migration du serveur web",
    "lines": [ { "productShortname": "vps-1", "recurrence": "monthly", "quantity": 1,
                 "unitPriceCents": 500, "unitTaxCents": 100, "totalCents": 1080,
                 "addons": [ { "shortname": "extra-ram-1gb", "quantity": 2, "unitPriceCents": 200 } ],
                 "configuration": { "os": "debian-13", "location": "paris" } } ],
    "serviceCodes": ["SRV-TKH243-7763"],
    "createdAt": 1787907301139, "paidAt": 1787907315110
  },
  "promoError": null,
  "payment": { "status": "CAPTURED", "paymentId": 244, "amountCents": 1080,
               "invoiceCode": "INV-202608-0084", "balanceCents": 3320 }
} }

Poser une commande par l'API ne touche jamais le panier ouvert dans le tableau de bord.

Refus

POST /orders/{orderNumber}/pay

Permissions : billing.invoices:pay, plus billing.saved_methods:charge avec saved_method. En-tête obligatoire : Idempotency-Key.

Paie ce qui reste dû sur une commande laissée en attente.

curl -X POST -H "Authorization: Bearer $FRESHPERF_KEY" \
     -H "Content-Type: application/json" \
     -H "Idempotency-Key: pay-ORD-20260828-0001" \
     -d '{"method":"saved_method","paymentMethodId":14}' \
     https://api.freshperf.fr/v1/orders/ORD-20260828-0001/pay

Répond le même bloc payment que POST /orders.

Plus les refus de paiement de la table précédente.

GET /orders et GET /orders/{orderNumber}

Permissions : orders:read

La liste rend un résumé (orderNumber, status, currency, totalCents, amountPaidCents, remainingDueCents, createdAt, paidAt) et omet les brouillons. Le détail rend la commande entière, avec lines[] et serviceCodes.

Suivre le provisionnement

1. GET /orders/{orderNumber} : status passe à PAID, puis à FULFILLED une fois chaque service en place.
2. serviceCodes se remplit avec les codes créés. C'est le lien entre une commande et les services qu'elle a produits.
3. GET /services/{code} rend provisioned: false tant que l'infrastructure se met en place, puis true.

Le provisionnement tourne en arrière-plan et prend quelques minutes. Interrogez toutes les 10 à 30 secondes.