API Connecteurs

Vous avez déjà vos clients, votre catalogue et vos informations dans vos outils. Cette API les envoie à votre agent VoixIA, qui s'en sert pour répondre au téléphone, par SMS et sur votre site.

1. Créer une clé

Dans votre espace VoixIA, ouvrez Clé API, donnez un nom à la clé et cochez « Autoriser l'envoi de données ». La clé commence par vxc_ et n'est affichée qu'une fois : rangez-la dans un coffre à secrets, jamais dans une page web. Chaque clé n'ouvre que votre compte. Révoquez-la à tout moment depuis la même page.

curl https://api.voixia.io/api/v1/voixia/cles/moi \
  -H "Authorization: Bearer vxc_VOTRE_CLE"

Réponse : le compte auquel la clé donne accès, et ses droits.

2. Le principe : créer ou mettre à jour

Chaque élément porte ref_externe : son identifiant dans VOTRE outil (l'id HubSpot, la référence produit…). Au premier envoi, l'élément est créé ; aux envois suivants avec la même ref_externe, il est mis à jour, sans doublon. Jusqu'à 200 éléments par appel. Un élément invalide est signalé dans la réponse sans bloquer les autres.

{ "success": true, "type": "produits", "recus": 3, "crees": 2, "mis_a_jour": 0, "fusionnes": 0,
  "erreurs": [ { "index": 2, "ref_externe": "P3", "erreur": "prix invalide" } ] }

3. Produits et prestations

curl -X POST https://api.voixia.io/api/v1/voixia/donnees/produits \
  -H "Authorization: Bearer vxc_VOTRE_CLE" -H "Content-Type: application/json" \
  -d '{ "produits": [
        { "ref_externe": "P1", "nom": "Vidange", "categorie": "entretien", "prix": 89, "duree_minutes": 60 },
        { "ref_externe": "P2", "nom": "Contrôle technique", "prix": 79, "disponible": true }
      ] }'

En mise à jour, un champ absent reste inchangé.

4. Informations (base de connaissances)

curl -X POST https://api.voixia.io/api/v1/voixia/donnees/informations \
  -H "Authorization: Bearer vxc_VOTRE_CLE" -H "Content-Type: application/json" \
  -d '{ "informations": [
        { "ref_externe": "horaires", "titre": "Horaires", "contenu": "Ouvert du lundi au vendredi, de 8h à 18h." }
      ] }'

5. Contacts

curl -X POST https://api.voixia.io/api/v1/voixia/donnees/contacts \
  -H "Authorization: Bearer vxc_VOTRE_CLE" -H "Content-Type: application/json" \
  -d '{ "contacts": [
        { "ref_externe": "hs_1024", "prenom": "Hélène", "nom": "Berger", "telephone": "+33611223344", "email": "helene@exemple.fr" }
      ] }'

Vous envoyez des données personnelles : vous en restez responsable, et VoixIA les traite pour votre compte (voir la page RGPD). N'envoyez que les contacts utiles à votre accueil.

6. Codes de réponse

7. Notifications vers vos outils (webhooks)

VoixIA prévient votre outil à chaque appel terminé, rendez-vous pris ou demande de rappel, par un POST JSON vers une adresse https que vous déclarez dans votre espace VoixIA, page Notifications(ou par l'API, avec votre session) :

POST https://api.voixia.io/api/v1/voixia/webhooks
{ "url": "https://votre-outil.fr/voixia", "evenements": ["appel.termine", "rendezvous.cree", "rappel.demande"] }

La réponse contient un secret whsec_…, affiché une seule fois. Chaque envoi porte l'en-tête X-VoixIA-Signature: t=<horodatage>,v1=<signature> : recalculez HMAC-SHA256 de « horodatage.corps » avec ce secret et comparez, pour être sûr que l'envoi vient de VoixIA.

{ "id": "evt_…", "type": "rendezvous.cree", "cree_le": "2026-11-05T09:12:00Z", "compte": "…",
  "donnees": { "rendezvous_id": "…", "date": "2026-11-06 10:00", "prestation": "Vidange",
               "client": { "nom": "Sylvie Marchand", "telephone": "+33633445566" }, "canal": "telephone" } }

Répondez par un code 2xx en moins de 5 secondes. Sinon, VoixIA réessaie après 1 min, 5 min, 30 min, 2 h et 6 h, puis abandonne. Un envoi de test : POST /api/v1/voixia/webhooks/<id>/test. Les rendez-vous et demandes de rappel pris par l'assistant de votre site sont aussi notifiés (champ canal : « site » ou « telephone »).

Bientôt : des connecteurs prêts à l'emploi (Salesforce, HubSpot). Une question : contact@voixia.io.