Documentation API Registeo
Bienvenue dans la documentation de l'API Registeo. Cette API vous permet d'intégrer le livre de police numérique Registeo directement dans vos outils métier : logiciel de caisse, ERP, application interne, etc.
Accès API
L'accès à l'API est disponible sur demande. Contactez-nous pour activer le mode API sur votre établissement.
Multi-établissement — Une clé API est rattachée à un seul établissement. Si vous gérez plusieurs établissements (multi-SIRET) sur le même compte Registeo, chaque établissement a sa propre clé. Vous basculez entre établissements via le sélecteur dans le header de l'app.
Mode contrôle extérieur
Lorsque l'API est activée pour votre établissement, son registre passe en mode contrôle extérieur :
- Les données du registre (objets, statuts, mouvements) sont mises à jour uniquement via l'API
- L'interface Registeo reste disponible en consultation et pour générer les exports PDF
- La gestion des vendeurs est intégrée aux objets : les informations vendeur sont fournies directement dans chaque objet, pas via un répertoire séparé
- La conformité légale est assurée de la même manière : audit log crypto-chaîné, horodatage, intégrité
Ce mode garantit que votre logiciel métier est la source unique des données du registre, sans risque de double saisie.
Découverte et réel
Un établissement en contrôle extérieur dispose de deux jeux de données étanches — découverte
(données fictives, clé rsk_test_…) et réel (le livre de police, clé rsk_live_…) — et peut
passer de l'un à l'autre dans les deux sens depuis son compte. Développez et rejouez vos scénarios
en découverte : rien de ce qui s'y écrit n'atteint le registre.
Le passage en réel exige un abonnement en règle (402 ABONNEMENT_REQUIS sinon). Ce n'est pas
une formalité de facturation : si l'abonnement s'interrompt en cours de flux, l'API refuse les
écritures, et ce que votre connecteur en fait décide de ce qui manque au registre.
Les écritures envoyées vous engagent. Elles entrent à votre livre de police, et c'est vous qui les produisez en contrôle.
Un flux automatique se relit moins qu'une saisie, et ses deux erreurs sont irréparables :
- une écriture envoyée deux fois fait un doublon. Le numéro d'ordre est consommé, et la suppression n'est que logique : la ligne reste, marquée supprimée ;
- une écriture perdue fait un trou, que rien ne vient combler après coup — la numérotation est continue et ne se réinsère pas.
Deux précautions couvrent l'essentiel : renseignez referenceExterne sur chaque création, et
traitez les refus au lieu de les ignorer. Testez la reprise après incident en découverte, jamais en
réel.
Base URL
https://api.registeo.fr/api
Authentification
Toutes les requêtes doivent inclure deux headers :
X-API-Key: rsk_votre_clé_api
X-Siret: 12345678901234
La clé est générée par l'équipe Registeo lors de l'activation de votre accès API. Une clé donne accès au registre d'un seul établissement : si vous en gérez plusieurs, vous disposez d'une clé par établissement, sans passerelle possible entre eux.
Pourquoi déclarer le SIRET
La clé suffirait techniquement à identifier l'établissement. Le X-Siret est un garde-fou contre l'erreur de configuration : il vous fait déclarer l'établissement que vous croyez viser, et l'API refuse si ce n'est pas celui de la clé.
Sans lui, deux clés interverties dans votre configuration enverraient des écritures dans le registre d'un autre professionnel, avec une réponse 201 et aucun signal d'alerte. Les entrées du livre de police étant scellées cryptographiquement et horodatées, elles ne peuvent pas être déplacées d'un registre à l'autre après coup : les deux registres deviendraient faux durablement. Le contrôle transforme cette erreur silencieuse en refus dès le premier appel.
| Situation | Réponse |
|---|---|
| Header absent | 400 MISSING_SIRET |
| SIRET différent de celui de la clé | 403 ETABLISSEMENT_MISMATCH |
Les espaces, points et tirets sont ignorés dans la comparaison. En cas de changement de SIRET de votre établissement (déménagement notamment), pensez à mettre à jour la valeur dans votre intégration : elle est comparée au SIRET enregistré sur votre fiche Registeo.
Exemple de requête
# Relire une entrée par votre référence
curl https://api.registeo.fr/api/objets/ref:TICKET-4712 \
-H "X-API-Key: rsk_votre_clé_api" \
-H "X-Siret: 12345678901234"
En écriture, le corps de la requête porte en plus un champ agent — le prénom et le nom de la personne physique effectuant l'opération. Voir Objets.
Sections de la documentation
- Objets — Enregistrement et gestion des objets du livre de police
- Ventilation — Démontage d'une entrée en entrées filles (module optionnel)
- Export PDF — Génération et envoi du registre en PDF (via l'interface uniquement)
- Audit — Journal d'audit et traçabilité
- Modèles de données — Référence des types et schémas
Hébergement & conformité
- Données hébergées en France
- Conforme aux exigences applicables au livre de police
- Registre traçable avec journal d'audit complet
- Chaque action via l'API est auditée et traçable
Codes d'erreur
| Code | Description |
|---|---|
400 | Requête invalide (champs manquants ou incorrects) |
401 | Clé API manquante ou invalide |
402 | Limite de l'offre gratuite atteinte |
403 | Accès interdit |
404 | Ressource non trouvée |
500 | Erreur serveur |
Les réponses d'erreur portent un champ code identifiant la cause précise. Traitez ce code plutôt que le message, qui peut être reformulé.
code | Statut | Signification |
|---|---|---|
MISSING_AGENT | 400 | Champ agent absent du corps — nommez la personne physique ayant effectué l'opération |
MISSING_SIRET | 400 | Header X-Siret absent — déclarez l'établissement visé |
SIRET_ETABLISSEMENT_ABSENT | 400 | Aucun SIRET n'est renseigné sur l'établissement — complétez-le depuis « Mon compte » |
ETABLISSEMENT_MISMATCH | 403 | Le X-Siret transmis n'est pas celui de la clé API utilisée |
CHAMPS_ACTIVITE_INVALIDES | 400 | Une clé de champsActivite n'appartient pas à l'activité ni aux régimes de l'établissement |
REGIME_NON_ACTIF | 400 | Un régime demandé n'est pas actif sur l'établissement (les régimes actifs sont listés dans la réponse) |
TYPE_OPERATION_INVALIDE | 400 | typeOperation inconnu (achat, dépôt, reprise, échange) |
OPERATION_NON_AUTORISEE | 400 | typeOperation valide mais hors du périmètre de l'activité (les opérations admises sont listées dans la réponse) |
PAIEMENT_ESPECES_INTERDIT | 400 | Règlement en espèces interdit par le régime de l'entrée (métaux ferreux et non ferreux, L112-6 CMF) |
PAIEMENT_ESPECES_PLAFONNE | 400 | Règlement en espèces au-delà du plafond légal face à un particulier (L112-6 CMF) |
DATE_ACHAT_FUTURE | 400 | La date d'achat est postérieure à aujourd'hui |
DATE_MOUVEMENT_ANTERIEURE | 400 | La date du mouvement précède la date d'entrée de l'objet |
DATE_MOUVEMENT_FUTURE | 400 | La date du mouvement est postérieure à aujourd'hui |
DATE_MOUVEMENT_INVALIDE | 400 | Date de mouvement illisible |
STATUT_INCOMPATIBLE_OPERATION | 400 | Statut réservé à d'autres types d'opération (ex. restitué sur un achat) |
DOCUMENTS_INVALIDES | 400 | Documents d'un mouvement dans un autre format que documentKeys: string[], y compris l'ancien champ documents, ou plus de 5 clés |
PIECES_JOINTES_TROP_NOMBREUSES | 400 | Plus de 5 photos (photoKeys) ou de 3 documents vendeur (vendeurDocumentKeys) sur une entrée |
FICHIER_INTROUVABLE | 400 | Une clé de pièce jointe ne correspond à aucun fichier de l'établissement |
STATUT_INVALIDE | 400 | Statut inconnu pour l'activité de l'établissement (les statuts valides sont listés dans la réponse) |
STATUT_NON_MOUVEMENT | 400 | Statut valide mais qui ne correspond pas à un mouvement de stock (ex. en_stock) |
QUANTITE_BELOW_ENGAGED | 400 | Quantité inférieure à celle déjà engagée dans des mouvements |
MOTIF_INSCRIPTION_REQUIS | 400 | Les régimes envoyés ne comportent aucun motif d'inscription — seulement des régimes de complément. Un complément s'ajoute à une cause d'inscription, il n'en tient pas lieu |
REGIMES_REQUIS | 400 | Le champ regimes est absent. Il est obligatoire via l'API : indiquez les régimes d'inscription, ou [] pour un objet hors livre de police |
HORS_REGISTRE_NON_AUTORISE | 400 | regimes: [] reçu alors que l'établissement n'est pas autorisé à tenir des objets hors livre de police |
REGISTRE_IRREVERSIBLE | 400 | Tentative d'inscrire au registre une entrée qui ne l'a jamais été, ou d'en retirer une qui y figure. L'état est fixé à la création |
MENTION_MANQUANTE | 400 | Une mention obligatoire du vendeur est absente. Le corps de la réponse nomme le champ dans champ |
SUBSCRIPTION_INACTIVE | 402 | Abonnement inactif |
ABONNEMENT_REQUIS | 402 | Passage en mode réel refusé : l'abonnement n'est pas en règle. Un flux ouvert sur une situation de paiement qui va rompre laisse des entrées manquantes ou en double |
FREE_LIMIT_REACHED | 402 | Limite de l'offre gratuite atteinte |
FREE_PERIOD_EXPIRED | 402 | Durée de l'offre gratuite écoulée. L'échéance est rappelée dans trialExpiresAt. La lecture et l'export restent ouverts : seule l'écriture s'arrête |
EXTERNAL_MODE | 403 | Écriture tentée depuis l'interface alors que l'établissement est en mode contrôle extérieur |
REGISTRE_CLOS | 403 | Votre livre de police a été clos. Il reste lisible et exportable, mais n'accepte plus aucune écriture — y compris par l'API. Cet état est définitif |
REFERENCE_DEJA_UTILISEE | 409 | La referenceExterne envoyée est déjà portée par une entrée supprimée. Une suppression étant logique, la ligne reste au registre et garde sa référence : employez-en une autre. La réponse donne le numero de l'entrée concernée et sa date de suppression |
PROFIL_REQUIRED | 412 | Aucun établissement actif sur le compte |
STOCK_DISABLED | 412 | Module de gestion de stock non activé |
Les modules optionnels portent des codes qui leur sont propres, documentés sur leur page : voir Ventilation.