Accès API et agents IA

SimplyQuote expose une API REST permettant à vos agents IA, scripts et intégrations de travailler avec vos devis et factures en votre nom. L'accès est contrôlé par des jetons d'accès personnels à portée limitée et révocables.

1. Activer l'accès API

1. Ouvrez votre page de paramètres et connectez-vous
2. Faites défiler jusqu'à la section « Accès API et agents IA ».
3. Nommez votre jeton, choisissez les portées et cliquez sur « Créer un jeton ».
4. Copiez le jeton immédiatement : pour des raisons de sécurité, il n'est affiché qu'une seule fois.

2. Effectuer une requête

Envoyez le jeton en tant que Bearer token dans l'en-tête Authorization :

curl https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here"

3. Créer et mettre à jour des documents

La création et la mise à jour de devis et de factures utilisent le même jeton avec une portée en écriture. Les totaux sont toujours calculés côté serveur à partir des articles envoyés :

curl -X POST https://simplyquote.net/api/v1/quotes \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Acme Ltd",
    "client_email": "billing@acme.example",
    "items": [
      { "description": "Consulting", "quantity": 4, "unit_price": 120 },
      { "description": "Hosting (1 month)", "quantity": 1, "unit_price": 30 }
    ],
    "currency": "USD",
    "tax_rate": 10,
    "expiry_date": "2026-10-01"
  }'

Réponse en cas de succès (idem pour les listes, avec quotes/invoices plus total/page/limit/has_more) :

// Wrapped envelope (POST/PATCH/lists): { success:true, data:{ quote } }
{
  "success": true,
  "data": {
    "quote": { "id": "uuid", "quote_number": "Q-1001", "total": 528.0 }
  }
}

curl -X PATCH https://simplyquote.net/api/v1/invoices/{id} \
  -H "Authorization: Bearer sq_your_token_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "paid" }'

Listes et pagination

Les points de terminaison de liste acceptent updated_since (ISO 8601), page (défaut 1), limit (défaut 20, max 100) et status (insensible à la casse ; les valeurs inconnues sont ignorées). Les réponses incluent total, page, limit et has_more.

GET /api/v1/quotes?status=sent&page=1&limit=20&updated_since=2026-01-01T00:00:00Z

Règles des champs (création et mise à jour)

items est requis en POST : tableau non vide, chaque ligne avec une description non vide, quantity > 0 (défaut 1), unit_price >= 0 (défaut 0). tax_rate est un pourcentage (0–100) ; à la création, tax_rate > 0 implique tax_enabled. currency est stockée en majuscules. issue_date accepte toute date valide (stockée AAAA-MM-JJ). Les devis utilisent expiry_date, les factures due_date (les deux alias sont acceptés, null efface). Statut : devis draft|sent, factures draft|sent|viewed|paid|cancelled — paid horodate paid_at. Les totaux sont toujours recalculés côté serveur.

4. Utiliser avec un agent IA

Donnez à votre agent l'URL de base, votre jeton et la liste des points de terminaison ci-dessous. Exemple d'instructions pour tout agent utilisant des outils (Claude, GPT, LangChain, etc.) :

Tu peux accéder à mon compte SimplyQuote.
URL de base : https://simplyquote.net
Pour chaque requête, envoie l'en-tête : Authorization: Bearer sq_votre_jeton_ici
Points de terminaison disponibles : GET/POST /api/v1/quotes, GET/PATCH /api/v1/quotes/{id},
GET/POST /api/v1/invoices, GET/PATCH /api/v1/invoices/{id}, POST /api/mcp
Les listes acceptent ?page, ?limit (max 100), ?status, ?updated_since et renvoient { success:true, data:{ quotes|invoices, total, page, limit, has_more } }.
Les lectures unitaires renvoient l'objet brut. {id} est l'UUID, pas le numéro de document.
Utilise POST pour créer des documents : envoie toujours items avec description, quantity et unit_price.

5. Connexion via MCP (recommandé pour les agents)

