Référence de l’API publique

Référence de l’API publiqueLes points d’entrée publics d’INODESK, tels qu’ils répondent aujourd’hui. Ils vivent hors du préfixe /v1 : ce sont des surfaces machine, appelées depuis vos pages ou depuis votre application métier.

Base : https://messagerie.inovertix.com

Format d’erreur : { "statusCode", "name", "message" } — identique dans tous les modules de CONTROL.

Pour le pas-à-pas d’installation, voir Démarrage en 5 minutes.Trois régimes d’authentificationINODESK n’a pas un mais trois modes d’accès, et c’est structurant :

Régime	Comment on s’identifie	Pour quoi
Clé	`INODSK_PUB_…` (navigateur) ou `INODSK_SEC_…` (serveur)	Widget, formulaires, avis, suivi de commande
Portail	Le slug du site, aucune clé	Les pages `/care/…` hébergées par CONTROL
Lien magique	Un jeton dans l’URL	Le fil d’un ticket, un devis, une enquête

Le second et le troisième ne vous concernent que si vous liez vers eux : ce sont nos pages, pas les vôtres.Emplacements acceptés pour la clé

Emplacement	Exemple
`Authorization`	`Authorization: Bearer INODSK_SEC_votre_cle_secrete`
En-tête dédié	`X-Inodesk-Key: INODSK_PUB_votre_cle`
Paramètre d’URL	`?k=INODSK_PUB_votre_cle` — clé publique uniquement

Attention

Une clé secrète dans l’URL est refusée (401 secret_key_in_url). Une clé publique n’est acceptée que depuis un domaine déclaré sur le site, sinon 403 origin_not_allowed.

GET /api/inodesk/pingLe test d’installation.

bash

curl -sS "https://messagerie.inovertix.com/api/inodesk/ping?k=INODSK_PUB_votre_cle"

json

{
  "ok": true,
  "site": { "name": "Mon site", "slug": "mon-site", "timezone": "Africa/Lome" },
  "kind": "public",
  "server_time": "2026-08-13T09:12:44+00:00"
}

Débit : 120 requêtes/min par site.GET /api/inodesk/configTout ce dont le widget a besoin pour se dessiner, en une seule requête : habillage, onglets, formulaires et leurs champs, horaires ouvrés, limite de pièce jointe.Utile même si vous n’utilisez pas notre widget : c’est là que vous lisez la définition des champs d’un formulaire pour construire le vôtre.

json

{
  "site": { "name": "…", "slug": "…", "timezone": "Africa/Lome", "portal_enabled": true },
  "branding": { "…": "couleurs, logo, nom affiché" },
  "widget": { "…": "onglets activés, position, textes" },
  "business_hours": { "days": [1,2,3,4,5], "start": "08:00", "end": "18:00", "open_now": true },
  "honeypot_field": "inodesk_website",
  "max_attachment_bytes": 5242880,
  "forms": [
    { "slug": "contact", "name": "Contact", "type": "contact", "fields": [], "success_message": "…" }
  ],
  "portal_url": "https://…/care/mon-site"
}

À noter

honeypot_field est publié volontairement : le formulaire doit rendre ce champ caché, sinon l’anti-spam n’a rien à observer. Le connaître ne l’affaiblit pas — un robot qui l’évite se fait prendre par les trois autres signaux.

Débit : 120 requêtes/min par site.POST /api/inodesk/submissionsL’envoi d’un formulaire. C’est l’appel principal d’une intégration.

Champ	Obligatoire	Description
`form_slug`	oui	Identifiant du formulaire dans CONTROL (`form` est aussi accepté)
`data`	oui	Objet des valeurs saisies. À défaut, le corps entier est pris comme `data`

Les pièces jointes s’envoient en multipart/form-data, dans le champ files[].

bash

curl -sS -X POST "https://messagerie.inovertix.com/api/inodesk/submissions?k=INODSK_PUB_votre_cle" \
  -H "Content-Type: application/json" \
  -d '{"form_slug":"contact","data":{"nom":"Awa","email":"awa@exemple.com","message":"Bonjour"}}'

Réponse 202 :

json

{
  "ok": true,
  "accepted": true,
  "message": "Merci, votre message a bien été envoyé. Nous vous répondons rapidement.",
  "reference": "DSK-1042",
  "rejected_files": []
}

