BCard - Documentation technique

Après contrôle de propriété (avec dérogation ROLE_ADMIN), l'annulation n'est autorisée que si le statut courant est Order::EN_ATTENTE : tout autre statut est refusé. Le motif est repris du corps JSON s'il est fourni, sinon il vaut « Annulation demandée par le client ». Le statut passe à Order::ANNULER, le motif et l'horodatage d'annulation sont enregistrés. Aucun remboursement n'est déclenché par cette action.

Route : /api/orders/{id}/cancel (POST), nom api_orders_cancel. Requiert IS_AUTHENTICATED_FULLY.

Corps attendu (optionnel) : {"reason": "string — motif d'annulation"}

Réponses : 200 commande annulée, 400 commande dont le statut n'est pas « en attente », 403 commande appartenant à un autre utilisateur (hors administrateur), 404 commande inexistante, 401 requête non authentifiée.

Contrôle d'abord la présence non vide des champs firstname, lastname, email, phone et items (le message d'erreur produit contient une accolade parasite), puis vérifie que items est bien un tableau non vide. Chaque article doit porter card_id et quantity ; la carte est chargée au catalogue et rejetée si elle est inexistante ou masquée. La quantité est ramenée à 1 au minimum. Le total est calculé à partir du seul prix de la carte : les options de couleur et d'impression ne sont ni lues ni facturées à la création, alors qu'elles sont prises en compte à la lecture. La commande est validée avant persistance, les lignes étant écrites en cascade avec elle.

Route : /api/orders (POST), nom api_orders_create. Requiert IS_AUTHENTICATED_FULLY.

Corps attendu : {"firstname": "string — obligatoire", "lastname": "string — obligatoire", "email": "string — obligatoire", "phone": "string — obligatoire", "items": "list<{card_id: int, quantity: int}> — obligatoire, au moins un élément", "compagny_name": "string — optionnel", "address_to_delivery": "string — optionnel", "order_notes": "string — optionnel"}

Réponses : 201 commande créée ({message, order_id, total}), 400 champ obligatoire manquant ou vide, 400 items absent ou non tableau, 400 card_id ou quantity manquant sur un article, 400 carte inexistante ou masquée, 400 violations de contraintes ({"errors": [...]}), 401 requête non authentifiée.

Les résultats sont restreints à l'utilisateur courant et triés par created_at décroissant. page est ramené à 1 au minimum et limit est borné à l'intervalle [1, 50] (défaut 10) ; le filtre status n'est appliqué que s'il est fourni et non vide, sans validation de la valeur. Chaque ligne de commande est recalculée à l'affichage via OrderApiController::priceToFloat() et OrderApiController::formatPrice() : le prix unitaire additionne le prix de la carte et ceux des options de couleur et d'impression, le total de ligne multipliant ce résultat par la quantité. Les champs address_to_delivery et order_notes sont renvoyés bien qu'absents du schéma OpenApi déclaré, et le champ price documenté au niveau des lignes n'est pas présent ici.

Route : /api/orders (GET), nom api_orders_list. Requiert IS_AUTHENTICATED_FULLY.

Paramètres de requête : status (optionnel), page (optionnel, défaut 1), limit (optionnel, défaut 10, plafonné à 50).

Réponses : 200 liste renvoyée (éventuellement vide), 401 requête non authentifiée.

La commande est chargée par sa clé primaire, puis un contrôle de propriété est appliqué : seul le titulaire, ou un porteur de ROLE_ADMIN, peut la consulter. Par rapport à OrderApiController::list(), la charge utile ajoute le type de produit sur chaque carte, un champ price correspondant au prix unitaire formaté, ainsi que les informations d'annulation (cancellationReason, cancelledAt) et de livraison (tracking_number, shipping_carrier, shipped_at, delivered_at).

Attention : cette route est déclarée avec un {id} sans exigence numérique.

Route : /api/orders/{id} (GET), nom api_orders_show. Requiert IS_AUTHENTICATED_FULLY.

Réponses : 200 commande renvoyée, 403 commande appartenant à un autre utilisateur (hors administrateur), 404 commande inexistante, 401 requête non authentifiée.