# Commerce 360 Developers

> Guide public et autonome destiné aux assistants IA et aux développeurs qui intègrent l’API externe Commerce 360 V1.

Commerce 360 est une plateforme de gestion commerciale. Son API externe permet à une application partenaire autorisée de consulter le catalogue, les clients, les ventes, le service après-vente et les cartes cadeaux. Les écritures actuellement disponibles sont celles listées dans le contrat OpenAPI. Aucune connaissance préalable de l’organisation qui édite Commerce 360 n’est nécessaire pour utiliser cette documentation.

Contrat courant : OpenAPI 3.0.3, version 1.0.0, 30 opérations exposées par le contrat : 28 routes métier, POST /auth et GET /v1/ping. Seul POST /auth s’appelle sans JWT ; GET /v1/ping exige un JWT mais aucun scope métier.

## Ressources canoniques

- Portail développeurs : https://developers.hbjo-online.com
- Contrat OpenAPI exécutable : https://developers.hbjo-online.com/openapi.json
- État opérationnel de l’API : https://api.hbjo-online.com/health
- Ce fichier : https://developers.hbjo-online.com/llms.txt
- Démarrage : https://developers.hbjo-online.com/docs/getting-started
- Authentification : https://developers.hbjo-online.com/docs/authentication
- Erreurs et reprises : https://developers.hbjo-online.com/docs/errors-and-retries
- Synchronisation catalogue : https://developers.hbjo-online.com/guides/catalog-sync
- Gestion des clients : https://developers.hbjo-online.com/guides/customer-management
- Référence lisible : https://developers.hbjo-online.com/api-reference
- Collection Postman : https://developers.hbjo-online.com/postman/commerce-360-v1.postman_collection.json
- Environnement Postman sans identifiants préremplis : https://developers.hbjo-online.com/postman/commerce-360-production.postman_environment.json
- Support technique : support@hbjo-online.com

Les domaines developers.hbjo-online.com et api.hbjo-online.com sont respectivement les hôtes officiels du portail public et de l’API Commerce 360.

GET /health est un point de contrôle opérationnel public : il indique uniquement si le service répond. Il ne retourne aucune donnée métier et ne fait pas partie du contrat OpenAPI V1. Toutes les autres routes utilisées par une intégration doivent être présentes dans openapi.json.

Pour les méthodes, chemins, paramètres, corps, formats et schémas de réponse, `openapi.json` est la source technique prioritaire. Les guides publics du portail décrivent l’ordre recommandé des appels et les règles métier. Ce fichier les résume pour une IA, mais ne remplace pas le contrat OpenAPI. Ne jamais inventer une route, un champ ou une valeur absente de l’OpenAPI. En cas d’écart, signaler l’écart et suivre l’OpenAPI courant.

## Disponibilité en production

Le contrat de production actuel n’expose aucune opération `POST /v1/*`. `POST /auth` reste disponible pour obtenir un JWT. Les opérations GET et PUT présentes dans `openapi.json` restent utilisables selon les scopes du compte d’intégration. Une route absente du contrat ne doit pas être appelée, même si elle apparaît dans un ancien exemple ou un ancien client généré.

## Vocabulaire public

- Compte d’intégration : compte API fourni à un partenaire pour les appels de serveur à serveur. Ses permissions sont appelées scopes. Un scope est attaché au compte ; ce n’est ni un paramètre de requête ni un en-tête à ajouter.
- Organisation autorisée : entreprise Commerce 360 dont les données sont accessibles au compte d’intégration. Elle est déterminée automatiquement après authentification.
- Boutique ou `shop` : point de vente rattaché à l’organisation autorisée, identifié notamment par `shopId`.
- Produit ou `product` : référence commerciale commune. Article ou `product-item` : variante physique réellement vendable, avec son propre identifiant, prix et stock.
- Client ou `customer` : fiche client Commerce 360. Vente ou `sale` : vente finalisée. `order` : commande client. `reservation` : réservation de stock. `deposit` : acompte encaissé.
- SAV : service après-vente. Un dossier SAV suit une demande de réparation ou d’intervention après une vente.
- Carte cadeau ou `gift card` : crédit prépayé dont le numéro est masqué dans les réponses de l’API.
- PII, dans les scopes `customers:pii:read` et `customers:pii:write` : données personnelles permettant d’identifier ou de contacter un client.
- Identifiant public : identifiant stable retourné par l’API et utilisable par une intégration externe. Selon la ressource, il se trouve dans un champ comme `id` ou `uuid`. Toujours reprendre la valeur exacte fournie par l’API ; ne jamais essayer de déduire un identifiant de base de données.

