Référence de l’API publique

Référence de l’API publiqueLes quatre routes d’ingestion d’INOTRACK, telles qu’elles répondent aujourd’hui. Elles vivent hors du préfixe /v1 : ce sont des points d’entrée machine, appelés depuis vos pages ou depuis votre serveur.

Base : https://messagerie.inovertix.com

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

Si vous cherchez le pas-à-pas d’installation plutôt que la référence, commencez par Brancher un site en 5 minutes.Les deux clésChaque site dispose d’une paire de clés, visible dans CONTROL → INOTRACK → Sites & clés → onglet Intégration.

Clé	Forme	Où elle vit	Ce qu’elle autorise
Publique	`INOTRK_PUB_…`	Dans la page, visible de tous	Envoyer de la navigation et des étapes de tunnel
Secrète	`INOTRK_SEC_…`	Sur votre serveur, jamais dans le navigateur	La même chose, plus les statuts de commande

Attention

Une clé secrète transmise dans l’URL est refusée (401 secret_key_in_url). Elle se retrouverait sinon dans les journaux d’accès, les référents et l’historique du navigateur. Utilisez l’en-tête.

Trois emplacements acceptés

Emplacement	Exemple	Quand l’utiliser
`Authorization`	`Authorization: Bearer INOTRK_SEC_votre_cle_secrete`	Appels serveur → serveur
En-tête dédié	`X-Inotrack-Key: INOTRK_PUB_votre_cle`	Clients HTTP qui réservent `Authorization`
Paramètre d’URL	`?k=INOTRK_PUB_votre_cle`	Clé publique uniquement — c’est ce que fait le traqueur

Contrôle d’origineUne clé publique n’est acceptée que depuis un domaine déclaré sur le site (CONTROL → INOTRACK → Sites & clés → Domaines autorisés). Sinon : 403 origin_not_allowed.Le CORS est traité par site : votre domaine, et lui seul, reçoit les en-têtes d’autorisation.TransportLe traqueur envoie ses lots en Content-Type: text/plain avec la clé en ?k=. Ce n’est pas une négligence : un text/plain sans en-tête personnalisé est une requête simple au sens CORS, donc sans requête préliminaire. Une page vue coûte un aller-retour au lieu de deux.Vos propres appels peuvent utiliser application/json sans réserve : les deux formats sont acceptés partout.Limites de charge : 32 Ko par corps de requête, profondeur JSON maximale de 6, 50 événements par lot.GET /api/inotrack/pingLe test d’installation. Répond que la clé est valide et à quel site elle appartient.

bash

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

json

{
  "ok": true,
  "site": { "name": "Ma boutique", "slug": "ma-boutique", "timezone": "Africa/Lome", "currency": "XOF" },
  "kind": "public",
  "server_time": "2026-08-13T09:12:44+00:00"
}

Débit : 120 requêtes/min par site.POST /api/inotrack/collectUn lot d’événements de navigation. C’est l’appel que fait le traqueur à chaque page vue.

Champ	Obligatoire	Description
`session.uid`	oui	Identifiant de session, 64 caractères maximum. C’est lui qui relie les événements entre eux
`events`	oui	Tableau de 1 à 50 événements

bash

curl -sS -X POST "https://messagerie.inovertix.com/api/inotrack/collect?k=INOTRK_PUB_votre_cle" \
  -H "Content-Type: text/plain" \
  --data-raw '{"session":{"uid":"s_9f2c…"},"events":[{"type":"pageview","url":"https://exemple.com/produit/42"}]}'

Réponse 202 :

json

{ "ok": true, "accepted": 1 }

Attention

Cette route ne casse jamais un site client. Une charge utile partiellement invalide n’annule pas le lot : les événements lisibles sont écrits, les autres ignorés. Une erreur interne de CONTROL répond quand même 202 — le navigateur n’en ferait rien, et le problème se traite de notre côté.

Code	`name`	Cas
`202`	—	Lot pris en compte
`413`	`payload_too_large`	Corps au-delà de 32 Ko
`422`	`validation_error`	`session.uid` absent, ou lot vide
`422`	`batch_too_large`	Plus de 50 événements
`422`	`invalid_json`	JSON illisible ou trop imbriqué

Débit : 600 requêtes/min par site. C’est la seule route appelée à chaque page vue de chaque visiteur, elle a donc sa propre limite.POST /api/inotrack/funnelUn franchissement d’étape du tunnel. Contrairement à /collect, les erreurs sont explicites : une étape mal nommée doit se voir pendant l’intégration, pas une semaine plus tard devant un tunnel vide.

Champ	Obligatoire	Description
`session_uid`	oui	La session concernée (`session.uid` est aussi accepté)
`step_key`	oui	Identifiant de l’étape, déclarée au préalable dans CONTROL (`step` est aussi accepté)
`data`	non	Objet libre : montant, référence, produits… Profondeur maximale 6

bash

curl -sS -X POST https://messagerie.inovertix.com/api/inotrack/funnel \
  -H "Authorization: Bearer INOTRK_SEC_votre_cle_secrete" \
  -H "Content-Type: application/json" \
  -d '{"session_uid":"s_9f2c…","step_key":"commande_validee","data":{"amount":24500,"order_ref":"CMD-1042"}}'

Réponse 202 :

json

{ "ok": true, "step": "commande_validee" }

Code	`name`	Cas
`202`	—	Étape enregistrée
`422`	`validation_error`	`session_uid` ou `step_key` manquant
`422`	`unknown_step`	L’étape n’est pas déclarée pour ce site — créez-la dans CONTROL, onglet Étapes du tunnel
`422`	`payload_too_deep`	`data` trop imbriqué
`500`	`server_error`	Étape non enregistrée

Débit : 120 requêtes/min par site.POST /api/inotrack/order-statusLe changement de statut d’une commande — c’est lui qui alimente le taux de livraison.

Attention

Clé secrète obligatoire. Ce canal décide d’un chiffre affiché à nos clients : il n’est pas ouvert au navigateur. Une clé publique reçoit 403 secret_key_required.

Un seul objet, ou un lot :

Champ	Obligatoire	Description
`order_ref`	oui	Votre référence de commande (`order_id` est aussi accepté)
`status`	oui	Le statut, tel que vous le nommez
`orders`	non	Tableau des deux champs ci-dessus — 200 commandes maximum par lot

bash

curl -sS -X POST https://messagerie.inovertix.com/api/inotrack/order-status \
  -H "Authorization: Bearer INOTRK_SEC_votre_cle_secrete" \
  -H "Content-Type: application/json" \
  -d '{"orders":[{"order_ref":"CMD-1042","status":"delivered"},{"order_ref":"CMD-1043","status":"cancelled"}]}'

json

{ "ok": true, "updated": 2, "ignored": 0 }

Une commande inconnue de CONTROL n’est pas une erreur : elle est comptée dans ignored. Le 422 n’arrive que si aucune commande du lot n’était exploitable.Débit : 120 requêtes/min par site.Codes d’erreur d’authentificationCommuns aux quatre routes, et volontairement précis : une clé révoquée, une clé d’un autre module et une clé inventée sont trois situations différentes.

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é INOTRACK — un marqueur `INOTRK_PUB_votre_cle` non remplacé ?
`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é