Connecter votre application ou votre ERP à l'API QuoteCrest

Dans la partie 1, nous avons configuré un espace de travail QuoteCrest — Stripe, synchronisation comptable, taux de taxe, conditions et bibliothèque d'articles. Nous allons maintenant connecter cet espace de travail à votre propre application ou ERP, pour que les devis circulent dans vos systèmes existants plutôt que dans un onglet de navigateur.

La REST API de QuoteCrest offre aux équipes du plan Business toute la surface de l'application : devis et lignes, clients, bibliothèque d'articles, taux de taxe, modèles de conditions, paiements, générateur de devis par IA et déclencheurs de synchronisation comptable. La référence complète se trouve sur quotecrest.com/api-docs ; cet article est la visite guidée, de zéro jusqu'au premier appel d'API.

Étape 1 : Enregistrez une application OAuth

Dans QuoteCrest, allez dans Paramètres → Développeurs et cliquez sur Enregistrer une application. Il vous faut trois choses :

Nom — affiché à votre équipe sur l'écran d'autorisation (« ERP Sync », « Acme Field App »).
Redirect URI — l'adresse vers laquelle QuoteCrest renvoie les utilisateurs après autorisation. Doit être en HTTPS (localhost est autorisé pour le développement). Une URI par ligne.
Scopes — read pour l'accès en lecture, write pour créer et mettre à jour. Ne demandez que ce dont vous avez besoin.

Laissez Client confidentiel activé pour les applications côté serveur capables de protéger un secret. À la création, vous obtenez un Client ID et — une seule fois — un Client Secret. Copiez le secret immédiatement ; il est stocké haché et ne peut plus être affiché.

Étape 2 : Autorisez avec OAuth 2.0 + PKCE

QuoteCrest utilise le grant Authorization Code avec PKCE, obligatoire pour tous les clients. Le flux :

1. Générez un code verifier et un challenge. Une chaîne aléatoire, et son hachage SHA-256 encodé en base64url :

code_verifier  = random 43-128 char string
code_challenge = base64url( sha256(code_verifier) )

2. Envoyez l'utilisateur vers l'écran d'autorisation :

GET https://quotecrest.com/oauth/authorize
    ?client_id=YOUR_CLIENT_ID
    &redirect_uri=https://yourapp.com/callback
    &response_type=code
    &scope=read+write
    &code_challenge=CODE_CHALLENGE
    &code_challenge_method=S256

L'utilisateur se connecte, voit ce que votre application pourra faire, et approuve. QuoteCrest redirige vers votre redirect_uri avec un paramètre ?code=.

3. Échangez le code contre des jetons :

curl -X POST https://quotecrest.com/oauth/token \
  -d grant_type=authorization_code \
  -d client_id=YOUR_CLIENT_ID \
  -d client_secret=YOUR_CLIENT_SECRET \
  -d redirect_uri=https://yourapp.com/callback \
  -d code=AUTHORIZATION_CODE \
  -d code_verifier=CODE_VERIFIER

Vous recevez un access_token (valide 2 heures), un refresh_token et les scopes accordés. Les access tokens sont liés à une seule équipe — celle de l'utilisateur qui a autorisé. Les refresh tokens tournent à chaque utilisation : chaque rafraîchissement renvoie une nouvelle paire et l'ancien refresh token est invalidé — persistez donc la paire la plus récente de façon atomique.

Étape 3 : Faites votre premier appel

Chaque requête envoie le jeton dans un en-tête Bearer. Commencez par /me, qui renvoie l'équipe autorisée, ses valeurs par défaut (conditions de paiement, expiration des devis, mode de tarification) et les scopes de votre jeton :

curl https://quotecrest.com/api/v1/me \
  -H "Authorization: Bearer ACCESS_TOKEN"

Les endpoints de liste se paginent avec page et per_page (100 maximum) et renvoient un bloc meta avec les totaux.

Étape 4 : Le flux ERP de base

Une intégration type reproduit ce qu'une personne fait dans l'application — créer le client, construire le devis, l'envoyer, puis surveiller l'acceptation et le paiement.

Créez un client :

curl -X POST https://quotecrest.com/api/v1/clients \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"client": {"name": "Meridian Property Group", "email": "ops@meridian.example"}}'

Créez un devis — les valeurs par défaut de l'équipe (modèle de conditions, expiration, conditions de paiement, mode de tarification) s'appliquent automatiquement à tout ce que vous omettez :

curl -X POST https://quotecrest.com/api/v1/quotes \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"quote": {"title": "Lobby renovation", "client_id": 42, "payment_percentage": 30}}'

Ajoutez les lignes en un seul appel avec bulk_create, puis envoyez :

curl -X POST https://quotecrest.com/api/v1/quotes/7/line_items/bulk_create ...
curl -X POST https://quotecrest.com/api/v1/quotes/7/send \
  -H "Authorization: Bearer ACCESS_TOKEN"

send envoie au client son lien vers le portail par e-mail ; utilisez plutôt publish si votre application transmet le lien elle-même. Le champ portal_url du devis est la page vue par le client, et GET /api/v1/quotes/7/pdf renvoie le PDF généré pour votre propre gestion documentaire.

Suivez l'acceptation et le paiement en interrogeant le devis (status, payment_status, payment_due) ou en listant /api/v1/payments — chaque paiement porte le montant, les frais et le net. Quand un devis est accepté avec la synchronisation automatique activée, la facture arrive dans QuickBooks ou Xero sans appel d'API supplémentaire ; vous pouvez aussi déclencher à tout moment une récupération du catalogue avec POST /api/v1/integrations/quickbooks/sync (ou xero).

Ou sautez entièrement la construction manuelle. Un seul appel au générateur de devis par IA transforme une description du travail en langage courant en un brouillon complet — titre, périmètre des travaux et lignes tarifées qui s'appuient sur votre bibliothèque d'articles et vos catégories :

curl -X POST https://quotecrest.com/api/v1/ai_quotes \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Replace 12 windows in a two-story office, energy-efficient double glazing", "client_id": 42}'

Erreurs, limites et bonne conduite

401 — jeton manquant, expiré ou révoqué. Rafraîchissez et réessayez.
403 plan_required — l'équipe n'est pas sur Business. 403 feature_disabled — un feature flag (par ex. la génération par IA) est désactivé pour l'équipe.
402 insufficient_credits — le solde de crédits IA de l'équipe est épuisé.
422 — erreurs de validation, avec les détails dans le corps de la réponse.
429 — limite de requêtes atteinte. Le trafic général de l'API est limité par IP ; la génération par IA est limitée à 10 requêtes par minute et par équipe. Patientez et réessayez après le délai indiqué.

Deux habitudes garderont votre intégration ennuyeuse (dans le bon sens du terme) : traitez le client secret et les refresh tokens comme des mots de passe — côté serveur uniquement, chiffrés au repos — et construisez votre synchronisation autour de l'idempotence, en vérifiant l'existence d'un enregistrement avant de le créer, car vos utilisateurs peuvent toujours modifier des éléments directement dans QuoteCrest.

La référence complète des endpoints, les schémas et les formats d'erreur sont sur quotecrest.com/api-docs. Si vous construisez quelque chose sur l'API, nous serions sincèrement ravis de le savoir.