Objets (Livre de police)

L'API Objets permet de gérer les entrées du livre de police numérique : enregistrement d'objets mobiliers, suivi du stock et des ventes, gestion des photos et documents vendeur.

Chaque objet reçoit automatiquement un numéro d'ordre séquentiel, conforme aux exigences réglementaires. La numérotation est propre à chaque établissement : si vous gérez plusieurs établissements, chacun a sa séquence indépendante (1, 2, 3... ou 2026-1, 2026-2... en mode annuel). Les informations du vendeur sont intégrées directement dans l'objet.

Scope — La clé API utilisée détermine l'établissement ciblé. Toutes les opérations (création, lecture, audit) sont scopées au livre de police de cet établissement.

Régimes juridiques

Chaque objet porte un ou plusieurs régimes juridiques qui déterminent les règles applicables (mentions obligatoires, seuils de paiement, obligations déclaratives, etc.). Les régimes disponibles dépendent de l'activité configurée sur l'établissement de la clé API utilisée.

Règles métier :

• Si le champ regimes est absent ou vide à la création, l'objet reprend automatiquement les regimesActifs configurés sur l'établissement de la clé API.
• Les valeurs envoyées qui ne figurent pas dans les regimesActifs de l'établissement sont ignorées (filtrage silencieux).
• Le régime détermine la validation du prix (voir ci-dessous) et les warnings affichés dans l'UI.

Lister les objets

GET /api/objets

Réponse 200

Retourne un tableau d'objets. Voir le type ObjetMobilier pour la structure complète.

Créer un objet

Enregistre un nouvel objet dans le livre de police. Le numero est attribué automatiquement.

POST /api/objets

Champs principaux

Vendeur particulier

Vendeur professionnel

Photos et documents

Exemple — vendeur particulier

{
  "typeOperation": "achat",
  "designation": "Montre ancienne en or",
  "marques": "Marque visible au dos",
  "provenanceDeclaree": "Succession familiale",
  "quantite": 1,
  "prixAchat": 150.00,
  "modePaiement": "espèces",
  "dateAchat": "2025-03-01",
  "regimes": ["OBJETS_OCCASION", "METAUX_PRECIEUX"],
  "champsActivite": {
    "poincon": "Tête d'aigle 750",
    "poidsMetaux": "Or 18k : 12 g",
    "titreMetaux": "750‰"
  },
  "vendeurType": "particulier",
  "vendeurNom": "Jean Dupont",
  "vendeurDateNaissance": "1985-06-15",
  "vendeurLieuNaissance": "Paris (75)",
  "vendeurNationalite": "Française",
  "vendeurAdresse": "12 rue de la Paix, 75002 Paris",
  "vendeurIdentiteType": "CNI",
  "vendeurIdentiteNumero": "AB123456",
  "vendeurIdentiteDelivrance": "Préfecture de Paris"
}

Exemple — vendeur professionnel avec documents

{
  "typeOperation": "achat",
  "designation": "Lampe art déco",
  "quantite": 1,
  "prixAchat": 80.00,
  "modePaiement": "carte",
  "dateAchat": "2025-04-10",
  "vendeurType": "professionnel",
  "vendeurRaisonSociale": "Emmaüs Armentières",
  "vendeurSiret": "39765682800035",
  "vendeurAdresse": "3 Place du 19 Mars 1962, 59280 Armentières",
  "vendeurDocumentKeys": ["key-du-kbis-uploadé"]
}

Réponse 201

Retourne l'objet créé avec son id, son numero attribué, et tous les champs du type ObjetMobilier.

Modifier un objet

PUT /api/objets/{id}

Mêmes champs que la création. Tous les champs doivent être fournis (pas de patch partiel). Les photos et documents passés dans photoKeys / vendeurDocumentKeys remplacent les listes existantes : une clé absente du tableau sera retirée de l'objet.

Réponse 200

{
  "success": true,
  "changes": 2
}

changes indique le nombre de champs modifiés enregistrés dans le journal d'audit.

Supprimer un objet

La suppression est logique (soft delete) : l'objet reste dans le registre avec une date deletedAt pour assurer la traçabilité réglementaire.

DELETE /api/objets/{id}

Corps de la requête

Réponse 200

{
  "success": true
}

Créer un mouvement de stock

Crée un mouvement de stock sur un objet : vente, mise en casse, réparation, exposition, expertise, etc. Le mouvement est enregistré dans le journal d'audit (crypto-chaîné) et le statut de l'objet est recalculé automatiquement.

Tout changement de statut passe par un mouvement. Un mouvement peut être annulé (résolu) pour remettre l'objet en stock.

POST /api/objets/{id}/mouvements

Corps de la requête

Réponse 201

{
  "success": true,
  "statut": "vendu",
  "quantite": 5,
  "dateVente": "2025-06-15T00:00:00.000Z",
  "prixVente": 280.00,
  "mouvements": [
    {
      "id": "mouvement-uuid",
      "quantite": 5,
      "statut": "vendu",
      "date": "2025-06-15T00:00:00.000Z",
      "prixVente": 280.00,
      "acheteurType": "particulier",
      "acheteurNom": null,
      "acheteurAdresse": null,
      "acheteurRaisonSociale": null,
      "acheteurSiret": null,
      "resolvedAt": null
    }
  ]
}

Exemple — vente à un particulier

{
  "statut": "vendu",
  "quantite": 2,
  "date": "2025-06-15",
  "prixVente": 120.00,
  "acheteurType": "particulier",
  "acheteurNom": "Marie Martin",
  "acheteurAdresse": "5 Rue des Lilas, 75011 Paris"
}

Exemple — vente à un professionnel

{
  "statut": "vendu",
  "quantite": 1,
  "date": "2025-06-20",
  "prixVente": 850.00,
  "acheteurType": "professionnel",
  "acheteurRaisonSociale": "Affinerie du Nord",
  "acheteurSiret": "39765682800035",
  "acheteurAdresse": "12 Zone Industrielle, 59800 Lille"
}

Exemple — mise en réparation

{
  "statut": "en_reparation"
}

Annuler un mouvement de stock

Si un mouvement de stock a été créé par erreur, il peut être résolu (annulé). Le mouvement reste dans l'historique avec un timestamp resolvedAt, et le stock disponible est recalculé.

PUT /api/objets/{id}/mouvements/{mouvementId}/resolve

Aucun corps de requête requis.

Réponse 200

{
  "success": true,
  "statut": "en_stock",
  "quantite": 5,
  "mouvements": [
    {
      "id": "mouvement-uuid",
      "quantite": 2,
      "statut": "vendu",
      "date": "2025-06-15T00:00:00.000Z",
      "prixVente": 120.00,
      "acheteurNom": "Marie Martin",
      "acheteurAdresse": "5 Rue des Lilas, 75011 Paris",
      "resolvedAt": "2025-06-16T09:00:00.000Z"
    }
  ]
}

Upload de photo ou document

Endpoint unique pour uploader des photos d'objet, des documents vendeur ou des signatures.

POST /api/objets/upload-photo

Content-Type : multipart/form-data

Réponse 201

{
  "key": "prefix/uuid.webp",
  "url": "https://..."
}

Utilisez la key retournée dans photoKeys, vendeurDocumentKeys ou signatureKey lors de la création ou modification d'un objet.

Supprimer une photo d'objet

DELETE /api/objets/{id}/photos

Corps de la requête

Réponse 200

{
  "success": true
}

La photo n'est supprimée physiquement que si elle n'est plus référencée par aucun autre objet.