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 :

• Le champ regimes est obligatoire via l'API (400 REGIMES_REQUIS s'il manque). Vous décidez ce qui entre au livre de police : nous ne le devinons pas à votre place.
• regimes: [] — tableau explicitement vide — signifie « aucun régime » : l'objet est tenu en stock et ne figure pas au livre de police. Il est absent de la consultation du registre et de l'extrait imprimé, mais il se relit par GET /api/objets/{id} et figure dans l'export du stock — il existe bel et bien.
• L'option se règle depuis votre compte, dans la gestion du stock. Si elle est fermée : 400 HORS_REGISTRE_NON_AUTORISE.
• Un objet hors registre ne consomme pas de numéro d'ordre : il relève d'une séquence d'inventaire distincte, préfixée INV-. La numérotation du livre de police reste continue.
• Une valeur qui ne figure pas dans les regimesActifs de l'établissement est refusée : 400 REGIME_NON_ACTIF, avec la liste des régimes actifs dans le champ regimesActifs de la réponse. Un régime détermine des obligations propres (prix d'achat obligatoire, plafonds de paiement en espèces, déclaration annuelle) : l'ignorer silencieusement laisserait croire que l'entrée y est soumise alors qu'elle ne le sera jamais.
• Les régimes disponibles dépendent de l'activité — un professionnel de l'automobile ne peut pas déclarer METAUX_PRECIEUX. Voir la page Modèles pour la correspondance activité / régimes.
• En modification (PUT), les régimes déjà portés par l'entrée restent acceptés, même s'ils ont été désactivés sur l'établissement depuis — sans quoi les entrées anciennes deviendraient inéditables.
• Le régime détermine la validation du prix (voir ci-dessous) et les warnings affichés dans l'UI.

Lire un objet

GET /api/objets/{id}
GET /api/objets/ref:{votre référence}

Rend une entrée, avec toutes ses mentions, ses mouvements, ses pièces jointes et son historique. Voir le type ObjetMobilier pour la structure complète. Une entrée supprimée se relit par son {id}, pas par sa référence.

L'API ne liste pas le registre : un connecteur relit une entrée à la fois, celle qu'il vient d'écrire ou celle qu'il doit resynchroniser. L'extraction du registre complet se fait depuis l'interface Registeo, par l'administrateur (PDF ou CSV).

Chaque lecture est inscrite au journal des consultations, comme l'ouverture d'une fiche à l'écran (voir Audit).

Réponse 200

L'objet. 404 Objet introuvable si l'identifiant ou la référence ne désigne aucune entrée de l'établissement.

Créer un objet

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

POST /api/objets

Champ obligatoire : agent

{ "agent": "Marie Dupont", "designation": "…" }

L'arrêté du 15 mai 2020 impose que toute mutation du livre de police (création, modification, suppression, mouvement) soit attribuée à une personne physique identifiable. Comme votre clé API est partagée entre toutes les opérations de votre établissement, vous devez transmettre l'identité de l'agent, dans le corps de la requête, sur chaque appel d'écriture :

