504 Voice Developer API

Conecta la inteligencia telefónica de tu negocio a cualquier sistema: tu sitio web WordPress, tienda Shopify, CRM (GoHighLevel, HubSpot), o aplicaciones móviles en tiempo real.

🔑 Autenticación

Todas las peticiones a la API v1 deben incluir tu clave de autenticación privada en la cabecera HTTP Authorization utilizando el esquema Bearer token.

¿Dónde generar tu clave? Ve al Portal de tu Negocio → Tab 8 (Configuración) → Sección API Keys. Cada clave tiene el prefijo tk_live_....
Header HTTP
Authorization: Bearer tk_live_948a7fbc20e54366914589d9cba41e21

⚡ Planes y Acceso a la API

La API v1 está incluida en los tres planes. Cada negocio genera sus claves en el portal y les asigna permisos (read, write, sms). Lo que cambia por plan son los minutos de voz de la recepcionista y el envío de SMS:

Plan Minutos de voz / mes Acceso API SMS por API
Starter ($29.99/mes) 300 min Catálogo, horarios, citas, llamadas y recados (lectura y escritura según la clave) 🔒 No disponible
Professional ($49.99/mes) 1,500 min Todo lo anterior + webhooks salientes ✅ Incluido
Enterprise ($149.99/mes) Ilimitados Todo lo anterior ✅ Incluido

Plan anual: 10 meses por 12 ($299.90, $499.90 y $1,499.90). No hay límite de peticiones por minuto configurado hoy; usa la API con criterio.

📋 Catálogo de Servicios

GET /api/v1/services
Plan Starter+

Retorna la lista oficial de tratamientos, servicios y precios vigentes configurados en la recepcionista telefónica.

cURL
curl -X GET "https://504voice.com/api/v1/services" -H "Authorization: Bearer tk_live_tu_clave_aqui"
Respuesta JSON (200 OK)
{ "status": "SUCCESS", "count": 3, "services": [ { "id": 1, "name": "Facial Profundo con Extracción", "price_usd": 100.0, "duration_min": 60, "category": "Tratamientos Faciales", "description": "Limpieza profunda de poros, exfoliación y mascarilla hidratante." }, { "id": 2, "name": "Masaje Relajante Integral", "price_usd": 75.0, "duration_min": 60, "category": "Masajes Terapéuticos", "description": "Terapia integral con aceites esenciales para alivio del estrés." } ] }

📅 Agendamiento de Citas

POST /api/v1/appointments
Plan Pro+

Permite a tu sitio web o aplicación externa reservar una cita en el calendario del negocio con verificación automática de anti-colisión.

ParámetroTipoDescripción
customer_name*stringNombre completo del cliente
customer_phone*stringNúmero telefónico en formato internacional o local
customer_emailstringCorreo para envío de archivo .ics de calendario
appointment_date*stringFecha y hora (ej: 2026-09-28 10:00)
notesstringTratamiento deseado o comentarios
Python (requests)
import requests payload = { "customer_name": "Laura Gómez", "customer_phone": "+1 (786) 555-1234", "customer_email": "[email protected]", "appointment_date": "2026-09-28 11:00", "notes": "Facial profundo anti-edad" } headers = {"Authorization": "Bearer tk_live_tu_clave_aqui"} res = requests.post("https://504voice.com/api/v1/appointments", json=payload, headers=headers) print(res.json())

📲 Mensajería SMS Transaccional

POST /api/v1/sms/send
Plan Pro+

Envía un mensaje de texto SMS oficial desde el número telefónico de tu negocio directamente al celular del cliente.

Node.js (Fetch)
const response = await fetch('https://504voice.com/api/v1/sms/send', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': 'Bearer tk_live_tu_clave_aqui' }, body: JSON.stringify({ to_phone: '+14845551234', message: 'Hola Laura, confirmamos tu cita para mañana a las 11:00 AM en BregaSpa. ¡Te esperamos!' }) }); const data = await response.json(); console.log(data);

🔗 Webhooks Salientes en Tiempo Real

Configura una URL en tu panel para que 504 Voice notifique a tu servidor cada vez que ocurra un evento relevante en la línea telefónica:

EventoMomento del DisparoDatos Adjuntos
appointment.confirmed La recepcionista cerró con éxito una cita en la llamada Cliente, Celular, Fecha/Hora, Servicio y Notas
recado.created El cliente dejó un mensaje o solicitud urgente de llamada Nombre, Teléfono, Nivel de Urgencia y Transcripción

Cada POST lleva el header X-Lpia-Secret con la clave del portal, pestaña Saludo. Brega Spa la guarda en Ajustes y rechaza el evento si no coincide.

En appointment.confirmed el objeto data trae customer_name, customer_phone, customer_email, appointment_date (YYYY-MM-DD HH:MM), service_name, notes y external_id.

En recado.created el objeto data trae customer_name, customer_phone, message_text y urgency.

Antes de confirmar, Brega responde huecos en GET /api/voice.php?action=availability y el catálogo en GET /api/voice.php?action=services, con el mismo header.