Zadarma API Service

Autenticación

🔑 Token de aplicación

Define APP_TOKEN en tu .env y envíalo como:

Authorization: Bearer <token>

También puedes usar el header X-Auth-Token

🔐 Credenciales Zadarma

Incluye key y secret en el JSON o via headers:

X-API-Key: YOUR_KEY
X-API-Secret: YOUR_SECRET

Endpoints disponibles

POST

💰 Balance

/api/balance

Consulta el saldo actual de tu cuenta Zadarma

curl -X POST http://localhost:8080/api/balance \
  -H 'Authorization: Bearer TOKEN' \
  -d '{"key":"KEY","secret":"SECRET"}'

POST

📞 Lista SIPs

/api/sip/list

Obtiene todos los números SIP activos

curl -X POST http://localhost:8080/api/sip/list \
  -H 'Authorization: Bearer TOKEN' \
  -d '{"key":"KEY","secret":"SECRET"}'

POST

📊 Estado SIP

/api/sip/status

Verifica el estado de un número SIP específico

curl -X POST http://localhost:8080/api/sip/status \
  -H 'Authorization: Bearer TOKEN' \
  -d '{"key":"KEY","secret":"SECRET","sipId":610739}'

GET/POST

🏢 Extensiones PBX

/api/pbx/extensions (alias /api/extensions)

Lista todas las extensiones internas de tu PBX (GET con query o POST con body)

# GET
curl -X GET 'http://localhost:8080/api/pbx/extensions?token=TOKEN&key=KEY&secret=SECRET'

# POST
curl -X POST http://localhost:8080/api/pbx/extensions \
  -H 'Authorization: Bearer TOKEN' \
  -d '{"key":"KEY","secret":"SECRET"}'

POST

📶 Estado Extensión PBX

/api/pbx/extension/status (alias /api/pbx/extension)

Comprueba si una extensión PBX está online

curl -X POST http://localhost:8080/api/pbx/extension/status \
    -H 'Authorization: Bearer TOKEN' \
    -H 'Content-Type: application/json' \
    -d '{"key":"KEY","secret":"SECRET","ext":"105","sandbox":true}'

POST

📲 Callback

/api/request-callback

Callback estándar (solo extensión, destino y CallerID)

curl -X POST http://localhost:8080/api/request-callback \
  -H 'Authorization: Bearer TOKEN' \
  -d '{"key":"KEY","secret":"SECRET","extension":"119","to":"+50584454076","callerId":"+50660589399"}'

POST

💬 Enviar SMS

/api/sms/send

Envía mensajes SMS a uno o varios destinatarios

curl -X POST http://localhost:8080/api/sms/send \
  -H 'Authorization: Bearer TOKEN' \
  -d '{"to":["+50584454076"],"message":"Hola"}'

POST

📈 Estadísticas

/api/stats/recent

Obtiene estadísticas de llamadas recientes

curl -X POST http://localhost:8080/api/stats/recent \
  -H 'Authorization: Bearer TOKEN' \
  -d '{"minutes":30,"to":"+50584454076"}'

POST

⚙️ Método genérico

/api/method

Ejecuta cualquier método permitido de la API

curl -X POST http://localhost:8080/api/method \
  -H 'Authorization: Bearer TOKEN' \
  -d '{"method":"getBalance","params":{}}'

Consola interactiva

LIVE

🧪 Try it - Prueba los endpoints en tiempo real

Ejecuta llamadas directamente desde tu navegador. Las credenciales solo se usan en tu sesión local.

⚠️ Aviso CORS: Si ves errores de origen null, sirve este archivo via HTTP (ej: python3 -m http.server 8000), no lo abras como file://

🌐 Base URL

🔑 App Token

🔐 Zadarma Key

🔒 Zadarma Secret

☎️ Caller ID (opcional) Debe ser un número verificado y no puede coincidir con to.

🏢 Extensión PBX Usada por los endpoints de callback.

👤 Cliente (to) Número destino del cliente para el callback.

🔄 Auto sync payload Actualizar JSON al cambiar credenciales / sandbox / endpoint

📍 Endpoint

📝 Payload JSON

Modo Sandbox

📥 Respuesta

// Esperando petición...

Errores comunes

Código	Causa	Solución
`401`	Token ausente o inválido	Verificar header `Authorization: Bearer`
`400`	Credenciales faltantes	Incluir `key` y `secret` en body
`400`	Método no permitido	Revisar lista de métodos en `/api/method`
`429`	Límite de rate excedido	Implementar exponential backoff

Mejores prácticas

✅ Usa sandbox para pruebas iniciales antes de ir a producción
🔒 Nunca expongas tu secret en clientes públicos o repositorios
📊 Registra solo metadatos, evita guardar payloads sensibles en logs
🔄 Implementa reintentos con jitter exponencial para llamadas fallidas
⚡ Usa webhooks en lugar de polling para eventos en tiempo real
☎️ Evita que callerId sea igual a to (la API lo rechaza)
🎯 Para callerId dinámico usa un SIP online y ajusta su CallerID antes del callback

📋 Lista completa de métodos permitidos en /api/method

getBalance          - Consultar saldo
getSip              - Obtener información SIP
getSipStatus        - Estado de número SIP
getSipRedirection   - Redirecciones configuradas
getDirectNumbers    - Números directos
getPbxInternal      - Extensiones internas PBX
getPbxStatus        - Estado del PBX
getPbxInfo          - Información del PBX
getStatistics       - Estadísticas generales
getPbxStatistics    - Estadísticas PBX
requestCallback     - Solicitar callback
getTimezone         - Zona horaria
getTariff           - Tarifas
getPrice            - Precio de llamadas
sendSms             - Enviar SMS
getWebrtcKey        - Clave WebRTC
numberLookup        - Buscar número
numberLookupMultiple - Buscar múltiples números