• POST /api/objets (création d'entrée)
• PUT /api/objets/:id (modification)
• DELETE /api/objets/:id (suppression motivée)
• DELETE /api/objets/:id/photos (retrait d'une photo)
• POST /api/objets/:id/mouvements (sortie, vente, mise en réparation, etc.)
• PUT /api/objets/:id/mouvements/:id/resolve (annulation d'un mouvement)

Indiquez le prénom et le nom de la personne qui a procédé à l'opération (ex. Marie Dupont). Elle n'a pas besoin d'avoir un compte Registeo : un vendeur en boutique, un opérateur d'entrepôt conviennent. En revanche, ni identifiant interne, ni pseudo, ni valeur générique du type API ou système : un humain identifiable et joignable en cas de contrôle par les forces de l'ordre.

La valeur est inscrite au registre telle que vous l'envoyez. Transmettez donc toujours la même graphie pour une même personne.

Ce contrôle est délibéré : votre intégration ne peut pas s'en exonérer. La traçabilité légale repose dessus, et chaque entrée du journal d'audit porte le nom de l'agent ayant effectué la modification.

Champs principaux

Règlement en espèces

L'article L112-6 du Code monétaire et financier encadre le paiement en espèces, et l'API applique ces limites à l'écriture :

Le montant retenu est le total de l'entrée (prixAchat × quantite), pas le prix unitaire. Le plafond ne s'applique pas à un vendeur professionnel.

Ce contrôle est volontairement bloquant : un registre qui enregistre un règlement illégal en constitue la preuve, scellée et horodatée. Mieux vaut refuser l'écriture que produire cette pièce.

Cohérence des dates

• dateAchat ne peut pas être postérieure à aujourd'hui → 400 DATE_ACHAT_FUTURE.
• La date d'un mouvement ne peut ni précéder la date d'entrée de l'objet (400 DATE_MOUVEMENT_ANTERIEURE), ni être dans le futur (400 DATE_MOUVEMENT_FUTURE).

La comparaison se fait à la journée près, pour rester tolérante aux fuseaux horaires.

Pièces jointes

Les clés transmises dans photoKeys, vendeurDocumentKeys, signatureKey ou documentKeys doivent correspondre à des fichiers réellement envoyés par votre établissement via upload-photo. Une clé inconnue est refusée en 400 FICHIER_INTROUVABLE — sans quoi le registre citerait une pièce justificative introuvable, ce qui ne se découvrirait qu'au contrôle.

Clés autorisées dans champsActivite

Les clés acceptées dépendent de l'activité de votre établissement et de ses régimes actifs : poincon pour un bijoutier, vin pour un professionnel de l'automobile, poidsMetaux et titreMetaux dès que le régime métaux précieux est actif. La liste exhaustive par activité est publiée sur la page Modèles.

Une clé qui n'appartient ni à votre activité ni à vos régimes est refusée : l'API renvoie 400 CHAMPS_ACTIVITE_INVALIDES en nommant le champ fautif et les champs acceptés.

{
  "success": false,
  "code": "CHAMPS_ACTIVITE_INVALIDES",
  "message": "Champ inconnu pour l'activité « automobile » : epoque. Champs acceptés : vin, immatriculation, carteGrise, controleTechnique."
}

Ce refus est volontaire : une clé inconnue serait enregistrée sans jamais apparaître ni dans le registre, ni dans le PDF remis lors d'un contrôle. Mieux vaut une erreur à l'intégration qu'une donnée perdue en silence.

En modification (PUT), les clés déjà portées par l'entrée restent acceptées même si l'activité de l'établissement a changé depuis — sans quoi les entrées anciennes deviendraient inéditables.

Champs personnalisés (stockMetadata)

Les champs que vous avez définis dans la gestion du stock (emplacement, prix conseillé, mise en vitrine…) se renseignent à la création : "stockMetadata": { "<clé>": valeur }, avec les clés de vos champs.

Ce sont des données d'inventaire : elles ne figurent pas au livre de police et ne sont pas scellées dans le journal d'audit. Elles se modifient ensuite librement depuis votre espace.

Une clé inconnue, une valeur du mauvais type, ou des champs personnalisés envoyés alors que la gestion du stock n'est pas activée sont refusés avant l'écriture (400 STOCK_METADATA_INVALIDE, 400 STOCK_DESACTIVE), sans consommer de numéro d'ordre — pour la même raison qu'avec champsActivite : une valeur perdue en silence est pire qu'une erreur à l'intégration.

Vendeur particulier

Vendeur professionnel

Photos et documents

Au-delà de ces plafonds, l'écriture est refusée en 400 PIECES_JOINTES_TROP_NOMBREUSES. Une clé présente deux fois ne compte qu'une fois.

Exemple — vendeur particulier

{
  "agent": "Marie Dupont",
  "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",
  "vendeurIdentiteDateDelivrance": "2019-03-12",
  "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",
  "vendeurNom": "Claire Bernard",
  "vendeurQualite": "Responsable de site",
  "vendeurIdentiteType": "CNI",
  "vendeurIdentiteNumero": "CB998877",
  "vendeurIdentiteDateDelivrance": "2020-06-08",
  "vendeurIdentiteDelivrance": "Préfecture du Nord",
  "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.

Rejouer sans créer de doublon

Envoyez referenceExterne : votre propre identifiant pour cette opération — numéro de ticket, de vente, de commande.

Un second appel portant la même référence ne crée rien : il retourne l'objet déjà enregistré, en 200 au lieu de 201, avec "rejeu": true en tête de réponse. Le corps est identique à celui d'une création.

Une référence ne se libère pas

Supprimer une entrée ne rend pas sa référence disponible. Un appel qui réemploie la référence d'une entrée supprimée est refusé en 409 REFERENCE_DEJA_UTILISEE : la suppression d'une écriture est logique, la ligne reste au registre et garde ce qui l'identifie. La réponse désigne l'entrée qui tient la référence.

{
  "success": false,
  "code": "REFERENCE_DEJA_UTILISEE",
  "message": "La référence « TICKET-4712 » a déjà été portée par l'entrée n° 312, depuis supprimée du registre. Une suppression n'efface pas l'écriture, elle la marque : la référence reste prise. Employez-en une autre pour cette nouvelle entrée.",
  "numero": "312",
  "supprimeeLe": "2026-09-15T20:54:19.666Z"
}

Reprenez une référence distincte pour la nouvelle entrée. En bac à sable, cela veut dire qu'un scénario de test rejoué après nettoyage demande des références neuves à chaque passage : préfixez-les par la date ou par un identifiant d'exécution.

Adresser un objet par votre référence

Partout où une route attend un {id}, vous pouvez écrire ref:<votre référence> :

POST /api/objets/ref:TICKET-4712/mouvements
PUT  /api/objets/ref:TICKET-4712

Vous n'avez donc pas à conserver nos identifiants dans votre système. 404OBJET_INTROUVABLE si aucune entrée ne porte cette référence.

Pour relire une entrée par sa référence : GET /api/objets/ref:TICKET-4712.

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.

Motif de la rectification : motif

Une entrée validée ne se réécrit pas : elle se rectifie. La correction s'ajoute à l'entrée d'origine, qui reste visible, et son motif est scellé avec elle dans le journal d'audit. Il apparaît dans l'historique de la fiche et dans l'export PDF.

{ "agent": "Marie Dupont", "motif": "Erreur de saisie du numéro IMEI", "designation": "…" }

Le motif est exigé par l'API comme par l'interface Registeo. Un refus n'écrit rien.

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

Champ obligatoire : agent

Comme pour la création d'objet, le champ agent (prénom et nom de la personne ayant effectué le mouvement) est requis dans le corps. 400 MISSING_AGENT sans lui.

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, des documents de mouvement ou des signatures.

POST /api/objets/upload-photo?context=objets

Content-Type : multipart/form-data

Paramètre d'URL obligatoire : context

Le contexte détermine où le fichier est rangé et comment il sera relu ensuite. Il est obligatoire : sans lui, l'API renvoie 400.

Réponse 201

{
  "key": "c-7dec0cf719a87d79170be95266c6f35101ae4e6b93a3a2387d53aabe0c84f149.webp",
  "url": "https://api.registeo.fr/objets/photo?key=c-7dec0cf7…webp&context=objets"
}

Utilisez la key retournée dans photoKeys, vendeurDocumentKeys, documentKeys ou signatureKey. Traitez-la comme un identifiant opaque : sa forme peut évoluer. Envoyer deux fois la même image renvoie la même clé.

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.