¿Cómo funciona la API de Talkyria antes de escribir una sola línea?

Objetivo: Entender las reglas generales de la API: dónde está la documentación, los dos hosts, la llave, los permisos, el modo de prueba, los límites y los errores.

Nivel: Avanzado · Duración: 3 min · Antes de esta lección: «¿Cómo disparo llamadas desde mi sistema con la API?»

Dónde, en Talkyria: app.talkyria.com/integraciones/api

Gancho

Antes de pedirle nada a la API conviene saber cinco reglas. Con ellas, tu desarrollador integra Talkyria en una tarde y sin escribirle a soporte.

Lo que vas a lograr

Vas a ubicar la documentación pública, entender los dos hosts, la llave, los permisos, el modo de prueba, los límites y cómo leer un error. Es la base de todo el módulo.

Pasos en pantalla

1. Abre app.talkyria.com/docs/api. Arriba está «Tu primera llamada» en tres pasos: «1 · Consigue tu clave», «2 · Comprueba que funciona» y «3 · Dispara tu primera llamada», con el comando listo para copiar.
2. Lee «Antes de integrar». Regla 1, dos hosts: api.talkyria.com sirve pedidos, llamadas, voces, saldo, webhooks, ofertas y leads; app.talkyria.com sirve agentes, analytics, teléfonos y números verificados. La misma llave funciona en los dos.
3. Si envías una operación al host equivocado, la respuesta trae «wrong_host» y el campo «correctUrl» con la dirección correcta. No tienes que adivinar.
4. Regla 2, la llave: cada petición lleva la cabecera Authorization con la palabra Bearer y tu llave, que empieza por tk_live_ o, si es de prueba, por tk_test_.
5. Regla 3, los permisos: cada llave tiene permisos. Si falta uno, la respuesta es «403» con «insufficient_scope» y el campo «required_scope» te dice cuál agregar en «Integraciones» → «API».
6. Regla 4, varias tiendas: si tu workspace tiene más de una, agrega la cabecera X-Talkyria-Shop con la tienda. Sin ella responde «shop_ambiguous».
7. Regla 5, los errores: ramifica siempre por el campo «code» y muestra «message» a las personas. Si recibes «429», espera los segundos de «Retry-After». Sin saldo, disparar una llamada responde «402».
8. En «Integraciones» → «API», la pestaña «Referencia» resume la «Autenticación», los «Endpoints» principales y la «Base URL», por si necesitas un recordatorio rápido.

Error común y cómo resolverlo

Pegar la llave en el código de una página web o de una app móvil. Cualquiera podría copiarla y usar tu saldo, y además la API rechaza esas peticiones. Guarda la llave en tu servidor; si ya se expuso, rótala en la lección «¿Qué permisos le doy a cada llave de API y cómo pruebo sin gastar saldo?».

¿Y ahora qué?

Ahora crea la llave correcta para tu sistema, con solo los permisos que necesita. Siguiente lección: «¿Qué permisos le doy a cada llave de API y cómo pruebo sin gastar saldo?».