DOCUMENTACIÓN PARA INTEGRADORES
Integra tu sistema con CopDigital
Consulta catálogos y saldo, compra servicios, obtén códigos de tus cuentas y consulta pagos. La disponibilidad depende de los permisos y servicios habilitados para tu usuario.
URL base: https://back.copdigital.co
HTTPS y UTF-8. Envía Content-Type: application/json con cuerpos JSON y Accept: application/json. Revisa cada ficha: no todas las respuestas tienen el mismo formato.
Tu primera integración
- Solicita habilitación. Contacta al administrador de CopDigital para activar tu acceso API, los servicios y los permisos
gen_hysy/opayments. Informa las IP públicas de salida de tu servidor si se requiere una lista autorizada. - Autentica desde tu servidor. Usa POST /api/auth/token. Guarda
data.access_tokeny calcula su vencimiento condata.expires_in. - Prueba una consulta. Envía
Authorization: Bearer TU_TOKENa GET /gen_hys/dashboard_state. No necesitas comprar para comprobar el acceso. - Selecciona el producto. Por ejemplo, consulta el catálogo Disney, presenta el precio y solicita confirmación del cliente final.
- Guarda la referencia antes de enviar. Para comprar Disney, genera una referencia numérica única de 6 a 16 dígitos. Conserva referencia, producto, correo e importe y envía los campos de su ficha.
- Interpreta el resultado. Disney
successentrega el enlace. HTTP 202 conpendingno es un rechazo. Guardamovement_idcuando exista. - Consulta antes de reintentar. Usa POST /enlace-disney/status con la misma referencia. No generes una nueva para repetir una compra cuyo resultado desconoces.
- Concilia. Entrega el enlace solo con éxito confirmado y consulta el historial. Si el estado sigue sin aclararse, contacta a soporte con la referencia.
Para pagos: genera enlace o QR, guarda reference, permite pagar y verifica el resultado. La generación y el retorno del navegador no confirman recepción de dinero.
Autenticación y seguridad
Usa Authorization: Bearer TU_TOKEN, no X-Api-Key. Guarda credenciales y tokens exclusivamente en el servidor. No los publiques en el navegador, repositorios o logs.
gen_hys permite acceder a los servicios autorizados; payments a las rutas de pagos /v2/. Para generar en /v2/ y verificar con /gen_hys/verifypay necesitas ambos. También se validan rol y habilitación del servicio.
No dependas de cookies de sesión web. Al vencer el token, solicita otro; no hay refresh token documentado. Coordina cambios de IP de salida antes de operar.
No se publica un webhook de salida al integrador en esta edición. Usa los endpoints de seguimiento; no inventes parámetros de callback.
Referencia técnica
- Importes: números sin símbolos ni separadores de miles; algunas fichas requieren cadenas de dígitos. La moneda depende de la operación.
- Referencias y teléfonos: conservar como cadenas, incluidos ceros iniciales. No convertir referencias largas a Number de JavaScript.
- Fechas: filtros
YYYY-MM-DD.Zindica UTC; conserva los offsets recibidos. No restes cinco horas a todas las fechas. Movimientos unificados incluyetimezone=America/Bogotayfecha_iso. - Paginación: no hay un parámetro page general. Usa rangos de fecha donde estén admitidos.
- Límites: no se garantiza una cuota única. Ante 429 respeta
Retry-Aftersi existe. QR COP limita las verificaciones a cinco intentos: agotar ese límite no se resuelve con un bucle de reintentos. - Idempotencia: no hay un header general
Idempotency-Key. Disney conserva referencias. No extrapoles esa garantía a otras compras, renovaciones o generación de pagos. - Respuestas: algunas listas usan
aaDataen la raíz; otras usandata.rows. Conserva el cuerpo como texto cuando no se pueda decodificar JSON.
Errores y estados
| HTTP | Interpretación | Acción |
|---|---|---|
| 200 | Solicitud atendida, no necesariamente exitosa. | Leer result, status, estado o code según la ficha. |
| 202 | Registrada o pendiente. | Consultar la misma referencia. |
| 400 / 422 | Datos inválidos o producto no disponible. | Revisar parámetros y catálogo. |
| 401 | Credenciales incorrectas o AUTH_API_INVALID. | Revisar token, vigencia, permisos e IP; no repetir cobros automáticamente. |
| 403 | Acceso restringido; en códigos también puede indicar correo o código no encontrado. | Interpretar error o code; no tratar todos los 403 como fallo de token. |
| 404 | Recurso no encontrado para tu usuario. | Revisar cuenta e identificador. |
| 409 | Conflicto, saldo insuficiente, pendiente o rechazo. | No interpretar todos los 409 como rechazo definitivo. |
| 429 | Límite de consultas. | Detener el bucle y respetar la política del endpoint. |
| 5xx / timeout | Resultado sin confirmar. | Consultar estado o historial antes de repetir una operación financiera. |
Los mensajes pueden variar. error y trace_id no están garantizados en todas las rutas. Solicitar código utiliza code; Disney puede responder solo ok y message.
- Disney:
success,pending,rejected. - QR:
approvedopending; cancelación:cancelled. - Verificación unificada:
appliedconfirma aplicación. - Renovación: solo
estado=1confirma éxito. - Especiales:
estado="00"puede ser solo recepción; consultar su historial.
Descargas
OpenAPI 3.0.3 · Postman multimedia · Postman multiproducto · Postman pagos
Introduce las credenciales solo en un entorno privado. No ejecutes colecciones completas: incluyen compras. OpenAPI admite campos adicionales; los fragmentos de respuesta no son esquemas exhaustivos.
Historial de cambios
2026-10-13 · Revisión documental
- Disney: referencia obligatoria y estados del flujo actual.
- Multiproducto: apuestas, EPM, convenios, facturas y revistas.
- Referencia común de multimedia y tablas de operadores.
- Se retiran de la oferta disponible los medios y variantes sin contrato vigente verificado en esta edición.
- Búsqueda, ejemplos copiables, navegación adaptable y definiciones centralizadas.
No se modifican rutas, autenticación ni comportamiento de la API. Disponibilidad comercial sujeta a la cuenta.
Referencia de operaciones
No hay coincidencias. Cambia el texto de búsqueda.