Commandes

Le plugin « commandes » permet de gérer des commandes.

Attention Le plugin ne s’occupe pas de la gestion des paniers, ni des paiements, ni des factures. Pour l’aspect « boutique », voir le post-scriptum.

Ce plugin a été élaboré grâce aux contributions de Matthieu Marcillaud, Rastapopoulos, Yffic, touti, Cyril, et du rédacteur de cet article.

Principe

Le plugin agit sur 2 fronts :
→ d’une part il permet aux utilisateurs de gérer les commandes depuis l’espace privé.
→ d’autre part, il fournit les outils permettants et aux développeurs et aux autres plugins de créer et manipuler des commandes.

Installation et dépendances

Le plugin est repertorié dans le dépôt proposé par défaut : « SPIP-Zone - Plugins ». Aussi, il est installable depuis la page Gestion des plugins, onglet Ajouter des plugins si vous avez activé ce dépôt.

2 dépendances seront installées automatiquement :

  • Saisies
  • API prix : permet de calculer les prix HT et TTC des commandes et de leurs détails.

D’autres plugins sont plus ou moins optionnels, là c’est à vous de voir :

  • Notifications avancées : à installer si on veut bénéficier de l’envoi de notifications par email.
  • Facteur : sans lui, les notifications seront au format texte au lieu d’un joli HTML.
  • Coordonnées : fortement recommandé afin de pouvoir gérer les adresses liées aux commandes (livraison et facturation).
  • Contacts et organisations : peut vous servir à gérer les auteurs/clients des commandes.

Fonctionnement

A l’installation, 2 tables sont créées :

  • La table principale spip_commandes sert à enregistrer les données de base des commandes : l’auteur/client, le numéro de référence, le statut et les dates.
  • La table auxiliaire spip_commandes_details sert à enregistrer les « détails » correspondants aux commandes, c’est à dire tous les éléments à partir desquels on va pouvoir calculer le prix total d’une commande : objets et services commandés, frais annexes, ristournes etc.

En théorie, à chaque commande enregistrée dans la table spip_commandes doit correspondre une ou plusieurs lignes de détails dans la table spip_commandes_details.

La table spip_commandes :
Une commande est un objet éditorial, au même titre que les articles, brèves et cie. Elles ont un auteur (le client), différents statuts et 3 types de dates : date de création, date de paiement & date d’envoi.
La date de création correspond au champ « date », elle est définie à la création de la commande, et n’est pas censée être altérée par la suite.
Le changement d’un statut peut déclencher l’envoi de notifications par email, et la mise à jour de la date s’y rapportant :
→ passer le statut à "payée" met à jour la date de paiement.
→ passer le statut à "envoyée" met à jour la date d’envoi.

composition de la table spip_commandes
id_commande Identifiant unique de la commande
reference Numéro de référence (il ne s’agit pas d’une clé unique).
id_auteur Identifiant de l’auteur/client
statut encours, attente, partiel, paye, envoye, retour_partiel, retour, erreur
date Date de création
date_paiement Date de paiement
date_envoi Date d’envoi
maj Date de la dernière mise à jour

La table spip_commandes_details :
Pour le contenu des commandes, on parle de « détails » : chaque commande est constituée d’une ou plusieurs lignes de détails.
Un détail est tout élément qui participe au prix d’une commande.
On peut distinguer 2 types de détails :

  • Les détails correspondants directement aux objets ou aux services commandés.
  • Les détails « annexes » : il peut s’agir des frais de port, des frais de dossier, des ristournes etc.

Une ligne de détail comprend à minima les champs descriptif et prix_unitaire_ht, le cas échéant complétés par les champs taxe et quantite.
Dans le cas où l’objet commandé est un objet éditorial SPIP, des champs objet et id_objet permettent de l’identifier.

composition de la table spip_commandes_details
id_commandes_detail Identifiant unique du détail (attention au « s » à commandes)
id_commande Identifiant de la commande concernée
descriptif Texte décrivant le détail. S’il s’agit d’un objet éditorial, il peut s’agir de son titre, descriptif ou autre.
quantite Quantité
prix_unitaire_ht Prix Hors Taxe
taxe Taxe (TVA)
statut Statut
objet Type d’objet s’il s’agit d’un objet éditorial
id_objet Identifiant de l’objet s’il s’agit d’un objet éditorial
maj Date de la dernière mise à jour

Exemple des enregistrements en base pour une commande et ses détails

Prenons une commande de 2 objets avec TVA à 20%, comportant des frais de port et une ristourne. Dans la base de donnée, ça nous donne ceci :

1 ligne dans la table spip_commandes

id_commande reference id_auteur statut date date_paiement date_envoi maj
1 xxxxxx 1 encours 2014-05-14 09:00:00 0000-00-00 00:00:00 0000-00-00 00:00:00 2014-05-14 09:00:00

4 lignes dans la table spip_commandes_details

id_commandes

_detail