## Consignes impératives pour une IA

1. Charger `openapi.json` avant de générer du code, des types ou des exemples de requêtes.
2. Toutes les routes métier prises en charge commencent par /v1. Ignorer toute route absente de l’OpenAPI, à l’unique exception de GET /health pour le contrôle de disponibilité.
3. Ne jamais demander de coller un mot de passe ou un JWT dans un prompt, un dépôt, du code source, des journaux ou une application envoyée au navigateur.
4. Lire les identifiants depuis un gestionnaire de secrets ou des variables d’environnement côté serveur. Toujours conserver le mot de passe et le JWT hors du navigateur.
5. Respecter exactement les champs requis, formats, enums et additionalProperties décrits par l’OpenAPI. Les paramètres inconnus sont refusés.
6. Utiliser les identifiants publics retournés par l’API comme identifiants durables. Ne jamais fabriquer ou déduire un identifiant interne.
7. Pour toute écriture dont le contrat exige une `Idempotency-Key`, générer une clé unique par écriture logique et réutiliser la même clé uniquement avec le même identifiant de ressource et un corps strictement identique.
8. Ne jamais recalculer côté application partenaire le prix officiel, le stock disponible ou le reste à payer lorsqu’une route Commerce 360 fournit ce résultat.
9. Minimiser les scopes demandés et traiter les champs conditionnels comme éventuellement absents.
10. Si un environnement de test a été attribué au projet, utiliser son URL, son compte et ses données. Ne pas tester une écriture en production sans autorisation explicite. Les fichiers téléchargeables ne contiennent aucun identifiant ni jeton.

## Connexion et authentification

URL de production : https://api.hbjo-online.com

Avant l’intégration, obtenir auprès de Commerce 360 l’URL de l’environnement, l’email et le mot de passe du compte d’intégration, ainsi que les scopes nécessaires au projet. Ces identifiants sont remis à l’intégrateur par un canal sécurisé ; ce ne sont jamais les identifiants d’un client final ou d’un utilisateur du site partenaire. Une URL de test peut différer de l’URL de production. Contacter support@hbjo-online.com si un accès ou un scope manque.

1. Depuis le backend de l’application partenaire, envoyer POST /auth avec Content-Type: application/json et un corps contenant les champs `email` et `password`.
2. Lire le champ `token` dans la réponse et le conserver uniquement côté serveur.
3. Envoyer ensuite `Authorization: Bearer <token>` sur GET /v1/ping et toutes les routes métier.
4. Un 401 impose de renouveler le jeton ou de vérifier les identifiants. Un 403 indique qu’au moins un scope requis manque au compte d’intégration.

Le compte authentifié détermine automatiquement l’organisation dont les données sont accessibles. L’intégration ne choisit pas cette organisation au moyen d’un en-tête HTTP.

## Provenance des identifiants

- `shopId` : utiliser un identifiant retourné par `GET /v1/shops`.
- `productId` et `itemId` : utiliser les identifiants retournés par les routes catalogue, produits et articles.
- `customerId` : utiliser l’identifiant retourné par une liste ou une recherche client non ambiguë.
- `saleId`, `savId` et `giftCardId` : reprendre l’identifiant retourné par une route de liste, de détail ou d’historique présente dans le contrat.

