---
title: Connecter votre call flow
excerpt: Authentifiez le call flow de votre IPBX et interrogez les endpoints de lookup Smart Routings, avec les paramètres, les formats de réponse et les codes d’erreur.
order: 5
---

## Vue d’ensemble

Votre call flow dialogue avec Smart Routings par de simples requêtes HTTP `GET` et lit des réponses JSON. Sur 3CX, construisez-le avec le Call Flow Designer ; tout IPBX dont le call flow sait envoyer une requête HTTP et lire une valeur JSON fonctionne de la même manière.

Toutes les URL ci-dessous sont relatives à l’API de votre espace :

```
https://your-workspace.cx-engine.com/api
```

Envoyez l’en-tête `Accept: application/json` sur chaque requête, pour que les erreurs soient elles aussi renvoyées en JSON.

Chaque lookup a besoin de votre compte, transmis via `customer_account` (l’identifiant de votre compte CX-Engine) ou `customer_id`.

## Authentification

Les endpoints de lookup demandent un jeton Bearer :

```
Authorization: Bearer {access-token}
```

Le jeton appartient à un utilisateur CX-Engine. Cet utilisateur doit avoir accès au compte et, dans son rôle, la permission **Interrogation** sur les ressources que le call flow interroge (**Règles entrantes**, **Géographique**, **CTI**).

### Jeton CFD (recommandé pour les call flows)

Un jeton CFD est un long secret conçu pour les call flows. Le call flow l’échange contre un jeton d’accès :

`GET /api/smart-routings/cfd-auth/t/{cfd-token}`

```json
{
  "message": "success",
  "token": "eyJ0eXAiOiJKV1Qi...",
  "expires_at": "2026-10-09T11:42:00+00:00",
  "user": { "id": 12, "name": "Call flows", "...": "..." }
}
```

Utilisez le `token` renvoyé comme jeton Bearer des lookups. Il porte le scope `cfd`, qui ne donne accès qu’aux endpoints de lookup et à l’enregistrement des enquêtes. Il est valable 1 heure : faites échanger le jeton CFD par le call flow à chaque appel. Faire expirer ou supprimer le jeton CFD révoque immédiatement ses jetons d’accès.

Un jeton CFD peut être limité à une liste d’adresses IP (`hosts`). Une requête venant d’une autre adresse reçoit `403 Host not authorised.`

Un jeton CFD peut aussi avoir une date d’expiration (`expires_at`). Une fois celle-ci passée, l’échange répond `404 This token does not exists or has expired.` Un jeton sans date d’expiration n’expire jamais.

Les jetons CFD se créent via l’API. Voir [API CX-Engine › Smart Routings](/fr/docs/cx-api/smart-routings).

### Jeton OAuth

