API publique et intégrations

Cette section explique comment les autres applications peuvent consommer notre API et comprendre nos fonctionnalités.

Accès au Swagger

Base URL

Hôte de référence (staging): https://referentiel.staging.ubsi.fr
API: https://referentiel.staging.ubsi.fr/api/...

Authentification

Pas d’authentification sur les routes publiques listées ci-dessous.

Conventions générales

Format: JSON UTF-8
Champs temporels: ISO 8601 (string) dans les DTOs de réponse. Exemple: 2025-09-27T12:34:56.000Z.
Découverte des endpoints: via Swagger (liens ci-dessus). Les ressources publiques sont préfixées par /api/publique/....
Pagination/tri/filtres: non disponibles pour l'instant; exposés dès que nécessaires.
Champs système: Les champs createdAt et updatedAt sont automatiquement gérés et renvoyés dans les réponses. Le champ deletedAt est utilisé en interne pour le soft-delete mais n'est jamais exposé dans les réponses de l'API.

Ressources publiques principales

Produits — /api/publique/produits

GET /api/publique/produits → 200: ProduitDto[]
GET /api/publique/produits/:id → 200: ProduitDto, 400 si id invalide, 404 si non trouvé
POST /api/publique/produits → 201: ProduitDto créé, 400/422 si payload invalide
PATCH /api/publique/produits/:id → 200: ProduitDto mis à jour, 400/404
PATCH /api/publique/produits → 200: BatchUpdateResponseDto, mise à jour en lot (1-500 items)
DELETE /api/publique/produits/:id → 200, 400/404
DELETE /api/publique/produits → 200: suppression en lot (1-500 IDs), 400 si certains IDs non trouvés, 404 si tous les IDs non trouvés

Payload création exemple

{
  "nom": "TV Samsung 4K",
  "prixDeVenteCents": 69900,
  "photosUrls": ["https://cdn.example.com/img1.jpg"],
  "ean": "1234567890123",
  "description": "Téléviseur UHD 55 pouces",
  "categories": "Électronique/TV",
  "marque": "Samsung",
  "poids": "14kg",
  "couleurs": "Noir",
  "dimensions": "123x77x10 cm",
  "caracteristiquesTechniques": "HDR10, HDMI 2.1",
  "statutProduit": "Disponible",
  "documentationUrl": "https://docs.samsung.com/tv.pdf",
  "dateFinReapprovisionnement": null,
  "dateFinDeVie": null
}

Fournisseurs — /api/publique/fournisseurs

GET /api/publique/fournisseurs → 200: FournisseurDto[]
GET /api/publique/fournisseurs/:id → 200: FournisseurDto, 400/404
POST /api/publique/fournisseurs → 201: FournisseurDto, 400/422
PATCH /api/publique/fournisseurs/:id → 200: FournisseurDto, 400/404
PATCH /api/publique/fournisseurs → 200: BatchUpdateResponseDto, mise à jour en lot (1-500 items)
DELETE /api/publique/fournisseurs/:id → 200, 400/404
DELETE /api/publique/fournisseurs → 200: suppression en lot (1-500 IDs), 400/404

Payload création exemple

{
  "nomLegal": "Samsung Electronics",
  "codeFournisseur": "SAMS001",
  "siret": "12345678901234",
  "adresse": "12 rue de Séoul, Paris",
  "email": "contact@samsung.com",
  "telephone": "+33123456789",
  "interlocuteurs": ["Jean Dupont"],
  "documentsContractuelUrls": ["https://contrats/samsung.pdf"],
  "statut": "Actif",
  "statutContractuel": "Validé"
}

Entrepôts — /api/publique/entrepots

GET /api/publique/entrepots → 200: EntrepotDto[]
GET /api/publique/entrepots/:id → 200: EntrepotDto, 400/404
POST /api/publique/entrepots → 201: EntrepotDto, 400/422
PATCH /api/publique/entrepots/:id → 200: EntrepotDto, 400/404
PATCH /api/publique/entrepots → 200: BatchUpdateResponseDto, mise à jour en lot (1-500 items)
DELETE /api/publique/entrepots/:id → 200, 400/404
DELETE /api/publique/entrepots → 200: suppression en lot (1-500 IDs), 400/404

Payload création exemple

