# UniPayWeb Market — API catalogue v1

## Parcours

1. Le propriétaire sélectionne son établissement dans `unipaywebmarket-import.html`.
2. Il charge un CSV ou JSON : 1 à 50 lignes, 512 Ko maximum, puis vérifie le lot.
3. Il confirme l’import en brouillons. Chaque article reste soumis au parcours de vérification, QR Banque et modération existant.

Le tableau « Reprendre un lot » retrouve les prévisualisations et les imports confirmés après fermeture du navigateur. Les images doivent avoir été chargées dans Market par ce propriétaire ; aucun téléchargement automatique d’URL externe.

## Connexion ERP

Créer une connexion depuis la rubrique privée « Connecter mon logiciel d’entreprise ». La clé est montrée une fois, stockée sous forme de condensat SHA-256 côté serveur, limitée à un établissement et expirant après 1 à 90 jours. La révocation prend effet sur l’opération suivante et est recontrôlée avant confirmation transactionnelle.

En-tête : `X-Market-Integration-Key: <clé créée dans votre espace>`.

- `catalog.read` : consulter les fiches du seul établissement autorisé, y compris ses brouillons ; aucune identité bancaire ou donnée client dans le contrat catalogue.
- `catalog.import` : prévisualiser, confirmer ou annuler des imports en brouillons. Ne donne pas le droit de publier, payer, prélever ou modifier une autre entreprise.

## Routes

Préfixe : `/api/market/integration/v1`.

| Méthode | Route | Effet |
|---|---|---|
| GET | `/catalog?after=<offer_id>` | Jusqu’à 50 offres, `nextCursor` pour la suite |
| GET | `/catalog-imports?before=<jobId>` | 50 lots, `nextCursor` pour les plus anciens |
| POST | `/catalog-imports/preview` | Vérifier le contenu sans créer de produit |
| GET | `/catalog-imports/{jobId}` | Retrouver une prévisualisation ou le résultat |
| POST | `/catalog-imports/{jobId}/commit` | Import atomique, `confirmDrafts: true` obligatoire |
| POST | `/catalog-imports/{jobId}/cancel` | Annuler un lot non confirmé |

Une connexion ne peut lire les lots d’une autre connexion ou les lots manuels du propriétaire. L’API retourne `version` et `expectedStock` pour la synchronisation d’une référence déjà importée par la même connexion ; les fiches manuelles ont `externalId: null` et ne sont pas reprises automatiquement comme de nouveaux produits.

## Corps de prévisualisation

```json
{
  "requestKey": "une-reference-stable-par-lot-0001",
  "rows": [{
    "externalId": "SKU-001",
    "title": "Lampe solaire",
    "categoryId": "00000000-0000-4000-8000-000000000001",
    "price": "10.0000",
    "currency": "USD",
    "stock": 8,
    "minimumQuantity": 2,
    "type": "general",
    "attributes": {"model": "Solaire 1"},
    "logistics": {"modes": ["local"], "delayDays": 2, "supplier": "Fournisseur", "zones": "Kinshasa", "conditions": "Remise locale"}
  }]
}
```

La catégorie doit être active dans l’établissement Market. Le modèle CSV téléchargeable utilise une catégorie réelle du catalogue. `price` est une chaîne décimale exacte, jamais un nombre flottant. `stock` représente le disponible à vendre ; il ne supprime pas les quantités déjà réservées ou expédiées. Les délais et le fournisseur sont repris des réglages de la boutique si le fichier les omet.

Champs complémentaires : `brand`, `sku`, `description`, `specificCategory`, `images` (10), `videos` (3), `seo`, `productProfile`, `salePolicy` (quantité par lot, volume, pays, promotion et production). Dans le CSV, ces structures sont des cellules JSON correctement citées. Les informations manquantes de catégorie sont signalées avant publication et peuvent être complétées dans le parcours article.

## Mise à jour et reprise

- Même `requestKey`, même contenu : retrouver le même lot, sans doublon. Contenu différent : `IMPORT_RETRY_CHANGED`.
- Même référence externe et mêmes renseignements déjà importés : `unchanged` ; le stock n’est pas ajouté une seconde fois.
- Modification : indiquer `expectedVersion`, obtenu dans le catalogue API. Une modification humaine rend l’ancienne version invalide.
- Si la quantité disponible doit changer, indiquer aussi `expectedStock` avec la quantité actuelle vérifiée. Une vente ou correction après la prévisualisation bloque la confirmation (`IMPORT_STOCK_CHANGED`). Recharger et vérifier avant de recommencer.
- Une seule ligne incorrecte empêche tout le lot de créer des articles. Annuler le lot et vérifier un nouveau fichier corrigé.
- Une mise à jour passe l’article en brouillon privé. Les commandes existantes conservent leurs prix et contrats enregistrés. Une devise existante ne se change pas par import ; les produits possédant plusieurs variantes se corrigent dans leur espace de travail.

## Connecteur local fourni

`apps/market/tools/market-catalog-sync.cjs` fonctionne sans installation supplémentaire avec Node déjà présent. Fournir la clé dans la variable d’environnement `MARKET_CATALOG_INTEGRATION_KEY` ; ne pas la placer dans une URL, un dépôt ou une commande sauvegardée.

```text
node tools/market-catalog-sync.cjs --base http://127.0.0.1:PORT --input catalogue.csv --request-key reference-stable-0001
node tools/market-catalog-sync.cjs --base http://127.0.0.1:PORT --resume UUID-DU-LOT --commit-drafts
node tools/market-catalog-sync.cjs --base http://127.0.0.1:PORT --export catalogue-market.json
```

La première commande prévisualise. La seconde confirme explicitement les brouillons. L’export ne remplace pas un fichier déjà existant. Les réponses et le journal ne contiennent pas la clé. Le contrat OpenAPI est fourni dans `market-catalog-api-v1.openapi.json`.

## Limite du lot

Le connecteur catalogue est opérationnel localement. Les exports supplémentaires commandes, recettes et clients vers un logiciel externe ont été refusés par le contrôle automatique d’autorisation ; leurs champs et leur destination doivent recevoir un accord explicite avant implémentation. Aucune connexion à un ERP distant nommé n’a été effectuée.