Les identifiants sont des chaînes opaques conformes au schéma OpenAPI. Ne pas imposer un validateur UUID RFC lorsque le contrat accepte des identifiants préfixés comme `customer_...`, `shop_...` ou `gift_card_...`.

## Formats communs

- Les requêtes et réponses utilisent JSON, sauf les routes de téléchargement PDF.
- Dates et heures : ISO 8601. Dates seules : YYYY-MM-DD.
- Devise actuelle : EUR.
- Pagination : `page` commence à 1 ; les listes retournent généralement `data` et `pagination`.
- Les détails et écritures retournent directement l’objet métier, sans enveloppe `data` universelle.
- `include` est une liste explicite séparée par des virgules ; aucune relation n’est incluse implicitement.
- Les factures et bons de service après-vente sont des flux application/pdf, avec affichage dans le navigateur ou téléchargement selon les paramètres du contrat.

## Erreurs, limites et reprises

Les erreurs JSON contiennent notamment `statusCode`, `code`, `error` et `message`. Certaines erreurs de permission ajoutent `missingScopes`. Conserver ces valeurs dans les journaux techniques, sans y inclure de secret ni de donnée personnelle.

- 400 : requête invalide ; corriger le contrat, ne pas réessayer à l’identique.
- 401 : jeton absent, expiré, invalide ou révoqué ; renouveler l’authentification.
- 403 : permissions insuffisantes ; demander le scope requis, ne pas contourner.
- 404 : ressource inconnue ou non accessible à l’organisation autorisée.
- 409 : conflit métier ou réutilisation incohérente d’une clé d’idempotence.
- 429 : limitation de débit ; respecter `Retry-After` s’il est présent et espacer progressivement les nouvelles tentatives, avec un petit délai aléatoire pour éviter des reprises simultanées.
- 500 ou 503 : erreur temporaire possible ; réessayer avec des délais croissants. Pour une écriture, conserver exactement la même `Idempotency-Key` et le même corps.
- Ne pas supposer une capacité fixe : une réponse 429 et les indications du serveur sont prioritaires.

## Écritures exigeant `Idempotency-Key`

- PUT /v1/gift-cards/{giftCardId}

Pour une même opération et un même identifiant de ressource, la même clé avec le même corps rejoue la réponse initiale. La même clé avec un identifiant ou un corps différent produit un conflit 409. Une clé représente une seule écriture logique, par exemple le débit d’une carte cadeau. Ne pas générer une nouvelle clé lors d’une simple reprise réseau dont le résultat est inconnu.

## Permissions principales

- Catalogue : products:read, stock:read, referentials:read.
- Clients : customers:read, customers:write, customers:pii:read, customers:pii:write, internal-comments:read. Les scopes pii donnent accès aux coordonnées personnelles ; internal-comments:read donne accès aux commentaires réservés aux utilisateurs autorisés.
- Ventes et historique : sales:read, orders:read.
- SAV : sav:read.
- Crédits : customer-credits:read.
- Cartes cadeaux : gift-cards:read, gift-cards:write.

Les droits sont réévalués côté serveur à chaque requête. Les inclusions sensibles peuvent être omises lorsque leur scope manque, même si la route principale répond avec succès.

## Règles métier par domaine

### Catalogue

Un `product` est une référence commune ; un `product-item` est l’article physique réellement vendable. Le prix de vente officiel vient du `product-item`. `promotionPrice` est distinct du prix de base. La disponibilité est calculée par l’API. Pour une synchronisation initiale, paginer `/v1/catalog/products` jusqu’à `hasNextPage=false`. Utiliser ensuite `/v1/catalog/changes` avec un curseur enregistré durablement, puis refaire périodiquement une synchronisation complète pour corriger un éventuel écart.

### Clients

