Documentation — niveau 2 sur 3
Brancher un site sur Structure Hub
Le branchement se fait entièrement par l'API : personne chez l'éditeur n'intervient. Le commerçant génère un jeton à usage unique depuis son espace, l'agent l'échange contre une clé, puis demande au Hub ce qui manque encore jusqu'à ce qu'il se déclare prêt. Les étapes ci-dessous nomment leurs routes ; la forme exacte de chaque réponse se lit dans la spécification machine, qui est la seule source.
Base de l'API : https://www.structureweb.fr — version du contrat : 2026-10-16.02.
Avant de commencer
- Un site en ligne, quel qu'en soit l'auteur, dont tu maîtrises le code serveur.
- Un compte Structure Hub ouvert par le commerçant, et un jeton de branchement qu'il génère lui-même.
- Un endroit sûr, côté serveur, pour garder la clé d'API : le Hub ne la montre qu'une fois.
Les 11 étapes, dans cet ordre
1. Lis la spécification machine, puis le master prompt
Ce sont les deux seules sources d'un site neuf, et elles ne disent pas la même chose : la spécification dit la FORME des réponses, le master prompt dit l'USAGE. Un agent qui commence par essayer des routes au hasard devine — et ce qu'il devine finit en production. Les deux se lisent sans clé, avant tout branchement.
GET /api/v1/specification
Rend ce document : la spécification OpenAPI 3.1 de l'API publique du Hub.
Aucune clé. L'opération est lisible avant même le branchement.
GET /api/v1/master-prompt
Le master prompt À JOUR, avec les valeurs de TA boutique. Ne contient jamais de jeton d'enrôlement.
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
2. Enrôle le site avec le jeton de branchement
Le commerçant génère un jeton à usage unique dans son espace et te le donne. L'enrôlement échange ce jeton contre une clé d'API que le Hub ne te montrera qu'UNE SEULE FOIS : enregistre-la immédiatement du côté serveur de ton site. C'est la seule porte d'entrée ; aucune clé ne se fabrique autrement.
POST /api/v1/enroll
Branche un site en un seul appel : clé d'API, webhook, secret, Deploy Hook, dépôt média, capacités — authentifié par un jeton d'enrôlement à usage unique.
Authentification particulière, décrite dans le texte de l'opération (jeton à usage unique, lien signé).
3. Demande au Hub ce qui manque encore
Cette route te rend les questions à poser au commerçant, ce qui est déjà réglé, et les gestes qu'aucune API ne peut faire à sa place. Elle t'évite de nous écrire, et elle ne redemande jamais ce que tu viens de donner. Relis-la après chaque réponse, jusqu'à ce qu'elle se déclare prête.
GET /api/v1/mise-en-service
Rend ce qui MANQUE pour que la boutique tourne, avec les questions à poser au commerçant et les gestes que personne ne peut faire à sa place.
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
PATCH /api/v1/settings
Écrit un ou plusieurs réglages de l'organisation (refus global au premier défaut) et rend l'état ENREGISTRÉ.
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
4. Lis le contrat de la boutique avant d'afficher un seul prix
Le régime de TVA, la zone de livraison, les moyens de paiement, les emballages et les coordonnées de virement sont des faits de la boutique, pas des réglages de ton site. Les recopier en dur dans ton code produit une information trompeuse le jour où le commerçant en change un — et personne ne le voit, parce que la page continue de s'afficher.
GET /api/v1/webhook
Rend le contrat complet de l'organisation : webhook, Deploy Hook, TVA, livraison, paiements, bandeau, retrait, fermeture, branchements, référencement, version du contrat.
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
GET /api/v1/settings
Rend tous les réglages de l'organisation de la clé ; les secrets sont remplacés par leur présence.
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
5. Publie le catalogue
Produits, rayons, marques, articles et médias descendent du Hub vers ton site. C'est le Hub qui fait autorité : ton site affiche ce qu'il reçoit et n'invente ni prix, ni stock, ni disponibilité. Une liste vide te le dit explicitement — ne la confonds jamais avec une panne.
GET /api/v1/products
Liste les produits VENDUS EN LIGNE de l'organisation (publiés ET en rupture par défaut) ; catalogue ENTIER sans « limit », pagination par curseur avec « limit ».
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
GET /api/v1/categories
Liste TOUTES les catégories (actives par défaut) ; ne pagine pas.
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
GET /api/v1/brands
Liste TOUTES les marques (actives par défaut) ; ne pagine pas et refuse « limit » / « cursor ».
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
GET /api/v1/articles
Liste les articles de blog (PUBLIÉS par défaut), pagination par curseur, filtre delta « since ».
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
GET /api/v1/media
Liste les adresses de médias RÉFÉRENCÉES par le Hub pour l'organisation (à conserver), en entier, sans pagination.
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
GET /api/v1/redirects
Liste les redirections SEO ACTIVES de l'organisation (enveloppe de liste, pagination par curseur).
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
6. Fais calculer les frais de port par le Hub
Le Hub connaît les transporteurs du commerçant, ses grilles, son franco, ses points relais et ses emballages. Un tunnel qui calcule lui-même ses frais de port annonce un prix que la facture démentira, et c'est l'acheteur qui le découvre au paiement.
POST /api/v1/shipping/quote
Calcule les frais de port d'un panier : une ligne par mode de livraison, avec la provenance du prix.
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
GET /api/v1/shipping/forfait
Lit les tranches de poids du forfait boutique, le franco et le mode de livraison en cours.
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
GET /api/v1/shipping/service-points
Cherche les points relais autour d'un code postal, ou relit UN point par son identifiant (via la clé SendCloud confiée au Hub).
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
7. Fais valider les codes de remise par le Hub
Les remises portent un ciblage : une personne, un groupe, certains produits, un nombre d'utilisations. Ton site ne peut pas le reconstituer. Un code accepté chez toi et refusé ici fait un panier faux, et un code accepté partout alors qu'il visait trois clients coûte de l'argent au commerçant.
POST /api/v1/discounts/validate
Valide un code saisi par l'acheteur, SANS le consommer (codes partagés et nominatifs).
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
GET /api/v1/discounts
Liste les remises (codes promo) de l'organisation, codes nominatifs EXCLUS (enveloppe de liste, pagination par curseur).
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
8. Crée la commande dans le Hub, et rien que là
La commande, le client et la facture naissent dans le Hub. Ton site n'émet AUCUN document intitulé « facture » et ne tient aucune numérotation : la numérotation légale doit être unique et continue, et elle l'est chez nous. Sers le PDF du Hub octet pour octet — le régénérer lui ferait perdre la pièce jointe de la facture électronique, sans que rien ne le signale.
POST /api/v1/orders
Enregistre une commande passée sur le site (totaux recalculés par le Hub, idempotente sur « externalRef »).
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
GET /api/v1/orders
Liste les commandes de l'organisation (200 au plus, les plus récemment modifiées d'abord, pas de pagination).
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
GET /api/v1/invoices/{number}/pdf
Le PDF d'une facture ou d'un avoir de l'organisation, servi directement (pas de redirection).
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
9. Branche les comptes clients, les avis et la rétractation
Ces trois parcours parlent à un CONSOMMATEUR, pas à toi. Les réponses portent pour cela deux messages : « message » t'est adressé, « messagePourAcheteur » est prêt à afficher tel quel. N'affiche jamais « message » ni « error » à un acheteur.
POST /api/v1/customers/register
Signale la création d'un compte acheteur : upsert du contact (source « compte ») et scénario de bienvenue s'il est activé.
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
POST /api/v1/reviews
Transmet un avis déposé par un acheteur ; refusé en 422 si aucun achat payé n'est prouvé (sauf réglage « ALL »).
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
POST /api/v1/withdrawals
Dépose la demande de rétractation d'un acheteur : le Hub l'horodate, l'enregistre, envoie l'accusé et prévient le gérant.
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
POST /api/v1/messages
Enregistre un message du formulaire de contact du site (statut NEW).
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
POST /api/v1/newsletter
Inscrit une adresse à la lettre d'information (consentement), renvoie le code de bienvenue éventuel.
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
10. Reçois les changements au lieu d'interroger en boucle
Le Hub pousse ses événements vers l'adresse que tu déclares, et confirme la reconstruction quand elle a eu lieu. La réconciliation rattrape ce qu'un webhook aurait manqué sans rien écrire. Un site qui redemande tout le catalogue toutes les minutes fausse les statistiques du commerçant et se fera couper.
POST /api/v1/webhook
Déclare ou remplace la configuration du site (URL de webhook, secret, Deploy Hook, dépôt de médias, gabarits d'adresse, capacités). Idempotent, rejouable.
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
POST /api/v1/reconcile
Provoque une passe de réconciliation du catalogue et rend son résultat, avec l'état du Deploy Hook et de son rejeu.
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
POST /api/v1/deploy/confirmed
Le site déclare la version qu'il sert réellement après sa reconstruction (ou son échec).
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
DELETE /api/v1/webhook
Désactive la notification : efface l'URL de webhook, conserve le secret.
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
11. Reste à jour tout seul
Le Hub publie des entrées de contrat datées : ce sont les instructions qu'un site DÉJÀ branché doit appliquer pour ne pas vieillir. Relis le master prompt à chaque version du contrat, applique ce qui te concerne, et déclare la version que tu appliques. Un site qui ne déclare rien est un site qu'on croit à jour.
GET /api/v1/master-prompt
Le master prompt À JOUR, avec les valeurs de TA boutique. Ne contient jamais de jeton d'enrôlement.
Clé d'API de la boutique, en lecture. En-tête « Authorization: Bearer <clé> », depuis ton serveur et jamais depuis le navigateur.
PATCH /api/v1/settings
Écrit un ou plusieurs réglages de l'organisation (refus global au premier défaut) et rend l'état ENREGISTRÉ.
Clé d'API de la boutique AVEC droits d'écriture. Une clé en lecture seule reçoit 403 sur cette opération.
Une fois le site branché
- Déclare la version du contrat que ton site applique : c'est ainsi que le Hub sait qui est à jour.
- Relis le master prompt à chaque nouvelle version du contrat — il porte les instructions datées à appliquer.
- Traite tout avertissement de paramètre inconnu comme une erreur : il signifie que tu crois filtrer et que tu ne filtres pas.
Le détail de chaque route
Cette page dit l'ordre et la raison. La forme exacte de chaque réponse — paramètres, corps, codes d'erreur — se lit dans la référence de l'API, et en machine par GET https://www.structureweb.fr/api/v1/specification.