{
  "nom": "Entrepôt Sud-Est",
  "adresse": "Zone industrielle Lyon Sud",
  "horaires": "08h-18h",
  "statut": "operationnel",
  "typeEntrepot": "electromenager",
  "estGrosVolume": true,
  "capaciteStockage": 50000,
  "capaciteLogistique": 20000,
  "rolesLogistiques": ["Stockage", "Préparation commandes"],
  "zoneGeographiqueDesservie": "Auvergne-Rhône-Alpes",
  "responsableLogistique": "Pierre Martin"
}

Nouveaux champs entrepôts :

typeEntrepot (optionnel, défaut: "generaliste") : Spécialisation de l'entrepôt
- Valeurs possibles : "informatique", "electromenager", "accessoires", "multimedia", "generaliste"
estGrosVolume (optionnel, défaut: false) : Booléen indiquant si l'entrepôt dispose d'une infrastructure adaptée aux produits volumineux (gros électroménager, TV grand format, etc.)

Magasins — /api/publique/magasins

GET /api/publique/magasins → 200: MagasinDto[]
GET /api/publique/magasins/:id → 200: MagasinDto, 400/404
POST /api/publique/magasins → 201: MagasinDto, 400/422
PATCH /api/publique/magasins/:id → 200: MagasinDto, 400/404
PATCH /api/publique/magasins → 200: BatchUpdateResponseDto, mise à jour en lot (1-500 items)
DELETE /api/publique/magasins/:id → 200, 400/404
DELETE /api/publique/magasins → 200: suppression en lot (1-500 IDs), 400/404

Payload création exemple

{
  "nom": "Fnac Lyon Part-Dieu",
  "adresse": "Centre Commercial La Part-Dieu, Lyon",
  "statut": "Ouvert",
  "servicesDisponibles": ["Retrait 1h", "Service après-vente"],
  "horaires": "10h-20h",
  "responsable": "Sophie Durand",
  "type": "Retail",
  "surfaceVente": 3500,
  "capaciteDAccueil": 500
}

Mise à jour en lot (batch)

Tous les endpoints de mise à jour supportent les opérations en lot via PATCH /api/publique/{resource} sans paramètre d'ID. Exemple pour produits:

{
  "produits": [
    {
      "id": 1,
      "prixDeVenteCents": 79900,
      "statutProduit": "Disponible"
    },
    {
      "id": 2,
      "nom": "TV LG OLED Mise à jour",
      "prixDeVenteCents": 89900
    }
  ]
}

Réponse:

{
  "succes": true,
  "modifies": 2,
  "resultats": [
    {
      "index": 0,
      "id": 1,
      "ean": "1234567890123",
      "statut": "ok"
    },
    {
      "index": 1,
      "id": 2,
      "ean": "2345678901234",
      "statut": "ok"
    }
  ]
}

Pour les autres ressources, remplacer "produits" par "fournisseurs", "entrepots", ou "magasins".

Suppression en lot (bulk delete)

Tous les endpoints de suppression supportent les opérations en lot via DELETE /api/publique/{resource} sans paramètre d'ID. Exemple pour produits:

{
  "ids": [1, 2, 3, 4, 5]
}

Réponse en cas de succès total:

{
  "succes": true,
  "supprimes": 5,
  "resultats": [
    {
      "index": 0,
      "id": 1,
      "ean": "1234567890123",
      "statut": "ok"
    },
    {
      "index": 1,
      "id": 2,
      "ean": "2345678901234",
      "statut": "ok"
    },
    {
      "index": 2,
      "id": 3,
      "ean": "3456789012345",
      "statut": "ok"
    }
  ]
}

Gestion des erreurs pour la suppression en lot:

200 OK: Tous les IDs ont été supprimés avec succès
400 Bad Request: Certains IDs n'existent pas (suppression partielle réussie)
- Message: IDs non trouvés: 999, 1001
404 Not Found: Aucun des IDs fournis n'existe
- Message: Aucun des IDs fournis n'existe: 998, 999, 1000
400 Bad Request: Erreurs de validation (tableau vide, IDs invalides, etc.)

Pour les fournisseurs, le champ identifiant dans la réponse sera nomLegal. Pour les entrepôts et magasins, ce sera nom.

Paramètres et erreurs typiques

:id est un entier positif.
400 Bad Request: paramètre id invalide, body mal formé.
404 Not Found: entité non trouvée.
422 Unprocessable Entity: violation métier/contraintes (ex: prix négatif, duplicata).
500 Internal Server Error: erreur serveur inattendue.

Notes

(Historique) Les modules de démonstration intercom et foods ont été retirés de l'API publique.

Découvrir/essayer l’API

Utiliser le Swagger pour tester les routes et voir les schémas DTO exposés par décorateurs @ApiProperty.