Le lien durable avec un compte utilisateur du site partenaire est `customer.uuid`, jamais l’email ou le téléphone. Pour le rapprochement, combiner plusieurs critères dans `/v1/customers/search`. Si plusieurs candidats sont retournés, ne jamais choisir automatiquement. `PUT /v1/customers/{customerId}` applique un remplacement complet des champs modifiables : envoyer un objet complet conforme au schéma.

### Ventes et factures

Utiliser `sale.uuid` comme identifiant durable. Les montants et statuts retournés par l’API sont les valeurs officielles. Le PDF officiel est retourné par `/v1/sales/{saleId}/invoice/download` ; ne pas tenter de reconstruire une facture depuis les lignes JSON.

### SAV

Utiliser `sav.uuid` comme identifiant durable du dossier de service après-vente. Le reste à payer et les étapes de suivi sont calculés par l’API. Le document officiel est le PDF de `/v1/sav/{savId}/slip`. Les commentaires et documents réservés aux équipes autorisées peuvent être absents des réponses de l’API.

### Cartes cadeaux

`GET /v1/gift-cards/{giftCardId}` consulte une carte cadeau et expose uniquement son numéro masqué. `PUT /v1/gift-cards/{giftCardId}` enregistre un débit ; cette écriture exige le scope `gift-cards:write` et l’en-tête `Idempotency-Key`. Ne jamais journaliser un identifiant ou une donnée sensible au-delà de ce qui est nécessaire au suivi technique.

## Catalogue des opérations OpenAPI

### Authentification

- POST /auth — Obtenir un jeton JWT. Accès : sans JWT. Scopes : aucun scope métier supplémentaire.

### Système

- GET /v1/ping — Vérifier la version de l’API V1. Accès : JWT Bearer requis. Scopes : aucun scope métier supplémentaire.

### Catalogue

- GET /v1/catalog/changes — Lire les changements incrémentaux du catalogue. Accès : JWT Bearer requis. Scopes : products:read + stock:read + referentials:read.
- GET /v1/catalog/products — Lister le catalogue produits complet. Accès : JWT Bearer requis. Scopes : products:read + stock:read + referentials:read.

### Produits

- GET /v1/products — Lister les références produits. Accès : JWT Bearer requis. Scopes : products:read ; conditionnel : `stock:read` lorsque `availableOnly`, `shopId`, `include=stock` ou `include=items` nécessite le calcul de disponibilité.
- GET /v1/products/{productId} — Consulter une référence produit. Accès : JWT Bearer requis. Scopes : products:read ; conditionnel : `stock:read` lorsque `include` demande `stock` ou `items`, ou lorsqu’une boutique est utilisée pour un calcul de disponibilité.
- GET /v1/products/{productId}/items — Lister les articles physiques d’un produit. Accès : JWT Bearer requis. Scopes : products:read + stock:read.
- GET /v1/product-items — Lister les articles physiques. Accès : JWT Bearer requis. Scopes : products:read + stock:read.
- GET /v1/product-items/{itemId} — Consulter un article physique. Accès : JWT Bearer requis. Scopes : products:read + stock:read.

### Référentiels

- GET /v1/categories — Lister les catégories. Accès : JWT Bearer requis. Scopes : referentials:read.
- GET /v1/product-types — Lister les types produits. Accès : JWT Bearer requis. Scopes : referentials:read.
- GET /v1/characteristics — Lister les caractéristiques. Accès : JWT Bearer requis. Scopes : referentials:read.
- GET /v1/characteristics/{characteristicId}/values — Lister les valeurs d’une caractéristique. Accès : JWT Bearer requis. Scopes : referentials:read.
- GET /v1/shops — Lister les boutiques. Accès : JWT Bearer requis. Scopes : referentials:read.

### Clients

