API de conversions

Envoi de conversions depuis votre backend, sans dépendre du pixel (ad-blockers, achats validés hors navigateur, paiements différés). La conversion est rattachée à la session la plus récente du visiteur dans la fenêtre d’attribution du site, puis passe par le même pipeline d’attribution que les événements du pixel.

Le contrat complet au format machine est disponible dans la référence API (OpenAPI).

Endpoint

POST /api/sites/:siteId/conversions

• siteId : l’UUID du site (visible dans le dashboard) — pas l’identifier du tracker.

Authentification

Authorization: Bearer ask_xxxxxxxxxxxxxxxx

Les clés API se créent dans le dashboard : Settings → API Keys. Elles sont scopées au tenant : le site ciblé doit appartenir au tenant de la clé (sinon 403). Les clés commencent par ask_ et sont stockées hachées (impossible de les réafficher — conservez-les à la création).

Corps de la requête

Content-Type: application/json

Champ	Type	Obligatoire	Description
clientId	string	l’un des trois¹	L’id utilisateur passé à identify() côté pixel — clé de jointure recommandée
visitorId	string	l’un des trois¹	Valeur du cookie _astr_vid (fallback)
sessionId	string	l’un des trois¹	Id de session (fallback)
orderId	string	requis si type = "purchase"	Id de commande, unique par site. Clé de déduplication avec les événements du pixel : une même commande envoyée par le pixel et par le serveur n’est comptée qu’une fois
type	string	non	Type de conversion, défaut "purchase"
value	number	non	Montant, ≥ 0
currency	string	non	ISO 4217, défaut "USD"
occurredAt	string	non	ISO 8601, défaut : maintenant (date de validation de la commande)

¹ Au moins un des trois identifiants (clientId, visitorId, sessionId) est requis pour résoudre la session.

Exemple

curl -X POST "https://tracker.adstrike.io/api/sites/9b2f1c3a-....-....-....-............/conversions" \
  -H "Authorization: Bearer ask_xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "USER_12345",
    "orderId": "ORDER-10042",
    "type": "purchase",
    "value": 129.5,
    "currency": "EUR",
    "occurredAt": "2026-07-22T10:32:00Z"
  }'

Réponses

Code	Signification	Corps
202	Conversion acceptée et mise en file	{ "success": true, "sessionId": "...", "eventId": "..." }
400	Erreur de validation (champ manquant/invalide)	{ "error": "..." }
401	Clé API absente ou invalide	{ "error": "..." }
403	Le site n’appartient pas au tenant de la clé	{ "error": "..." }
404	Site inconnu	{ "error": "..." }
422	Aucune session résoluble à partir des identifiants fournis (visiteur inconnu ou hors fenêtre d’attribution)	{ "error": "..." }
503	File d’attente indisponible — réessayer (backoff exponentiel recommandé)	{ "error": "..." }

Le 202 signifie « accepté et mis en file » : le traitement (attribution, conversion de devise) est asynchrone.

Bonnes pratiques

• Appelez l’API à la validation de la commande, pas au checkout. Une conversion envoyée au moment du paiement confirmé/validé garantit que les commandes annulées ou échouées ne sont jamais comptées.

• Envoyez toujours orderId + clientId. orderId rend l’appel idempotent (retries sûrs, dédup avec le pixel) ; clientId est la clé de jointure la plus fiable, y compris cross-device.

• Laissez le pixel purchase actif. Les deux sources sont complémentaires : le pixel couvre le temps réel côté navigateur, le serveur couvre les cas où le pixel est bloqué. La déduplication par orderId/tid rend l’ensemble idempotent — même commande = une seule conversion.

• Maximisez la couverture d’identify(). Plus tôt identify() est appelé côté site (via la file pré-init), plus la résolution de session par clientId est fiable :

  (window.adstrikeQ = window.adstrikeQ || []).push(["identify", "USER_12345"]);

  Voir tracker.md.

• Gérez le 422 avec UN retry différé pour les commandes fraîches. Juste après un achat, le batch du pixel qui crée la session peut encore être en vol — réessayez une fois après 1–2 minutes. S’il persiste, traitez-le comme permanent (l’utilisateur n’a jamais visité le site avec le pixel actif) ; seul le 503 justifie des retries avec backoff.