Smart Routings — Routage géographique

Le routage géographique envoie un appel vers une destination choisie selon la zone géographique de l'appelant. Consultez Smart Routings pour les notions communes à tous les endpoints Smart Routings.

Tous les endpoints de cette section sont propres à l'espace de travail et nécessitent le scope OAuth client. L'endpoint de lookup accepte également le scope cfd.

Headers : Authorization: Bearer {workspace-token}

Paramètre de requête obligatoire : customer_account — le compte client concerné. Voir Choix du compte client.

#Modèles géographiques

Un modèle géographique définit l'ensemble des zones sur lesquelles une liste peut router, et la façon dont un numéro de téléphone est associé à une zone. Les modèles sont communs à tous les clients de l'espace de travail et sont en lecture seule via l'API. Les modèles fournis couvrent notamment les départements français (zones 01 à 98), les préfixes internationaux (codes ISO 3166-1 alpha-2) et les États membres de l'Union européenne.

#GET /api/smart-routings/geo/models

Renvoie la liste paginée des modèles géographiques.

Paramètres de requête

Réponse 200 — réponse paginée

{
  "data": [
    {
      "id": 1,
      "name": "French Districts",
      "created_at": "2024-01-15T09:30:00.000000Z",
      "updated_at": "2024-01-15T09:30:00.000000Z"
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 3
}

#GET /api/smart-routings/geo/models/{id}

Renvoie un modèle géographique, avec la liste des zones qu'il définit.

Réponse 200

{
  "id": 1,
  "name": "French Districts",
  "zones": ["01", "02", "03", "...", "98"],
  "created_at": "2024-01-15T09:30:00.000000Z",
  "updated_at": "2024-01-15T09:30:00.000000Z"
}

#Listes de routage géographique

Une liste associe un modèle géographique à un ensemble de destinations. Chaque liste possède un identifiant numérique list_id, unique par client, et jusqu'à quatre destinations de repli utilisées lorsqu'aucune destination ne couvre la zone de l'appelant.

#GET /api/smart-routings/geo/lists

Renvoie la liste paginée des listes de routage géographique du client. Chaque liste inclut l'id et le name de son modèle.

Paramètres de requête

Réponse 200 — réponse paginée

{
  "data": [
    {
      "id": 4,
      "customer_id": 12,
      "geo_routing_model_id": 1,
      "list_id": 1,
      "list_name": "Sales France",
      "fallback_destination_1": "100",
      "fallback_destination_2": null,
      "fallback_destination_3": null,
      "fallback_destination_4": null,
      "created_at": "2024-03-02T10:00:00.000000Z",
      "updated_at": "2024-03-02T10:00:00.000000Z",
      "model": { "id": 1, "name": "French Districts" }
    }
  ],
  "current_page": 1,
  "last_page": 1,
  "per_page": 20,
  "total": 1
}

#GET /api/smart-routings/geo/lists/{id}

Renvoie une liste avec son modèle géographique complet et orphan_zones : les zones du modèle qu'aucune destination de la liste ne couvre encore.

Réponse 200

{
  "id": 4,
  "customer_id": 12,
  "geo_routing_model_id": 1,
  "list_id": 1,
  "list_name": "Sales France",
  "fallback_destination_1": "100",
  "fallback_destination_2": null,
  "fallback_destination_3": null,
  "fallback_destination_4": null,
  "created_at": "2024-03-02T10:00:00.000000Z",
  "updated_at": "2024-03-02T10:00:00.000000Z",
  "orphan_zones": ["01", "02", "04"],
  "model": {
    "id": 1,
    "name": "French Districts",
    "zones": ["01", "02", "03", "...", "98"],
    "created_at": "2024-01-15T09:30:00.000000Z",
    "updated_at": "2024-01-15T09:30:00.000000Z"
  }
}

Réponse 403 — la liste appartient à un autre client, ou la permission est manquante

#POST /api/smart-routings/geo/lists

Crée une liste de routage géographique pour le client.

Corps de la requête

Réponse 201 — la liste créée

Réponse 400 — erreur de validation, ou une autre liste du client utilise déjà ce list_id

{
  "response": "bad request: please check body parameters.",
  "hint": ["Another list with the same list_id exists."]
}

#PUT /api/smart-routings/geo/lists/{id}

Met à jour une liste. Tous les champs de l'endpoint de création sont acceptés et facultatifs. PATCH est également accepté.

Lorsque list_id est omis (ou null), la liste conserve son list_id actuel. Envoyez-le uniquement pour renuméroter la liste.

Réponse 201 — la liste mise à jour

Réponse 400 — erreur de validation, ou une autre liste du client utilise déjà ce list_id

#DELETE /api/smart-routings/geo/lists/{id}

Supprime une liste ainsi que toutes ses destinations.

Réponse 200

{ "response": "element deleted" }

#Destinations d'une liste

Une destination associe une ou plusieurs zones du modèle de la liste à un maximum de quatre destinations. Une zone ne peut appartenir qu'à une seule destination d'une liste.

#GET /api/smart-routings/geo/lists/{list}/destinations

Renvoie toutes les destinations de la liste (sans pagination).

Réponse 200

[
  {
    "id": 21,
    "geo_routing_list_id": 4,
    "nickname": "Paris area",
    "zones": ["75", "77", "78", "91", "92", "93", "94", "95"],
    "destination_1": "201",
    "destination_2": "202",
    "destination_3": null,
    "destination_4": null,
    "created_at": "2024-03-02T10:05:00.000000Z",
    "updated_at": "2024-03-02T10:05:00.000000Z"
  }
]

#GET /api/smart-routings/geo/lists/{list}/destinations/{id}

Renvoie une destination.

Réponse 200 — objet destination

Réponse 404 — la destination n'appartient pas à cette liste

#POST /api/smart-routings/geo/lists/{list}/destinations

Ajoute une destination à la liste.

Corps de la requête

Réponse 201 — la destination créée

Réponse 400 — erreur de validation, ou zones invalides. Le message indique les zones en cause :

• Some selected zones are unknown to the selected model (99).
• Some selected zones are already used (75, 92).

#PUT /api/smart-routings/geo/lists/{list}/destinations/{id}

Met à jour une destination. Tous les champs de l'endpoint de création sont acceptés et facultatifs ; les zones sont contrôlées de la même façon. PATCH est également accepté.

Réponse 201 — la destination mise à jour

Réponse 400 — erreur de validation ou zones invalides

#DELETE /api/smart-routings/geo/lists/{list}/destinations/{id}

Supprime une destination. Ses zones redeviennent disponibles.

Réponse 200

{ "response": "element deleted" }

#Lookup

#GET /api/smart-routings/geo/destinations/lookup

Trouve les destinations à utiliser pour un appelant. Généralement appelé depuis un flux d'appel 3CX. Accepte le scope client ou cfd et nécessite la permission geo-routing-list.lookup.

Le client doit correspondre au compte client sélectionné pour la requête.

Paramètres de requête

*L'un des paramètres customer_account ou customer_id est obligatoire.
**L'un des paramètres list_id ou list_name est obligatoire.
***L'un des paramètres number ou zone est obligatoire. Si les deux sont envoyés, la zone déduite de number est prioritaire lorsque le numéro peut être analysé.

Si une destination de la liste couvre la zone, ses destinations sont renvoyées avec fallback: false. Sinon, ce sont les destinations de repli de la liste qui sont renvoyées, avec fallback: true.

Réponse 200

{
  "destination1": "201",
  "destination2": "202",
  "destination3": null,
  "destination4": null,
  "fallback": false
}

Réponse 400 — paramètres manquants

Réponse 404 — aucun client ou aucune liste correspondante, ou aucune destination (ni destination de repli) configurée