API REST

9.1 Vue d'Ensemble

Voki propose une API REST complete pour l'integration avec des systemes externes. L'API permet de gerer les appels, les clients, les departements, les liens d'acces et bien plus encore de maniere programmatique.

URL de base : https://voki.avanter.com.br/api

Format : JSON (Content-Type: application/json)

9.2 Authentification

Toutes les requetes authentifiees doivent inclure le token JWT dans l'en-tete :

Authorization: Bearer {access_token}

Pour obtenir un token :

curl -X POST https://voki.avanter.com.br/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "email": "utilisateur@entreprise.com.br",
    "password": "votreMotDePasse",
    "tenant": "nom-de-lentreprise"
  }'

Reponse :

{
  "access_token": "eyJhbGciOi...",
  "refresh_token": "eyJhbGciOi...",
  "user": {
    "id": "uuid",
    "name": "Nom de l'Utilisateur",
    "email": "utilisateur@entreprise.com.br",
    "role": "manager"
  }
}

9.3 Endpoints Principaux

Authentification

Methode	Endpoint	Description
POST	/api/auth/login	Connexion
POST	/api/auth/refresh	Renouveler le token
POST	/api/auth/mfa/verify	Verifier le code MFA
POST	/api/auth/logout	Deconnexion
POST	/api/auth/forgot-password	Demander la reinitialisation du mot de passe
POST	/api/auth/reset-password	Redefinir le mot de passe

Utilisateurs

Methode	Endpoint	Description
GET	/api/v1/users/me	Donnees de l'utilisateur authentifie
GET	/api/v1/users	Lister les utilisateurs
GET	/api/v1/users/:id	Details d'un utilisateur
POST	/api/v1/users	Creer un utilisateur
PUT	/api/v1/users/:id	Mettre a jour un utilisateur

Departements

Methode	Endpoint	Description
GET	/api/v1/departments	Lister les departements
GET	/api/v1/departments/:id	Details d'un departement
POST	/api/v1/departments	Creer un departement
PUT	/api/v1/departments/:id	Mettre a jour un departement
DELETE	/api/v1/departments/:id	Supprimer un departement
POST	/api/v1/departments/:id/users	Ajouter un agent au departement
DELETE	/api/v1/departments/:id/users/:user_id	Retirer un agent du departement
GET	/api/v1/departments/:id/users	Lister les agents du departement

Appels

Methode	Endpoint	Description
GET	/api/v1/calls	Lister les appels
GET	/api/v1/calls/:id	Details d'un appel
POST	/api/v1/calls/:id/assign	Attribuer un appel a un agent
POST	/api/v1/calls/:id/start	Demarrer un appel
POST	/api/v1/calls/:id/complete	Terminer un appel
POST	/api/v1/calls/:call_id/upload	Envoyer un fichier dans l'appel
GET	/api/v1/calls/:call_id/recording	Obtenir l'enregistrement
POST	/api/v1/calls/:call_id/recording/upload	Envoyer l'enregistrement

Clients

Methode	Endpoint	Description
GET	/api/v1/customers	Lister les clients
GET	/api/v1/customers/:id	Details d'un client
POST	/api/v1/customers	Creer un client
PUT	/api/v1/customers/:id	Mettre a jour un client
DELETE	/api/v1/customers/:id	Supprimer un client
POST	/api/v1/customers/merge	Fusionner des clients en double

Liens d'Acces

Methode	Endpoint	Description
GET	/api/v1/access-links	Lister les liens
GET	/api/v1/access-links/:id	Details d'un lien
POST	/api/v1/access-links	Creer un lien
POST	/api/v1/access-links/batch	Creer des liens par lot
POST	/api/v1/access-links/:id/cancel	Annuler un lien

Rendez-vous

Methode	Endpoint	Description
GET	/api/v1/appointments	Lister les rendez-vous
GET	/api/v1/appointments/:id	Details d'un rendez-vous
POST	/api/v1/appointments	Creer un rendez-vous
PUT	/api/v1/appointments/:id	Mettre a jour un rendez-vous
GET	/api/v1/appointments/conflicts	Verifier les conflits d'horaire
POST	/api/v1/appointments/:id/confirm	Confirmer un rendez-vous
POST	/api/v1/appointments/:id/cancel	Annuler un rendez-vous
POST	/api/v1/appointments/:id/complete	Marquer comme termine
POST	/api/v1/appointments/:id/no-show	Marquer comme non presente

Tags

Methode	Endpoint	Description
GET	/api/v1/tags	Lister les tags
GET	/api/v1/tags/tree	Arborescence des tags
POST	/api/v1/tags	Creer un tag
PUT	/api/v1/tags/:id	Mettre a jour un tag
DELETE	/api/v1/tags/:id	Supprimer un tag
GET	/api/v1/calls/:call_id/tags	Tags d'un appel
POST	/api/v1/calls/:call_id/tags	Appliquer un tag a un appel
DELETE	/api/v1/calls/:call_id/tags/:tag_id	Retirer un tag d'un appel

Analytics

Methode	Endpoint	Description
GET	/api/v1/analytics/overview	Vue d'ensemble des metriques
GET	/api/v1/analytics/hourly	Metriques par heure
GET	/api/v1/analytics/agents	Metriques par agent
GET	/api/v1/analytics/trends	Tendances
POST	/api/v1/analytics/refresh-views	Actualiser les materialized views

Webhooks

Methode	Endpoint	Description
GET	/api/v1/webhooks	Lister les webhooks
GET	/api/v1/webhooks/:id	Details d'un webhook
POST	/api/v1/webhooks	Creer un webhook
PUT	/api/v1/webhooks/:id	Mettre a jour un webhook
DELETE	/api/v1/webhooks/:id	Supprimer un webhook
GET	/api/v1/webhooks/:id/deliveries	Historique des livraisons
POST	/api/v1/webhooks/:id/test	Tester un webhook

Exportation

Methode	Endpoint	Description
GET	/api/v1/export/calls.csv	Exporter les appels en CSV
GET	/api/v1/export/customers.csv	Exporter les clients en CSV
GET	/api/v1/export/links.csv	Exporter les liens en CSV

Acces Public (Clients)

Methode	Endpoint	Description
GET	/api/v1/call/:token/validate	Valider le token d'acces
POST	/api/v1/call/:token/join	Rejoindre la file de service
GET	/api/v1/call/status/:call_id	Statut de l'appel
POST	/api/v1/call/evaluate/:call_id	Envoyer l'evaluation post-service

9.4 Limitation de Debit (Rate Limiting)

Type d'Endpoint	Limite	Intervalle
Authentification	5 requetes	Par minute
API publique	30 requetes	Par minute

En cas de depassement de la limite :

• Code HTTP : 429 Too Many Requests
• En-tete Retry-After : secondes avant de pouvoir reessayer

9.5 Codes de Reponse

Code	Signification
200	Succes
201	Ressource creee avec succes
400	Requete invalide (parametres manquants ou incorrects)
401	Non authentifie (token absent ou expire)
403	Acces refuse (role insuffisant ou limite de plan)
404	Ressource non trouvee
422	Erreur de validation (donnees invalides)
429	Limite de debit depassee
500	Erreur interne du serveur

9.6 Documentation Interactive

La documentation complete de l'API avec des exemples de requete et de reponse est disponible a l'adresse :

https://voki.avanter.com.br/docs

---