VOS3000 API Desarrollo Integración: La Guía Completa para Desarrolladores Web

El desarrollo con VOS3000 API permite la integración completa de la plataforma softswitch con sistemas externos, portales de clientes, plataformas de facturación y aplicaciones personalizadas. Esta guía proporciona documentación completa de los endpoints disponibles, formato de datos y ejemplos de implementación basados en el manual oficial VOS3000 Web API.

📌 Visión General de VOS3000 Web API

La API de VOS3000 utiliza el formato JSON codificado en UTF-8. Según el manual oficial:

• ✅ Método HTTP: POST para todas las operaciones
• ✅ Formato: JSON con codificación UTF-8
• ✅ Content-Type: text/html; charset=UTF-8
• ✅ Código de Retorno: 0 = éxito, no-cero = error

🔹 URL Base de la API

Las interfaces se acceden mediante:

http://IP:6541/external/server/[endpoint]
https://IP:6454/external/server/[endpoint]

Directorios según manual:

• /external/server: Interfaces de producción
• /external/test/server: Interfaces de prueba y debugging

⚙️ Configuración de Acceso API (VOS3000 API Desarrollo Integración)

🔹 Control de Acceso Web

El manual VOS3000 especifica la configuración en Interface Management > Web Access Control:

⚠️ Seguridad: Solo las IPs autorizadas pueden acceder a la API. Configure cuidadosamente las IPs de sus servidores de aplicación.

📊 API de Gestión de Cuentas

🔹 Crear Cuenta (CreateCustomer)

Endpoint: /external/server/CreateCustomer

Ejemplo de Request:

{
  "account": "cliente001",
  "name": "Cliente Demo Colombia",
  "money": 100.00,
  "limitMoney": 50.00,
  "feeRateGroup": "tarifas_mayorista",
  "type": 0,
  "lockType": 0
}

Response de Éxito:

{"retCode": 0}

Response de Error:

{"retCode": -10007, "exception": "Account already exists"}

🔹 Modificar Cuenta (ModifyCustomer)

Endpoint: /external/server/ModifyCustomer

Permite modificar: name, limitMoney, feeRateGroup, type, lockType, memo y otros campos opcionales.

🔹 Consultar Cuenta (GetCustomer)

Endpoint: /external/server/GetCustomer

Parámetros de búsqueda:

• accounts: Lista de IDs de cuenta
• e164s: Lista de números telefónicos
• filterAgentAccount: Filtrar por cuenta agente

🔹 Eliminar Cuenta (DeleteCustomer)

Endpoint: /external/server/DeleteCustomer

{"account": "cliente001"}

📞 API de Gestión de Teléfonos

🔹 Crear Teléfono (CreatePhone)

Endpoint: /external/server/CreatePhone

🔹 Permisos de Llamada (callLevel)

Según el manual VOS3000:

• 1: Solo llamadas dentro de la red
• 2: Llamadas locales
• 4: Llamadas nacionales
• 5: Llamadas internacionales

🔹 Servicios de Valor Agregado

El manual especifica parámetros avanzados para CreatePhone:

• Caller ID Display: Mostrar/ocultar identificador
• Call Forwarding: Desvío incondicional, ocupado, sin respuesta
• Voicemail: Configuración de buzón de voz
• Do Not Disturb: Modo no molestar

🌐 API de Gestión de Gateways (VOS3000 API Desarrollo Integración)

🔹 Crear Routing Gateway

Endpoint: /external/server/CreateRoutingGateway

Parámetros principales según manual:

• gatewayName: Identificador único
• gatewayPrefix: Prefijos de destino
• lineLimit: Límite de canales
• priority: Orden de selección
• gatewayType: Static/Dynamic
• protocol: 0=H323, 1=SIP

🔹 Crear Mapping Gateway

Endpoint: /external/server/CreateMappingGateway

Para gateways de clientes originales:

• account: Cuenta de facturación
• gatewayName: Identificador
• gatewayType: Static/Dynamic
• ip: Dirección IP
• lineLimit: Canales máximos

📊 API de CDR y Facturación (VOS3000 API Desarrollo Integración)

🔹 Consultar CDR

Los endpoints de CDR permiten:

• Consultar llamadas por período
• Filtrar por cuenta, número, gateway
• Exportar registros detallados

🔹 Gestión de Pagos

La API soporta:

• Recargas de balance
• Consultas de saldo
• Historial de transacciones

💻 Mejores Prácticas de Implementación

🔹 Manejo de Errores

Siempre verifique retCode en las respuestas:

if (response.retCode === 0) {
  // Éxito
} else {
  console.error("Error:", response.exception);
}

🔹 Autenticación y Seguridad

• ✅ Use siempre HTTPS en producción
• ✅ Configure IP whitelist en Web Access Control
• ✅ Almacene credenciales de forma segura
• ✅ Implemente rate limiting en su aplicación

🔹 Debugging

El manual VOS3000 proporciona interfaces de prueba en:

https://IP:6454/external/test/server/

Cada endpoint tiene una página de prueba visual para debugging.

🔗 Recursos Relacionados – VOS3000 API Desarrollo Integración

Recursos Internos:

• VOS3000 Web Interface Developing Manual
• VOS3000 Web API Manual English
• VOS3000 API Overview

Recursos Externos:

• VOS3000 Official Website
• VOS3000 Downloads

❓ Preguntas Frecuentes (FAQ) – VOS3000 API Desarrollo Integración

Q1: ¿Cuál es el formato de respuesta de error?
💡 A1: El formato es {“retCode”: código_error, “exception”: “mensaje descriptivo”}. retCode 0 indica éxito, cualquier otro valor es error.

Q2: ¿Cómo autentico las peticiones API?
💡 A2: La autenticación se basa en IP whitelist configurada en Web Access Control. Las peticiones deben originarse desde IPs autorizadas.

Q3: ¿Puedo crear cuenta y teléfono en una sola petición?
💡 A3: Sí, use autoCreateAccount=true en CreatePhone para crear automáticamente la cuenta de facturación.

Q4: ¿Qué Content-Type debo usar?
💡 A4: Use Content-Type: text/html; charset=UTF-8 según especifica el manual VOS3000.

Q5: ¿Dónde encuentro los códigos de error?
💡 A5: El manual Web API incluye tabla completa de códigos de error. Los más comunes: -10007 (no encontrado), -10001 (parámetro inválido), -10002 (ya existe).

📞 Soporte para Desarrolladores

Para soporte técnico de integración API:

📱 WhatsApp: +8801911119966
🌐 Website: www.vos3000.com
🌐 Blog: multahost.com/blog
📥 Downloads: VOS3000 Downloads