CopDigital / APIDocumentación para integradores

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

Las compras afectan saldo real. No se publica un ambiente de pruebas en este contrato. Los valores de ejemplo son ficticios: no ejecutes compras para probar conectividad.

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

  1. Solicita habilitación. Contacta al administrador de CopDigital para activar tu acceso API, los servicios y los permisos gen_hys y/o payments. Informa las IP públicas de salida de tu servidor si se requiere una lista autorizada.
  2. Autentica desde tu servidor. Usa POST /api/auth/token. Guarda data.access_token y calcula su vencimiento con data.expires_in.
  3. Prueba una consulta. Envía Authorization: Bearer TU_TOKEN a GET /gen_hys/dashboard_state. No necesitas comprar para comprobar el acceso.
  4. Selecciona el producto. Por ejemplo, consulta el catálogo Disney, presenta el precio y solicita confirmación del cliente final.
  5. 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.
  6. Interpreta el resultado. Disney success entrega el enlace. HTTP 202 con pending no es un rechazo. Guarda movement_id cuando exista.
  7. Consulta antes de reintentar. Usa POST /enlace-disney/status con la misma referencia. No generes una nueva para repetir una compra cuyo resultado desconoces.
  8. 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. Z indica UTC; conserva los offsets recibidos. No restes cinco horas a todas las fechas. Movimientos unificados incluye timezone=America/Bogota y fecha_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-After si 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 aaData en la raíz; otras usan data.rows. Conserva el cuerpo como texto cuando no se pueda decodificar JSON.

Errores y estados

HTTPInterpretaciónAcción
200Solicitud atendida, no necesariamente exitosa.Leer result, status, estado o code según la ficha.
202Registrada o pendiente.Consultar la misma referencia.
400 / 422Datos inválidos o producto no disponible.Revisar parámetros y catálogo.
401Credenciales incorrectas o AUTH_API_INVALID.Revisar token, vigencia, permisos e IP; no repetir cobros automáticamente.
403Acceso 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.
404Recurso no encontrado para tu usuario.Revisar cuenta e identificador.
409Conflicto, saldo insuficiente, pendiente o rechazo.No interpretar todos los 409 como rechazo definitivo.
429Límite de consultas.Detener el bucle y respetar la política del endpoint.
5xx / timeoutResultado 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: approved o pending; cancelación: cancelled.
  • Verificación unificada: applied confirma aplicación.
  • Renovación: solo estado=1 confirma é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.