API Partenaires Callsens

Version 3.1 — dernière mise à jour : 25 juin 2026

L'API Partenaires permet aux membres du Programme Partenaire d'intégrer les données de leur parc de lignes Callsens dans leurs propres outils : appels, transcriptions, rendez-vous, consommation — en lecture directe ou en temps réel via webhooks signés.

Accès sur invitation. L'API est réservée aux partenaires du programme white label. Pour obtenir vos clés, déposez votre candidature.

URL de base

https://callsens.fr/api/partenaires/v3

Toutes les réponses sont en JSON, encodées en UTF-8.

Authentification

Chaque requête doit porter votre token dans l'en-tête Authorization :

curl -H "Authorization: Bearer cs_live_votre_token" \
  "https://callsens.fr/api/partenaires/v3/calls?limit=10"

Deux types de tokens vous sont remis à l'activation :

Token	Usage
`cs_test_…`	Bac à sable : mêmes routes, données de démonstration. Développez votre intégration sans toucher à de vraies données.
`cs_live_…`	Production : accès aux données réelles de votre parc.

Vos tokens sont affichés une seule fois à leur création — stockez-les immédiatement dans un coffre (variables d'environnement, gestionnaire de secrets). Ne les exposez jamais côté navigateur ni dans un dépôt de code. En cas de doute sur une fuite, contactez-nous : révocation et remplacement immédiats.

Périmètre des données

Chaque token ne voit que les numéros de votre parc. Un numéro hors de votre périmètre répond 404, comme s'il n'existait pas.

Lecture

`GET /phone-numbers`

Les numéros de votre parc.

{ "data": [{ "e164": "+33900000001", "label": "Client Untel" }] }

`GET /calls`

Les appels traités par l'agent, du plus récent au plus ancien.

Paramètres : phone_number (filtre sur une ligne), since (ISO 8601), limit (≤ 200, défaut 50), offset.

{
  "data": [{
    "id": "call_001",
    "phoneNumber": "+33900000001",
    "direction": "inbound",
    "startedAt": "2026-07-10T09:15:00.000Z",
    "endedAt": "2026-07-10T09:17:05.000Z",
    "callerNumber": "+33600000010",
    "callerName": "Jean Dupont",
    "status": "completed",
    "transferredTo": null,
    "durationSeconds": 125,
    "summary": "Demande de rendez-vous pour un devis…",
    "sentiment": "positive"
  }],
  "pagination": { "limit": 50, "offset": 0, "hasMore": false }
}

Statuts possibles : completed, transferred, missed, voicemail, busy, failed.

`GET /calls/:id` et `GET /calls/:id/transcript`

Le détail d'un appel, et sa transcription complète en tours de parole :

{
  "callId": "call_001",
  "summary": "…",
  "turns": [
    { "role": "caller", "text": "Bonjour, je voudrais un devis.", "at": null },
    { "role": "agent", "text": "Bien sûr, je peux prendre vos coordonnées.", "at": null }
  ]
}

`GET /usage?month=YYYY-MM`

La consommation par numéro : nombre d'appels et minutes à la minute entamée (la référence de facturation).

{
  "month": "2026-07",
  "totals": { "calls": 42, "minutes": 96 },
  "data": [{ "e164": "+33900000001", "calls": 42, "minutes": 96 }]
}

`GET /bookings`

Les rendez-vous pris par l'agent (paramètre optionnel phone_number).

Webhooks (temps réel)

Recevez chaque appel terminé sur votre serveur, à la seconde, sans interroger l'API.

Gérer vos webhooks

# Créer (HTTPS obligatoire, 5 webhooks max)
curl -X POST -H "Authorization: Bearer cs_live_…" -H "Content-Type: application/json" \
  -d '{"url": "https://votre-domaine.fr/callsens-hook", "events": ["call.completed", "call.failed"]}' \
  "https://callsens.fr/api/partenaires/v3/webhooks"

La réponse contient votre secret (whsec_…), affiché une seule fois : c'est la clé qui vous permet de vérifier que les événements viennent bien de Callsens. Stockez-la immédiatement.

Ensuite : GET /webhooks (liste), POST /webhooks/:id/test (envoi d'un événement call.test signé, avec la réponse de votre serveur pour déboguer), DELETE /webhooks/:id.

Format des événements

{
  "event": "call.completed",
  "timestamp": "2026-07-13T14:00:00.000Z",
  "data": {
    "id": "call_001",
    "phoneNumber": "+33900000001",
    "direction": "inbound",
    "callerNumber": "+33600000010",
    "callerName": "Jean Dupont",
    "status": "completed",
    "durationSeconds": 125,
    "summary": "…",
    "sentiment": "positive"
  }
}

data suit le même format que GET /calls.

Vérifier la signature (obligatoire)

Chaque livraison porte deux en-têtes :

X-Callsens-Event: call.completed
X-Callsens-Signature: t=1783949777,v1=8be63ea28baa6f9472…

v1 = HMAC_SHA256(secret, "<t>.<corps brut>"). Vérifiez-la ainsi (Node.js) :

import crypto from "node:crypto";

function verify(rawBody, signatureHeader, secret) {
  const { t, v1 } = Object.fromEntries(
    signatureHeader.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; // anti-rejeu
  const expected = crypto.createHmac("sha256", secret)
    .update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));
}

Rejetez toute livraison dont la signature est invalide ou dont le timestamp t s'écarte de plus de 5 minutes.

Règles de livraison

Répondez 2xx en moins de 8 secondes — traitez en asynchrone si besoin.
Répondez 2xx aussi pour un événement déjà reçu (livraison au-moins-une-fois).
3 tentatives par événement en cas d'échec.
Un endpoint en échec 10 fois d'affilée est désactivé — supprimez-le et recréez-le après correction.

Erreurs

Code	Signification
`401 invalid_token`	Token absent, invalide ou révoqué
`404 not_found`	Ressource inconnue ou hors de votre périmètre
`405 method_not_allowed`	L'API est en lecture seule (hors webhooks)
`429 rate_limited`	Plus de 120 requêtes/minute — ralentissez
`502 upstream_error`	Incident temporaire de notre côté — réessayez

Limites

120 requêtes / minute / token.
5 webhooks par compte partenaire.
limit maximal de 200 résultats par page.

Versions

Version actuelle : 3.1. L'API est versionnée dans l'URL (/v3). Les évolutions rétrocompatibles (nouveaux champs, nouvelles routes) peuvent arriver sans préavis : votre intégration doit ignorer les champs inconnus. Tout changement cassant fera l'objet d'une nouvelle version et d'un préavis aux partenaires.

Support

Une question, un besoin d'accès ? Écrivez-nous via la page contact ou déposez votre candidature partenaire.