Les ventes s’articulent autour de deux objets. Une opportunité est une affaire potentielle qui progresse à travers les étapes du pipeline. Un devis est une proposition chiffrée rattachée à une opportunité, que vous envoyez au client puis acceptez ou refusez.

1. Créer une opportunité

Une opportunité appartient à un client et se situe à une étape : identified, qualified, proposed, negotiation, won ou lost.

POST /opportunities HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "client_id": "0190a1c2-...",
  "name": "Website rebuild",
  "stage": "qualified",
  "probability": 50,
  "estimated_value": "48000.00",
  "expected_close_date": "2026-03-31"
}

Renvoie 201 Created avec une OpportunityResponse. probability est un entier entre 0 et 100.

Visualisez le pipeline sous forme de tableau avec GET /opportunities/board, qui regroupe les opportunités par étape. Faites avancer une affaire en mettant à jour son stage avec PUT /opportunities/{id}. GET /opportunities/{id} renvoie l’opportunité accompagnée de son client, de ses devis et de ses activités.

2. Créer un devis

Un devis chiffre une opportunité au moyen d’une ou plusieurs lignes. Une ligne est soit rate_based (jours x tarif journalier), soit fixed (un montant forfaitaire).

POST /quotes HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "opportunity_id": "0190a1c2-...",
  "valid_until": "2026-02-28",
  "lines": [
    {
      "kind": "rate_based",
      "profile_label": "Senior Developer",
      "days": "20",
      "day_rate": "800.00",
      "discount_percent": "0"
    },
    {
      "kind": "fixed",
      "profile_label": "Discovery workshop",
      "fixed_amount": "3000.00",
      "discount_percent": "0"
    }
  ]
}

Renvoie 201 Created avec un QuoteResponse au statut draft. Un nouveau devis reprend les informations de facturation du client, sauf si vous passez une valeur bill_to de substitution. discount_percent est une chaîne décimale entre 0 et 100.

3. Envoyer, accepter ou refuser

Envoyez le devis au client :

POST /quotes/{id}/send HTTP/1.1
Authorization: Bearer <access_token>

Enregistrez ensuite le résultat :

POST /quotes/{id}/accept HTTP/1.1
Authorization: Bearer <access_token>

POST /quotes/{id}/decline HTTP/1.1
Authorization: Bearer <access_token>
Content-Type: application/json

{ "reason": "Over budget" }

Le status du devis passe de draft -> sent -> accepted ou declined (il peut aussi devenir expired). Agir dans le désordre renvoie 409.

4. Télécharger le PDF

GET /quotes/{id}/pdf HTTP/1.1
Authorization: Bearer <access_token>

Renvoie 200 OK avec Content-Type: application/pdf et un nom de fichier en pièce jointe. C’est le seul point d’entrée qui ne renvoie pas de JSON.

Rentabilité et masquage

GET /quotes/{id} renvoie le devis ainsi qu’un bloc profitability (chiffre d’affaires, coût, pourcentage de marge) et l’opportunité et le client associés. Le coût et la marge sont null pour les appelants avec le rôle consultant ; le chiffre d’affaires est toujours visible (voir Rôles et permissions).

Points d’entrée en un coup d’œil

Une fois un devis accepté, lancez la livraison avec Piloter une mission.