SparkTG

Documentación de Pasar a la API v2

Pasar a la API v2

v2

Pasar a la API v2

Autenticación con tokens para tu integración actual

Tu integración llama a la API de SparkTG en /api/v1 enviando un usuario y una contraseña de SparkTG en cada solicitud. La autenticación de la API pasa a tokens de API firmados, disponibles para los mismos endpoints en /api/v2. Los endpoints, parámetros y respuestas no cambian: en la mayoría de las integraciones solo cambian la URL base y la cabecera Authorization.

Por qué pasar a v2

Qué se envía
Usuario + contraseña (v1):Una contraseña de acceso, en cada solicitud
Token de API (v2):Un token firmado; ninguna contraseña sale nunca de manos de tu administrador
Si se filtra
Usuario + contraseña (v1):Funciona hasta que se cambia la contraseña, y esa misma contraseña puede abrir también el panel
Token de API (v2):Revoca ese token al instante en la pantalla API Access Tokens; los accesos al panel no se ven afectados
Alcance
Usuario + contraseña (v1):Todo lo que ese usuario puede ver
Token de API (v2):Un único servicio, fijado en el token
Vigencia
Usuario + contraseña (v1):Sin caducidad
Token de API (v2):Caduca al cabo de un año; renuévalo generando un token nuevo
Quién puede crearlo
Usuario + contraseña (v1):Cualquiera que tenga la contraseña
Token de API (v2):Solo un administrador del servicio, tras verificar una contraseña de un solo uso (OTP)
Estabilidad
Usuario + contraseña (v1):Deja de funcionar cuando alguien cambia la contraseña
Token de API (v2):No depende de ninguna contraseña de acceso
Visibilidad
Usuario + contraseña (v1):—
Token de API (v2):Cada solicitud queda registrada a nombre del servicio del token

Generar un token de API

  1. 1Abre Admin → Settings → API Access Tokens en el panel de SparkTG.
  2. 2En Generate a new token, elige dónde recibir la contraseña de un solo uso (SMS, WhatsApp o Email) y solicítala.
  3. 3Introduce el OTP, añade una etiqueta si quieres (por ejemplo, el nombre de tu integración) y genera el token.
  4. 4Copia el token y guárdalo de forma segura. Solo se muestra una vez y es válido durante un año.

El token lo genera el administrador de tu servicio. En esa misma pantalla aparecen tus tokens y puedes revocar cualquiera. Antes de que un token caduque, genera uno nuevo y cambia tu integración a él.

Qué cambia

URL base
v1 (actual):https://telephonycloud.co.in/api/v1
v2:https://telephonycloud.co.in/api/v2
Autenticación
v1 (actual):Authorization: Basic <username:password>
v2:Authorization: Bearer <YOUR_TOKEN>
Id de servicio (svc-id / service-id)
v1 (actual):Selecciona el servicio.
v2:Opcional. El servicio siempre sale del token. Si lo envías, debe coincidir con el servicio del token; si no, HTTP 403.
Agente de una acción
v1 (actual):Se toma de los parámetros que envías.
v2:Igual. Si no envías agent-sip, agent-id ni agent-number, la acción se asigna al administrador que generó el token; envía el agent-sip, agent-id o agent-number del agente.
Eliminar llamadas programadas
v1 (actual):GET o POST
v2:Solo DELETE, con los parámetros en la query string
Enviar mensaje de WhatsApp
v1 (actual):Se envía como el agente del usuario
v2:El parámetro opcional agent-id elige el agente que envía
Listar servicios
v1 (actual):Todos los servicios del usuario
v2:Solo el servicio del token

Las respuestas correctas y los errores propios de cada endpoint son los mismos que en v1. Cada solicitud v2 se registra para facturar el uso de la API.

Ejemplos

Usuario + contraseña (v1)
curl -u '<username>:<password>' \
  'https://telephonycloud.co.in/api/v1/calls?service-id=<SERVICE_ID>&number=9XXXXXXXXX&agent-id=<AGENT_ID>'
Token de API (v2)
curl -H 'Authorization: Bearer <YOUR_TOKEN>' \
  'https://telephonycloud.co.in/api/v2/calls?number=9XXXXXXXXX&agent-id=<AGENT_ID>'

Sustituye <YOUR_TOKEN> por tu token de API

Errores del token

El token se comprueba antes de ejecutar el endpoint, así que cualquier solicitud v2 puede devolverlos.

HTTP 401Falta la cabecera Authorization o es incorrecta, o el token ha caducado.
{"status":"error","code":401,"message":"invalid or missing JWT"}
HTTP 401El token se revocó en la pantalla API Access Tokens.
{"status":"error","code":401,"message":"token revoked or unknown"}
HTTP 403El servicio al que pertenece el token no está activo.
{"status":"error","code":403,"message":"service inactive (svcId=<id>)"}
HTTP 403Se envió un parámetro svc-id o service-id con otro id de servicio.
{"status":"error","code":403,"message":"svc-id does not match token's service"}

Endpoints de v2

Estas API ya están disponibles en v2. El resto de las API de SparkTG pasará a la v2 pronto.