id_commande descriptif quantite prix

_unitaire_ht

taxe statut objet id_objet maj
1 1 Gibolin 2000 2 8 0.2 produit 1 2014-05-14 09:00:00
2 1 Ripolin 5000 1 12 0.2 produit 2 2014-05-14 09:00:00
3 1 Frais de port 0 4 0 2014-05-14 09:00:00
4 1 Ristourne 0 -2 0 2014-05-14 09:00:00

Boucles et balises

Balises #PRIX et #PRIX_HT

Grâce au plugin API prix, les balises #PRIX et #PRIX_HT permettent d’obtenir automagiquement les prix TTC et HT d’une commande ou d’un de ses détails.

Dans une boucle COMMANDES :

  • #PRIX = somme des prix TTC des détails.
  • #PRIX_HT = somme des prix HT des détails.

Dans une boucle COMMANDES_DETAILS :

  • #PRIX = #QUANTITE * (#PRIX_UNITAIRE_HT + (#TAXE * #PRIX_UNITAIRE_HT))
  • #PRIX_HT = #QUANTITE * #PRIX_UNITAIRE_HT.

Boucles

Exemple minimal de boucle affichant pour chaque commande un résumé de ses détails et son prix total TTC :

<BOUCLE_commandes(COMMANDES)>
<h4>Commande N°#ID_COMMANDE</h4>
<ul><BOUCLE_details(COMMANDES_DETAILS){id_commande}>
<li>[(#QUANTITE) *]#DESCRIPTIF = #PRIX</li>
</BOUCLE_details></ul>
Prix total TTC : #PRIX
</BOUCLE_commandes>

Gestion dans l’espace privé

Configuration
La page de configuration est accessible depuis le menu Configuration > Commandes
On peut y gérer les 3 points suivants :

  • La durée d’expiration des commandes ayant le statut « en cours ». On considère que les commandes restant « en cours » pendant plus d’un certain temps sont des commandes abandonnées : il est inutile de les conserver dans la base.
  • l’activation et le fonctionnement des notifications (cf. plus bas).
  • L’affichage en page d’accueil de la liste des commandes « actives » (cf. plus bas).

Liste des commandes
Une page Commandes est accessible depuis le menu Edition.
L’encart à gauche sert à filtrer les commandes en fonction de leurs états, de leurs dates de création, et des auteurs/clients.
Au niveau de la liste, les commandes ayant le statut « envoyé » sont surlignées en vert, afin de repérer facilement les commandes terminées.

Page de gestion des commandes

Fiche d’une commande
La fiche d’une commande est composé de 3 parties :

  • Le contenu de la commande : il s’agit d’un tableau listant les détails de la commande.
  • Les adresses : si le plugin Coordonnées est installé, sont affichées les adresses associées à la commande, ou à défaut celles associées à l’auteur de la commande.
  • L’auteur/client de la commande : si le plugin Contacts et Organisations est installé, on affiche les infos du contact, sinon des infos sur le client.

A noter : Pour les adresses, il n’est pas nécessaire d’activer l’ajout de coordonnées aux commandes dans les options du plugin Coordonnées.

Fiche d’une commande

Commandes « actives »
Il est possible d’afficher en page d’accueil la liste des commandes « actives ». il s’agit des commandes nécessitant une prise en charge. Pour se faire, il faut activer l’option dans la configuration du plugin, et choisir les statuts correspondants.

Commandes « actives » en page d’accueil

Notifications

Mise en place
On peut activer ’envoi d’emails de notification au vendeur et au client lorsque les commandes acquièrent certains statuts.
Le plugin « Notifications avancées » doît être installé. Le plugin Facteur est également fortement recommandé afin d’envoyer les messages au format HTML.
Rendez vous ensuite sur le formulaire de configuration du plugin pour activer et configurer les notifications.

Personnalisation des emails
Par défaut, les messages envoyés sont spartiates :

Email par défaut envoyé au client

Leurs squelettes sont présents dans le répertoire /notifications du plugin.
Pour chaque type de notification (vendeur & client), il y a 3 variantes :

  • commande_xxx_html.html au format HTML.
  • commande_xxx.html au format texte brut.
  • commande_xxx_court.html au format court, type microblog ou SMS.

Par commodité, ces 6 squelettes incluent tous le même squelette mutualisé, avec différents paramètres pour moduler l’affichage : contenu_commande_mail.html.
Il suffit de surcharger ce squelette pour le personnaliser selon vos besoins.

Si vous avez besoin de 2 squelettes vraiment différents pour les emails vendeur et client, vous pouvez au choix :

  • Faire ça au niveau du squelette contenu_commande_mail.html en jouant sur le paramètre #ENV{qui} :
    [(#ENV{qui}|=={client}|oui)<INCLURE{fond=mon_squelette_mail_client, env}>][(#ENV{qui}|=={vendeur}|oui)<INCLURE{fond=mon_squelette_mail_vendeur, env}>]
  • Ou bien surcharger directement les 6 squelettes clients et vendeurs.

Fonctions utiles

Voici une liste non exhaustive de certaines fonctions, celles qui pourront vous être utiles lors de l’intégration du plugin dans votre projet. Pour les détails (paramètres etc.) et la liste complète, voir le site https://code.spip.net/commandes/.

commandes_fonctions.php
commandes_lister_statuts
Cette fonction retourne les différents statuts des commandes. On peut s’en servir comme filtre dans les squelettes pour obtenir la chaîne de langue d’un statut : [(#STATUT|commandes_lister_statut)]
inc/commandes.php
creer_commande_encours
Crée une commande avec le statut « en cours » pour le visiteur actuel. La commande créée est « vide » : la fonction ne se charge pas de créer les détails. C’est le rôle des plugins tiers (Commandes de paniers par ex.).

A noter : on considère qu’il ne peut y avoir qu’une commande « en cours » par session et par auteur. Si une telle commande est déjà présente dans la session, elle va être supprimée de la base et de la session avant la création de la nouvelle.

Exemple :

$creer_commande = charger_fonction('creer_commande_encours', 'inc/');
$id_commande = $creer_commande;
commandes_supprimer
Permet de supprimer « proprement » une ou plusieurs commandes, en s’occupant également des données associées. Pour chaque commande à supprimer, la fonction effectue les actions suivantes :
-  suppression de la commande
-  suppression de ses détails
-  dissociation de ses adresses liées, et éventuellement suppression si elles se retrouvent orphelines.

Exemple :
$ids_commandes = array(1,2,3);
$supprimer_commandes = charger_fonction('commandes_supprimer', 'inc/');
$supprimer_commandes($ids_commandes);
traiter_notifications_commande
Envoie les notifications par email d’une commande, si les conditions sont réunies. Cette fonction est appelée lors de la création d’une commande, puis à chaque changement de statut.
inc/commandes_reference.php
inc_commandes_reference_dist
Cette fonction retourne une référence unique utilisée pour remplir le champ éponyme lors de la création d’une commande. Il s’agit du temps écoulé depuis le 1er janvier 1970, en secondes.
Elle est destinée à être surchargée pour l’adapter à vos besoins.
action/xxx.php
supprimer_commande
Supprime « proprement » une commande. Fait appel à la fonction commandes_effacer, avec les mêmes effets donc.

Exemple :
#URL_ACTION_AUTEUR{supprimer_commande,#ID_COMMANDE,#SELF}
instituer_commande
Change le statut d’une commandes

Exemple :
#URL_ACTION_AUTEUR{instituer_commande,#ID_COMMANDE-envoye,#SELF}

Pour aller plus loin : « Commandes » au sein du framework e-commerce

Ce plugin fait partie d’un framework dédié au e-commerce, il s’interface notamment avec les plugins suivants :

Il n’y a pas encore de documentation qui traite du framework dans son ensemble, on notera cependant les 2 plugins suivants :

  • Tuto commerce » : tutoriel des briques minimales à mettre en place pour une boutique en ligne.
  • Zcommerce : charger les plugins nécessaires à la création d’une boutique en ligne

Pour un aperçu général de tous les outils destinés au e-commerce, voir l’article Inventaire des outils SPIP pour du e-commerce

Discussion

Aucune discussion

Ajouter un commentaire

Avant de faire part d’un problème sur un plugin X, merci de lire ce qui suit :

  • Désactiver tous les plugins que vous ne voulez pas tester afin de vous assurer que le bug vient bien du plugin X. Cela vous évitera d’écrire sur le forum d’une contribution qui n’est finalement pas en cause.
  • Cherchez et notez les numéros de version de tout ce qui est en place au moment du test :
    • version de SPIP, en bas de la partie privée
    • version du plugin testé et des éventuels plugins nécessités
    • version de PHP (exec=info en partie privée)
    • version de MySQL / SQLite
  • Si votre problème concerne la partie publique de votre site, donnez une URL où le bug est visible, pour que les gens puissent voir par eux-mêmes.
  • En cas de page blanche, merci d’activer l’affichage des erreurs, et d’indiquer ensuite l’erreur qui apparaît.

Merci d’avance pour les personnes qui vous aideront !

Par ailleurs, n’oubliez pas que les contributeurs et contributrices ont une vie en dehors de SPIP.

Qui êtes-vous ?
[Se connecter]

Pour afficher votre trombine avec votre message, enregistrez-la d’abord sur gravatar.com (gratuit et indolore) et n’oubliez pas d’indiquer votre adresse e-mail ici.

Ajoutez votre commentaire ici

Ce champ accepte les raccourcis SPIP {{gras}} {italique} -*liste [texte->url] <quote> <code> et le code HTML <q> <del> <ins>. Pour créer des paragraphes, laissez simplement des lignes vides.

Ajouter un document

Suivre les commentaires : RSS 2.0 | Atom