Aller au contenu

#Atelier, transfert et devis

Les routes que la portée atelier ouvre aux clés d'API — ce que le CLI appelle pour construire un site et le remettre à sa cliente. Même authentification que le reste (Authorization: Bearer wc_…, X-Webcosa-Site-Cible pour désigner le site), même forme d'erreur.

Une clé atelier ne se délivre qu'à un compte partenaire ou agence (POST /api/cles répond 403 portee_reservee sinon). Elle couvre aussi tout ce que themes couvrait.

#Sites

RouteCe qu'elle fait
POST /api/sitescrée un site. Corps { nom, slug?, theme?, metier?, pour? }. Un partenaire le crée en atelier (formule atelier, rien de facturé, pas d'essai) ; un client, dans la limite de sa formule ; l'agence peut ajouter proprietaire. pour: { courriel?, formule?, presence?, devis_id? } pose l'intention « pour une cliente » : elle préremplit le transfert et relie le devis au site
GET /api/sitesles sites accessibles : { id, slug, name, status, role, proprietaire, formule, etat, presence }
POST /api/sites/publierdraft → live. Refusé si le site attend son paiement (402 site_a_activer) ou est suspendu
POST /api/sites/transfertenvoie « Reprenez votre site ». Corps { courriel, formule: depart|pro|croissance, presence?, message?, devis? } — chaque champ absent est pris dans le pour de la création. Propriétaire + partenaire, site en atelier
GET /api/sites/transfertle transfert vivant, ou null — jamais l'empreinte du lien. ouvert_le / ouvertures : la cliente a demandé son code
PATCH /api/sites/transfert{ action: "renvoyer" } : jeton neuf, l'ancien meurt, trois par jour
DELETE /api/sites/transfertannule
GET /api/sites/maquettela maquette du site, ou null : { maquette: { prospect, expire_le, etat: active|echue|expiree, whatsapp, devis_id, activer_vers_devis, visites, pages_vues, derniere_visite_le, expiree_le, medias_supprimes }, code_pose } — jamais le lien du devis
PUT /api/sites/maquettepose ou modifie le mode maquette. Corps { prospect?, expire?, prolonger?, whatsapp?, devis? } : prospect (1 à 80 caractères, obligatoire à la création), expire en jours (21, le défaut) ou en date (2026-12-08, jusqu'au soir, heure de Paris), prolonger en jours à partir de l'échéance en cours — trois mois au plus devant soi ; whatsapp un portable (null le retire), devis un identifiant ou un numéro WC-… de ce partenaire (null le retire). Propriétaire + partenaire, site en atelier. devis_a_renvoyer: true : le devis était déjà parti, son lien n'est connu qu'en empreinte — le renvoyer (POST /api/devis/<id>/envoyer) donne son lien à « Activer »
DELETE /api/sites/maquetteretire le mode maquette ; le site reste tel quel, avec son code d'accès

theme doit être un identifiant du catalogue (vela, origo, fondant…) ; sinon 400 theme_inconnu avec la liste themes.

#Contenu

RouteCe qu'elle fait
GET /api/pages, POST /api/pagesle routage des pages ; POST { title, slug? }. Une adresse que la plateforme sert avant toute page est refusée (409 adresse_reservee, avec un message) : blog, legal, password, api, theme-assets, h, d, p, s, o, index, page, les cibles des robots malveillants — une telle page ne s'afficherait jamais
PATCH /api/pages/<id>, DELETE, POST /api/pages/<id>/publishtitre, adresse, SEO, accueil, indexable (false : la page reste servie, en noindex, follow, hors du plan et de llms.txt ; 409 migration_requise avant la mise à jour de la base) ; corbeille ; publication. Une nouvelle adresse emporte la mise en page (templates/<adresse>.json de chaque thème du site, sans jamais écraser un gabarit déjà présent à la nouvelle), les liens du menu et, toujours, une 308 depuis l'ancienne (rediriger est accepté et ignoré) ; la réponse dit ce qui a suivi (renommage). Mettre en ligne par ce PATCH (status: "published", is_home) sur un site inactif répond 402 site_inactif, comme publish. Renommer vers une adresse réservée : 409 adresse_reservee. Après la réponse, la page est relue par l'adresse du site et annoncée aux moteurs — voir Publier
PATCH /api/pages/referencementle référencement de plusieurs pages en une requête : { pages: [{ id, seo }] }, 1 à 60 pages, seo complet (déjà fusionné) ; même permission que la route unitaire, pages à la corbeille refusées, cache public purgé une fois. Le champ seo (ici comme dans PATCH /api/pages/<id>, /api/posts/<id> et /api/blogs/<id>) est validé : title (une ligne, 300 signes), description (1 000 signes), image (une ligne), d'autres clés conservées ; l'ancienne clé titre est acceptée et versée dans title quand celui-ci est vide — 400 invalid_input sinon
GET /api/menus, PATCH /api/menus{ slug: "main-menu" | "footer-menu", content: { items } }, le menu entier. garde: { site, majLe } facultatif : 409 autre_site ou 409 modifie_entre_temps si le site ou le menu a changé depuis la lecture (updated_at)
GET /api/parametres/<onglet>, PATCHgeneral, contact, seo, legal, suivi, acces, ia ; { content }, le bloc entier. Des champs ajoutés depuis sont facultatifs et conservés quand l'envoi les omet : general.icone (l'icône d'onglet), general.langue (la langue des pages, fr), seo.imagePartage (l'image de partage par défaut), seo.auteur ({ nom, url? } : la personne qui signe les articles — url un chemin du site, /agence, ou une adresse https:// ; elle devient l'author Person du BlogPosting et la ligne « Par … » du blog, l'entreprise restant l'éditeur), seo.fondateur (booléen : une boutique dont la forme juridique est une société publie son dirigeant en founder Person — une entreprise individuelle le publie d'office, son nom étant déjà dans ses mentions légales), contact.horairesDetail (les horaires jour par jour, lundi d'abord), contact.whatsapp (le bouton WhatsApp), contact.pays (FR), contact.activite (l'activité précise, plombier), contact.zone ({ communes: [{ nom, code?, codePostal?, departement? }], rayonKm }, 50 communes, 1 à 300 km), contact.reseaux ({ instagram, facebook, linkedin, pinterest, youtube, tiktok, googleBusiness, pagesJaunes }, chaque lien vérifié et ramené à l'adresse du profil) ; "" retire une image, null les horaires. contact.position est calculée par le serveur à partir de l'adresse (API Adresse, France seulement) et rendue dans la réponse ; un envoi ne compte que s'il pose une position source: "manuel" nouvelle, ou null pour revenir au calcul. legal.siret refuse quatorze chiffres qui ratent la clé de contrôle. ia règle les robots d'IA du robots.txt du site : { gere, chatgpt, perplexity, claude, gemini, entrainement }, six booléens ; gere: true (le défaut) laisse la plateforme décider et ignore les cinq autres, false ferme chaque assistant à false (gemini = Google-Extended, entrainement = GPTBot, ClaudeBot, CCBot). garde: { site, majLe } facultatif, comme pour les menus
GET /api/fiche-google, PATCHla fiche Google préparée (bloc settings/fiche-google, privé) : { accueil: "oui" | "non" | null, zones[] (20), categories: { principale, secondaires[] (9) }, description (750 signes, "" : celle écrite des faits du site), services[] (30), ouverture ("2019" ou "2019-04"), photos: { logo, couverture, autres[] (10) } (des noms de fichiers de la médiathèque du site), etapes[] }. Un PATCH n'envoie que ce qui change. lien relie la fiche : le lien « Partager » de Maps (maps.app.goo.gl/…), g.page/…, google.<pays>/maps/place/…, ?cid=, ou le lien d'avis g.page/r/<id>/review ; il s'écrit dans contact.reseaux.googleBusiness (donc dans sameAs, et en hasMap d'une entreprise située), null le retire. Un maps.app.goo.gl est suivi chez Google (trois sauts, hôtes de Google seulement) : 422 lien_invalide s'il ne mène pas à une fiche. lienAvis : le lien « Laisser un avis » seul. 400 lien_invalide avec raison pour toute autre adresse
GET /api/fiche-google/photosle pack photo en ZIP : le logo (720 × 720, entier sur fond blanc), la couverture (1 080 × 608), les photos (1 200 px sur le grand côté, 720 au moins sur le petit, jamais agrandies), JPG ou PNG de 10 Ko à 5 Mo, sans EXIF ni GPS, aux noms descriptifs (lyvora-agence-web-paris-mayalice.jpg), plus fiche-google.txt. Une image trop petite est écartée et nommée dans le texte ; 400 aucune_image, 422 aucune_image_valable
GET /api/bing/webmaster, POST, DELETEBing Webmaster Tools, une fois branché depuis le CMS (OAuth, /api/connecteurs/bing/demarrer) : GET rend { suivi: { plans: [{ url, statut, soumisLe, luLe, adresses }], exploration: { le, pagesExplorees, dansIndex } } } ou { suivi: null } ; POST rejoue l'ajout du site, sa validation (le code de Bing posé dans seo.verificationBing) et l'envoi de sitemap.xml — { reglages, en_attente }, 409 absent, 409 hors_ligne ; DELETE débranche (la balise reste). Permission facturation, comme les autres branchements
PUT /api/parametres/politiques/<cle>, DELETEune politique publiée à /legal/<cle> (mentions-legales, confidentialite, cgv, retours, conditions-utilisation, cookies) ; { contenu }, un document Tiptap ({ type: "doc", content } — paragraphes, titres 2 et 3, listes, citations, gras, italique, barré, liens ; le reste est retiré). DELETE rend la page au document rédigé d'office (mentions légales, confidentialité) ou la retire. 400 vide pour un texte vide, 503 migration_manquante tant que la base n'a pas la 0120
PUT /api/theme/compositionune page validée contre les schémas de section
POST /api/fichiers/televersermultipart/form-data, champ fichier (JPEG, PNG, WebP, AVIF, 5 Mo). L'image est compressée avant d'être écrite : redressée, 2 560 px au plus sur son grand côté (jamais agrandie), réencodée dans son format — et gardée seulement si elle reste visuellement identique (SSIM ≥ 0,985, aucun carreau de 64 px sous 0,95) et pèse au moins 10 % de moins ; sinon l'original est gardé. Les métadonnées partent dans tous les cas (GPS, boîtier, auteur), le profil de couleur et l'orientation restent. Le chemin peut donc changer d'extension (une photo enregistrée en PNG devient un .jpg). Rend { fichier: { path, publicUrl, sizeBytes, … }, compression: { octetsAvant, octetsApres, ssim, raison, gpsRetire } } ; 415 fichier_refuse si les octets ne sont pas une image acceptée, 422 fichier_illisible

Les textes d'une page vivent dans templates/<adresse>.json du thème publié : PUT /api/themes/<id>/fichiers les écrit, comme n'importe quel fichier de thème.

#Blog et redirections

Lister et lire : une clé lecture suffit. Le reste : atelier. Chaque route filtre sur le site désigné par X-Webcosa-Site-Cible, revalidé contre les sites du porteur ; un identifiant de blog reçu n'est cru qu'après lecture sur ce site.

RouteCe qu'elle fait
GET /api/blogs{ blogs: [{ id, slug, titre, description, seo, position }] }
POST /api/blogs{ titre, slug?, description? }. Le deuxième blog demande la capacité blogs_multiples (402 formule_insuffisante) ; 409 slug_pris
PATCH /api/blogs/<id>, DELETE /api/blogs?id=renommer (titre, slug, description, seo) — l'ancienne adresse redirige, ses articles suivent ; supprimer (les articles sont détachés, pas effacés)
GET /api/postsles articles, brouillons compris, sans leur corps
GET /api/posts/<id>l'article, corps compris (content, document de l'éditeur)
PUT /api/postscrée ou met à jour un article par son adresse. Corps { slug, blog, titre, format: "markdown" | "html", contenu, extrait?, description?, couverture?, couverture_alt?, publie_le?, modifie_le?, publier? }. Idempotent : sans changement, rien n'est écrit (modifie: false). Rend { post, adresse, cree, modifie, publie, constats? } — constats compte ce que la liste blanche a retiré. 404 blog_inconnu (avec blogs), 422 image_hors_mediatheque (avec images : toute image, couverture comprise, doit être dans site-media/<site>/), 422 corps_illisible, 400 date_invalide (illisible ou future). publie_le est gardée ; modifie_le ne vaut qu'à la création
PATCH /api/posts/<id>, DELETE, POST /api/posts/<id>/publishcomme l'éditeur : champs, status: "draft" pour dépublier, programme_le (date ISO à venir, null pour déprogrammer — l'article reste brouillon jusque-là, 400 date_passee sinon), etiquettes (30 au plus, 40 signes chacune) ; suppression — rend corbeille: true quand l'article est gardé dans la corbeille ; publication (la date de première publication est gardée)
POST /api/posts/<id>/corbeille, DELETErestaure un article de la corbeille (même id ; son adresse reprise entre-temps → suffixe -2 et brouillon) ; l'efface pour de bon
GET /api/redirections{ redirections: [{ id, depuis, vers, permanente, note, cree_le }] }, 5 000 au plus
POST /api/redirectionsune règle { depuis, vers, permanente?, note? }, par le moteur : un saut, ni chaîne ni boucle (400 boucle)
POST /api/redirections/migration{ action: "csv", texte } : un CSV depuis,vers, 2 000 lignes au plus (400 trop_de_lignes, rien d'écrit). Rend { ecrites, resultats: [{ ligne, depuis, vers?, ok, message?, avertissement? }] }
DELETE /api/redirections?id=retire une règle

Écrire, publier ou supprimer purge le cache du site concerné et relit les adresses touchées après la réponse, comme depuis le CMS.

#Devis

RouteCe qu'elle fait
POST /api/devisun brouillon. Corps : { site_id?, cliente: { nom, courriel, entreprise?, adresse?, code_postal?, ville?, siret? }, objet, formule, presence?, inclus[], delais?, validite_jours?, mise_en_route_cents?, corrections_heure_cents? }
GET /api/devisles devis du compte
GET /api/devis/<id ou numéro>le devis, une URL de PDF valable cinq minutes, et evenements[] — le journal : cree, modifie, envoye, renvoye, ouvert, code_demande, signe, refuse, paye, annule, expire, chacun avec cree_le et un detail (le motif d'un refus, par exemple). Le devis porte aussi ouvert_le, ouvertures, refuse_le, refus_motif
GET /api/devis/<id>/pdfle PDF lui-même — le signé s'il existe ; un brouillon se rend à la volée (aperçu) — servi par notre domaine, inline
GET /api/devis/completer?siret=… ou ?adresse=…remplir la cliente : l'entreprise et son adresse d'après le SIRET (annuaire des entreprises), ou des adresses complètes en tapant (Base Adresse Nationale) — { entreprise, adresse, code_postal, ville, siret } / { adresses: [{ label, adresse, code_postal, ville }] }
PATCH /api/devis/<id>tant qu'il est brouillon
POST /api/devis/<id>/envoyerrend le PDF, pose le lien de signature, envoie le courriel
DELETE /api/devis/<id>annule (jamais un devis signé)

Le numéro est WC-AAAA-NNNN. La facture, elle, est émise par Stripe au paiement.

#La signature — publique

Ces routes n'ont ni clé ni session : le jeton du lien reçu par la cliente est l'autorisation. Elles répondent sur signature.webcosa.com comme sur le CMS.

RouteCe qu'elle fait
GET /api/signature/<jeton>le devis tel que la page l'affiche, peutSigner, peutPayer, URL du PDF
POST /api/signature/<jeton>/otpenvoie un code à six chiffres à l'adresse du devis (cinq par heure)
POST /api/signature/<jeton>/signer{ nom, code, consentement: true, demarrageImmediat: true }. Empreinte SHA-256 du PDF, horodatage RFC 3161, PDF signé, ligne de preuve
POST /api/signature/<jeton>/payerStripe Checkout, paiement unique, facture Stripe. Exige un devis signé
POST /api/signature/<jeton>/ouvert« la page a été affichée » — appelée par le navigateur au montage, jamais au rendu serveur (les antivirus suivent les liens). Compte les ouvertures ; le partenaire est prévenu à la première
POST /api/signature/<jeton>/compte{ motDePasse } (8 caractères au moins), sur un devis réglé : créez le compte Webcosa à l'adresse du devis (déjà prouvée par le code de signature), le relie au devis (compte_id), journalise acces_cree. 409 compte_existant si l'adresse a déjà un compte (relié au passage) ; 409 devis_non_paye avant le paiement
POST /api/signature/<jeton>/refuser{ motif? } (600 caractères). Le devis passe refuse, la signature se ferme, le partenaire reçoit le mot. Sans code : refuser n'engage à rien

#La reprise d'un site — publique

POST /api/transferts/code avec { jeton } envoie un code de connexion à l'adresse du transfert — et crée le compte s'il n'existe pas. La réponse est la même que le jeton existe ou non. L'acceptation (POST /api/transferts/accepter) exige une session à cette adresse.

#Codes d'erreur propres à l'atelier

errorStatutSignification
portee_reservee403une clé atelier demandée par un compte qui n'est ni partenaire ni agence
partenaire_requis403la route exige un partenaire ou l'agence
theme_inconnu400theme n'est pas dans le catalogue (themes liste les valeurs)
transfert_en_attente409cette adresse a un site qui l'attend : elle passe par le lien de reprise, pas par une création
site_hors_atelier409le site n'est plus en atelier, il ne se transfère pas
transfert_deja_envoye409un transfert vivant existe déjà (renvoyer ou annuler)
transfert_a_soi_meme400l'adresse est celle du partenaire
site_a_activer402le site attend son premier paiement : rien ne le met en ligne d'ici là
prospect_requis, prospect_invalide400une maquette se pose pour quelqu'un : 1 à 80 caractères
echeance_invalide, echeance_ambigue400l'échéance est passée, dépasse trois mois, ou expire et prolonger sont donnés ensemble
whatsapp_invalide400ni un portable français, ni un numéro international
devis_introuvable404ce devis n'existe pas ou n'est pas à ce partenaire
maquette_indisponible503le mode maquette n'est pas encore ouvert sur la plateforme
devis_fige409le devis n'est plus brouillon (ou est signé, payé, annulé)
devis_non_signe409paiement demandé avant la signature
devis_non_refusable409seul un devis envoyé se refuse
code_faux, code_expire, code_epuise403le code de signature