Code	`name`	Cas
`202`	—	Demande enregistrée
`422`	`validation_error`	`form_slug` manquant, `data` invalide, ou champ obligatoire absent (le message les nomme)
`422`	`unknown_form`	Formulaire inconnu ou désactivé pour ce site
`413`	`payload_too_large`	Corps trop volumineux

Attention

Les champs obligatoires sont contrôlés côté serveur, pas seulement dans le navigateur : un formulaire public est appelable sans passer par votre page. En revanche, une panne interne de CONTROL renvoie quand même 202 — votre site ne doit jamais afficher une erreur pour un problème qui n’est pas le sien.

Débit : 20 requêtes/min par site et par IP. C’est la limite qui protège une file traitée par des humains.POST /api/inodesk/ticketsL’ouverture directe d’une demande, sans passer par un formulaire déclaré. Deux appelants : l’onglet Support du widget (clé publique) et votre application métier (clé secrète).

Champ	Obligatoire	Description
`message`	oui	Le corps de la demande
`email`	selon le cas	Adresse du demandeur — refusée si syntaxiquement invalide

json

{ "ok": true, "reference": "DSK-1043", "track_url": "https://…/t/eyJ…" }

Attention

track_url n’est renvoyé qu’à une clé secrète. Côté navigateur, le lien de suivi part par email et n’apparaît jamais dans la page : c’est un lien magique, il vaut autorisation.

Code	`name`	Cas
`202`	—	Demande créée
`422`	`validation_error`	Message manquant, ou adresse email invalide
`500`	`server_error`	Demande non enregistrée

Débit : 20 requêtes/min par site et par IP.POST /api/inodesk/tracking« Suivre ma demande » : le visiteur donne son adresse, CONTROL lui envoie ses liens de suivi par email.

json

{ "email": "awa@exemple.com" }

La réponse est toujours la même, que l’adresse soit connue ou non :

json

{
  "ok": true,
  "message": "Si des demandes sont associées à cette adresse, un email vient de partir avec vos liens de suivi."
}

Attention

C’est délibéré. Une réponse différenciée transformerait ce formulaire en oracle : « cette adresse a-t-elle déjà écrit à cette marque ? » n’est pas une question à laquelle un inconnu doit pouvoir obtenir une réponse.

Débit : 20 requêtes/min par site et par IP.Avis publics

Route	Ce qu’elle fait
`GET /api/inodesk/reviews`	Les avis publiés d’un site — note moyenne, nombre, témoignages. C’est ce que lit le mur d’avis embarquable
`POST /api/inodesk/reviews`	Dépôt d’un avis depuis le widget

Le balisage schema.org qui fait apparaître les étoiles dans les résultats de recherche est détaillé dans Avis clients et référencement.Débit : 120 requêtes/min en lecture, 20/min en dépôt.Suivi de commande

Route	Ce qu’elle fait
`POST /api/inodesk/order-lookup`	Recherche d’une commande à partir des informations du client
`POST /api/inodesk/order-issue`	Signalement d’un problème sur une commande retrouvée

Attention

Débit volontairement bas : 6 requêtes/min par IP. C’est la seule route publique qui interroge des commandes réelles à partir d’informations qu’un tiers pourrait tenter de deviner. S’y ajoutent un verrouillage après plusieurs échecs et un plancher de temps de réponse — une recherche qui aboutit et une qui échoue prennent le même temps.

Codes d’erreur d’authentification

Code	`name`	Ce que ça veut dire
`401`	`missing_api_key`	Aucune clé transmise
`401`	`malformed_api_key`	La valeur n’a pas la forme d’une clé INODESK
`401`	`wrong_module_key`	C’est une clé d’un autre module de CONTROL
`401`	`invalid_api_key`	Clé inconnue, ou clé d’un autre site
`401`	`revoked_api_key`	Clé révoquée — le message indique la date
`401`	`secret_key_in_url`	Clé secrète passée en `?k=`
`403`	`site_inactive`	Le site est désactivé dans CONTROL
`403`	`secret_key_required`	Route réservée à la clé secrète
`403`	`origin_not_allowed`	Domaine non déclaré pour cette clé publique
`429`	`rate_limit_exceeded`	Débit dépassé