Développeurs
Tout ce que fait la console, l’API le fait aussi.
Une API publique versionnée, des événements en temps réel et des webhooks signés. Ce n’est pas une couche marketing par-dessus un produit fermé : la console d’administration Konvoice consomme exactement ces mêmes points d’accès.
Principes
Quatre engagements qui comptent plus que la liste des points d’accès.
Versionnée
/api/v1/ est stable. Une rupture entraîne une nouvelle version majeure, jamais une modification silencieuse. L’ancienne version reste servie douze mois au minimum.
Traçable
Chaque requête porte un identifiant de corrélation que vous retrouvez dans nos journaux et dans votre journal d’audit. Un ticket de support commence par ce numéro.
Idempotente
Toute écriture accepte une clé d’idempotence. Rejouer une requête après un délai réseau ne crée pas un second utilisateur ni un second appel.
Cloisonnée
Un jeton appartient à une entreprise et porte des portées explicites. Il ne peut rien lire au-delà, et une portée en lecture ne devient jamais une écriture.
REST
Créer un utilisateur avec son poste.
Une seule requête crée la personne, son poste, ses identifiants d’appareil et déclenche le provisionnement de son téléphone.
POST /api/v1/users HTTP/1.1
Host: api.konvoice.io
Authorization: Bearer kv_live_…
Idempotency-Key: 4f1c-9a02-b7
{
"display_name": "Amadou Diallo",
"email": "[email protected]",
"site_id": "site_lyon",
"extension": "203",
"role": "agent",
"devices": [
{ "type": "deskphone", "mac": "805e0c1a2b3c" },
{ "type": "mobile" },
{ "type": "web" }
],
"teams": ["support"]
}
Avant la production
Des numéros qui répondent faux, exprès.
Le pire environnement de test d’une intégration téléphonique est un collègue qu’on appelle vingt fois. Le bac à sable fournit des numéros dont le comportement est prévisible — décroché, non-réponse, occupation, messagerie, échec opérateur — et vos tests cessent de dépendre de quelqu’un.
- Des scénarios déterministes — un numéro par issue, toujours la même.
- De vrais webhooks — signés, rejouables, avec le même format qu’en production.
- Un identifiant de corrélation sur chaque requête, que le support retrouve dans nos journaux.
- Aucun appel facturé — le bac à sable ne consomme rien.
Événements
Ce qui se passe, au moment où cela se passe.
Les événements sont diffusés par webhook signé et par flux temps réel. Les deux transportent la même charge utile, avec la même garantie de livraison au moins une fois.
| Événement | Quand | Usage courant |
|---|---|---|
call.ringing | Un appel commence à sonner | Afficher la fiche client avant le décroché |
call.answered | Quelqu’un a décroché | Démarrer un chronomètre, ouvrir un ticket |
call.ended | L’appel est terminé | Écrire l’activité dans le CRM |
call.missed | Personne n’a répondu | Créer une tâche de rappel |
recording.ready | L’enregistrement est disponible | Archiver dans votre propre stockage |
transcript.ready | La transcription et le résumé sont produits | Alimenter votre outil d’analyse |
voicemail.received | Un message vocal est déposé | Notifier une équipe |
device.registered | Un téléphone s’enregistre | Superviser le parc |
site.link_lost | Un site passe en autonomie locale | Alerter votre supervision réseau |
site.link_restored | La liaison d’un site est rétablie | Clore l’alerte, vérifier la file de synchronisation |
fraud.route_blocked | Une route a été coupée par le moteur anti-fraude | Réveiller quelqu’un |
Webhooks
Signés, horodatés, rejoués.
Vérifiez la signature avant de traiter la charge utile. L’horodatage protège du rejeu, la clé d’idempotence protège des doublons quand nous réessayons.
- Signature HMAC-SHA256 sur le corps brut, avec un secret par point de livraison.
- Réessais avec attente croissante pendant 24 heures, puis file d’échec consultable.
- Refusez un horodatage plus vieux que cinq minutes : c’est un rejeu.
- Répondez 2xx rapidement et traitez en arrière-plan ; nous coupons à 10 secondes.
POST /votre-endpoint HTTP/1.1
Konvoice-Signature: t=1743158400,
v1=8c1f…d40a
Konvoice-Event-Id: evt_01HZ…
Konvoice-Delivery: 1
{
"type": "call.ended",
"created_at": "2026-03-28T09:20:00Z",
"tenant_id": "ten_8f3c",
"data": {
"call_id": "call_01HZ…",
"direction": "inbound",
"from": "+33478XXXXXX",
"to": "+33472XXXXXX",
"extension": "203",
"duration_s": 214,
"disposition": "answered",
"site_id": "site_lyon",
"handled_locally": true
}
}Nos propres écrans ne consomment que cette API. C’est la seule garantie sérieuse qu’elle restera complète.
Le jour où il lui manque quelque chose, notre application s’arrête aussi
Environnement de test
Développez sans appeler de vrais clients.
Un environnement séparé, avec ses propres jetons, ses numéros de test et un jeu d’appels simulables à la demande.
Numéros de test
Des numéros qui répondent avec un scénario prévisible : décroché, non-réponse, occupation, message vocal, échec opérateur. Vos tests automatisés cessent de dépendre d’un collègue.
Événements déclenchables
Émettez n’importe quel événement de la liste depuis la console, y compris la perte de liaison d’un site, pour vérifier que votre intégration réagit correctement.
Journal des livraisons
Chaque webhook envoyé, sa réponse, son délai et ses réessais. Le rejeu manuel d’une livraison se fait d’un bouton.
Questions développeur
Y a-t-il des limites de débit ?
Fournissez-vous une spécification OpenAPI ?
Peut-on contrôler les appels en temps réel ?
L’API est-elle disponible sur un site hors ligne ?
Un accès de test, gratuitement.
Dites-nous ce que vous voulez construire. Nous ouvrons un environnement avec des numéros de test et nous restons joignables pendant votre intégration.
Sans engagement. Aucun numéro de carte demandé.