Tout jeton d’accès OAuth d’un utilisateur avec le scope `client` fonctionne aussi sur les lookups. Il est nécessaire pour lire les [contacts de routage](/fr/docs/smart-routings/contacts-geographic-routing#interroger-les-contacts-depuis-un-call-flow), que le scope `cfd` ne couvre pas. Voir [API CX-Engine › Authentification](/fr/docs/cx-api/authentication).

## Lookup d’une règle entrante

Renvoie la destination d’une [règle entrante](/fr/docs/smart-routings/inbound-rules) à la date et à l’heure courantes.

`GET /api/smart-routings/call-queues/lookup`

| Paramètre | Obligatoire | Description |
|---|---|---|
| `customer_account` ou `customer_id` | Oui | Votre compte |
| `queue_id`, `queue_number` ou `queue_name` | Oui, l’un des trois | La règle : son ID, son numéro de file (**Ressource** d’une règle de type file) ou son **Nom** |
| `day` | Non | Date à évaluer, `AAAA-MM-JJ`. Par défaut, aujourd’hui. |
| `time` | Non | Heure à évaluer, `HH:MM:SS`. Par défaut, maintenant. |

`day` et `time` sont lus dans le fuseau horaire de votre compte. Servez-vous-en pour tester un planning (« que se passe-t-il le 25 décembre à 10 h ? »).

**Exemple**

```
GET /api/smart-routings/call-queues/lookup?customer_account=ACME&queue_number=800
```

**Réponse `200` — une plage horaire correspond**

```json
{
  "reference": "open",
  "destination": "801",
  "label": null,
  "inherited": false,
  "matched": "time_span,day_of_week"
}
```

**Réponse `200` — une exception correspond**

```json
{
  "reference": "France:christmasDay",
  "destination": "999",
  "label": "Noël",
  "inherited": false,
  "matched": "exception"
}
```

| Champ | Description |
|---|---|
| `reference` | Référence interne de la plage horaire ou de l’exception trouvée |
| `destination` | Destination vers laquelle router l’appel. Peut valoir `null` si aucune n’a été renseignée sur la ligne. |
| `label` | Libellé de l’exception, `null` pour une plage horaire |
| `inherited` | `true` quand la ligne trouvée est définie sur le groupe de règles lui-même |
| `matched` | `exception`, `time_span,date_full` (plage à date précise) ou `time_span,day_of_week` (plage hebdomadaire) |

L’ordre d’évaluation est détaillé dans [Comment la destination est choisie](/fr/docs/smart-routings/opening-hours#comment-la-destination-est-choisie).

**Erreurs**

| Statut | Message | Signification |
|---|---|---|
| `404` | `No destination found matching given parameters.` | Aucune exception ni plage horaire ne correspond : la règle est **fermée**. Dirigez l’appel vers votre message de fermeture. |
| `404` | `No queue found matching given parameters.` | Aucune règle **active** ne correspond au paramètre `queue_*` |
| `404` | `No customer found matching given parameters.` | Compte inconnu |
| `400` | `Invalid date or time provided.` | `day` ou `time` illisible |
| `403` | | L’utilisateur du jeton n’a pas accès au compte ou n’a pas la permission **Interrogation** |

> [!WARNING]
> `queue_number` ne correspond qu’aux règles de type **file**. Pour une règle de type **SDA**, interrogez par `queue_name` ou `queue_id`.

## Lookup géographique

Renvoie les destinations d’une [liste géographique](/fr/docs/smart-routings/contacts-geographic-routing#routage-géographique) pour un appelant.

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

| Paramètre | Obligatoire | Description |
|---|---|---|
| `customer_account` ou `customer_id` | Oui | Votre compte |
| `list_id` ou `list_name` | Oui, l’un des deux | L’**Identifiant unique** ou le **Nom** de la liste |
| `number` ou `zone` | Oui, l’un des deux | Le numéro appelant (converti en zone par le modèle géographique de la liste), ou directement une zone |

**Exemple**

```
GET /api/smart-routings/geo/destinations/lookup?customer_account=ACME&list_id=1&number=0472000000
```

**Réponse `200`**

```json
{
  "destination1": "810",
  "destination2": "811",
  "destination3": null,
  "destination4": null,
  "fallback": false
}
```

`fallback` vaut `true` quand la zone de l’appelant n’est pas couverte par la liste : les quatre valeurs sont alors les **destinations de secours** de la liste. Si les quatre valeurs sont vides, l’API répond `404 No destination found matching given parameters.` Une liste inconnue renvoie `404 No list found matching given parameters.`

## Lookup CTI

### URL à jeton

Copiez l’**URL d’interrogation** depuis la page du CTI et ajoutez-y le numéro appelant. Aucune autre authentification n’est nécessaire :

`GET /api/smart-routings/ctis/t/{cti-token}/{origin}`

```json
{
  "id": 42,
  "origin": "0033612345678",
  "destination": "https://erp.example.com/customers/1234"
}
```

L’origine doit correspondre exactement. Sans correspondance, l’API répond `404`.

### Lookup authentifié

Avec un jeton Bearer (scope `cfd` ou `client`), appelez `GET /api/smart-routings/ctis/lookup` avec :

| Paramètre | Requis | Description |
|---|---|---|
| `customer_account` ou `customer_id` | Oui | Votre compte |
| `cti_id`, `cti_name` ou `cti_token` | Oui, l’un d’eux | Le CTI à interroger |
| `origin` | Oui | Le numéro appelant, comparé à l’identique |

**Exemple**

```
GET /api/smart-routings/ctis/lookup?customer_account=ACME&cti_name=VIP%20callers&origin=0033612345678
```

**Réponse `200`**

```json
{
  "id": 42,
  "cti_id": 4,
  "origin": "0033612345678",
  "destination": "https://erp.example.com/customers/1234",
  "created_at": "2024-03-04T10:15:00.000000Z",
  "updated_at": "2024-03-04T10:15:00.000000Z"
}
```

Sans correspondance, l’API répond `404` avec `No customer found matching given parameters.`, `No CTI found matching given parameters.` ou `No destination found matching given parameters.`

## Enquêtes

Les call flows peuvent aussi enregistrer les réponses d’une enquête post-appel avec `POST /api/smart-routings/survey-records`, avec le même jeton. Les réponses sont listées dans **Routages** > **Enquêtes**. Le format de la requête est détaillé dans [API CX-Engine › Smart Routings](/fr/docs/cx-api/smart-routings).