SimplyQuote intègre un serveur MCP (Model Context Protocol) à l'adresse /api/mcp (HTTP streaming sans état, JSON-RPC 2.0). Les agents prenant en charge les serveurs MCP distants (Claude, ChatGPT, Cursor, VS Code, etc.) peuvent s'y connecter directement avec votre jeton, sans configuration de prompts. Outils disponibles :

list_quotesget_quotecreate_quotelist_invoicesget_invoicecreate_invoice

{
  "mcpServers": {
    "simplyquote": {
      "type": "http",
      "url": "https://simplyquote.net/api/mcp",
      "headers": {
        "Authorization": "Bearer sq_your_token_here"
      }
    }
  }
}

Exemple d'appel d'outil (JSON-RPC 2.0 — lots rejetés, notifications → 202, GET → 405) :

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": { "name": "list_quotes", "arguments": { "limit": 5 } }
}

Chaque appel d'outil est contrôlé par les portées de votre jeton : un jeton en lecture seule peut lister et consulter, tandis que la création de devis ou de factures nécessite la portée en écriture correspondante.

Points de terminaison

Portées

• quotes:read — Lire vos devis
• invoices:read — Lire vos factures
• clients:read — Réservé — pas encore de point de terminaison clients dédié (les infos client figurent sur devis/factures)
• quotes:write — Créer et mettre à jour des devis
• invoices:write — Créer et mettre à jour des factures
• clients:write — Réservé — pas encore de point de terminaison clients dédié (les infos client sont créées/mises à jour implicitement lors de l’enregistrement des devis/factures)

Format de réponse et erreurs

Les points de terminaison REST utilisent deux formats — vérifiez celui qui s'applique :

{
  "success": true,
  "data": { ... },
  "error": { "code": "...", "message": "...", "details": { ... } }
}

Les lectures unitaires renvoient l'objet brut ci-dessus (sans enveloppe), avec des erreurs plates { error, message } — p. ex. 404 si l'id est inconnu. Les listes et POST/PATCH utilisent toujours l'enveloppe.

// Flat envelope (single GET): bare object, no success/data wrapper
{
  "id": "uuid",
  "quote_number": "Q-1001",
  "status": "sent",
  "total": 528.0
}

// unknown id:
{ "error": "not_found", "message": "Quote not found" }

• success — true en cas de succès, false en cas d'échec
• data — les données en cas de succès
• error — code d'erreur, message et détails facultatifs en cas d'échec

Les codes d'erreur les plus courants :

• UNAUTHORIZED — Jeton manquant, invalide ou expiré (HTTP 401)
• FORBIDDEN — Le jeton ne dispose pas de la portée requise (HTTP 403)
• VALIDATION_ERROR — Le corps de la requête a échoué à la validation (HTTP 400)
• NOT_FOUND — Le document demandé n'existe pas (HTTP 404)
• DATABASE_ERROR — Erreur de stockage lors du traitement de la requête (HTTP 500)
• RATE_LIMIT — Trop de requêtes — réessayez plus tard (HTTP 429)

Webhooks, OAuth et référence complète

Webhooks : gérez les abonnements via GET/POST/PATCH/DELETE /api/v1/webhooks (tout jeton valide, aucune portée spécifique). L'url doit être un point de terminaison HTTPS public. Le secret n'est renvoyé qu'à la création — vérifiez les livraisons via l'en-tête X-SimplyQuote-Signature (HMAC-SHA256).

Les applications partenaires utilisent OAuth 2.0 (/api/oauth/authorize, /api/oauth/token, /api/oauth/revoke) au lieu des jetons personnels. Détails dans docs/API.md et dans la spécification lisible par machine à /api/v1/openapi.json.

Notes de sécurité

• Les jetons sont stockés hachés : SimplyQuote ne conserve jamais le jeton en clair.
• N'accordez que les portées dont votre agent a besoin ; les portées en lecture seule suffisent généralement.
• Révoquez un jeton à tout moment depuis les Paramètres pour couper immédiatement l'accès.
• Une spécification lisible par machine pour les agents est disponible à l'adresse /api/v1/openapi.json