# Trombone

> Vente et location de trombones. Banc d’essai d’un écosystème de commande automatisée par des agents IA — paiements Stripe en mode test, rien n’est encaissé.

Page lisible (HTML) : https://trombone.guetna.com/agents
API JSON            : https://trombone.guetna.com/api/agent/manifest

## Points d'accès

- Manifeste : https://trombone.guetna.com/api/agent/manifest
- Catalogue : https://trombone.guetna.com/api/agent/catalog
- Disponibilité (exemple) : https://trombone.guetna.com/api/agent/availability?sku=TRB-GIANT&start=2026-10-01&end=2026-10-03
- Devis vente (exemple) : https://trombone.guetna.com/api/agent/quote?sku=TRB-STD-100&quantity=3
- Devis location (exemple) : https://trombone.guetna.com/api/agent/quote?sku=TRB-GIANT&start=2026-10-01&end=2026-10-03
- Déposer une commande : POST https://trombone.guetna.com/api/orders
- Ouvrir le paiement : POST https://trombone.guetna.com/api/stripe/create-checkout
- Suivre une commande : GET https://trombone.guetna.com/api/agent/order/{reference}

## Catalogue

- TRB-STD-100 — Trombones standard — boîte de 100 : achat 2,49 € l’unité ; location 0,50 €/jour (1 à 30 j) ; 500 exemplaire(s). Le classique. Acier galvanisé, 28 mm. Tient 20 feuilles sans faiblir.
- TRB-COL-50 — Trombones couleur — boîte de 50 : achat 3,99 € l’unité ; location 0,80 €/jour (1 à 30 j) ; 120 exemplaire(s). Cinq couleurs. Parfait pour classer, ou pour faire joli.
- TRB-GOLD-1 — Trombone plaqué or 24 carats : achat 49,00 € l’unité ; location 9,00 €/jour (1 à 14 j, caution 50,00 €) ; 7 exemplaire(s). Un seul, dans un écrin. Pour le contrat qui compte.
- TRB-GIANT — Trombone géant (1,80 m) : achat 890,00 € l’unité ; location 35,00 €/jour (1 à 30 j, caution 200,00 €) ; 2 exemplaire(s). Sculpture en acier pour salon, vitrine ou photo de mariage. Livré, repris.
- TRB-DISP — Distributeur de trombones vintage : achat 149,00 € l’unité ; location 12,00 €/jour (1 à 14 j, caution 50,00 €) ; 3 exemplaire(s). Le modèle magnétique des années 60, révisé. Pour vos événements.

## Parcours de commande

1. Lire le catalogue — GET https://trombone.guetna.com/api/agent/catalog — SKU, prix d’achat, prix de location par jour, caution, stock.
2. Vérifier la disponibilité — GET https://trombone.guetna.com/api/agent/availability?sku=…&start=…&end=… (location) ou ?sku=… (vente). Jamais mis en cache.
3. Obtenir un prix ferme — GET https://trombone.guetna.com/api/agent/quote?sku=…&quantity=… ou &start=…&end=…
4. Déposer la commande — POST https://trombone.guetna.com/api/orders avec { sku, quantity | startDate + endDate, customerName, customerEmail, customerPhone?, comments?, source: "agent" }. Réponse 201 : reference, totalCents, amountDueNowCents, statusUrl.
5. Ouvrir le paiement — POST https://trombone.guetna.com/api/stripe/create-checkout avec { reference }. Réponse : url (page Stripe) à présenter à l’humain.
6. Suivre — GET https://trombone.guetna.com/api/agent/order/{reference} jusqu’à status = paid puis confirmed.

## Faits à ne pas deviner

- Chaque produit peut être ACHETÉ ou LOUÉ. C’est la commande qui décide : une quantité → vente (prix à l’unité) ; des dates startDate/endDate → location (prix par jour). Le stock est commun à la vente et à la location. Une unité vendue ne se loue plus ; une unité promise à une location future ne se vend pas. Le champ stock du catalogue = exemplaires vendables aujourd’hui ; une annulation rend les unités automatiquement.
- Une vente se paie à 100 % à la commande. Une location se paie par un acompte de 30 % à la commande, le solde à la remise.
- Les locations comportent une caution (champ securityDepositCents) : une empreinte de garantie, jamais encaissée. Ne pas la confondre avec l'acompte à payer maintenant (champ amountDueNowCents).
- Le prix est toujours recalculé par le serveur à partir du SKU : un montant envoyé par le client n’est jamais pris en compte.
- Une commande déposée est en statut « pending » ; elle passe à « paid » après paiement Stripe, puis « confirmed » quand le marchand la valide. « cancelled » et « refunded » existent aussi.
- La référence de commande (TRV- pour une vente, TRL- pour une location, suivi de 12 caractères) est le seul identifiant à conserver : elle sert à payer et à suivre. Elle ne donne accès à aucune donnée nominative.
- Le paiement lui-même n’est pas automatisable : l’URL Stripe doit être présentée à un humain qui saisit sa carte. En mode test, la carte 4242 4242 4242 4242 fonctionne.
- Aucun paiement en cryptomonnaie ni en stablecoin.
- Ce site est un banc d’essai : les produits sont fictifs, aucune expédition n’a lieu, aucun euro réel n’est débité.

## Codes d'erreur

- unknown_product : SKU inconnu (404).
- invalid_quantity : Quantité hors de 1..100 (400).
- out_of_stock : Stock insuffisant (409).
- invalid_dates : Dates mal formées, passées ou inversées (400).
- invalid_duration : Durée hors des bornes du produit (400).
- dates_unavailable : Plus d’exemplaire sur ces dates (409).
- not_found : Référence inconnue (404).
- not_payable : Commande déjà payée ou annulée (409).
- rate_limited : Plus de 10 requêtes par minute (429).