SparkTG

Documentation de Passer à l’API v2

Passer à l’API v2

v2

Passer à l’API v2

Une authentification par jeton pour votre intégration existante

Votre intégration appelle l’API SparkTG sur /api/v1 en envoyant un identifiant et un mot de passe SparkTG à chaque requête. L’authentification de l’API passe à des jetons d’API signés, disponibles pour les mêmes endpoints sur /api/v2. Les endpoints, paramètres et réponses restent identiques : pour la plupart des intégrations, seuls l’URL de base et l’en-tête Authorization changent.

Pourquoi passer à la v2

Ce qui est envoyé
Identifiant + mot de passe (v1):Un mot de passe de connexion, à chaque requête
Jeton d’API (v2):Un jeton signé ; aucun mot de passe ne quitte jamais les mains de votre administrateur
En cas de fuite
Identifiant + mot de passe (v1):Fonctionne jusqu’au changement du mot de passe, et ce même mot de passe peut aussi ouvrir le tableau de bord
Jeton d’API (v2):Révoquez ce seul jeton instantanément sur l’écran API Access Tokens ; les connexions au tableau de bord ne sont pas affectées
Portée
Identifiant + mot de passe (v1):Tout ce à quoi cet utilisateur a accès
Jeton d’API (v2):Un seul service, fixé dans le jeton
Durée de vie
Identifiant + mot de passe (v1):Aucune expiration
Jeton d’API (v2):Expire au bout d’un an ; renouvelez-le en générant un nouveau jeton
Qui peut le créer
Identifiant + mot de passe (v1):Toute personne qui connaît le mot de passe
Jeton d’API (v2):Seul un administrateur du service, après vérification d’un mot de passe à usage unique (OTP)
Stabilité
Identifiant + mot de passe (v1):Cesse de fonctionner quand quelqu’un change le mot de passe
Jeton d’API (v2):Indépendant de tout mot de passe de connexion
Visibilité
Identifiant + mot de passe (v1):—
Jeton d’API (v2):Chaque requête est enregistrée au nom du service du jeton

Générer un jeton d’API

  1. 1Ouvrez Admin → Settings → API Access Tokens dans le tableau de bord SparkTG.
  2. 2Sous Generate a new token, choisissez où recevoir le mot de passe à usage unique (SMS, WhatsApp ou Email) et demandez-le.
  3. 3Saisissez l’OTP, ajoutez si vous le souhaitez un libellé (par exemple le nom de votre intégration) et générez le jeton.
  4. 4Copiez le jeton et conservez-le en lieu sûr. Il n’est affiché qu’une fois et reste valable un an.

C’est l’administrateur de votre service qui génère le jeton. Le même écran liste vos jetons et permet d’en révoquer un. Avant qu’un jeton n’expire, générez-en un nouveau et basculez votre intégration dessus.

Ce qui change

URL de base
v1 (actuelle):https://telephonycloud.co.in/api/v1
v2:https://telephonycloud.co.in/api/v2
Authentification
v1 (actuelle):Authorization: Basic <username:password>
v2:Authorization: Bearer <YOUR_TOKEN>
Id de service (svc-id / service-id)
v1 (actuelle):Sélectionne le service.
v2:Facultatif. Le service provient toujours du jeton. Si vous l’envoyez, il doit correspondre au service du jeton, sinon HTTP 403.
Agent d’une action
v1 (actuelle):Déduit des paramètres que vous envoyez.
v2:Identique. Si vous n’envoyez ni agent-sip, ni agent-id, ni agent-number, l’action est attribuée à l’administrateur qui a généré le jeton : envoyez donc l’agent-sip, l’agent-id ou l’agent-number de l’agent.
Supprimer des appels planifiés
v1 (actuelle):GET ou POST
v2:DELETE uniquement, paramètres dans la query string
Envoyer un message WhatsApp
v1 (actuelle):Envoyé en tant qu’agent de l’utilisateur
v2:Le paramètre facultatif agent-id choisit l’agent expéditeur
Lister les services
v1 (actuelle):Tous les services de l’utilisateur
v2:Uniquement le service du jeton

Les réponses réussies et les erreurs propres à chaque endpoint sont les mêmes qu’en v1. Chaque requête v2 est enregistrée pour la facturation de l’usage de l’API.

Exemples

Identifiant + mot de passe (v1)
curl -u '<username>:<password>' \
  'https://telephonycloud.co.in/api/v1/calls?service-id=<SERVICE_ID>&number=9XXXXXXXXX&agent-id=<AGENT_ID>'
Jeton d’API (v2)
curl -H 'Authorization: Bearer <YOUR_TOKEN>' \
  'https://telephonycloud.co.in/api/v2/calls?number=9XXXXXXXXX&agent-id=<AGENT_ID>'

Remplacez <YOUR_TOKEN> par votre jeton d’API

Erreurs de jeton

Le jeton est vérifié avant l’exécution de l’endpoint : toute requête v2 peut donc les renvoyer.

HTTP 401L’en-tête Authorization est absent ou mal formé, ou le jeton a expiré.
{"status":"error","code":401,"message":"invalid or missing JWT"}
HTTP 401Le jeton a été révoqué sur l’écran API Access Tokens.
{"status":"error","code":401,"message":"token revoked or unknown"}
HTTP 403Le service auquel appartient le jeton n’est pas actif.
{"status":"error","code":403,"message":"service inactive (svcId=<id>)"}
HTTP 403Un paramètre svc-id ou service-id a été envoyé avec un autre id de service.
{"status":"error","code":403,"message":"svc-id does not match token's service"}

Endpoints v2

Ces API sont déjà disponibles en v2. Les autres API SparkTG passeront bientôt à la v2.