- GET /v1/customers — Lister les clients. Accès : JWT Bearer requis. Scopes : customers:read ; conditionnel : `customers:pii:read` pour demander ou filtrer des coordonnées personnelles. `internal-comments:read` pour inclure les commentaires internes.
- GET /v1/customers/search — Rechercher des clients pour rapprochement. Accès : JWT Bearer requis. Scopes : customers:read + customers:pii:read.
- GET /v1/customers/{customerId} — Consulter un client. Accès : JWT Bearer requis. Scopes : customers:read ; conditionnel : `customers:pii:read` pour les coordonnées personnelles. `internal-comments:read` pour les commentaires internes.
- PUT /v1/customers/{customerId} — Remplacer les informations modifiables d’un client. Accès : JWT Bearer requis. Scopes : customers:write + customers:pii:write.
- GET /v1/customers/{customerId}/credits — Lister les crédits d’un client. Accès : JWT Bearer requis. Scopes : customers:read + customer-credits:read ; conditionnel : `gift-cards:read` lorsque le filtre `types` contient `gift_card`.
- GET /v1/customers/{customerId}/history — Consulter l’historique commercial d’un client. Accès : JWT Bearer requis. Scopes : customers:read ; au moins un parmi sales:read, orders:read, sav:read, customer-credits:read ; conditionnel : Chaque famille demandée dans `include` nécessite son scope de lecture ; les familles non autorisées sont omises.

### Ventes

- GET /v1/sales — Lister les ventes. Accès : JWT Bearer requis. Scopes : sales:read ; conditionnel : `customers:pii:read` pour les coordonnées client. `customer-credits:read` pour le détail des crédits utilisés.
- GET /v1/sales/{saleId} — Consulter une vente. Accès : JWT Bearer requis. Scopes : sales:read ; conditionnel : `customers:pii:read` pour les coordonnées client. `customer-credits:read` pour le détail des crédits utilisés.
- GET /v1/sales/{saleId}/invoice — Consulter les métadonnées de facture. Accès : JWT Bearer requis. Scopes : sales:read.
- GET /v1/sales/{saleId}/invoice/download — Télécharger la facture PDF. Accès : JWT Bearer requis. Scopes : sales:read.

### SAV

- GET /v1/sav — Lister les dossiers SAV. Accès : JWT Bearer requis. Scopes : sav:read ; conditionnel : `customers:pii:read` pour les coordonnées client. `customer-credits:read` pour les acomptes détaillés.
- GET /v1/sav/{savId} — Consulter un dossier SAV. Accès : JWT Bearer requis. Scopes : sav:read ; conditionnel : `customers:pii:read` pour les coordonnées client. `customer-credits:read` pour les acomptes détaillés.
- GET /v1/sav/{savId}/log — Consulter le journal public d’un SAV. Accès : JWT Bearer requis. Scopes : sav:read.
- GET /v1/sav/{savId}/slip — Télécharger le bon SAV PDF. Accès : JWT Bearer requis. Scopes : sav:read.

### Cartes cadeaux

- GET /v1/gift-cards/{giftCardId} — Consulter une carte cadeau. Accès : JWT Bearer requis. Scopes : gift-cards:read ; conditionnel : `customers:read` pour `include=customer` ; le bloc est omis sans cette permission. `sales:read` pour `include=origin`, `include=usages` ou `include=invoice` ; les blocs sont omis sans cette permission.
- PUT /v1/gift-cards/{giftCardId} — Débiter une carte cadeau. Accès : JWT Bearer requis. Scopes : gift-cards:write.

## Checklist avant livraison

- Client HTTP généré ou validé depuis `openapi.json`.
- Secrets uniquement dans un gestionnaire de secrets ou des variables d’environnement serveur.
- Scopes minimaux confirmés pour chaque parcours.
- Pagination, champs conditionnels éventuellement absents et réponses PDF correctement gérés.
- Reprises progressives des erreurs 429/503 et renouvellement du jeton après une erreur 401 implémentés.
- Clés d’idempotence persistées avec l’intention métier jusqu’à obtention d’un résultat certain.
- Tests réalisés avec le compte, l’URL et les données de test fournis pour le projet d’intégration.
- Aucun email, mot de passe, JWT, code de carte cadeau ou donnée personnelle dans le dépôt et les logs.