API Call Tracking

Introduction #

L'API Optico Call Tracking vous permet de remplacer les numéros de téléphone de votre site par des numéros de tracking pour générer des revenus supplémentaires et mesurer l'attribution. Vous appelez l'API avec les informations de visite et les numéros de téléphone, et l'API répond avec les numéros de tracking à afficher. Tout au long de cette documentation, l'API est désignée par OSP.

Fonctionnement

Votre système transmet les informations de visite à OSP à chaque chargement de page : URL de la page, URL de référence, adresse IP. OSP les utilise pour regrouper les appels en vues de page et en visites, et pour suivre les sources de trafic, les mots-clés et le trafic mobile. Une visite représente une session utilisateur et peut contenir une ou plusieurs vues de page. Chaque vue de page peut générer un ou plusieurs appels.

OSP suit la conversion des vues en appels et expose les statistiques dans l'interface client. Pour les visiteurs venant d'un moteur de recherche ou d'une campagne Google Ads, le mot-clé d'origine est enregistré sur l'appel, ce qui vous permet de voir lesquels mènent aux conversations les plus rentables.

Transport & conventions

Démarrage #

1. Créez un compte sur www.optico.fr : vous recevrez un nom d'utilisateur, un mot de passe, une clé API, et l'accès à la plateforme back-end pour la gestion.
2. Intégrez l'API pour obtenir les numéros de tracking associés à vos téléphones. Appelez /ospView sur chaque page et utilisez les numéros de tracking renvoyés.

Authentification #

Chaque requête doit inclure votre api_key en tant que champ POST.

api_key=osp_3a8f1c5d7b2e4906a8c1f5d3b9e7042c

La clé API est délivrée lors de votre inscription sur www.optico.fr. Chaque domaine enregistré possède sa propre clé unique.

Erreurs #

Toutes les réponses d'erreur partagent la même structure, quel que soit l'endpoint :

{ "status": "AUTHENTICATION_ERROR", "errorMessage": "Invalid API key" }

Endpoints #

Concepts #

Le cookie visitId

Stockez le visitId renvoyé par ospView dans un cookie et envoyez-le sur chaque requête suivante de la même session.

Modes d'affichage #

Il existe deux stratégies pour afficher les numéros de tracking aux visiteurs. Les deux peuvent coexister sur le même site, mais il faut conserver le même mode pour une page donnée. Le mode est contrôlé par le paramètre direct_display de /ospView.

POST /ospView #

Affichage Direct

Tous les numéros de téléphone de la page sont remplacés par des numéros de tracking au chargement de la page. Définissez direct_display=true et passez les numéros d'origine via le paramètre phones. OSP répond avec une correspondance des numéros d'origine vers les numéros de tracking dans surtaxPhones. Cela suppose que vous disposiez d'un nombre suffisant de numéros de tracking pour en attribuer un unique par visiteur et par numéro de téléphone.

Flux

Affichage Click

Avec l'affichage Click (direct_display=false), aucun numéro de téléphone n'est affiché par défaut sur la page : un texte tel que « Cliquer pour afficher le numéro » apparaît à la place de chaque numéro. Lorsqu'un visiteur clique sur ce lien, un appel AJAX est effectué vers votre serveur, qui demande un numéro de tracking à /ospClick et le renvoie au navigateur pour affichage.

Vous pouvez utiliser l'affichage Click avec ou sans tracking des informations de visite. Si vous souhaitez uniquement un numéro de tracking pour un téléphone, sans statistiques de visite, appelez directement /ospClick (en omettant view_id). Si vous souhaitez le tracking complet de la visite, appelez d'abord /ospView pour enregistrer la vue de page et obtenir un viewId, puis transmettez ce viewId à /ospClick.

Flux

Paramètres obligatoires

Affichage Direct : paramètres supplémentaires

Paramètres optionnels

Réponse en cas de succès

Exemples

Affichage Direct

curl -X POST https://www.optico.fr/ospView   -d "api_key=osp_3a8f1c5d7b2e4906a8c1f5d3b9e7042c"   -d "visit_id=0"   -d "ip=84.72.113.98"   -d "url=http://www.mysite.com/contact"   -d "page_title=Contact Us"   -d "is_mobile=false"   -d "referer_url=http://www.google.com/"   -d "nr_phones=2"   -d "direct_display=true"   -d "phones=0490260716,0450982756"   -d "user_agent=Mozilla/5.0 ..."
# → { "status": "OK", "visitId": 42, "surtaxPhones": { "0490260716": { "surtaxPhoneNumber": "01.02.03.04.05" } } }

Affichage Click

# Étape 1 : chargement de page
curl -X POST https://www.optico.fr/ospView \
  -d "api_key=osp_..." \
  -d "direct_display=false" \
  -d "visit_id=0" \
  -d "ip=84.72.113.98" \
  -d "url=http://www.mysite.com/contact" \
  -d "page_title=Contact Us" \
  -d "is_mobile=false" \
  -d "referer_url=http://www.google.com/" \
  -d "nr_phones=1" \
  -d "user_agent=Mozilla/5.0 ..."
# → { "status": "OK", "visitId": 42, "viewId": 101 }

# Étape 2 : au clic
curl -X POST https://www.optico.fr/ospClick \
  -d "api_key=osp_..." \
  -d "view_id=101" \
  -d "phone=0490260716"
# → { "status": "OK", "surtaxPhone": { "surtaxPhoneNumber": "01.02.03.04.05" } }

POST /ospClick #

Appelé côté serveur lorsqu'un visiteur clique pour révéler un numéro de tracking. Renvoie un numéro de tracking attribué à la demande pour le téléphone fourni. Pour le pattern d'intégration complet en deux étapes, voir Affichage Click.

Paramètres obligatoires

Paramètres optionnels

Réponse en cas de succès

POST /ospExpiration #

Utilisez ospExpiration pour prolonger ou libérer immédiatement un numéro de tracking actuellement attribué.

Paramètres obligatoires

Paramètres optionnels

Réponse en cas de succès

Exemple

# Prolonger de 10 minutes
curl -X POST https://www.optico.fr/ospExpiration \
  -d "api_key=osp_..." \
  -d "surtax_phone=08.90.12.34.56" \
  -d "expiration=600"
# → { "status": "OK", "surtaxPhone": "08.90.12.34.56", "expiresAt": "2026-03-13 14:30:00" }

# Libérer immédiatement
curl -X POST https://www.optico.fr/ospExpiration \
  -d "api_key=osp_..." \
  -d "surtax_phone=08.90.12.34.56" \
  -d "expiration=0"
# → { "status": "OK", "surtaxPhone": "08.90.12.34.56", "expiresAt": "2026-03-13 13:47:02" }

Annexe : tableau des préfixes par type de tracking #

Le paramètre type sélectionne le pool de numéros de téléphone à utiliser. Nécessaire uniquement lorsque votre domaine est configuré avec plusieurs pools.