Modèle de données

Cette page décrit comment les données sont rattachées aux locataires et aux sites, et présente les entités que vous rencontrerez le plus souvent à travers l'API. L'API renvoie de simples objets JSON : les noms d'entités ci-dessous désignent des notions, pas des noms de types visibles dans les réponses.

Multi-tenancy

Inklura est multi-locataire, et la portée est portée par les données elles-mêmes :

  • tenantId (uuid) figure sur chaque enregistrement qui appartient à un locataire.
  • siteId (uuid) figure en plus lorsqu'un enregistrement appartient à un site précis.

Un locataire a un nom, un identifiant court code unique (par exemple acme) et un statut. Il possède un ou plusieurs sites, chacun avec un nom, un slug facultatif, un status et des data libres. Le statut d'un site vaut ACTIVE, INACTIVE ou PENDING ; celui d'un locataire peut aussi valoir SUSPENDED. Dans les deux cas, la valeur initiale est PENDING.

À chaque requête, l'API résout une portée locataire/site (voir Sessions et tokens) et ne lit ni n'écrit que les enregistrements de cette portée. Votre token indique le locataire et le site d'origine de votre compte, mais la portée n'y est pas figée : elle est résolue à chaque requête, puis vérifiée au regard des accès de votre compte. Voir la portée locataire.

Entités principales

Les entités suivantes sont celles que vous manipulerez le plus souvent à travers l'API.

Entité Description
Locataire Le locataire : nom, code unique (par ex. acme), statut.
Site Un site appartenant à un locataire : nom, slug, status, data.
Appartenance Donne à un utilisateur un rôle (OWNER ou MEMBER) dans un locataire, éventuellement limité à un site.
Utilisateur Un utilisateur : e-mail, tenantId d'origine, siteId facultatif.
Rôle / Permission Rôles et permissions de la forme ressource:action (par exemple products:read).
Produit Les produits du catalogue, avec leur stock disponible.
Commande Les commandes, leurs lignes et leur préparation.
Mouvement de stock Le journal des mouvements de stock.
Fournisseur / Commande fournisseur Les fournisseurs et les commandes passées auprès d'eux.
Facture Factures, devis et avoirs.
Abonnement Les abonnements.
Campagne Les campagnes marketing.
Domaine / Paramètres du site Les domaines et les paramètres d'un site.
Clé API de feed Une clé à portée limitée pour les feeds de contenu d'un site.

Clés API de feed

Les feeds de contenu d'un site peuvent s'authentifier avec leurs propres clés à portée limitée plutôt qu'avec une session utilisateur. Une clé de feed :

  • commence par le préfixe feed_. La clé complète n'est renvoyée qu'une fois, à la création ou à la régénération ; seul son préfixe (keyPrefix) reste consultable ensuite ;
  • appartient à un locataire et à un site. Il faut donc qu'un site soit sélectionné pour en créer une, et son nom (name, 100 caractères au plus) est unique pour ce couple (locataire, site) ;
  • porte une limite de requêtes par heure (rateLimit, de 0 à 10000, 1 000 par défaut, 0 pour illimité) ;
  • accepte une liste d'adresses autorisées allowedIps facultative : adresses IPv4, plages CIDR IPv4 ou adresses IPv6, séparées par des virgules (les plages IPv6 ne sont pas acceptées). Une entrée invalide est refusée avec BAD_REQUEST, une valeur vide retire la restriction ;
  • peut avoir une date d'expiration expiresAt et être désactivée sans être supprimée ;
  • porte un ensemble de permissions parmi full_content, unlimited_requests et custom_cache (["full_content"] par défaut).

Les clés se gèrent via le router tRPC feedApiKeys :

Procédure Type Rôle
list query Les clés du locataire et du site courants (sans la clé complète).
get query Une clé, par id.
create mutation Crée une clé et renvoie la clé complète dans key.
update mutation Modifie nom, description, permissions, limite, IP autorisées, expiration ou isActive.
regenerate mutation Remplace la clé (l'ancienne cesse de fonctionner) et renvoie la nouvelle dans key.
toggleActive mutation Active ou désactive une clé.
delete mutation Supprime une clé.
getStats query Nombre de clés, clés actives, clés expirées, total des requêtes, clés utilisées sur 24 h.

Les lectures demandent les permissions feed:read et cms:read, les écritures feed:write et cms:write.

Le widget de chat en direct intégrable utilise lui aussi ses propres clés, distinctes des clés de feed.

Ces clés restent l'exception ; l'API générale utilise des sessions et des JWT Bearer (voir Authentification).