Connexion à la boutique : l’interface en bref

Qui peut l’utiliser ?

Il n’existe pas de modules prêts à l’emploi pour des systèmes de boutique en particulier. Convient toute boutique ou tout service capable d’envoyer, pour chaque commande, un appel HTTP POST avec du JSON (webhook, service d’automatisation ou code personnel). La connexion à la boutique fait partie des formules Standard et Professional (abonnement actif ou mois d’essai).

Mise en place

Dans votre compte, sous « Mon entreprise » → « Connexion à la boutique », vous générez la clé API. Elle n’est affichée qu’une seule fois ; l’adresse exacte (URL) pour votre boutique y figure aussi. Vous pouvez remplacer ou révoquer la clé à tout moment.

Requête

Méthode et adresse : POST vers le chemin /api/shop/orders (URL complète dans votre compte)

En-têtes

Exemple de corps

{
  "order_id": "10045",
  "buyer": {
    "name": "Anna Muster",
    "email": "anna@example.ch",
    "street": "Bahnhofstrasse",
    "house_number": "12",
    "postal_code": "8001",
    "city": "Zürich",
    "country": "CH"
  },
  "items": [
    { "name": "Kaffeebohnen 500 g", "quantity": 2, "unit_price": 5.00, "vat_rate": 2.6 }
  ],
  "currency": "CHF",
  "prices_include_vat": true
}

Sont obligatoires : order_id, buyer (name ou company) et au moins une entrée dans items (name, quantity, unit_price). Devise : CHF uniquement. prices_include_vat : true (par défaut) signifie que les prix incluent la TVA ; vat_rate par article est facultatif (valeurs admises : 0, 2.6, 3.8, 8.1), sinon le taux par défaut du profil d’entreprise s’applique. Sans numéro de TVA dans le profil d’entreprise, aucune TVA n’est indiquée. 200 articles au maximum.

Réponse

Pour une nouvelle commande, l’interface répond 201 avec les champs ok: true, duplicate: false, order_id, invoice_id, invoice_number, invoice_number_pending, total, currency (CHF) et delivery (prepared ou sent) ; pour une facture seulement préparée parce que l’envoi automatique, bien qu’activé, n’a pas été possible, s’ajoute delivery_note avec le motif. Si votre entreprise utilise sa propre série de numéros, une facture seulement préparée n’a pas encore de numéro : invoice_number vaut alors null, invoice_number_pending vaut true et invoice_draft_id contient un identifiant provisoire de brouillon, à ne pas afficher comme numéro de facture. Si vous renvoyez le même order_id, elle répond 200 avec duplicate: true et ne crée pas de seconde facture. Au maximum 30 requêtes par minute sont admises par clé (60 par adresse IP) ; le corps ne doit pas dépasser 200 000 octets.

Codes d’erreur

Que devient la commande ?

OfficePilot crée une facture avec section de paiement QR. Si « Envoyer la facture automatiquement » est désactivé (par défaut), la facture est seulement préparée : vous recevez un e-mail, vérifiez la facture et l’envoyez vous-même. Si le réglage est activé, elle part immédiatement par e-mail à l’acheteuse ou à l’acheteur, sauf si son adresse e-mail manque, si les indications de facturation du profil d’entreprise sont incomplètes ou si l’envoi échoue : elle est alors seulement préparée et vous en êtes informé. N’activez l’envoi automatique qu’après avoir vérifié votre liste de prix et vos textes.