API Offline

Introduction #

L'API Optico Offline Numbers gère des numéros de tracking statiques, attribués de manière permanente à des numéros de destination spécifiques pour les médias offline tels que les annonces presse, panneaux d'affichage, cartes de visite et catalogues. Contrairement aux numéros de tracking online (attribués dynamiquement par visiteur web), les numéros offline sont persistants et liés à une campagne ou destination nommée.

Transport & conventions

Authentification #

Chaque requête doit inclure le paramètre key, la clé API Offline Numbers du domaine. Cette clé est disponible dans les paramètres de votre domaine dans le back-end Optico.

/offline-numbers-api?key=offl_b7e2c8a14f9dcdef&action=check&tracking_number=0899123456

Erreurs #

Enveloppe de réponse

Chaque requête renvoie 200 OK avec une enveloppe JSON. Branchez-vous sur le champ status ; en cas d'erreur, le champ error indique la raison.

{ "status": "success", "phone_number": "0612345678", "tracking_number": "0899123456" }

{ "status": "error",
  "error": "No tracking number available" }

Messages d'erreur courants

Idempotence

Les actions de lecture (check, /list) peuvent être appelées de manière répétée sans risque. Les actions d'écriture (assign, unassign, reassign, redirect_setup) renvoient l'état courant en cas de succès ; renvoyer un unassign ou redirect_setup après succès est un no-op. assign alloue un nouveau numéro depuis le pool à chaque succès ; ne réessayez pas aveuglément sur timeout, appelez d'abord check.

Réessais & timeouts

Utilisez un timeout client de 5 secondes. Réessayez sur timeout réseau ou HTTP 5xx uniquement pour les actions de lecture. Pour assign, traitez un timeout comme « inconnu » et appelez check avec le phone_number de destination pour savoir si un numéro a été alloué avant de réessayer.

Limites de taux

Aucune limite de taux publique fixe n'est appliquée. Ces endpoints sont administratifs ; l'usage typique est de quelques requêtes par jour, pas par seconde. Contactez le support avant de scripter des réassignations en masse.

Endpoints #

GET /offline-numbers-api #

Paramètres communs

Type et référence des préfixes

Champs de la réponse en cas de succès

Action : assign #

Attribuer un numéro de tracking issu du pool privé du domaine à un numéro de téléphone de destination.

/offline-numbers-api?key=offl_key&action=assign&phone_number=0612345678&description=Magazine+Ad&type=1&allow_redirect=1

{ "status": "success", "phone_number": "0612345678", "tracking_number": "0899123456", "allow_redirect": "1" }

Action : unassign #

Libérer un numéro de tracking et le remettre dans le pool privé. Fournissez soit tracking_number, soit phone_number.

/offline-numbers-api?key=offl_key&action=unassign&tracking_number=0899123456

Action : reassign #

Changer le numéro de téléphone de destination d'un numéro de tracking existant.

Action : check #

Interroger l'état courant d'un numéro de tracking ou d'un téléphone de destination. Fournissez soit tracking_number, soit phone_number.

{ "status": "success", "phone_number": "0612345678", "tracking_number": "0899123456", "allow_redirect": "1" }

Action : redirect_setup #

Mettre à jour le drapeau de redirection d'appels et/ou la plage horaire d'un numéro de tracking existant.

{ "status": "success", "phone_number": "0612345678", "tracking_number": "0899123456",
  "allow_redirect": "1", "timetable": [{ "day": "mon", "from": "09:00", "to": "18:00" }] }

GET /offline-numbers-api/list #

Renvoie tous les numéros de tracking (à la fois les numéros offline attribués et les numéros du pool non attribués) associés au domaine.

Paramètres

{
  "0899123456": "0612345678",
  "0899789012": "0698765432"
}

{
  "tracking_number_details": [{
    "tracking_phone": "0899123456",
    "destination_phone": "0612345678",
    "description": "Magazine Ad",
    "product_name": "example.com",
    "last_update": "2019-10-01 12:00:00"
  }]
}