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

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:

Parámetro	Descripción	Valor
Web Server Device	Nombre del dispositivo	Nombre configurado
Directory Name	Directorio permitido	/external/server
Allowed Access IP	IPs autorizadas	Lista de IPs

⚠️ 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

Parámetro	Requerido	Tipo	Descripción
account	Sí	String	Identificador único de cuenta
name	Sí	String	Nombre de la cuenta
money	No	Double	Balance inicial (default: 0)
limitMoney	No	Double	Límite de sobregiro (default: 0)
feeRateGroup	No	String	Grupo de tarifas
type	No	Integer	0=Ordinario, 1=Phone Card, 2=Settlement
lockType	No	Integer	0=Desbloqueado, 1=Bloqueado

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

Parámetro	Requerido	Tipo	Descripción
e164	Sí	String	Número telefónico
autoCreateAccount	Sí	Boolean	Crear cuenta automáticamente
account	No	String	Cuenta asociada
password	No	String	Contraseña SIP
displayNumber	No	String	Caller ID saliente
callLevel	No	Integer	1=Intra-red, 2=Local, 4=Nacional, 5=Internacional
lockType	No	Integer	0=Ninguno, 1=Saliente, 2=Entrante, 3=Todo

🔹 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

---

---